Namespaced actors

daprdocs/content/en/concepts/dapr-services/placement.md

@@ -5,7 +5,7 @@ linkTitle: "Placement"
 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 >}}). This hash table maps actor IDs to pods or processes so a Dapr application can communicate with the actor.Anytime a Dapr application activates a Dapr actor, the placement 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 updates the hash tables with the latest actor locations.
 
 ## Self-hosted mode
 
@@ -19,6 +19,10 @@ The placement service is deployed as part of `dapr init -k`, or via the Dapr Hel
 
 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.
+{{% /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.
 
@@ -61,26 +65,29 @@ updatedAt | timestamp | Timestamp of the actor registered/updated.
 
 ```json
 {
-	"hostList": [{
-			"name": "198.18.0.1:49347",
-			"appId": "actor1",
-			"actorTypes": ["testActorType1", "testActorType3"],
-			"updatedAt": 1690274322325260000
-		},
-		{
-			"name": "198.18.0.2:49347",
-			"appId": "actor2",
-			"actorTypes": ["testActorType2"],
-			"updatedAt": 1690274322325260000
-		},
-		{
-			"name": "198.18.0.3:49347",
-			"appId": "actor2",
-			"actorTypes": ["testActorType2"],
-			"updatedAt": 1690274322325260000
-		}
-	],
-	"tableVersion": 1
+    "hostList": [{
+            "name": "198.18.0.1:49347",
+                        "namespace": "ns1",
+            "appId": "actor1",
+            "actorTypes": ["testActorType1", "testActorType3"],
+            "updatedAt": 1690274322325260000
+        },
+        {
+            "name": "198.18.0.2:49347",
+                        "namespace": "ns2",
+            "appId": "actor2",
+            "actorTypes": ["testActorType2"],
+            "updatedAt": 1690274322325260000
+        },
+        {
+            "name": "198.18.0.3:49347",
+                        "namespace": "ns2",
+            "appId": "actor2",
+            "actorTypes": ["testActorType2"],
+            "updatedAt": 1690274322325260000
+        }
+    ],
+    "tableVersion": 1
 }
 ```
 

daprdocs/content/en/developing-applications/building-blocks/actors/actor-reentrancy.md

@@ -2,7 +2,7 @@
 type: docs
 title: "How-to: Enable and use actor reentrancy in Dapr"
 linkTitle: "How-To: Actor reentrancy"
-weight: 70
+weight: 80
 description: Learn more about actor reentrancy
 ---
 

daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md

@@ -54,6 +54,12 @@ You would use Dapr Workflow when you need to define and orchestrate complex work
 
 ## Features
 
+### Namespaced actors
+
+Dapr supports namespaced actors. For example, with Dapr's multi-tenant placement service, 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. 
+
+[Learn more about namespaced actors and how they work.]({{< ref namespaced-actors.md >}})
+
 ### Actor lifetime
 
 Since Dapr actors are virtual, they do not need to be explicitly created or destroyed. The Dapr actor runtime:

daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md

@@ -2,7 +2,7 @@
 type: docs
 title: "Actors timers and reminders"
 linkTitle: "Timers and reminders"
-weight: 40
+weight: 50
 description: "Setting timers and reminders and performing error handling for your actors"
 aliases:
   - "/developing-applications/building-blocks/actors/actors-background"

daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors-partitioning.md

@@ -2,7 +2,7 @@
 type: docs
 title: "How to: Enable partitioning of actor reminders"
 linkTitle: "How to: Partition reminders"
-weight: 50
+weight: 60
 description: "Enable actor reminders partitioning for your application"
 aliases:
   - "/developing-applications/building-blocks/actors/actors-background"

daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md

@@ -2,7 +2,7 @@
 type: docs
 title: "How-to: Interact with virtual actors using scripting"
 linkTitle: "How-To: Interact with virtual actors"
-weight: 60
+weight: 70
 description: Invoke the actor method for state management
 ---
 

daprdocs/content/en/developing-applications/building-blocks/actors/namespaced-actors.md

@@ -0,0 +1,57 @@
+---
+type: docs
+title: "Namespaced actors"
+linkTitle: "Namespaced actors"
+weight: 40
+description: "Learn about the multi-tenant placement service in actors"
+---
+
+Namespaced actors use the multi-tenant placement service. For example, sidecars belonging to "Tenant A" don't receive placement information meant for "Tenant B". 
+
+<!-- need diagram --> 
+
+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.
+
+## Example
+
+In the following example...
+
+<!-- need example? ok to use from placement API? --> 
+
+## Migrating data to a new namespace
+
+If you're moving to a new namespace and starting to use a new state store, make sure you migrate your data.
+
+## Backwards compatibilty
+
+Namespaced actors are backwards compatible, allowing you to block newer sidecar versions from seeing the actor types within older sidecar versions.
+
+Depending on whether mTLS is enabled, the namespace is either:
+- Verified through Spiffe ID (mTLS enabled), or
+- Accepted as-is (mTLS not enabled)
+
+### With mTLS enabled
+
+Let's say you've enabled mTLS. As soon as the placement server is updated, the sidecars in namespace X (A, B, and C) can see each other’s actor types, and no others. The same is true for sidecars D, E, and F in namespace Y.
+
+<img src="/images/namespaced-actors-with-mtls.png" width=900>
+
+### Without mTLS enabled
+
+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.
+
+Sidecars C, E, and F, however, can see each other’s actor-types. 
+
+<img src="/images/namespaced-actors-without-mtls.png" width=900>
+
+For older 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 old sidecars in the empty namespace that are not on mTLS.
+
+<img src="/images/empty-namespace.png" width=900>
+
+{{% 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 %}}
+
+## Next steps
+- [Learn more about the Dapr placement service]({{< ref placement.md >}})
+- [Placement API reference guide]({{< ref placement_api.md >}})

daprdocs/content/en/reference/api/placement_api.md

@@ -10,6 +10,10 @@ Dapr has an HTTP API `/placement/state` for placement service that exposes place
 
 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" >}}).
 
+{{% 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.
+{{% /alert %}}
+
 If you are using Helm for deployment of the Placement service on Kubernetes then to enable the placement metadata, set `dapr_placement.metadataEnabled` to `true`.
 
 ## Usecase