From 564cfd8adb1eb856aa6f9a1526c1aab1ed7172ce Mon Sep 17 00:00:00 2001 From: Taction Date: Sat, 23 Sep 2023 01:28:24 +0800 Subject: [PATCH 1/2] Add placement table api doc (#3631) * add placement table api doc Signed-off-by: zhangchao * typo fix Signed-off-by: zhangchao * fix review Signed-off-by: zhangchao * fix example Signed-off-by: zhangchao --------- Signed-off-by: zhangchao Co-authored-by: Mark Fussell Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- .../en/concepts/dapr-services/placement.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/daprdocs/content/en/concepts/dapr-services/placement.md b/daprdocs/content/en/concepts/dapr-services/placement.md index 85d9c6448..5cb1d9995 100644 --- a/daprdocs/content/en/concepts/dapr-services/placement.md +++ b/daprdocs/content/en/concepts/dapr-services/placement.md @@ -14,3 +14,72 @@ The placement service Docker container is started automatically as part of [`dap ## 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 >}}). + +## 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. + +### 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 + +``` +GET http://localhost:/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](#actorhostinfo)[] | 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 + +```shell + curl localhost:8080/placement/state +``` + +```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 +} +``` From c79c7d5cd0bc4b10cd9bdc1c48425190f8957566 Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Fri, 22 Sep 2023 14:17:10 -0400 Subject: [PATCH 2/2] Update daprdocs/content/en/reference/environment/_index.md Co-authored-by: Mark Fussell Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- daprdocs/content/en/reference/environment/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/environment/_index.md b/daprdocs/content/en/reference/environment/_index.md index 88f018f22..f5081802f 100644 --- a/daprdocs/content/en/reference/environment/_index.md +++ b/daprdocs/content/en/reference/environment/_index.md @@ -27,4 +27,4 @@ The following table lists the environment variables used by the Dapr runtime, CL | OTEL_EXPORTER_OTLP_PROTOCOL | OpenTelemetry Tracing | The OTLP protocol to use Transport protocol. (`grpc`, `http/protobuf`, `http/json`) | | DAPR_COMPONENTS_SOCKETS_FOLDER | Dapr runtime and the .NET, Go, and Java pluggable component SDKs | The location or path where Dapr looks for Pluggable Components Unix Domain Socket files. If unset this location defaults to `/tmp/dapr-components-sockets` | | DAPR_COMPONENTS_SOCKETS_EXTENSION | .NET and Java pluggable component SDKs | A per-SDK configuration that indicates the default file extension applied to socket files created by the SDKs. Not a Dapr-enforced behavior. | -| DAPR_PLACEMENT_METADATA_ENABLED | Dapr placement | A placement service that exposes placement table information. Set to `true` to enable. [Learn more about the Placement API]({{< ref placement_api.md >}}) | \ No newline at end of file +| DAPR_PLACEMENT_METADATA_ENABLED | Dapr placement | Enable an endpoint for the Placement service that exposes placement table information on actor usage. Set to `true` to enable. [Learn more about the Placement API]({{< ref placement_api.md >}}) | \ No newline at end of file