Skip to content

Commit 377c28a

Browse files
hhunter-mshhunter-ms
authored
Merge pull request #3745 from hhunter-ms/placement_tables_pt2
Add Placement API topic
2 parents 70e3a5e + 4d9c5fa commit 377c28a

File tree

4 files changed

+87
-3
lines changed

4 files changed

+87
-3
lines changed

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ The placement service is deployed as part of `dapr init -k`, or via the Dapr Hel
1717

1818
## Placement tables
1919

20-
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.
20+
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.
2121

2222
### Usecase:
2323
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.
@@ -83,3 +83,7 @@ updatedAt | timestamp | Timestamp of the actor registered/updated.
8383
"tableVersion": 1
8484
}
8585
```
86+
87+
## Related links
88+
89+
[Learn more about the Placement API.]({{< ref placement_api.md >}})

‎daprdocs/content/en/reference/api/error_codes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ type: docs
33
title: "Error codes returned by APIs"
44
linkTitle: "Error codes"
55
description: "Detailed reference of the Dapr API error codes"
6-
weight: 1200
6+
weight: 1300
77
---
88

99
For http calls made to Dapr runtime, when an error is encountered, an error json is returned in http response body. The json contains an error code and an descriptive error message, e.g.

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
type: docs
3+
title: "Placement API reference"
4+
linkTitle: "Placement API"
5+
description: "Detailed documentation on the Placement API"
6+
weight: 1200
7+
---
8+
9+
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.
10+
11+
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" >}}).
12+
13+
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`.
14+
15+
## Usecase
16+
17+
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.
18+
19+
## HTTP Request
20+
21+
```
22+
GET http://localhost:<healthzPort>/placement/state
23+
```
24+
25+
## HTTP Response Codes
26+
27+
Code | Description
28+
---- | -----------
29+
200 | Placement tables information returned
30+
500 | Placement could not return the placement tables information
31+
32+
## HTTP Response Body
33+
34+
**Placement tables API Response Object**
35+
36+
Name | Type | Description
37+
---- | ---- | -----------
38+
tableVersion | int | The placement table version
39+
hostList | [Actor Host Info](#actorhostinfo)[] | A json array of registered actors host info.
40+
41+
<a id="actorhostinfo"></a>**Actor Host Info**
42+
43+
Name | Type | Description
44+
---- | ---- | -----------
45+
name | string | The host:port address of the actor.
46+
appId | string | app id.
47+
actorTypes | json string array | List of actor types it hosts.
48+
updatedAt | timestamp | Timestamp of the actor registered/updated.
49+
50+
## Examples
51+
52+
```shell
53+
curl localhost:8080/placement/state
54+
```
55+
56+
```json
57+
{
58+
"hostList": [{
59+
"name": "198.18.0.1:49347",
60+
"appId": "actor1",
61+
"actorTypes": ["testActorType1", "testActorType3"],
62+
"updatedAt": 1690274322325260000
63+
},
64+
{
65+
"name": "198.18.0.2:49347",
66+
"appId": "actor2",
67+
"actorTypes": ["testActorType2"],
68+
"updatedAt": 1690274322325260000
69+
},
70+
{
71+
"name": "198.18.0.3:49347",
72+
"appId": "actor2",
73+
"actorTypes": ["testActorType2"],
74+
"updatedAt": 1690274322325260000
75+
}
76+
],
77+
"tableVersion": 1
78+
}
79+
```

‎daprdocs/content/en/reference/environment/_index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,5 @@ The following table lists the environment variables used by the Dapr runtime, CL
2626
| OTEL_EXPORTER_OTLP_INSECURE | OpenTelemetry Tracing | Sets the connection to the endpoint as unencrypted. (`true`, `false`) |
2727
| OTEL_EXPORTER_OTLP_PROTOCOL | OpenTelemetry Tracing | The OTLP protocol to use Transport protocol. (`grpc`, `http/protobuf`, `http/json`) |
2828
| 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` |
29-
| 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. |
29+
| 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. |
30+
| 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 in self-hosted mode. [Learn more about the Placement API]({{< ref placement_api.md >}}) |

0 commit comments

Comments
 (0)