From 7e2b92c8231d037a8750727aca065bbe4b5a28ea Mon Sep 17 00:00:00 2001 From: Ricardo Niepel Date: Tue, 31 Mar 2020 17:21:54 +0200 Subject: [PATCH 1/3] add pubsub scopes howto --- howto/pubsub-scopes/README.md | 125 ++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 howto/pubsub-scopes/README.md diff --git a/howto/pubsub-scopes/README.md b/howto/pubsub-scopes/README.md new file mode 100644 index 00000000000..6ae1d286370 --- /dev/null +++ b/howto/pubsub-scopes/README.md @@ -0,0 +1,125 @@ +# Limit the Pub/Sub topics used or scope them to one or more applications + +[Namespaces or component scopes](../components-scopes/README.md) can be used to limit component access to particular Dapr instances. + +In addition to this, the following can be limited at pub/sub components: +- the topics which can be used +- which applications are allowed to publish to specific topics +- which applications are allowed to subscribe to specific topics + +To use this topic scoping, three metadata properties can be set at the pub/sub component: +- ```spec.metadata.publishingScopes```: list of application to topic scopes to allow publishing, separated by semicolons. If an app is not specified in ```publishingScopes```, its allowed to publish to all topics. +- ```spec.metadata.subscriptionScopes```: list of application to topic scopes to allow subscription, separated by semicolons. If an app is not specified in ```subscriptionScopes```, its allowed to subscribe to all topics. +- ```spec.metadata.allowedTopics```: a comma-separated list for allowed topics for all applications. ```publishingScopes``` or ```subscriptionScopes``` can be used in addition to add granular limitations. If ```allowedTopics``` is not set, all topics are valid and then ```subscriptionScopes``` and ```publishingScopes``` take place if existent. + +The following scenarios are using Redis as pub/sub component, but this is only an example. These metadata properties can be used at all pub/sub components. + +## Scenario 1: Limit which application can publish or subscribe to topics + +This can be useful, if you have topics which contain sensitive information and only a subset of your applications are allowed to publish or subscribe to these. + +It can also be used for all topics to have always a ground truth which applications are using which topics as publishers/subscribers. + +An example of three applications and three topics: +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: messagebus +spec: + type: pubsub.redis + metadata: + - name: redisHost + value: "localhost:6379" + - name: redisPassword + value: "" + - name: publishingScopes + value: "app1=topic1;app2=topic2,topic3;app3=" + - name: subscriptionScopes + value: "app2=;app3=topic1" +``` + +See below which application is allowed to publish into the topics: +| Publishing | app1 | app2 | app3 | +|------------|------|------|------| +| topic1 | X | | | +| topic2 | | X | | +| topic3 | | X | | + +Below you can see which application is allowed to subscribe to the topics: +| Subscription | app1 | app2 | app3 | +|--------------|------|------|------| +| topic1 | X | | X | +| topic2 | X | | | +| topic3 | X | | | + +> Hint: Be aware that if an application is not listed (e.g. app1 in subscriptionScopes), it is allowed to subscribe to all topics. Because ```allowedTopics``` (see below of examples) is not used and app1 does not have any subscription scopes, it can also use additional topics not listed above. + +## Scenario 2: Limit which topics can be used by all applications without granular limitations + +A new topic is automatically created if a Dapr applications sends a message to it. +In some scenarios this topic creation should be governed: +- a bug in a Dapr application on generating the topic name can lead to an unlimited amount of topics created +- streamline the topics names and total count and don't allow a wild growth of unmanageable topics + +In these situations ```allowedTopics``` can be used. + +An example of three topics: +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: messagebus +spec: + type: pubsub.redis + metadata: + - name: redisHost + value: "localhost:6379" + - name: redisPassword + value: "" + - name: allowedTopics + value: "topic1,topic2,topic3" +``` + +All applications can use these topics, but only those, others are not allowed. + +## Scenario 3: Combine both + +Sometimes you want to combine both limitations, thus only having a fixed set of allowed topic and specify some application scoping on top of it. + +An example of three applications and two topics: +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: messagebus +spec: + type: pubsub.redis + metadata: + - name: redisHost + value: "localhost:6379" + - name: redisPassword + value: "" + - name: allowedTopics + value: "A,B" + - name: publishingScopes + value: "app1=A" + - name: subscriptionScopes + value: "app1=;app2=A" +``` + +> Hint: The third application is not listed, because if an app is not specified inside the scopes, its allowed to use all topics. + +See below which application is allowed to publish into the topics: +| Publishing | app1 | app2 | app3 | +|------------|------|------|------| +| A | X | X | X | +| B | | X | X | + +Below you can see which application is allowed to subscribe to the topics: +| Subscription | app1 | app2 | app3 | +|--------------|------|------|------| +| A | | X | X | +| B | | | X | + +No other topics can be used, only A and B. \ No newline at end of file From 98b56fff43ecbcc1b3d3a03a00176db5f39f1250 Mon Sep 17 00:00:00 2001 From: Ricardo Niepel Date: Tue, 31 Mar 2020 17:30:25 +0200 Subject: [PATCH 2/3] link pubsub scopes howto --- howto/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/howto/README.md b/howto/README.md index 122c534d6ed..fb2922b543d 100644 --- a/howto/README.md +++ b/howto/README.md @@ -38,7 +38,8 @@ Here you'll find a list of How To guides that walk you through accomplishing spe * [Setup Dapr Pub/Sub](./setup-pub-sub-message-broker) * [Use Pub/Sub to publish messages to a given topic](./publish-topic) * [Use Pub/Sub to consume events from a topic](./consume-topic) -* [Configuring Redis for pub/sub ](./configure-redis) +* [Configuring Redis for pub/sub](./configure-redis) +* [Limit the Pub/Sub topics used or scope them to one or more applications](./pubsub-scopes) ## Bindings and Triggers * [Implementing a new binding](https://github.com/dapr/docs/tree/master/reference/specs/bindings) From e5a6936d800b70394f87fba36436bcc60861a8b4 Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Tue, 31 Mar 2020 13:47:14 -0700 Subject: [PATCH 3/3] Update README.md --- howto/pubsub-scopes/README.md | 51 ++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/howto/pubsub-scopes/README.md b/howto/pubsub-scopes/README.md index 6ae1d286370..2d770ad7838 100644 --- a/howto/pubsub-scopes/README.md +++ b/howto/pubsub-scopes/README.md @@ -1,26 +1,28 @@ # Limit the Pub/Sub topics used or scope them to one or more applications -[Namespaces or component scopes](../components-scopes/README.md) can be used to limit component access to particular Dapr instances. +[Namespaces or component scopes](../components-scopes/README.md) can be used to limit component access to particular applications. These application scopes added to a component limit only the applications with specific IDs to be able to use the component. -In addition to this, the following can be limited at pub/sub components: -- the topics which can be used +In addition to this general component scope, the following can be limited for pub/sub components: +- the topics which can be used (published or subscribed) - which applications are allowed to publish to specific topics - which applications are allowed to subscribe to specific topics -To use this topic scoping, three metadata properties can be set at the pub/sub component: -- ```spec.metadata.publishingScopes```: list of application to topic scopes to allow publishing, separated by semicolons. If an app is not specified in ```publishingScopes```, its allowed to publish to all topics. -- ```spec.metadata.subscriptionScopes```: list of application to topic scopes to allow subscription, separated by semicolons. If an app is not specified in ```subscriptionScopes```, its allowed to subscribe to all topics. -- ```spec.metadata.allowedTopics```: a comma-separated list for allowed topics for all applications. ```publishingScopes``` or ```subscriptionScopes``` can be used in addition to add granular limitations. If ```allowedTopics``` is not set, all topics are valid and then ```subscriptionScopes``` and ```publishingScopes``` take place if existent. +This is called pub/sub topic scoping. -The following scenarios are using Redis as pub/sub component, but this is only an example. These metadata properties can be used at all pub/sub components. +To use this topic scoping, three metadata properties can be set for a pub/sub component: +- ```spec.metadata.publishingScopes```: the list of applications to topic scopes to allow publishing, separated by semicolons. If an app is not specified in ```publishingScopes```, its allowed to publish to all topics. +- ```spec.metadata.subscriptionScopes```: the list of applications to topic scopes to allow subscription, separated by semicolons. If an app is not specified in ```subscriptionScopes```, its allowed to subscribe to all topics. +- ```spec.metadata.allowedTopics```: a comma-separated list for allowed topics for all applications. ```publishingScopes``` or ```subscriptionScopes``` can be used in addition to add granular limitations. If ```allowedTopics``` is not set, all topics are valid and then ```subscriptionScopes``` and ```publishingScopes``` take place if present. + +These metadata properties can be used for all pub/sub components. The following examples use Redis as pub/sub component. ## Scenario 1: Limit which application can publish or subscribe to topics This can be useful, if you have topics which contain sensitive information and only a subset of your applications are allowed to publish or subscribe to these. -It can also be used for all topics to have always a ground truth which applications are using which topics as publishers/subscribers. +It can also be used for all topics to have always a "ground truth" for which applications are using which topics as publishers/subscribers. -An example of three applications and three topics: +Here is an example of three applications and three topics: ```yaml apiVersion: dapr.io/v1alpha1 kind: Component @@ -39,32 +41,31 @@ spec: value: "app2=;app3=topic1" ``` -See below which application is allowed to publish into the topics: +The table below shows which application is allowed to publish into the topics: | Publishing | app1 | app2 | app3 | |------------|------|------|------| | topic1 | X | | | | topic2 | | X | | | topic3 | | X | | -Below you can see which application is allowed to subscribe to the topics: +The table below shows can see which application is allowed to subscribe to the topics: | Subscription | app1 | app2 | app3 | |--------------|------|------|------| | topic1 | X | | X | | topic2 | X | | | | topic3 | X | | | -> Hint: Be aware that if an application is not listed (e.g. app1 in subscriptionScopes), it is allowed to subscribe to all topics. Because ```allowedTopics``` (see below of examples) is not used and app1 does not have any subscription scopes, it can also use additional topics not listed above. +> Note: If an application is not listed (e.g. app1 in subscriptionScopes), it is allowed to subscribe to all topics. Because ```allowedTopics``` (see below of examples) is not used and app1 does not have any subscription scopes, it can also use additional topics not listed above. ## Scenario 2: Limit which topics can be used by all applications without granular limitations -A new topic is automatically created if a Dapr applications sends a message to it. -In some scenarios this topic creation should be governed: +A topic is created if a Dapr application sends a message to it. In some scenarios this topic creation should be governed. For example; - a bug in a Dapr application on generating the topic name can lead to an unlimited amount of topics created -- streamline the topics names and total count and don't allow a wild growth of unmanageable topics +- streamline the topics names and total count and prevent a unlimited growth of topics In these situations ```allowedTopics``` can be used. -An example of three topics: +Here is an example of three allowed topics: ```yaml apiVersion: dapr.io/v1alpha1 kind: Component @@ -81,13 +82,13 @@ spec: value: "topic1,topic2,topic3" ``` -All applications can use these topics, but only those, others are not allowed. +All applications can use these topics, but only those topic, no others are allowed. -## Scenario 3: Combine both +## Scenario 3: Combine both allowed topics allowed applications that can publish and subscribe -Sometimes you want to combine both limitations, thus only having a fixed set of allowed topic and specify some application scoping on top of it. +Sometimes you want to combine both scopes, thus only having a fixed set of allowed topics and specify scoping to certain applications. -An example of three applications and two topics: +Here is an example of three applications and two topics: ```yaml apiVersion: dapr.io/v1alpha1 kind: Component @@ -108,18 +109,18 @@ spec: value: "app1=;app2=A" ``` -> Hint: The third application is not listed, because if an app is not specified inside the scopes, its allowed to use all topics. +> Note: The third application is not listed, because if an app is not specified inside the scopes, its allowed to use all topics. -See below which application is allowed to publish into the topics: +The table below shows which application is allowed to publish into the topics: | Publishing | app1 | app2 | app3 | |------------|------|------|------| | A | X | X | X | | B | | X | X | -Below you can see which application is allowed to subscribe to the topics: +The table below shows which application is allowed to subscribe to the topics: | Subscription | app1 | app2 | app3 | |--------------|------|------|------| | A | | X | X | | B | | | X | -No other topics can be used, only A and B. \ No newline at end of file +No other topics can be used, only A and B.