updates per Mark

Signed-off-by: Hannah Hunter <[email protected]>
dapr · Jun 14, 2024 · 87456a6 · 87456a6
1 parent 0ab817d
commit 87456a6
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 32 deletions.
diff --git a/daprdocs/content/en/concepts/dapr-services/placement.md b/daprdocs/content/en/concepts/dapr-services/placement.md
@@ -2,29 +2,29 @@
 type: docs
 title: "Dapr Placement control plane service overview"
 linkTitle: "Placement"
-description: "Overview of the Dapr placement service"
+description: "Overview of the Dapr Placement service"
 ---
 
-The Dapr Placement service is used to calculate and distribute distributed hash tables for the location of [Dapr actors]({{< ref actors >}}) running in [self-hosted mode]({{< ref self-hosted >}}) or on [Kubernetes]({{< ref kubernetes >}}). Grouped by namespace, the hash tables map actor types to pods or processes so a Dapr application can communicate with the actor. Anytime a Dapr application activates a Dapr actor, the placement service updates the hash tables with the latest actor locations.
+The Dapr Placement service is used to calculate and distribute distributed hash tables for the location of [Dapr actors]({{< ref actors >}}) running in [self-hosted mode]({{< ref self-hosted >}}) or on [Kubernetes]({{< ref kubernetes >}}). Grouped by namespace, the hash tables map actor types to pods or processes so a Dapr application can communicate with the actor. Anytime a Dapr application activates a Dapr actor, the Placement service updates the hash tables with the latest actor location.
 
 ## Self-hosted mode
 
-The placement service Docker container is started automatically as part of [`dapr init`]({{< ref self-hosted-with-docker.md >}}). It can also be run manually as a process if you are running in [slim-init mode]({{< ref self-hosted-no-docker.md >}}).
+The Placement service Docker container is started automatically as part of [`dapr init`]({{< ref self-hosted-with-docker.md >}}). It can also be run manually as a process if you are running in [slim-init mode]({{< ref self-hosted-no-docker.md >}}).
 
 ## Kubernetes mode
 
-The placement service is deployed as part of `dapr init -k`, or via the Dapr Helm charts. For more information on running Dapr on Kubernetes, visit the [Kubernetes hosting page]({{< ref kubernetes >}}).
+The Placement service is deployed as part of `dapr init -k`, or via the Dapr Helm charts. For more information on running Dapr on Kubernetes, visit the [Kubernetes hosting page]({{< ref kubernetes >}}).
 
 ## Placement tables
 
-There is an [HTTP API `/placement/state` for placement service]({{< ref placement_api.md >}}) that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default. You need to set `DAPR_PLACEMENT_METADATA_ENABLED` environment or `metadata-enabled` command line args to true to enable it. If you are using helm you just need to set `dapr_placement.metadataEnabled` to true.
+There is an [HTTP API `/placement/state` for Placement service]({{< ref placement_api.md >}}) that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default. You need to set `DAPR_PLACEMENT_METADATA_ENABLED` environment or `metadata-enabled` command line args to true to enable it. If you are using helm you just need to set `dapr_placement.metadataEnabled` to true.
 
 {{% alert title="Important" color="warning" %}}
-When running placement in [multi-tenant mode]({{< ref namespaced-actors.md >}}), disable the `metadata-enabled` command line args to prevent different namespaces from seeing each other's data.
+When deploying actors into different namespaces ({{< ref namespaced-actors.md >}}), it is recommended to disable the `metadata-enabled` if you want to prevent retrieving actors from all namespaces. The metadata endpoint is scoped to all namespaces.
 {{% /alert %}}
 
 ### Usecase:
-The placement table API can be used for retrieving the current placement table, which contains all the actors registered. This can be helpful for debugging and allows tools to extract and present information about actors.
+The placement table API can be used to retrieve the current placement table, which contains all the actors registered across all namespaces. This is helpful for debugging and allowing tools to extract and present information about actors.
 
 ### HTTP Request
 
@@ -74,14 +74,14 @@ updatedAt | timestamp | Timestamp of the actor registered/updated.
         },
         {
             "name": "198.18.0.2:49347",
-                        "namespace": "ns2",
+            "namespace": "ns2",
             "appId": "actor2",
             "actorTypes": ["testActorType2"],
             "updatedAt": 1690274322325260000
         },
         {
             "name": "198.18.0.3:49347",
-                        "namespace": "ns2",
+            "namespace": "ns2",
             "appId": "actor2",
             "actorTypes": ["testActorType2"],
             "updatedAt": 1690274322325260000

diff --git a/daprdocs/content/en/concepts/terminology.md b/daprdocs/content/en/concepts/terminology.md
@@ -20,3 +20,5 @@ This page details all of the common terms you may come across in the Dapr docs.
 | Self-hosted | Windows/macOS/Linux machine(s) where you can run your applications with Dapr. Dapr provides the capability to run on machines in "self-hosted" mode. | [Self-hosted mode]({{< ref self-hosted-overview.md >}})
 | Service | A running application or binary. This can refer to your application or to a Dapr application.
 | Sidecar | A program that runs alongside your application as a separate process or container. | [Sidecar pattern](https://docs.microsoft.com/azure/architecture/patterns/sidecar)
+| Namespacing | Namespacing in Dapr provides isolation, and thus provides multi-tenancy. | Learn more about namespacing [components]({{< ref component-scopes.md >}}), [service invocation]({{< service-invocation-namespaces.md >}}), [pub/sub]({{< ref pubsub-scopes.md >}}), and [actors]({{< ref namespaced-actors.md >}})
+
diff --git a/...cs/content/en/developing-applications/building-blocks/actors/actors-overview.md b/...cs/content/en/developing-applications/building-blocks/actors/actors-overview.md
@@ -56,8 +56,8 @@ You would use Dapr Workflow when you need to define and orchestrate complex work
 
 ### Namespaced actors
 
-Dapr supports namespaced actors. For example, with Dapr's multi-tenant placement service, where each tenant has its own namespace, sidecars belonging to a tenant named "Tenant A" won't receive placement information for "Tenant B". This means that multiple tenants can have actor types with the same name. 
-
+Dapr supports namespaced actors. An actor type can be deployed into different namespaces. Instances of each actor type can call across namespaces. 
+ 
 [Learn more about namespaced actors and how they work.]({{< ref namespaced-actors.md >}})
 
 ### Actor lifetime

diff --git a/.../content/en/developing-applications/building-blocks/actors/namespaced-actors.md b/.../content/en/developing-applications/building-blocks/actors/namespaced-actors.md
@@ -3,39 +3,107 @@ type: docs
 title: "Namespaced actors"
 linkTitle: "Namespaced actors"
 weight: 40
-description: "Learn about the multi-tenant placement service in actors"
+description: "Learn about namespaced actors"
 ---
 
-Namespaced actors use the multi-tenant placement service. With this service, in a scenario where each tenant has its own namespace, sidecars belonging to a tenant named "Tenant A" won't receive placement information for "Tenant B". 
+Namespaced actors use the multi-tenant Placement service. With this service, in a scenario where each tenant has its own namespace, sidecars belonging to a tenant named "Tenant A" won't receive placement information for "Tenant B". 
 
-<img src="/images/multi-tenancy-overview.png" width=900>
+Namespacing in Dapr provides isolation, and thus multi-tenancy. With namespacing, the same actor type can be deployed into different namespaces. Instances of actors can call across these namespaces. 
 
-In order for multiple tenants to have actor types and/or IDs with the same name, every namespace should have its own state store. Otherwise, apps in different namespaces with the same actor type and/or ID may overwrite each other's data in the state store.
+{{% alert title="Note" color="primary" %}}
+Note that the namespace is not part of the actor name (that is an actor id), namespace is used for the isolation of the deployed actor services.
+{{% /alert %}}
 
-If you're moving to a new namespace and starting to use a new state store, make sure you migrate your data.
+## Creating and configuring namespaces
 
-## Backwards compatibilty
+You can use namespaces either in self-hosted mode or on Kubernetes.
 
-Namespaced actors are backwards compatible for deployments that use mTLS, because the sidecar's namespace is inferred from the Spiffe ID, allowing for multi-tenancy out-of-the-box.
+{{< tabs "Self-Hosted" "Kubernetes">}}
 
-<img src="/images/namespaced-actors-with-mtls.png" width=900>
+{{% codetab %}}
+In self-hosted mode, you can specify the namespace for a Dapr instance by setting [the `NAMESPACE` environment variable]({{< ref environment.md >}}).
 
-### Without mTLS enabled
+{{% /codetab %}}
 
-If you haven't enabled mTLS, sidecars A and B won't have information about the actor types hosted on sidecar C. In namespace Y, sidecar D won't have information about the actor types hosted on sidecars E and F.
+{{% codetab %}}
+On Kubernetes, you can create and configure namepaces when deploying actor applications. For example, start with the following `kubectl` commands:
 
-Sidecars C, E, and F, however, can see each other’s actor-types. 
+```bash
+kubectl create namespace namespace-actorA
+kubectl config set-context --current --namespace=namespace-actorA
+```
 
-<img src="/images/namespaced-actors-without-mtls.png" width=900>
+Then, deploy your actor applications into this namespace (in the example, `namespace-actorA`).
 
-For pre-v1.14 sidecars that don't use mTLS, the placement service uses a special “empty” namespace. When these sidecars connect to a new placement service, they only get the actor types hosted on other pre-v1.14 sidecars in the empty namespace that are not on mTLS.
+{{% /codetab %}}
 
-<img src="/images/empty-namespace.png" width=900>
+{{< /tabs >}}
 
-{{% alert title="Important" color="warning" %}}
-If you’re not using mTLS, make sure you have a uniform version per namespace. Either upgrade all sidecars in a namespace or none.
-{{% /alert %}}
+## Configuring actor state stores for namespacing
+
+While you could use different physical databases for each actor namespace, some state store components provide a way to logically separate data by table, prefix, collection, and more. This allows you to use the same physical database for multiple namespaces, as long as you provide the logical separation in the Dapr component definition.
+
+### Example 1: By a prefix in etcd
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: statestore
+spec:
+  type: state.etcd
+  version: v2
+  metadata:
+  - name: endpoints
+    value: localhost:2379
+  - name: keyPrefixPath
+    value: namespace1
+  - name: actorStateStore
+    value: "true"
+```
+
+### Example 2: By table name in SQLite
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: statestore
+spec:
+  type: state.sqlite
+  version: v1
+  metadata:
+  - name: connectionString
+    value: "data.db"
+  - name: tableName
+    value: "namespace1"
+  - name: actorStateStore
+    value: "true"
+```
+
+### Example 3: By logical database number in Redis
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: statestore
+spec:
+  type: state.redis
+  version: v1
+  metadata:
+  - name: redisHost
+    value: localhost:6379
+  - name: redisPassword
+    value: ""
+  - name: actorStateStore
+    value: "true"
+  - name: redisDB
+    value: "1"
+```
+
+Check your [state store component specs]({{< ref supported-state-stores.md >}}) to see what it provides.
 
 ## Next steps
-- [Learn more about the Dapr placement service]({{< ref placement.md >}})
+- [Learn more about the Dapr Placement service]({{< ref placement.md >}})
 - [Placement API reference guide]({{< ref placement_api.md >}})
diff --git a/daprdocs/content/en/reference/api/placement_api.md b/daprdocs/content/en/reference/api/placement_api.md
@@ -6,7 +6,7 @@ description: "Detailed documentation on the Placement API"
 weight: 1200
 ---
 
-Dapr has an HTTP API `/placement/state` for placement service that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default. 
+Dapr has an HTTP API `/placement/state` for Placement service that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default. 
 
 To enable the placement metadata in self-hosted mode you can either set`DAPR_PLACEMENT_METADATA_ENABLED` environment variable or `metadata-enabled` command line args on the Placement service to `true` to. See [how to run the Placement service in self-hosted mode]({{< ref "self-hosted-no-docker.md#enable-actors" >}}).
 
@@ -68,14 +68,14 @@ updatedAt | timestamp | Timestamp of the actor registered/updated.
         },
         {
             "name": "198.18.0.2:49347",
-                        "namespace": "ns2",
+            "namespace": "ns2",
             "appId": "actor2",
             "actorTypes": ["testActorType2"],
             "updatedAt": 1690274322325260000
         },
         {
             "name": "198.18.0.3:49347",
-                        "namespace": "ns2",
+            "namespace": "ns2",
             "appId": "actor2",
             "actorTypes": ["testActorType2"],
             "updatedAt": 1690274322325260000