docs: Add namespace parameters to /agent/service*

Document supported namespace parameters for /agent/service* API
endpoints.

Resolves #9710
This commit is contained in:
Blake Covarrubias 2021-06-21 22:47:03 -07:00
parent 9a84fe7864
commit 963981bc11
1 changed files with 46 additions and 3 deletions

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:
@ -523,6 +548,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 +691,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 +737,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