luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #10462 from hashicorp/docs/add-ns-agent-services-9710 

docs: Add namespace parameters to /agent/service* endpoints
This commit is contained in:
Blake Covarrubias 2021-07-21 11:16:49 -07:00 committed by GitHub
parent a5ab658bf8 a0fb38ad48
commit a0c531a54f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 252 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

353
website/content/api-docs/agent/service.mdx
View File

@ -42,6 +42,12 @@ The table below shows this endpoint's support for
- `filter` `(string: "")` - Specifies the expression used to filter the - `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data. queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which
to list services. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
```shell-session ```shell-session
@ -63,13 +69,14 @@ $ curl \
"port": 8000 "port": 8000
}, },
"wan": { "wan": {
"address": "198.18.0.53", "address": "198.51.100.53",
"port": 80 "port": 80
} }
}, },
"Meta": { "Meta": {
"redis_version": "4.0" "redis_version": "4.0"
}, },
"Namespace": "default",
"Port": 8000, "Port": 8000,
"Address": "", "Address": "",
"EnableTagOverride": false, "EnableTagOverride": false,
@ -158,6 +165,12 @@ The table below shows this endpoint's support for
- `service_id` `(string: <required>)` - Specifies the ID of the service to - `service_id` `(string: <required>)` - Specifies the ID of the service to
fetch. This is specified as part of the URL. fetch. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the service's configuration. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
```shell-session ```shell-session
@ -174,6 +187,7 @@ $ curl \
"Service": "web-sidecar-proxy", "Service": "web-sidecar-proxy",
"Tags": null, "Tags": null,
"Meta": null, "Meta": null,
"Namespace": "default",
"Port": 18080, "Port": 18080,
"Address": "", "Address": "",
"TaggedAddresses": { "TaggedAddresses": {
@ -182,7 +196,7 @@ $ curl \
"port": 8000 "port": 8000
}, },
"wan": { "wan": {
"address": "198.18.0.53", "address": "198.51.100.53",
"port": 80 "port": 80
} }
}, },
@ -246,6 +260,17 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- | | ---------------- | ----------------- | ------------- | -------------- |
| `NO` | `none` | `none` | `service:read` | | `NO` | `none` | `none` | `service:read` |
### Parameters
- `service_name` `(string: <required>)` - Specifies the name of the service to
retrieve. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the service's health data. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
Those endpoints return the aggregated values of all health checks for the Those endpoints return the aggregated values of all health checks for the
service instance(s) and will return the corresponding HTTP codes: service instance(s) and will return the corresponding HTTP codes:
@ -267,7 +292,7 @@ Those endpoints might be useful for the following use-cases:
##### Note ##### Note
If you know the ID of service you want to target, it is recommended to use If you know the ID of service you want to target, it is recommended to use
[`/v1/agent/health/service/id/:service_id`](/api/agent/service#get-local-service-health-by-its-id) [`/v1/agent/health/service/id/:service_id`](/api/agent/service#get-local-service-health-by-id)
so you have the result for the service only. When requesting so you have the result for the service only. When requesting
`/v1/agent/health/service/name/:service_name`, the caller will receive the `/v1/agent/health/service/name/:service_name`, the caller will receive the
worst state of all services having the given name. worst state of all services having the given name.
@ -276,77 +301,214 @@ worst state of all services having the given name.
Given 2 services with name `web`, with web2 critical and web1 passing: Given 2 services with name `web`, with web2 critical and web1 passing:
#### List worst statuses of all instances of web-demo services (HTTP 503) #### List the worst status across all instances of the `web` service (HTTP 503)
##### By Name, Text ##### By Name, Text
```shell ```shell
curl http://localhost:8500/v1/agent/health/service/name/web?format=text $ curl http://localhost:8500/v1/agent/health/service/name/web?format=text
critical critical
``` ```
##### By Name, JSON ##### By Name, JSON
In JSON, the detail of passing/warning/critical services is present in output, For the JSON output, the response is an array containing the details of each
in a array. passing, warning, or critical service.
```shell ```shell
curl localhost:8500/v1/agent/health/service/name/web curl localhost:8500/v1/agent/health/service/name/web
``` ```
```json ```json
[
{ {
"critical": [ "AggregatedStatus": "passing",
{ "Service": {
"ID": "web2", "ID": "web1",
"Service": "web", "Service": "web",
"Tags": ["rails"], "Tags": [
"rails"
],
"Meta": {},
"Port": 80,
"Address": "", "Address": "",
"SocketPath": "",
"TaggedAddresses": { "TaggedAddresses": {
"lan": { "lan": {
"address": "127.0.0.1", "Address": "127.0.0.1",
"port": 8000 "Port": 8000
}, },
"wan": { "wan": {
"address": "198.18.0.53", "Address": "198.51.100.53",
"port": 80 "Port": 80
} }
}, },
"Meta": null, "Weights": {
"Port": 80, "Passing": 1,
"Warning": 1
},
"EnableTagOverride": false, "EnableTagOverride": false,
"Datacenter": "dc1", "Namespace": "default",
"Connect": { "Datacenter": "dc1"
"Native": false, },
"Proxy": null "Checks": []
},
{
"AggregatedStatus": "critical",
"Service": {
"ID": "web2",
"Service": "web",
"Tags": [
"rails"
],
"Meta": {},
"Port": 80,
"Address": "",
"SocketPath": "",
"TaggedAddresses": {
"lan": {
"Address": "127.0.0.1",
"Port": 8000
},
"wan": {
"Address": "198.51.100.54",
"Port": 80
}
},
"Weights": {
"Passing": 1,
"Warning": 1
},
"EnableTagOverride": false,
"Namespace": "default",
"Datacenter": "dc1"
},
"Checks": [
{
"Node": "server1",
"CheckID": "service:web2",
"Name": "Service 'web' check",
"Status": "critical",
"Notes": "",
"Output": "Get \"http://localhost/health\": dial tcp [::1]:80: connect: connection refused",
"ServiceID": "web2",
"ServiceName": "web",
"ServiceTags": [
"rails"
],
"Type": "",
"Namespace": "default",
"Definition": {
"Interval": "0s",
"Timeout": "0s",
"DeregisterCriticalServiceAfter": "0s",
"HTTP": "",
"Header": null,
"Method": "",
"Body": "",
"TLSServerName": "",
"TLSSkipVerify": false,
"TCP": ""
}, },
"CreateIndex": 0, "CreateIndex": 0,
"ModifyIndex": 0 "ModifyIndex": 0
} }
], ]
"passing": [ }
]
```
## Get local service health by ID ((#get-local-service-health-by-its-id))
Retrieve the health state of a specific service on the local agent by ID.
| Method | Path | Produces |
| ------ | -------------------------------------------------- | ------------------ |
| `GET` | `/agent/health/service/id/:service_id` | `application/json` |
| `GET` | `/agent/health/service/id/:service_id?format=text` | `text/plain` |
The supported request parameters are the same as
[`/v1/agent/health/service/name/:service_name`](/api/agent/service#get-local-service-health).
### Sample Requests
Query the health status of the service with ID `web2`.
#### List status of web2 (HTTP 503)
##### Failure By ID, Text
```shell
$ curl http://localhost:8500/v1/agent/health/service/id/web2?format=text
critical
```
##### Failure By ID, JSON
In JSON, the output for a query by ID is an object containing only the details
for that service.
```shell
curl localhost:8500/v1/agent/health/service/id/web2
```
```json
{ {
"ID": "web1", "AggregatedStatus": "critical",
"Service": {
"ID": "web2",
"Service": "web", "Service": "web",
"Tags": ["rails"], "Tags": [
"rails"
],
"Meta": {},
"Port": 80,
"Address": "", "Address": "",
"SocketPath": "",
"TaggedAddresses": { "TaggedAddresses": {
"lan": { "lan": {
"address": "127.0.0.1", "Address": "127.0.0.1",
"port": 8000 "Port": 8000
}, },
"wan": { "wan": {
"address": "198.18.0.53", "Address": "198.51.100.54",
"port": 80 "Port": 80
} }
}, },
"Meta": null, "Weights": {
"Port": 80, "Passing": 1,
"Warning": 1
},
"EnableTagOverride": false, "EnableTagOverride": false,
"Datacenter": "dc1", "Namespace": "default",
"Connect": { "Datacenter": "dc1"
"Native": false, },
"Proxy": null "Checks": [
{
"Node": "server1",
"CheckID": "service:web2",
"Name": "Service 'web' check",
"Status": "critical",
"Notes": "",
"Output": "Get \"http://localhost/health\": dial tcp [::1]:80: connect: connection refused",
"ServiceID": "web2",
"ServiceName": "web",
"ServiceTags": [
"rails"
],
"Type": "",
"Namespace": "default",
"Definition": {
"Interval": "0s",
"Timeout": "0s",
"DeregisterCriticalServiceAfter": "0s",
"HTTP": "",
"Header": null,
"Method": "",
"Body": "",
"TLSServerName": "",
"TLSSkipVerify": false,
"TCP": ""
}, },
"CreateIndex": 0, "CreateIndex": 0,
"ModifyIndex": 0 "ModifyIndex": 0
@ -355,61 +517,12 @@ curl localhost:8500/v1/agent/health/service/name/web
} }
``` ```
#### List status of web2 (HTTP 503) #### List status of web1 (HTTP 200)
##### Failure By ID, Text
```shell
curl http://localhost:8500/v1/agent/health/service/id/web2?format=text
critical
```
##### Failure By ID, JSON
In JSON, the output per ID is not an array, but only contains the value
of service.
```shell
curl localhost:8500/v1/agent/health/service/id/web2
```
```json
{
"critical": {
"ID": "web2",
"Service": "web",
"Tags": ["rails"],
"Address": "",
"TaggedAddresses": {
"lan": {
"address": "127.0.0.1",
"port": 8000
},
"wan": {
"address": "198.18.0.53",
"port": 80
}
},
"Meta": null,
"Port": 80,
"EnableTagOverride": false,
"Datacenter": "dc1",
"Connect": {
"Native": false,
"Proxy": null
},
"CreateIndex": 0,
"ModifyIndex": 0
}
}
```
#### List status of web2 (HTTP 200)
##### Success By ID, Text ##### Success By ID, Text
```shell ```shell
curl localhost:8500/v1/agent/health/service/id/web1?format=text $ curl localhost:8500/v1/agent/health/service/id/web1?format=text
passing passing
``` ```
@ -421,49 +534,39 @@ curl localhost:8500/v1/agent/health/service/id/web1
```json ```json
{ {
"passing": { "AggregatedStatus": "passing",
"Service": {
"ID": "web1", "ID": "web1",
"Service": "web", "Service": "web",
"Tags": ["rails"], "Tags": [
"rails"
],
"Meta": {},
"Port": 80,
"Address": "", "Address": "",
"SocketPath": "",
"TaggedAddresses": { "TaggedAddresses": {
"lan": { "lan": {
"address": "127.0.0.1", "Address": "127.0.0.1",
"port": 8000 "Port": 8000
}, },
"wan": { "wan": {
"address": "198.18.0.53", "Address": "198.51.100.53",
"port": 80 "Port": 80
} }
}, },
"Meta": null, "Weights": {
"Port": 80, "Passing": 1,
"Warning": 1
},
"EnableTagOverride": false, "EnableTagOverride": false,
"Datacenter": "dc1", "Namespace": "default",
"Connect": { "Datacenter": "dc1"
"Native": false,
"Proxy": null
}, },
"CreateIndex": 0, "Checks": []
"ModifyIndex": 0
}
} }
``` ```
## Get local service health by its ID
Retrieve an aggregated state of service(s) on the local agent by ID.
See:
| Method | Path | Produces |
| ------ | -------------------------------------------------- | ------------------ |
| `GET` | `/agent/health/service/id/:service_id` | `application/json` |
| `GET` | `/agent/health/service/id/:service_id?format=text` | `text/plain` |
Parameters and response format are the same as
[`/v1/agent/health/service/name/:service_name`](/api/agent/service#get-local-service-health).
## Register Service ## Register Service
This endpoint adds a new service, with optional health checks, to the local This endpoint adds a new service, with optional health checks, to the local
@ -523,6 +626,12 @@ service definition keys for compatibility with the config file format.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata - `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the service instance. linked to the service instance.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
which to register the service. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
- `Port` `(int: 0)` - Specifies the port of the service. - `Port` `(int: 0)` - Specifies the port of the service.
- `Kind` `(string: "")` - The kind of service. Defaults to "" which is a - `Kind` `(string: "")` - The kind of service. Defaults to "" which is a
@ -660,7 +769,13 @@ The table below shows this endpoint's support for
### Parameters ### Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to - `service_id` `(string: <required>)` - Specifies the ID of the service to
deregister. This is specified as part of the URL. deregister. This is specifi### Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which
to deregister the service. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -700,6 +815,12 @@ The table below shows this endpoint's support for
maintenance mode. This is specified as part of the URL as a query string maintenance mode. This is specified as part of the URL as a query string
parameter. parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace
of the service to place into maintenance mode. This value can be specified as
the `ns` URL query parameter or the `X-Consul-Namespace` header. If not provided
by either, the namespace will be inherited from the request's ACL token or will
default to the `default` namespace. Added in Consul 1.7.0.
- `reason` `(string: "")` - Specifies a text string explaining the reason for - `reason` `(string: "")` - Specifies a text string explaining the reason for
placing the node into maintenance mode. This is simply to aid human operators. placing the node into maintenance mode. This is simply to aid human operators.
If no reason is provided, a default value will be used instead. This is If no reason is provided, a default value will be used instead. This is