Dapr Placement control plane service overview

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 running in self-hosted mode or on 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. It can also be run manually as a process if you are running in slim-init mode.

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.

Placement tables

There is 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. 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.

Important

When deploying actors into different namespaces (https://docs.dapr.io/developing-applications/building-blocks/actors/namespaced-actors/)), 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.

Usecase:

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

GET http://localhost:<healthzPort>/placement/state

HTTP Response Codes

Code	Description
200	Placement tables information returned
500	Placement could not return the placement tables information

HTTP Response Body

Placement tables API Response Object

Name	Type	Description
tableVersion	int	The placement table version
hostList	Actor Host Info[]	A json array of registered actors host info.

Actor Host Info

Name	Type	Description
name	string	The host:port address of the actor.
appId	string	app id.
actorTypes	json string array	List of actor types it hosts.
updatedAt	timestamp	Timestamp of the actor registered/updated.

Examples

 curl localhost:8080/placement/state

{
    "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
}

Learn more about the Placement API.

Last modified October 11, 2024: Fixed typo (#4389) (fe17926)

Placement