Placement API reference

Detailed documentation on the Placement API

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 setDAPR_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.

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

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.

HTTP Request

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

HTTP Response Codes

CodeDescription
200Placement tables information returned
500Placement could not return the placement tables information

HTTP Response Body

Placement tables API Response Object

NameTypeDescription
tableVersionintThe placement table version
hostListActor Host Info[]A json array of registered actors host info.

Actor Host Info

NameTypeDescription
namestringThe host:port address of the actor.
appIdstringapp id.
actorTypesjson string arrayList of actor types it hosts.
updatedAttimestampTimestamp of the actor registered/updated.

Examples

  1.  curl localhost:8080/placement/state
  1. {
  2.     "hostList": [{
  3.             "name": "198.18.0.1:49347",
  4.             "appId": "actor1",
  5.             "actorTypes": ["testActorType1", "testActorType3"],
  6.             "updatedAt": 1690274322325260000
  7.         },
  8.         {
  9.             "name": "198.18.0.2:49347",
  10.             "appId": "actor2",
  11.             "actorTypes": ["testActorType2"],
  12.             "updatedAt": 1690274322325260000
  13.         },
  14.         {
  15.             "name": "198.18.0.3:49347",
  16.             "appId": "actor2",
  17.             "actorTypes": ["testActorType2"],
  18.             "updatedAt": 1690274322325260000
  19.         }
  20.     ],
  21.     "tableVersion": 1
  22. }

Last modified October 12, 2023: Update config.toml (#3826) (0ffc2e7)