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

Merge pull request #13006 from hashicorp/docs/http-api-breakout-path-parameters 

HTTP API Docs: Separate path parameters from query parameters
This commit is contained in:
Jared Kirschner 2022-05-25 18:20:40 -04:00 committed by GitHub
parent e5f1d8dce4 daf5e3ea10
commit 13e2c81451
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 1039 additions and 932 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
website/content/api-docs/acl/auth-methods.mdx
View File

@ -36,7 +36,12 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl auth-method create`](/commands/acl/auth-method/create). The corresponding CLI command is [`consul acl auth-method create`](/commands/acl/auth-method/create).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you create.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Name` `(string: <required>)` - Specifies a name for the ACL auth method. The - `Name` `(string: <required>)` - Specifies a name for the ACL auth method. The
name can contain alphanumeric characters, dashes `-`, and underscores `_`. name can contain alphanumeric characters, dashes `-`, and underscores `_`.
@ -71,11 +76,9 @@ The corresponding CLI command is [`consul acl auth-method create`](/commands/acl
For more information on configuring specific auth method types, see the [auth For more information on configuring specific auth method types, see the [auth
method documentation](/docs/security/acl/auth-methods). method documentation](/docs/security/acl/auth-methods).
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
create the auth method within. If not provided in the JSON body, the value of the auth method you create. This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, the namespace will be inherited from the request's ACL
token or will default to the `default` namespace. Added in Consul 1.7.0.
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set - `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
of rules that can control which namespace tokens created via this auth method of rules that can control which namespace tokens created via this auth method
@ -164,16 +167,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl auth-method read`](/commands/acl/auth-method/read). The corresponding CLI command is [`consul acl auth-method read`](/commands/acl/auth-method/read).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to - `name` `(string: <required>)` - Specifies the name of the ACL auth method to read.
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
the auth method within. This value can be specified as the `ns` URL query
parameter or in the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -218,11 +219,19 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl auth-method update`](/commands/acl/auth-method/update). The corresponding CLI command is [`consul acl auth-method update`](/commands/acl/auth-method/update).
### Parameters ### Path Parameters
- `Name` `(string: <required>)` - Specifies the name of the auth method to - `name` `(string: <required>)` - Specifies the name of the auth method you update.
update. This is required in the URL path but may also be specified in the
JSON body. If specified in both places then they must match exactly. ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Name` `(string: <optional>)` - If specified, this field must be an exact match
with the `name` path parameter.
- `Type` `(string: <required>)` - Specifies the type of the auth method being - `Type` `(string: <required>)` - Specifies the type of the auth method being
updated. This field is immutable so if present in the body then it must updated. This field is immutable so if present in the body then it must
@ -255,10 +264,8 @@ The corresponding CLI command is [`consul acl auth-method update`](/commands/acl
method documentation](/docs/security/acl/auth-methods). method documentation](/docs/security/acl/auth-methods).
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the auth method to update. If not provided in the JSON body, the value of the auth method you update. This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, the namespace will be inherited from the request's ACL
token or will default to the `default` namespace. Added in Consul 1.7.0.
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set - `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
of rules that can control which namespace tokens created via this auth method of rules that can control which namespace tokens created via this auth method
@ -351,16 +358,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl auth-method delete`](/commands/acl/auth-method/delete). The corresponding CLI command is [`consul acl auth-method delete`](/commands/acl/auth-method/delete).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to - `name` `(string: <required>)` - Specifies the name of the ACL auth method to delete.
delete. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the ### Query Parameters
Auth Method to delete. This value can be specified as the `ns` URL query
parameter or in the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you delete.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -395,14 +400,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl auth-method list`](/commands/acl/auth-method/list). The corresponding CLI command is [`consul acl auth-method list`](/commands/acl/auth-method/list).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list - `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the auth methods in the specified namespace.
the auth methods for. This value can be specified as the `ns` URL query The namespace may be specified as '\*' to return results for all namespaces.
parameter or in the `X-Consul-Namespace` header. If not provided by either, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. The namespace may be specified as '\*' and then The namespace may be specified as '\*' and then
results will be returned for all namespaces. Added in Consul 1.7.0. results will be returned for all namespaces.
## Sample Request ## Sample Request
@ -433,3 +438,15 @@ listing and must be retrieved by the [auth method reading endpoint](#read-an-aut
} }
] ]
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
Auth method create, read, update, and delete endpoints
support several methods for specifying the namespace of the auth method resource.
When multiple methods are used, namespace precedence occurs in the following order:
1. `Namespace` field of the JSON request body -
only applies to [create](#create-an-auth-method) and [update](#update-an-auth-method) endpoints
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

90
website/content/api-docs/acl/binding-rules.mdx
View File

@ -36,7 +36,12 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl binding-rule create`](/commands/acl/binding-rule/create). The corresponding CLI command is [`consul acl binding-rule create`](/commands/acl/binding-rule/create).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you create.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Description` `(string: "")` - Free form human readable description of the binding rule. - `Description` `(string: "")` - Free form human readable description of the binding rule.
@ -99,11 +104,9 @@ The corresponding CLI command is [`consul acl binding-rule create`](/commands/ac
prefixed-${serviceaccount.name} prefixed-${serviceaccount.name}
``` ```
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you create.
create the binding rule. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -162,16 +165,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl binding-rule read`](/commands/acl/binding-rule/read). The corresponding CLI command is [`consul acl binding-rule read`](/commands/acl/binding-rule/read).
### Parameters ### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule - `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to read.
to read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
the binding rule. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -214,11 +215,19 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl binding-rule update`](/commands/acl/binding-rule/update). The corresponding CLI command is [`consul acl binding-rule update`](/commands/acl/binding-rule/update).
### Parameters ### Path Parameters
- `ID` `(string: <required>)` - Specifies the ID of the binding rule to update. - `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule you update.
This is required in the URL path but may also be specified in the JSON body.
If specified in both places then they must match exactly. ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `ID` `(string: <optional>)` - If specified, this field must be an exact match
with the `id` path parameter.
- `Description` `(string: "")` - Free form human readable description of the binding rule. - `Description` `(string: "")` - Free form human readable description of the binding rule.
@ -283,11 +292,9 @@ The corresponding CLI command is [`consul acl binding-rule update`](/commands/ac
prefixed-${serviceaccount.name} prefixed-${serviceaccount.name}
``` ```
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you update.
the binding rule to update. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -346,16 +353,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl binding-rule delete`](/commands/acl/binding-rule/delete). The corresponding CLI command is [`consul acl binding-rule delete`](/commands/acl/binding-rule/delete).
### Parameters ### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to - `id` `(string: <required>)` - Specifies the UUID of the binding rule you delete.
delete. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the ### Query Parameters
binding rule to delete. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you delete.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -390,17 +395,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl binding-rule list`](/commands/acl/binding-rule/list). The corresponding CLI command is [`consul acl binding-rule list`](/commands/acl/binding-rule/list).
## Parameters ## Query Parameters
- `authmethod` `(string: "")` - Filters the binding rule list to those binding - `authmethod` `(string: "")` - Filters the binding rule list to those binding
rules that are linked with the specific named auth method. rules that are linked with the specific named auth method.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list - `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the binding rules in the specified namespace.
the binding rules for. This value can be specified as the `ns` URL query The namespace may be specified as '\*' to return results for all namespaces.
parameter or the `X-Consul-Namespace` header. If not provided by either, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. The namespace may be specified as '\*' and then
results will be returned for all namespaces. Added in Consul 1.7.0.
## Sample Request ## Sample Request
@ -433,3 +435,15 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rules
} }
] ]
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
Binding rule create, read, update, and delete endpoints
support several methods for specifying the namespace of the auth method resource
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to [create](#create-a-binding-rule) and [update](#update-a-binding-rule) endpoints
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

63
website/content/api-docs/acl/index.mdx
View File

@ -105,11 +105,10 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `consistent` | `none` | `none` | | `NO` | `consistent` | `none` | `none` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Request ### Sample Request
@ -302,7 +301,12 @@ replication enabled.
The corresponding CLI command is [`consul login`](/commands/login). The corresponding CLI command is [`consul login`](/commands/login).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login. - `AuthMethod` `(string: <required>)` - The name of the auth method to use for login.
@ -314,11 +318,9 @@ The corresponding CLI command is [`consul login`](/commands/login).
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata - `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the token. Can be useful to track origins. linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
the Auth Method to use for Login. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -430,7 +432,12 @@ enabled. Login requires the ability to create local tokens which is restricted
to the primary datacenter and any secondary datacenters with ACL token to the primary datacenter and any secondary datacenters with ACL token
replication enabled. replication enabled.
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for - `AuthMethod` `(string: <required>)` - The name of the auth method to use for
login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc). login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc).
@ -444,11 +451,9 @@ replication enabled.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata - `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the token. Can be useful to track origins. linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
the Auth Method to use for Login. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, the namespace will be inherited from the request's ACL
token, or will default to the `default` namespace.
This must match the namespace provided on the [OIDC Callback](#oidc-callback). This must match the namespace provided on the [OIDC Callback](#oidc-callback).
@ -510,7 +515,12 @@ enabled. Login requires the ability to create local tokens which is restricted
to the primary datacenter and any secondary datacenters with ACL token to the primary datacenter and any secondary datacenters with ACL token
replication enabled. replication enabled.
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for - `AuthMethod` `(string: <required>)` - The name of the auth method to use for
login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc). login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc).
@ -528,13 +538,9 @@ replication enabled.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata - `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the token. Can be useful to track origins. linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
the Auth Method to use for Login. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, the namespace will be inherited from the request's ACL
token, or will default to the `default` namespace.
This must match the namespace provided on the [OIDC Callback](#oidc-callback).
### Sample Payload ### Sample Payload
@ -581,3 +587,14 @@ $ curl \
"ModifyIndex": 36 "ModifyIndex": 36
} }
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
Some ACL endpoints support several methods for specifying the namespace of the resource
with the following order of precedence:
1. Namespace` field of the JSON request body -
only applies to endpoints that accept an JSON request body
1. ns` query parameter
1. X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

104
website/content/api-docs/acl/policies.mdx
View File

@ -35,7 +35,12 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl policy create`](/commands/acl/policy/create). The corresponding CLI command is [`consul acl policy create`](/commands/acl/policy/create).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you create.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name - `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name
can contain alphanumeric characters, dashes `-`, and underscores `_`. can contain alphanumeric characters, dashes `-`, and underscores `_`.
@ -50,11 +55,9 @@ The corresponding CLI command is [`consul acl policy create`](/commands/acl/poli
When no datacenters are provided the policy is valid in all datacenters including When no datacenters are provided the policy is valid in all datacenters including
those which do not yet exist but may in the future. those which do not yet exist but may in the future.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you create.
create the policy. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -110,16 +113,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl policy read`](/commands/acl/policy/read). The corresponding CLI command is [`consul acl policy read`](/commands/acl/policy/read).
### Parameters ### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to - `id` `(string: <required>)` - Specifies the UUID of the policy you lookup.
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
the policy. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -162,16 +163,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl policy read -name=<string>`](/commands/acl/policy/read#name). The corresponding CLI command is [`consul acl policy read -name=<string>`](/commands/acl/policy/read#name).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL policy to - `name` `(string: <required>)` - Specifies the name of the ACL policy to read.
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
the policy. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -214,11 +213,19 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl policy update`](/commands/acl/policy/update). The corresponding CLI command is [`consul acl policy update`](/commands/acl/policy/update).
### Parameters ### Path Parameters
- `ID` `(string: <required>)` - Specifies the UUID of the policy to update. This is - `id` `(string: <required>)` - Specifies the UUID of the policy you update.
required in the URL path but may also be specified in the JSON body. If specified
in both places then they must match exactly. ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `ID` `(string: <optional>)` - If specified, this field must be an exact match
with the `id` path parameter.
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name - `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name
can only contain alphanumeric characters as well as `-` and `_` and must be can only contain alphanumeric characters as well as `-` and `_` and must be
@ -233,11 +240,9 @@ The corresponding CLI command is [`consul acl policy update`](/commands/acl/poli
When no datacenters are provided the policy is valid in all datacenters including When no datacenters are provided the policy is valid in all datacenters including
those which do not yet exist but may in the future. those which do not yet exist but may in the future.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you update.
the policy to update. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -295,16 +300,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl policy delete`](/commands/acl/policy/delete). The corresponding CLI command is [`consul acl policy delete`](/commands/acl/policy/delete).
### Parameters ### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to - `id` `(string: <required>)` - Specifies the UUID of the policy you delete.
delete. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the ### Query Parameters
policy to delete. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you delete.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -339,14 +342,11 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl policy list`](/commands/acl/policy/list). The corresponding CLI command is [`consul acl policy list`](/commands/acl/policy/list).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list - `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the auth methods in the specified namespace.
the Policies for. This value can be specified as the `ns` URL query The namespace may be specified as '\*' to return results for all namespaces.
parameter or the `X-Consul-Namespace` header. If not provided by either, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. The namespace may be specified as '\*' and then
results will be returned for all namespaces. Added in Consul 1.7.0.
## Sample Request ## Sample Request
@ -381,3 +381,15 @@ retrieved by the [policy reading endpoint](#read-a-policy)
} }
] ]
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
ACL policy endpoints
support several methods for specifying the namespace of the ACL policy resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to [create](#create-a-policy) and [update](#update-a-policy) endpoints
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

109
website/content/api-docs/acl/roles.mdx
View File

@ -34,11 +34,17 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl role create`](/commands/acl/role/create). The corresponding CLI command is [`consul acl role create`](/commands/acl/role/create).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you create.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name - `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
can contain alphanumeric characters, dashes `-`, and underscores `_`. can contain alphanumeric characters, dashes `-`, and underscores `_`.
This name must be unique. This name must be unique.
- `Description` `(string: "")` - Free form human readable description of the role. - `Description` `(string: "")` - Free form human readable description of the role.
- `Policies` `(array<PolicyLink>)` - The list of policies that should be - `Policies` `(array<PolicyLink>)` - The list of policies that should be
@ -75,11 +81,9 @@ The corresponding CLI command is [`consul acl role create`](/commands/acl/role/c
- `Datacenter` `(string: <required>)` - Specifies the nodes datacenter. This - `Datacenter` `(string: <required>)` - Specifies the nodes datacenter. This
will result in effective policy only being valid in that datacenter. will result in effective policy only being valid in that datacenter.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you create.
create the role. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -176,16 +180,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl role read`](/commands/acl/role/read). The corresponding CLI command is [`consul acl role read`](/commands/acl/role/read).
### Parameters ### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to - `id` `(string: <required>)` - Specifies the UUID of the role you lookup.
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
the role. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -248,16 +250,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl role read -name=<string>`](/commands/acl/role/read#name). The corresponding CLI command is [`consul acl role read -name=<string>`](/commands/acl/role/read#name).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the Name of the ACL role to - `name` `(string: <required>)` - Specifies the name of the ACL role to read.
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
the role. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -319,11 +319,19 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl role update`](/commands/acl/role/update). The corresponding CLI command is [`consul acl role update`](/commands/acl/role/update).
### Parameters ### Path Parameters
- `ID` `(string: <required>)` - Specifies the ID of the role to update. This is - `id` `(string: <required>)` - Specifies the UUID of the role you update.
required in the URL path but may also be specified in the JSON body. If specified
in both places then they must match exactly. ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `ID` `(string: <optional>)` - If specified, this field must be an exact match
with the `id` path parameter.
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name - `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
can only contain alphanumeric characters as well as `-` and `_` and must be can only contain alphanumeric characters as well as `-` and `_` and must be
@ -346,11 +354,9 @@ The corresponding CLI command is [`consul acl role update`](/commands/acl/role/u
identities](/docs/security/acl#node-identities) that should be identities](/docs/security/acl#node-identities) that should be
applied to the role. Added in Consul 1.8.1. applied to the role. Added in Consul 1.8.1.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you update.
the role to update. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -437,16 +443,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl role delete`](/commands/acl/role/delete). The corresponding CLI command is [`consul acl role delete`](/commands/acl/role/delete).
### Parameters ### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to - `id` `(string: <required>)` - Specifies the UUID of the role you delete.
delete. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the ### Query Parameters
role to delete. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you delete.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -481,19 +485,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl role list`](/commands/acl/role/list). The corresponding CLI command is [`consul acl role list`](/commands/acl/role/list).
## Parameters ### Query Parameters
- `policy` `(string: "")` - Filters the role list to those roles that are - `policy` `(string: "")` - Filters the role list to those roles that are
linked with the specific policy ID. linked with this specific policy ID.
### Parameters - `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the roles in the specified namespace.
The namespace may be specified as '\*' to return results for all namespaces.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list You can also [specify the namespace through other methods](#methods-to-specify-namespace).
the roles for. 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. The namespace may be specified as '\*' and then
results will be returned for all namespaces. Added in Consul 1.7.0.
## Sample Request ## Sample Request
@ -550,3 +549,15 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/roles
} }
] ]
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
ACL role endpoints
support several methods for specifying the namespace of the ACL role resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to [create](#create-a-role) and [update](#update-a-role) endpoints
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

126
website/content/api-docs/acl/tokens.mdx
View File

@ -34,7 +34,12 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl token create`](/commands/acl/token/create). The corresponding CLI command is [`consul acl token create`](/commands/acl/token/create).
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you create.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `AccessorID` `(string: "")` - Specifies a UUID to use as the token's Accessor ID. - `AccessorID` `(string: "")` - Specifies a UUID to use as the token's Accessor ID.
If not specified a UUID will be generated for this field. Added in v1.5.0. If not specified a UUID will be generated for this field. Added in v1.5.0.
@ -101,11 +106,9 @@ The corresponding CLI command is [`consul acl token create`](/commands/acl/token
respectively). This value must be no smaller than 1 minute and no longer than respectively). This value must be no smaller than 1 minute and no longer than
24 hours. Added in Consul 1.5.0. 24 hours. Added in Consul 1.5.0.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you create.
create the token. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -177,16 +180,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl token read`](/commands/acl/token/read). The corresponding CLI command is [`consul acl token read`](/commands/acl/token/read).
### Parameters ### Path Parameters
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to - `AccessorID` `(string: <required>)` - Specifies the accessor ID of the token you lookup.
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
the token. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
- `expanded` `(bool: false)` - If this field is set, the contents of all policies and - `expanded` `(bool: false)` - If this field is set, the contents of all policies and
roles affecting the token will also be returned. roles affecting the token will also be returned.
@ -390,11 +391,21 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl token update`](/commands/acl/token/update). The corresponding CLI command is [`consul acl token update`](/commands/acl/token/update).
### Parameters ### Path Parameters
- `AccessorID` `(string: "")` - Specifies the accessor ID of the token being updated. This is - `AccessorID` `(string: <required>)` - Specifies the accessor ID of the token you update.
required in the URL path but may also be specified in the JSON body. If specified
in both places then they must match exactly. This field is immutable. If not present in ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `AccessorID` `(string: "")` - Specifies the accessor ID of the token being updated.
This field is required in the URL path but may also be specified in the JSON body.
If specified in both places then they must be an exact match.
This field is immutable. If not present in
the body and only in the URL then it will be filled in by Consul. the body and only in the URL then it will be filled in by Consul.
- `SecretID` `(string: "")` - Specifies the secret ID of the token being updated. This field is - `SecretID` `(string: "")` - Specifies the secret ID of the token being updated. This field is
@ -457,11 +468,9 @@ The corresponding CLI command is [`consul acl token update`](/commands/acl/token
match the existing value. If not present then the value will be filled in by match the existing value. If not present then the value will be filled in by
Consul. Consul.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you update.
the token to update. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -540,18 +549,22 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl token clone`](/commands/acl/token/clone). The corresponding CLI command is [`consul acl token clone`](/commands/acl/token/clone).
### Parameters ### Path Parameters
- `AccessorID` `(string: <required>)` - The accessor ID of the token to clone. This is required - `AccessorID` `(string: <required>)` - The accessor ID of the token to clone.
in the URL path
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you clone.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Description` `(string: "")` - Free form human readable description for the cloned token. - `Description` `(string: "")` - Free form human readable description for the cloned token.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you clone.
the token to be cloned. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -621,16 +634,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl token delete`](/commands/acl/token/delete). The corresponding CLI command is [`consul acl token delete`](/commands/acl/token/delete).
### Parameters ### Path Parameters
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to - `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to delete.
delete. This is required and is specified as part of the URL path.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the ### Query Parameters
token to delete. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you delete.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -665,29 +676,24 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl token list`](/commands/acl/token/list). The corresponding CLI command is [`consul acl token list`](/commands/acl/token/list).
## Parameters ## Query Parameters
- `policy` `(string: "")` - Filters the token list to those tokens that are - `policy` `(string: "")` - Filters the token list to those tokens that are
linked with the specific policy ID. linked with this specific policy ID.
- `role` `(string: "")` - Filters the token list to those tokens that are - `role` `(string: "")` - Filters the token list to those tokens that are
linked with the specific role ID. linked with this specific role ID.
- `authmethod` `(string: "")` - Filters the token list to those tokens that are - `authmethod` `(string: "")` - Filters the token list to those tokens that are
linked with the specific named auth method. linked with this specific named auth method.
- `authmethod-ns` `(string: "")` <EnterpriseAlert inline /> - Specifics the namespace - `authmethod-ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
of the `authmethod` being used for token lookup. If not provided, the namespace `authmethod` used for token lookup. If not provided, the namespace
provided by the `ns` parameter will be used. If neither of those is provided provided by the `ns` parameter or [through other methods](#methods-to-specify-namespace) will be used.
then the namespace will be inherited from the request's ACL token. Added in
Consul 1.7.0.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list - `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the tokens in the specified namespace.
the tokens for. This value can be specified as the `ns` URL query The namespace may be specified as '\*' to return results for all namespaces.
parameter or the `X-Consul-Namespace` header. If not provided by either, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. The namespace may be specified as '\*' and then
results will be returned for all namespaces. Added in Consul 1.7.0.
## Sample Request ## Sample Request
@ -754,3 +760,15 @@ for reading other secrets which given even more permissions.
} }
] ]
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
ACL token endpoints
support several methods for specifying the namespace of the ACL token resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to [create](#create-a-token) and [update](#update-a-token) endpoints
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

30
website/content/api-docs/admin-partitions.mdx
View File

@ -31,9 +31,9 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul partition create`](/commands/partition#create). The corresponding CLI command is [`consul partition create`](/commands/partition#create).
### Parameters ### JSON Request Body Schema
- `Name` `(string: <required>)` - The partition name. This must be a valid - `Name` `(string: <required>)` - The partition name. This field must be a valid
DNS hostname label. DNS hostname label.
- `Description` `(string: "")` - Free form partition description. - `Description` `(string: "")` - Free form partition description.
@ -56,7 +56,7 @@ $ curl ---request PUT \
http://127.0.0.1:8500/v1/partition http://127.0.0.1:8500/v1/partition
``` ```
### SampleResponse ### Sample Response
```json ```json
{ {
@ -89,10 +89,9 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul partition read`](/commands/partition#read). The corresponding CLI command is [`consul partition read`](/commands/partition#read).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the partition to read. This - `name` `(string: <required>)` - Specifies the partition to read.
is required and is specified as part of the URL path.
### Sample Request ### Sample Request
@ -132,11 +131,15 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul partition write`](/commands/partition#write). The corresponding CLI command is [`consul partition write`](/commands/partition#write).
### Parameters ### Path Parameters
- `Name` `(string: <optional>)` - The partition name. This must be a valid - `name` `(string: <required>)` - Specifies the partition to update.
DNS hostname label. If present in the payload it must match what was given This parameter must be a valid DNS hostname label.
in the URL path.
### JSON Request Body Schema
- `Name` `(string: <optional>)` - If specified, this field must be an exact match
with the `name` path parameter.
- `Description` `(string: "")` - Free form partition description. - `Description` `(string: "")` - Free form partition description.
@ -157,7 +160,7 @@ $ curl --request PUT \
http://127.0.0.1:8500/v1/partition/na-west http://127.0.0.1:8500/v1/partition/na-west
``` ```
### SampleResponse ### Sample Response
```json ```json
{ {
@ -196,10 +199,9 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul partition delete`](/commands/partition#delete). The corresponding CLI command is [`consul partition delete`](/commands/partition#delete).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the partition to delete. This - `name` `(string: <required>)` - Specifies the partition to delete.
is required and is specified as part of the URL path.
### Sample Request ### Sample Request

113
website/content/api-docs/agent/check.mdx
View File

@ -37,16 +37,13 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------ | | ---------------- | ----------------- | ------------- | ------------------------ |
| `NO` | `none` | `none` | `node:read,service:read` | | `NO` | `none` | `none` | `node:read,service:read` |
### Parameters ### Query Parameters
- `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 - `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the checks in the specified namespace.
which to list checks. This value can be specified as the `ns` URL query You can also [specify the namespace through other methods](#methods-to-specify-namespace).
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
@ -118,7 +115,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you register.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Name` `(string: <required>)` - Specifies the name of the check. - `Name` `(string: <required>)` - Specifies the name of the check.
@ -126,12 +128,9 @@ The table below shows this endpoint's support for
This defaults to the `"Name"` parameter, but it may be necessary to provide an This defaults to the `"Name"` parameter, but it may be necessary to provide an
ID for uniqueness. This value will return in the response as `"CheckId"`. ID for uniqueness. This value will return in the response as `"CheckId"`.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you register.
which to register the check. This parameter is only valid for service checks. This field takes precedence over the `ns` query parameter,
If not provided in the JSON body, the value of the `ns` URL query parameter or one of several [other methods to specify the namespace](#methods-to-specify-namespace).
in the `X-Consul-Namespace` header will be used. 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.
- `Interval` `(string: "")` - Specifies the frequency at which to run this - `Interval` `(string: "")` - Specifies the frequency at which to run this
check. This is required for HTTP and TCP checks. check. This is required for HTTP and TCP checks.
@ -313,16 +312,16 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
deregister. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in ### Path Parameters
which to deregister the check. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either, - `check_id` `(string: "")` - Specifies the unique ID of the check to deregister.
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0. ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you deregister.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request ### Sample Request
@ -351,19 +350,17 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters ### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to - `check_id` `(string: "")` - Specifies the unique ID of the check to use.
use. This is specified as part of the URL.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be - `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field. passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
which to update the check. This value can be specified as the `ns` URL query You can also [specify the namespace through other methods](#methods-to-specify-namespace).
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
@ -392,19 +389,17 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters ### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to - `check_id` `(string: "")` - Specifies the unique ID of the check to use.
use. This is specified as part of the URL.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be - `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field. passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
which to update the check. This value can be specified as the `ns` URL query You can also [specify the namespace through other methods](#methods-to-specify-namespace).
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
@ -432,19 +427,17 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters ### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to - `check_id` `(string: "")` - Specifies the unique ID of the check to use.
use. This is specified as part of the URL.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be - `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field. passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
which to update the check. This value can be specified as the `ns` URL query You can also [specify the namespace through other methods](#methods-to-specify-namespace).
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
@ -472,10 +465,16 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters ### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to - `check_id` `(string: "")` - Specifies the unique ID of the check to use.
use. This is specified as part of the URL.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Status` `(string: "")` - Specifies the status of the check. Valid values are - `Status` `(string: "")` - Specifies the status of the check. Valid values are
`"passing"`, `"warning"`, and `"critical"`. `"passing"`, `"warning"`, and `"critical"`.
@ -483,11 +482,7 @@ The table below shows this endpoint's support for
- `Output` `(string: "")` - Specifies a human-readable message. This will be - `Output` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field. passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in <!-- Are we missing a Namespace field here? -->
which to update the check. 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 Payload ### Sample Payload
@ -506,3 +501,15 @@ $ curl \
--data @payload.json \ --data @payload.json \
http://127.0.0.1:8500/v1/agent/check/update/my-check-id http://127.0.0.1:8500/v1/agent/check/update/my-check-id
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
Local agent health check endpoints
support several methods for specifying the namespace of the check resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to the [register](#register-check) endpoint
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

41
website/content/api-docs/agent/connect.mdx
View File

@ -52,7 +52,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | -------------------- | --------------- | | ---------------- | ----------------- | -------------------- | --------------- |
| `NO` | `none` | `background refresh` | `service:write` | | `NO` | `none` | `background refresh` | `service:write` |
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the target service.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Target` `(string: <required>)` - The name of the service that is being - `Target` `(string: <required>)` - The name of the service that is being
requested. requested.
@ -65,10 +70,8 @@ The table below shows this endpoint's support for
number for the requesting client cert. number for the requesting client cert.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the target service. If not provided in the JSON body, the value of the target service. This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, 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 Payload ### Sample Payload
@ -192,17 +195,15 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | -------------------- | --------------- | | ---------------- | ----------------- | -------------------- | --------------- |
| `YES` | `all` | `background refresh` | `service:write` | | `YES` | `all` | `background refresh` | `service:write` |
### Parameters ### Path Parameters
- `Service` `(string: <required>)` - The name of the service for the leaf - `service` `(string: <required>)` - The name of the service for the leaf certificate.
certificate. This is specified in the URL. The service does not need to The service does not need to exist in the catalog, but the proper ACL permissions must be available.
exist in the catalog, but the proper ACL permissions must be available.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in ### Query Parameters
which to request the leaf certificate. This value can be specified as the `ns`
URL query parameter or the `X-Consul-Namespace` header. If not provided by either, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the leaf certificate you request.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -244,3 +245,15 @@ $ curl \
- `ValidBefore` `(string)` - The time before which the certificate is valid. - `ValidBefore` `(string)` - The time before which the certificate is valid.
Used with `ValidAfter` this can determine the validity period of the certificate. Used with `ValidAfter` this can determine the validity period of the certificate.
## Methods to Specify Namespace <EnterpriseAlert inline />
Local agent connect endpoints
support several methods for specifying the namespace of resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to the [register](#register-check) endpoint
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

48
website/content/api-docs/agent/index.mdx
View File

@ -231,11 +231,11 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul members`](/commands/members). The corresponding CLI command is [`consul members`](/commands/members).
### Parameters ### Query Parameters
- `wan` `(bool: false)` - Specifies to list WAN members instead of the LAN - `wan` `(bool: false)` - Specifies to list WAN members instead of the LAN
members (which is the default). This is only eligible for agents running in members (which is the default). This is only eligible for agents running in
**server mode**. This is specified as part of the URL as a query parameter. **server mode**.
- `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for. - `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for.
If left blank, this will query for the default segment when connecting to a server and If left blank, this will query for the default segment when connecting to a server and
@ -412,17 +412,15 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul maint`](/commands/maint). The corresponding CLI command is [`consul maint`](/commands/maint).
### Parameters ### Query Parameters
- `enable` `(bool: <required>)` - Specifies whether to enable or disable - `enable` `(bool: <required>)` - Specifies whether to enable or disable
maintenance mode. This is specified as part of the URL as a query string maintenance mode.
parameter.
- `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 is used instead.
specified as part of the URL as a query string parameter, and, as such, must This parameter must be URI-encoded.
be URI-encoded.
### Sample Request ### Sample Request
@ -593,10 +591,11 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `agent:read` | | `NO` | `none` | `none` | `agent:read` |
### Parameters ### Query Parameters
- `loglevel` `(string: "info")` - Specifies a text string containing a log level - `loglevel` `(string: "info")` - Specifies a text string containing a log level
to filter on, such as `info`. to filter on, such as `info`.
- `logjson` `(bool: false)` - Specifies whether the logs will be output in JSON - `logjson` `(bool: false)` - Specifies whether the logs will be output in JSON
format. format.
@ -639,14 +638,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul join`](/commands/join). The corresponding CLI command is [`consul join`](/commands/join).
### Parameters ### Path Parameters
- `address` `(string: <required>)` - Specifies the address of the other agent to - `address` `(string: <required>)` - Specifies the address of the other agent to join.
join. This is specified as part of the URL.
### Query Parameters
- `wan` `(bool: false)` - Specifies to try and join over the WAN pool. This is - `wan` `(bool: false)` - Specifies to try and join over the WAN pool. This is
only optional for agents running in server mode. This is specified as part of only optional for agents running in server mode.
the URL as a query parameter
### Sample Request ### Sample Request
@ -698,15 +697,15 @@ belonging to that node will not be cleaned up. Forcing a node into the `left`
state allows its old entries to be removed. state allows its old entries to be removed.
| Method | Path | Produces | | Method | Path | Produces |
| ------ | -------------------------- | ------------------ | | ------ | ------------------------------- | ------------------ |
| `PUT` | `/agent/force-leave/:node` | `application/json` | | `PUT` | `/agent/force-leave/:node_name` | `application/json` |
Additionally, by specifying the `prune` flag, a node can be forcibly removed from Additionally, by specifying the `prune` flag, a node can be forcibly removed from
the list of members entirely. the list of members entirely.
| Method | Path | Produces | | Method | Path | Produces |
| ------ | -------------------------------- | ------------------ | | ------ | ------------------------------------- | ------------------ |
| `PUT` | `/agent/force-leave/:node?prune` | `application/json` | | `PUT` | `/agent/force-leave/:node_name?prune` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking), [blocking queries](/api-docs/features/blocking),
@ -720,17 +719,18 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul force-leave`](/commands/force-leave). The corresponding CLI command is [`consul force-leave`](/commands/force-leave).
### Parameters ### Path Parameters
- `node` `(string: <required>)` - Specifies the name of the node to be forced into `left` state. This is specified as part of the URL. - `node_name` `(string: <required>)` - Specifies the name of the node to be forced into `left` state.
### Query Parameters
- `prune` `(bool: false)` - Specifies whether to forcibly remove the node from the list of members. - `prune` `(bool: false)` - Specifies whether to forcibly remove the node from the list of members.
Pruning a node in the `left` or `failed` state removes it from the list altogether. Pruning a node in the `left` or `failed` state removes it from the list altogether.
This is specified as part of the URL as a query parameter. Added in Consul 1.6.2. Added in Consul 1.6.2.
- `wan` `(bool: false)` - Specifies the node should only be removed from the WAN - `wan` `(bool: false)` - Specifies the node should only be removed from the WAN
gossip pool. This is specified as part of the URL as a query parameter. Added gossip pool. Added in Consul 1.11.0.
in Consul 1.11.0.
### Sample Request ### Sample Request
@ -796,7 +796,7 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul acl set-agent-token`](/commands/acl/set-agent-token). The corresponding CLI command is [`consul acl set-agent-token`](/commands/acl/set-agent-token).
### Parameters ### JSON Request Body Schema
- `Token` `(string: "")` - Specifies the ACL token to set. - `Token` `(string: "")` - Specifies the ACL token to set.

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

@ -39,16 +39,13 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- | | ---------------- | ----------------- | ------------- | -------------- |
| `NO` | `none` | `none` | `service:read` | | `NO` | `none` | `none` | `service:read` |
### Parameters ### Query Parameters
- `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 - `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the services in the specified namespace.
to list services. This value can be specified as the `ns` URL query You can also [specify the namespace through other methods](#methods-to-specify-namespace).
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
@ -162,16 +159,14 @@ The table below shows this endpoint's support for
hash-based blocking hash-based blocking
</a> only. </a> only.
### Parameters ### Path Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to - `service_id` `(string: <required>)` - Specifies the ID of the service to fetch.
fetch. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup ### Query Parameters
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, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you lookup.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -262,17 +257,6 @@ 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:
@ -299,6 +283,15 @@ 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.
### Path Parameters
- `service_name` `(string: <required>)` - Specifies the name of the service to retrieve.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Requests ### Sample Requests
Given 2 services with name `web`, with web2 critical and web1 passing: Given 2 services with name `web`, with web2 critical and web1 passing:
@ -597,11 +590,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul services register`](/commands/services/register). The corresponding CLI command is [`consul services register`](/commands/services/register).
### Query string parameters ### Query Parameters
- `replace-existing-checks` - Missing health checks from the request will be deleted from the agent. Using this parameter allows to idempotently register a service and its checks without having to manually deregister checks. - `replace-existing-checks` - Missing health checks from the request will be deleted from the agent. Using this parameter allows to idempotently register a service and its checks without having to manually deregister checks.
### Parameters - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you register.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
Note that this endpoint, unlike most also [supports `snake_case`](/docs/discovery/services#service-definition-parameter-case) Note that this endpoint, unlike most also [supports `snake_case`](/docs/discovery/services#service-definition-parameter-case)
service definition keys for compatibility with the config file format. service definition keys for compatibility with the config file format.
@ -630,11 +626,9 @@ 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 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you register.
which to register the service. This value can be specified as the `ns` URL query This field takes precedence over the `ns` query parameter,
parameter or the `X-Consul-Namespace` header. If not provided by either, one of several [other methods to specify the namespace](#methods-to-specify-namespace).
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.
@ -772,16 +766,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul services deregister`](/commands/services/deregister). The corresponding CLI command is [`consul services deregister`](/commands/services/deregister).
### Parameters ### Path Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to - `service_id` `(string: <required>)` - Specifies the ID of the service to deregister.
deregister. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which ### Query Parameters
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, - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you deregister.
the namespace will be inherited from the request's ACL token or will default You can also [specify the namespace through other methods](#methods-to-specify-namespace).
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -812,26 +804,23 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- | | ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` | | `NO` | `none` | `none` | `service:write` |
### Parameters ### Path Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to put - `service_id` `(string: <required>)` - Specifies the ID of the service to put in maintenance mode.
in maintenance mode. This is specified as part of the URL.
### Query Parameters
- `enable` `(bool: <required>)` - Specifies whether to enable or disable - `enable` `(bool: <required>)` - Specifies whether to enable or disable
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 is used instead.
specified as part of the URL as a query string parameter, and, as such, must This parameter must be URI-encoded.
be URI-encoded.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you place into maintenance mode.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request ### Sample Request
@ -840,3 +829,15 @@ $ curl \
--request PUT \ --request PUT \
http://127.0.0.1:8500/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs http://127.0.0.1:8500/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
Local agent service endpoints
support several methods for specifying the namespace of service resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to the [register](#register-check) endpoint
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

170
website/content/api-docs/catalog.mdx
View File

@ -33,7 +33,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you register.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `ID` `(string: "")` - An optional UUID to assign to the node. This must be a 36-character UUID-formatted string. - `ID` `(string: "")` - An optional UUID to assign to the node. This must be a 36-character UUID-formatted string.
@ -87,13 +92,9 @@ The table below shows this endpoint's support for
already registered. Note, if the parameter is enabled for a node that doesn't already registered. Note, if the parameter is enabled for a node that doesn't
exist, it will still be created. exist, it will still be created.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which the - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you register.
service and checks will be registered. This value may be provided by either the This field takes precedence over the `ns` query parameter,
`ns` URL query parameter or in the `X-Consul-Namespace` header. Additionally, one of several [other methods to specify the namespace](#methods-to-specify-namespace).
the namespace may be provided within the `Service` or `Check` fields but if
present in multiple places, they must all be the same. If not provided,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
It is important to note that `Check` does not have to be provided with `Service` It is important to note that `Check` does not have to be provided with `Service`
and vice versa. A catalog entry can have either, neither, or both. and vice versa. A catalog entry can have either, neither, or both.
@ -184,7 +185,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- | | ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` | | `NO` | `none` | `none` | `node:write,service:write` |
### Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you deregister.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
The behavior of the endpoint depends on what keys are provided. The behavior of the endpoint depends on what keys are provided.
@ -195,16 +201,16 @@ The behavior of the endpoint depends on what keys are provided.
- `Datacenter` `(string: "")` - Specifies the datacenter, which defaults to the - `Datacenter` `(string: "")` - Specifies the datacenter, which defaults to the
agent's datacenter if not provided. agent's datacenter if not provided.
- `CheckID` `(string: "")` - Specifies the ID of the check to remove. - `CheckID` `(string: "")` - Specifies the ID of the check to remove.
- `ServiceID` `(string: "")` - Specifies the ID of the service to remove. The - `ServiceID` `(string: "")` - Specifies the ID of the service to remove. The
service and all associated checks will be removed. service and all associated checks will be removed.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which the - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you deregister.
service and checks will be deregistered. If not provided in the JSON body, the value of This field takes precedence over the `ns` query parameter,
the `ns` URL query parameter or the `X-Consul-Namespace` header will be used. one of several [other methods to specify the namespace](#methods-to-specify-namespace).
If not provided, the namespace will be inherited from the request's ACL You can also specify the namespace in the `Service` or `Check` fields;
token or will default to the `default` namespace. Added in Consul 1.7.0. if namespaces are specified in multiple places, they must all be the same.
### Sample Payloads ### Sample Payloads
@ -303,23 +309,20 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul catalog nodes`](/commands/catalog/nodes). The corresponding CLI command is [`consul catalog nodes`](/commands/catalog/nodes).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query.
the datacenter of the agent being queried. This is specified as part of the This parameter defaults to the datacenter of the agent being queried.
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in - `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as `?near=_agent` uses the agent's node for the sort.
part of the URL as a query parameter.
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Meta` selector instead. - `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Meta` selector instead.
This parameter will be removed in a future version of Consul. This parameter will be removed in a future version of Consul.
Specifies a desired node metadata key/value pair Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is filters the results to nodes with the specified key/value pairs.
specified as part of the URL as a query parameter.
- `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.
@ -402,21 +405,17 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul catalog services`](/commands/catalog/services). The corresponding CLI command is [`consul catalog services`](/commands/catalog/services).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair - `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is filters the results to nodes with the specified key/value pairs.
specified as part of the URL as a query parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
This value may be provided by either the `ns` URL query parameter or in the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
`X-Consul-Namespace` header. If not provided, 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
@ -445,8 +444,8 @@ This endpoint returns the nodes providing a service in a given datacenter.
@include 'http_api_results_filtered_by_acls.mdx' @include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces | | Method | Path | Produces |
| ------ | --------------------------- | ------------------ | | ------ | -------------------------------- | ------------------ |
| `GET` | `/catalog/service/:service` | `application/json` | | `GET` | `/catalog/service/:service_name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking), [blocking queries](/api-docs/features/blocking),
@ -458,40 +457,37 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | -------------------- | ------------------------ | | ---------------- | ----------------- | -------------------- | ------------------------ |
| `YES` | `all` | `background refresh` | `node:read,service:read` | | `YES` | `all` | `background refresh` | `node:read,service:read` |
### Parameters ### Path Parameters
- `service` `(string: <required>)` - Specifies the name of the service for which - `service_name` `(string: <required>)` - Specifies the name of the service for which
to list nodes. This is specified as part of the URL. to list nodes.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `tag` `(string: "")` **Deprecated** - Use `filter` with the `ServiceTags` selector instead. - `tag` `(string: "")` **Deprecated** - Use `filter` with the `ServiceTags` selector instead.
This parameter will be removed in a future version of Consul. This parameter will be removed in a future version of Consul.
Specifies the tag to filter on. This is specified as part of Specifies the tag to filter on.
the URL as a query parameter. Can be used multiple times for additional filtering, Can be used multiple times for additional filtering,
returning only the results that include all of the tag values provided. returning only the results that include all of the tag values provided.
- `near` `(string: "")` - Specifies a node name to sort the node list in - `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as `?near=_agent` uses the agent's node for the sort.
part of the URL as a query parameter.
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `NodeMeta` selector instead. - `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `NodeMeta` selector instead.
This parameter will be removed in a future version of Consul. This parameter will be removed in a future version of Consul.
Specifies a desired node metadata key/value pair Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is filters the results to nodes with the specified key/value pairs.
specified as part of the URL as a query parameter.
- `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 to use for the - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
query. This value may be provided by either the `ns` URL query parameter or in the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
`X-Consul-Namespace` header. If not provided, 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
@ -664,7 +660,7 @@ so this endpoint may be used to filter only the Connect-capable endpoints.
| `GET` | `/catalog/connect/:service` | `application/json` | | `GET` | `/catalog/connect/:service` | `application/json` |
Parameters and response format are the same as Parameters and response format are the same as
[`/catalog/service/:service`](/api-docs/catalog#list-nodes-for-service). [`/catalog/service/:service_name`](/api-docs/catalog#list-nodes-for-service).
## Retrieve Map of Services for a Node ## Retrieve Map of Services for a Node
@ -673,8 +669,8 @@ This endpoint returns the node's registered services.
@include 'http_api_results_filtered_by_acls.mdx' @include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces | | Method | Path | Produces |
| ------ | --------------------- | ------------------ | | ------ | -------------------------- | ------------------ |
| `GET` | `/catalog/node/:node` | `application/json` | | `GET` | `/catalog/node/:node_name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking), [blocking queries](/api-docs/features/blocking),
@ -686,22 +682,20 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------ | | ---------------- | ----------------- | ------------- | ------------------------ |
| `YES` | `all` | `none` | `node:read,service:read` | | `YES` | `all` | `none` | `node:read,service:read` |
### Parameters ### Path Parameters
- `node` `(string: <required>)` - Specifies the name of the node for which - `node_name` `(string: <required>)` - Specifies the name of the node to list services for.
to list services. This is specified as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `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 to list services. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
This value may be provided by either the `ns` URL query parameter or in the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
`X-Consul-Namespace` header. If not provided, 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
@ -804,8 +798,8 @@ This endpoint returns the node's registered services.
@include 'http_api_results_filtered_by_acls.mdx' @include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces | | Method | Path | Produces |
| ------ | ------------------------------ | ------------------ | | ------ | ----------------------------------- | ------------------ |
| `GET` | `/catalog/node-services/:node` | `application/json` | | `GET` | `/catalog/node-services/:node_name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking), [blocking queries](/api-docs/features/blocking),
@ -817,23 +811,21 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------ | | ---------------- | ----------------- | ------------- | ------------------------ |
| `YES` | `all` | `none` | `node:read,service:read` | | `YES` | `all` | `none` | `node:read,service:read` |
### Parameters ### Path Parameters
- `node` `(string: <required>)` - Specifies the name of the node for which - `node_name` `(string: <required>)` - Specifies the name of the node to list services for.
to list services. This is specified as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `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 to list services. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
This value may be provided by either the `ns` URL query parameter or in the The namespace may be specified as '\*' to return results for all namespaces.
`X-Consul-Namespace` header. If not provided, the namespace will be inherited You can also [specify the namespace through other methods](#methods-to-specify-namespace).
from the request's ACL token or will default to the `default` namespace. The `*`
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -953,20 +945,18 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- | | ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `service:read` | | `YES` | `all` | `none` | `service:read` |
### Parameters ### Path Parameters
- `gateway` `(string: <required>)` - Specifies the name of the node for which - `gateway` `(string: <required>)` - Specifies the name of the node to list services for.
to list services. This is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to ### Query Parameters
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the gateway. - `dc` `(string: "")` - Specifies the datacenter to query.
This value may be provided by either the `ns` URL query parameter or in the This parameter defaults to the datacenter of the agent being queried.
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. The `*` - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0. The namespace may be specified as '\*' to return results for all namespaces.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request ### Sample Request
@ -1075,3 +1065,15 @@ $ curl \
- `FromWildcard` determines whether the service was associated with the gateway by providing a wildcard specifier - `FromWildcard` determines whether the service was associated with the gateway by providing a wildcard specifier
in the gateway's configuration entry in the gateway's configuration entry
## Methods to Specify Namespace <EnterpriseAlert inline />
Catalog endpoints
support several methods for specifying the namespace of resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to the [register entity](#register-entity) endpoint
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

93
website/content/api-docs/config.mdx
View File

@ -50,22 +50,18 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul config write`](/commands/config/write). The corresponding CLI command is [`consul config write`](/commands/config/write).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query.
the datacenter of the agent being queried. This is specified as part of the This parameter defaults to the datacenter of the agent being queried.
URL as a query parameter.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. If the index is - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. If the index is
0, Consul will only store the entry if it does not already exist. If the index is 0, Consul will only store the entry if it does not already exist. If the index is
non-zero, the entry is only set if the current index matches the `ModifyIndex` non-zero, the entry is only set if the current index matches the `ModifyIndex`
of that entry. of that entry.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace the config - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entry you apply.
entry will apply to. This value may be provided by either the `ns` URL query You can also [specify the namespace through other methods](#methods-to-specify-namespace).
parameter or in the `X-Consul-Namespace` header. If not provided,
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 Payload ### Sample Payload
@ -119,23 +115,21 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul config read`](/commands/config/read). The corresponding CLI command is [`consul config read`](/commands/config/read).
### Parameters ### Path Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `kind` `(string: <required>)` - Specifies the kind of the entry to read.
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `kind` `(string: <required>)` - Specifies the kind of the entry to read. This - `name` `(string: <required>)` - Specifies the name of the entry to read.
is specified as part of the URL. The name of the `proxy-defaults` config entry
- `name` `(string: <required>)` - Specifies the name of the entry to read. This
is specified as part of the URL. The name of the `proxy-defaults` config entry
must be `global`, and the name of the `mesh` config entry must be `mesh`. must be `global`, and the name of the `mesh` config entry must be `mesh`.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. ### Query Parameters
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header. If not provided, the namespace will be inherited from - `dc` `(string: "")` - Specifies the datacenter to query.
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0. This parameter defaults to the datacenter of the agent being queried.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entry you lookup
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request ### Sample Request
@ -192,19 +186,17 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul config list`](/commands/config/list). The corresponding CLI command is [`consul config list`](/commands/config/list).
### Parameters ### Path Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `kind` `(string: <required>)` - Specifies the kind of the entry to list.
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `kind` `(string: <required>)` - Specifies the kind of the entry to list. This ### Query Parameters
is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `dc` `(string: "")` - Specifies the datacenter to query.
This value may be provided by either the `ns` URL query parameter or in the This parameter defaults to the datacenter of the agent being queried.
`X-Consul-Namespace` header. If not provided, the namespace will be inherited from
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entries you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request ### Sample Request
@ -268,29 +260,26 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul config delete`](/commands/config/delete). The corresponding CLI command is [`consul config delete`](/commands/config/delete).
### Parameters ### Path Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `kind` `(string: <required>)` - Specifies the kind of the entry to delete.
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `kind` `(string: <required>)` - Specifies the kind of the entry to delete. This - `name` `(string: <required>)` - Specifies the name of the entry to delete.
is specified as part of the URL. The name of the `proxy-defaults` config entry
- `name` `(string: <required>)` - Specifies the name of the entry to delete. This
is specified as part of the URL. The name of the `proxy-defaults` config entry
must be `global`, and the name of the `mesh` config entry must be `mesh`. must be `global`, and the name of the `mesh` config entry must be `mesh`.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to delete from. ### Query Parameters
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header. If not provided, the namespace will be inherited - `dc` `(string: "")` - Specifies the datacenter to query.
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0. This parameter defaults to the datacenter of the agent being queried.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. Unlike `PUT`, - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. Unlike `PUT`,
the index must be greater than 0 for Consul to take any action: a 0 index will the index must be greater than 0 for Consul to take any action: a 0 index will
not delete the config entry. If the index is non-zero, the config entry is only not delete the config entry. If the index is non-zero, the config entry is only
deleted if the index matches the `ModifyIndex` of that config entry. This is deleted if the index matches the `ModifyIndex` of that config entry.
specified as part of the URL as a query parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entry you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request ### Sample Request
@ -299,3 +288,13 @@ $ curl \
--request DELETE \ --request DELETE \
http://127.0.0.1:8500/v1/config/service-defaults/web http://127.0.0.1:8500/v1/config/service-defaults/web
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
Config endpoints
support several methods for specifying the namespace of configuration entry resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

4
website/content/api-docs/connect/ca.mdx
View File

@ -30,7 +30,7 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `none` | | `YES` | `all` | `none` | `none` |
### Parameters ### Query Parameters
- `pem` `(boolean: false)` - Specifies that the return body should be a PEM encoded - `pem` `(boolean: false)` - Specifies that the return body should be a PEM encoded
certificate chain suitable for use by applications needing to trust Connect CA certificate chain suitable for use by applications needing to trust Connect CA
@ -169,7 +169,7 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul connect ca set-config`](/commands/connect/ca#set-config). The corresponding CLI command is [`consul connect ca set-config`](/commands/connect/ca#set-config).
### Parameters ### JSON Request Body Schema
- `Provider` `(string: <required>)` - Specifies the CA provider type to use. - `Provider` `(string: <required>)` - Specifies the CA provider type to use.

168
website/content/api-docs/connect/intentions.mdx
View File

@ -56,25 +56,20 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention create -replace`](/commands/intention/create#replace). The corresponding CLI command is [`consul intention create -replace`](/commands/intention/create#replace).
### URL Parameters ### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This - `source` `(string: <required>)` - Specifies the source service
is specified as part of the URL. according to the [source naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This - `destination` `(string: <required>)` - Specifies the destination service
is specified as part of the URL. according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
namespace to use when `source` or `destination` parameters lack namespaces. to use when `source` or `destination` query parameters do not include a namespace
If not provided, the default namespace will be inherited from the as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
request's ACL token or will default to the `default` namespace. You can also [specify the namespace through other methods](#methods-to-specify-namespace).
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
Added in Consul 1.9.0.
### PUT Body Parameters ### JSON Request Body Schema
- `SourceType` `(string: "")` - The type for the `SourceName` value. - `SourceType` `(string: "")` - The type for the `SourceName` value.
This can be only "consul" today to represent a Consul service. If not This can be only "consul" today to represent a Consul service. If not
@ -167,28 +162,25 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention create`](/commands/intention/create). The corresponding CLI command is [`consul intention create`](/commands/intention/create).
### URL Parameters ### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
namespace to use when `SourceNS` or `DestinationNS` are omitted or empty. to use when `SourceNS` or `DestinationNS` request body parameters do not include a namespace
If not provided, the default namespace will be inherited from the as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
request's ACL token or will default to the `default` namespace. You can also [specify the namespace through other methods](#methods-to-specify-namespace).
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
Added in Consul 1.9.0.
### POST Body Parameters ### JSON Request Body Schema
- `SourceName` `(string: <required>)` - The source of the intention. - `SourceName` `(string: <required>)` - The source of the intention.
For a `SourceType` of `consul` this is the name of a Consul service. The For a `SourceType` of `consul` this is the name of a Consul service. The
service doesn't need to be registered. service does not need to be registered.
- `SourceNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the - `SourceNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
`SourceName` parameter. `SourceName` parameter.
- `DestinationName` `(string: <required>)` - The destination of the intention. - `DestinationName` `(string: <required>)` - The destination of the intention.
The intention destination is always a Consul service, unlike the source. The intention destination is always a Consul service, unlike the source.
The service doesn't need to be registered. The service does not need to be registered.
- `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the - `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
`DestinationName` parameter. `DestinationName` parameter.
@ -265,12 +257,12 @@ The table below shows this endpoint's support for
for more details. for more details.
</p> </p>
### Parameters This endpoint supports the same parameters as the [create an intention](#create-intention-with-id) endpoint.
Additional parameters unique to this endpoint include:
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update. This ### Path Parameters
is specified as part of the URL.
- Other parameters are identical to creating an intention. - `uuid` `(string: <required>)` - Specifies the UUID of the intention to update.
### Sample Payload ### Sample Payload
@ -321,23 +313,18 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention get`](/commands/intention/get). The corresponding CLI command is [`consul intention get`](/commands/intention/get).
### Parameters ### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This - `source` `(string: <required>)` - Specifies the source service
is specified as part of the URL. according to the [source naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This - `destination` `(string: <required>)` - Specifies the destination service
is specified as part of the URL. according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
namespace to use when `source` or `destination` parameters lack namespaces. to use when `source` or `destination` query parameters do not include a namespace
If not provided, the default namespace will be inherited from the as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
request's ACL token or will default to the `default` namespace. You can also [specify the namespace through other methods](#methods-to-specify-namespace).
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
Added in Consul 1.9.0.
### Sample Request ### Sample Request
@ -398,10 +385,9 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention get`](/commands/intention/get). The corresponding CLI command is [`consul intention get`](/commands/intention/get).
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This - `uuid` `(string: <required>)` - Specifies the UUID of the intention to read.
is specified as part of the URL.
### Sample Request ### Sample Request
@ -462,7 +448,7 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention list`](/commands/intention/list). The corresponding CLI command is [`consul intention list`](/commands/intention/list).
### Parameters ### Query Parameters
- `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.
@ -470,11 +456,7 @@ The corresponding CLI command is [`consul intention list`](/commands/intention/l
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the
namespace to list intentions from. namespace to list intentions from.
The `*` wildcard may be used to list intentions from all namespaces. The `*` wildcard may be used to list intentions from all namespaces.
If not provided, the default namespace will be inherited from the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
request's ACL token or will default to the `default` namespace.
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
Added in Consul 1.9.0.
### Sample Request ### Sample Request
@ -553,23 +535,18 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention delete`](/commands/intention/delete). The corresponding CLI command is [`consul intention delete`](/commands/intention/delete).
### Parameters ### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This - `source` `(string: <required>)` - Specifies the source service
is specified as part of the URL. according to the [source naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This - `destination` `(string: <required>)` - Specifies the destination service
is specified as part of the URL. according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
namespace to use when `source` or `destination` parameters lack namespaces. to use when `source` or `destination` query parameters do not include a namespace
If not provided, the default namespace will be inherited from the as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
request's ACL token or will default to the `default` namespace. You can also [specify the namespace through other methods](#methods-to-specify-namespace).
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
Added in Consul 1.9.0.
### Sample Request ### Sample Request
@ -613,10 +590,9 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention delete`](/commands/intention/delete). The corresponding CLI command is [`consul intention delete`](/commands/intention/delete).
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to delete. This - `uuid` `(string: <required>)` - Specifies the UUID of the intention to delete.
is specified as part of the URL.
### Sample Request ### Sample Request
@ -670,23 +646,18 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention check`](/commands/intention/check). The corresponding CLI command is [`consul intention check`](/commands/intention/check).
### Parameters ### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This - `source` `(string: <required>)` - Specifies the source service
is specified as part of the URL. according to the [source naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This - `destination` `(string: <required>)` - Specifies the destination service
is specified as part of the URL. according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
namespace to use when `source` or `destination` parameters lack namespaces. to use when `source` or `destination` query parameters do not include a namespace
If not provided, the default namespace will be inherited from the as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
request's ACL token or will default to the `default` namespace. You can also [specify the namespace through other methods](#methods-to-specify-namespace).
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
Added in Consul 1.9.0.
### Sample Request ### Sample Request
@ -735,22 +706,19 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul intention match`](/commands/intention/match). The corresponding CLI command is [`consul intention match`](/commands/intention/match).
### Parameters ### Query Parameters
- `by` `(string: <required>)` - Specifies whether to match the "name" value - `by` `(string: <required>)` - Specifies whether to match the "name" value
by "source" or "destination". by "source" or "destination".
- `name` `(string: <required>)` - Specifies a name to match. This parameter - `name` `(string: <required>)` - Specifies a name to match
can be repeated for batching multiple matches. according to the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
This can take [several forms](/commands/intention#source-and-destination-naming). You can repeat this parameter for batching multiple matches.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
namespace to use when `name` parameter lacks namespaces. to use when the `name` query parameter does not include a namespace
If not provided, the default namespace will be inherited from the as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
request's ACL token or will default to the `default` namespace. You can also [specify the namespace through other methods](#methods-to-specify-namespace).
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
Added in Consul 1.9.0.
### Sample Request ### Sample Request
@ -791,3 +759,13 @@ $ curl \
] ]
} }
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
Connect intention endpoints
support several methods for specifying the namespace of intention resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

25
website/content/api-docs/coordinate.mdx
View File

@ -96,11 +96,11 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul rtt`](/commands/rtt). The corresponding CLI command is [`consul rtt`](/commands/rtt).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for. - `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for.
If left blank, this will query for the default segment when connecting to a server and If left blank, this will query for the default segment when connecting to a server and
the agent's own segment when connecting to a client (clients can only be part of one the agent's own segment when connecting to a client (clients can only be part of one
@ -140,8 +140,8 @@ segment.
This endpoint returns the LAN network coordinates for the given node. This endpoint returns the LAN network coordinates for the given node.
| Method | Path | Produces | | Method | Path | Produces |
| ------ | ------------------------ | ------------------ | | ------ | ----------------------------- | ------------------ |
| `GET` | `/coordinate/node/:node` | `application/json` | | `GET` | `/coordinate/node/:node_name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking), [blocking queries](/api-docs/features/blocking),
@ -153,11 +153,15 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `node:read` | | `YES` | `all` | `none` | `node:read` |
### Parameters ### Path Parameters
- `node_name` `(string: <required>)` - Specifies the name of the node to return LAN network coordinates for.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for. - `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for.
If left blank, this will query for the default segment when connecting to a server and If left blank, this will query for the default segment when connecting to a server and
the agent's own segment when connecting to a client (clients can only be part of one the agent's own segment when connecting to a client (clients can only be part of one
@ -211,11 +215,10 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `node:write` | | `NO` | `none` | `none` | `node:write` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Payload ### Sample Payload

34
website/content/api-docs/discovery-chain.mdx
View File

@ -27,9 +27,9 @@ If overrides are needed they are passed as the JSON-encoded request body and
the `POST` method must be used, otherwise `GET` is sufficient. the `POST` method must be used, otherwise `GET` is sufficient.
| Method | Path | Produces | | Method | Path | Produces |
| ------------------ | --------------------------- | ------------------ | | ------------------ | -------------------------------- | ------------------ |
| `GET` | `/discovery-chain/:service` | `application/json` | | `GET` | `/discovery-chain/:service_name` | `application/json` |
| `POST`<sup>1</sup> | `/discovery-chain/:service` | `application/json` | | `POST`<sup>1</sup> | `/discovery-chain/:service_name` | `application/json` |
<p> <p>
<sup>1</sup> Both GET and POST are for <strong>read</strong> operations. GET <sup>1</sup> Both GET and POST are for <strong>read</strong> operations. GET
@ -47,27 +47,25 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | -------------------- | -------------- | | ---------------- | ----------------- | -------------------- | -------------- |
| `YES` | `all` | `background refresh` | `service:read` | | `YES` | `all` | `background refresh` | `service:read` |
### URL Parameters ### Path Parameters
- `service` `(string: <required>)` - Specifies the service to query when - `service_name` `(string: <required>)` - Specifies the service to query when
compiling the discovery chain. This is provided as part of the URL. compiling the discovery chain.
### Query Parameters
- `compile-dc` `(string: "")` - Specifies the datacenter to use as the basis of - `compile-dc` `(string: "")` - Specifies the datacenter to use as the basis of
compilation. This will default to the datacenter of the agent being queried. compilation. This will default to the datacenter of the agent being queried.
This is specified as part of the URL as a query parameter.
This value comes from an [upstream This value comes from an [upstream
configuration](/docs/connect/registration/service-registration#upstream-configuration-reference) configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
[`datacenter`](/docs/connect/registration/service-registration#datacenter) [`datacenter`](/docs/connect/registration/service-registration#datacenter)
parameter. parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the source namespace - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the source namespace you use as the basis of compilation.
to use as the basis of compilation. This value can be specified as the `ns` You can also [specify the namespace through other methods](#methods-to-specify-namespace).
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.
### POST Body Parameters ### JSON Request Body Schema
- `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect - `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect
timeout](/docs/connect/config-entries/service-resolver#connecttimeout) for timeout](/docs/connect/config-entries/service-resolver#connecttimeout) for
@ -568,3 +566,13 @@ Response:
} }
} }
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
The discovery chain endpoint
supports several methods for specifying the namespace to use as the basis of discovery chain compilation
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

30
website/content/api-docs/event.mdx
View File

@ -31,24 +31,22 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul event`](/commands/event). The corresponding CLI command is [`consul event`](/commands/event).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the event to fire. This - `name` `(string: <required>)` - Specifies the name of the event to fire.
is specified as part of the URL. This name must not start with an underscore, This name must not start with an underscore,
since those are reserved for Consul internally. since those are reserved for Consul internally.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `node` `(string: "")` - Specifies a regular expression to filter by node name. - `node` `(string: "")` - Specifies a regular expression to filter by node name.
This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service - `service` `(string: "")` - Specifies a regular expression to filter by service name.
name. This is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This - `tag` `(string: "")` - Specifies a regular expression to filter by tag.
is specified as part of the URL as a query parameter.
### Sample Payload ### Sample Payload
@ -109,19 +107,15 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `none` | `none` | `event:read` | | `YES` | `none` | `none` | `event:read` |
### Parameters ### Query Parameters
- `name` `(string: <required>)` - Specifies the name of the event to filter. - `name` `(string: "")` - Specifies the name of the event to filter.
This is specified as part of the URL as a query parameter.
- `node` `(string: "")` - Specifies a regular expression to filter by node name. - `node` `(string: "")` - Specifies a regular expression to filter by node name.
This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service - `service` `(string: "")` - Specifies a regular expression to filter by service name.
name. This is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This - `tag` `(string: "")` - Specifies a regular expression to filter by tag.
is specified as part of the URL as a query parameter.
### Sample Request ### Sample Request

85
website/content/api-docs/health.mdx
View File

@ -34,23 +34,20 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------ | | ---------------- | ----------------- | ------------- | ------------------------ |
| `YES` | `all` | `none` | `node:read,service:read` | | `YES` | `all` | `none` | `node:read,service:read` |
### Parameters ### Path Parameters
- `node` `(string: <required>)` - Specifies the name or ID of the node to query. - `node` `(string: <required>)` - Specifies the name or ID of the node to query.
This is specified as part of the URL
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `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 to list checks. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the checks you lookup.
This value may be provided by either the `ns` URL query parameter or in the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. To view
checks for multiple namespaces the `*` wildcard namespace may be used. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -131,32 +128,30 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------ | | ---------------- | ----------------- | ------------- | ------------------------ |
| `YES` | `all` | `none` | `node:read,service:read` | | `YES` | `all` | `none` | `node:read,service:read` |
### Parameters ### Path Parameters
- `service` `(string: <required>)` - Specifies the service to list checks for. - `service` `(string: <required>)` - Specifies the service to list checks for.
This is provided as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in - `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as `?near=_agent` uses the agent's node for the sort. This is specified as
part of the URL as a query parameter. part of the URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair - `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is filters the results to nodes with the specified key/value pairs. This is
specified as part of the URL as a query parameter. specified as part of the URL as a query parameter.
- `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 of the service. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service.
This value may be provided by either the `ns` URL query parameter or in the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
`X-Consul-Namespace` header. If not provided, 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
@ -228,36 +223,34 @@ The table below shows this endpoint's support for
<a href="/api/features/blocking#streaming-backend">streaming backend</a> <a href="/api/features/blocking#streaming-backend">streaming backend</a>
</p> </p>
### Parameters ### Path Parameters
- `service` `(string: <required>)` - Specifies the service to list services for. - `service` `(string: <required>)` - Specifies the service to list services for.
This is provided as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in - `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as `?near=_agent` uses the agent's node for the sort.
part of the URL as a query parameter. **Note** that using `near` will ignore **Note** that using `near` will ignore
[`use_streaming_backend`](/docs/agent/config/config-files#use_streaming_backend) and always [`use_streaming_backend`](/docs/agent/config/config-files#use_streaming_backend) and always
use blocking queries, because the data required to sort the results is not available use blocking queries, because the data required to sort the results is not available
to the streaming backend. to the streaming backend.
- `tag` `(string: "")` **Deprecated** - Use `filter` with the `Service.Tags` selector instead. - `tag` `(string: "")` **Deprecated** - Use `filter` with the `Service.Tags` selector instead.
This parameter will be removed in a future version of Consul. This parameter will be removed in a future version of Consul.
Specifies the tag to filter the list. This is Specifies the tag to filter the list.
specified as part of the URL as a query parameter. Can be used multiple times You can use this parameter multiple times to
for additional filtering, returning only the results that include all of the tag return only the results that include all of the tag values provided.
values provided.
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Node.Meta` selector instead. - `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Node.Meta` selector instead.
This parameter will be removed in a future version of Consul. This parameter will be removed in a future version of Consul.
Specifies a desired node metadata key/value pair Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is filters the results to nodes with the specified key/value pairs.
specified as part of the URL as a query parameter.
- `passing` `(bool: false)` - Specifies that the server should return only nodes - `passing` `(bool: false)` - Specifies that the server should return only nodes
with all checks in the `passing` state. This can be used to avoid additional with all checks in the `passing` state. This can be used to avoid additional
@ -267,9 +260,7 @@ The table below shows this endpoint's support for
queries results prior to returning the data. queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service.
This value may be provided by either the `ns` URL query parameter or in the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
`X-Consul-Namespace` header. If not provided, 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
@ -443,7 +434,6 @@ Parameters and response format are the same as
**Note** that unlike `/health/connect/:service` and `/health/service/:service` this **Note** that unlike `/health/connect/:service` and `/health/service/:service` this
endpoint does not support the [streaming backend](/api-docs/features/blocking#streaming-backend). endpoint does not support the [streaming backend](/api-docs/features/blocking#streaming-backend).
## List Checks in State ## List Checks in State
This endpoint returns the checks in the state provided on the path. This endpoint returns the checks in the state provided on the path.
@ -464,33 +454,30 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------ | | ---------------- | ----------------- | ------------- | ------------------------ |
| `YES` | `all` | `none` | `node:read,service:read` | | `YES` | `all` | `none` | `node:read,service:read` |
### Parameters ### Path Parameters
- `state` `(string: <required>)` - Specifies the state to query. Supported states - `state` `(string: <required>)` - Specifies the state to query. Supported states
are `any`, `passing`, `warning`, or `critical`. The `any` state is a wildcard are `any`, `passing`, `warning`, or `critical`. The `any` state is a wildcard
that can be used to return all checks. that can be used to return all checks.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in - `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as `?near=_agent` uses the agent's node for the sort.
part of the URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair - `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is filters the results to nodes with the specified key/value pairs.
specified as part of the URL as a query parameter.
- `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 to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
This value may be provided by either the `ns` URL query parameter or in the You can also [specify the namespace through other methods](#methods-to-specify-namespace).
`X-Consul-Namespace` header. If not provided, 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
@ -546,3 +533,13 @@ the following selectors and filter operations being supported:
| `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches | | `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty | | `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
| `Status` | Equal, Not Equal, In, Not In, Matches, Not Matches | | `Status` | Equal, Not Equal, In, Not In, Matches, Not Matches |
## Methods to Specify Namespace <EnterpriseAlert inline />
The health endpoints
support several methods for specifying the namespace of resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

72
website/content/api-docs/kv.mdx
View File

@ -51,37 +51,33 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul kv get`](/commands/kv/get). The corresponding CLI command is [`consul kv get`](/commands/kv/get).
### Parameters ### Path Parameters
- `key` `(string: "")` - Specifies the path of the key to read. - `key` `(string: "")` - Specifies the path of the key to read.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `recurse` `(bool: false)` - Specifies if the lookup should be recursive and - `recurse` `(bool: false)` - Specifies if the lookup should be recursive and
`key` treated as a prefix instead of a literal match. This is specified as treat `key` as a prefix instead of a literal match.
part of the URL as a query parameter.
- `raw` `(bool: false)` - Specifies the response is just the raw value of the - `raw` `(bool: false)` - Specifies the response is just the raw value of the
key, without any encoding or metadata. This is specified as part of the URL as key, without any encoding or metadata.
a query parameter.
- `keys` `(bool: false)` - Specifies to return only keys (no values or - `keys` `(bool: false)` - Specifies to return only keys (no values or
metadata). Specifying this implies `recurse`. This is specified as part of the metadata). Specifying this parameter implies `recurse`.
URL as a query parameter.
- `separator` `(string: "")` - Specifies the string to use as a separator - `separator` `(string: "")` - Specifies the string to use as a separator
for recursive key lookups. This option is only used when paired with the `keys` for recursive key lookups. This option is only used when paired with the `keys`
parameter to limit the prefix of keys returned, only up to the given separator. parameter to limit the prefix of keys returned, only up to the given separator.
This is specified as part of the URL as a query parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. For recursive lookups, the namespace may be specified as '\*'
For recursive lookups, the namespace may be specified as '\*' and then results to return results for all namespaces.
will be returned for all namespaces. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -126,7 +122,7 @@ $ curl \
- `Key` is simply the full path of the entry. - `Key` is simply the full path of the entry.
- `Flags` is an opaque unsigned integer that can be attached to each entry. - `Flags` is an opaque unsigned integer that can be attached to each entry.
Clients can choose to use this however makes sense for their application. API consumers can use this field any way they choose for their application.
- `Value` is a base64-encoded blob of data. - `Value` is a base64-encoded blob of data.
@ -183,17 +179,18 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul kv put`](/commands/kv/put). The corresponding CLI command is [`consul kv put`](/commands/kv/put).
### Parameters ### Path Parameters
- `key` `(string: "")` - Specifies the path of the key. - `key` `(string: "")` - Specifies the path of the key.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to ### Query Parameters
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `flags` `(int: 0)` - Specifies an unsigned value between `0` and `(2^64)-1`. - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
Clients can choose to use this however makes sense for their application. This the datacenter of the agent being queried.
is specified as part of the URL as a query parameter.
- `flags` `(int: 0)` - Specifies an unsigned value between `0` and `(2^64)-1`
to store with the key.
API consumers can use this field any way they choose for their application.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. This is very - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. This is very
useful as a building block for more complex synchronization primitives. If the useful as a building block for more complex synchronization primitives. If the
@ -221,9 +218,7 @@ The corresponding CLI command is [`consul kv put`](/commands/kv/put).
of the key. The key must be held by this session to be unlocked. of the key. The key must be held by this session to be unlocked.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
### Sample Payload ### Sample Payload
@ -271,12 +266,15 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul kv delete`](/commands/kv/delete). The corresponding CLI command is [`consul kv delete`](/commands/kv/delete).
### Parameters ### Path Parameters
- `key` `(string: "")` - Specifies the path of the key to delete.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried. If the DC is invalid,
URL as a query parameter, and gives "No path to datacenter" error when dc is the error "No path to datacenter" is returned.
invalid.
- `recurse` `(bool: false)` - Specifies to delete all keys which have the - `recurse` `(bool: false)` - Specifies to delete all keys which have the
specified prefix. Without this, only a key with an exact match will be specified prefix. Without this, only a key with an exact match will be
@ -289,9 +287,7 @@ The corresponding CLI command is [`consul kv delete`](/commands/kv/delete).
deleted if the index matches the `ModifyIndex` of that key. deleted if the index matches the `ModifyIndex` of that key.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -306,3 +302,13 @@ $ curl \
```json ```json
true true
``` ```
## Methods to Specify Namespace <EnterpriseAlert inline />
The key-value store endpoints
support several methods for specifying the namespace of resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

33
website/content/api-docs/namespaces.mdx
View File

@ -31,10 +31,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul namespace create`](/commands/namespace/create). The corresponding CLI command is [`consul namespace create`](/commands/namespace/create).
### Parameters ### JSON Request Body Schema
- `Name` `(string: <required>)` - The namespaces name. This must be a valid - `Name` `(string: <required>)` - The namespace's name.
DNS hostname label. This field must be a valid DNS hostname label.
- `Description` `(string: "")` - Free form namespaces description. - `Description` `(string: "")` - Free form namespaces description.
@ -106,7 +106,7 @@ $ curl --request PUT \
http://127.0.0.1:8500/v1/namespace http://127.0.0.1:8500/v1/namespace
``` ```
### SampleResponse ### Sample Response
```json ```json
{ {
@ -165,10 +165,9 @@ the request has been granted any access in the namespace (read, list or write).
The corresponding CLI command is [`consul namespace read`](/commands/namespace/read). The corresponding CLI command is [`consul namespace read`](/commands/namespace/read).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the namespace to read. This - `name` `(string: <required>)` - Specifies the namespace to read.
is required and is specified as part of the URL path.
### Sample Request ### Sample Request
@ -177,7 +176,7 @@ $ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
http://127.0.0.1:8500/v1/namespace/team-1 http://127.0.0.1:8500/v1/namespace/team-1
``` ```
### SampleResponse ### Sample Response
```json ```json
{ {
@ -233,11 +232,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul namespace update`](/commands/namespace/update) or [`consul namespace write`](/commands/namespace/write). The corresponding CLI command is [`consul namespace update`](/commands/namespace/update) or [`consul namespace write`](/commands/namespace/write).
### Parameters ### Path Parameters
- `Name` `(string: <optional>)` - The namespaces name. This must be a valid - `name` `(string: <required>)` - The namespaces name. This must be a valid DNS hostname label.
DNS hostname label. If present in the payload it must match what was given
in the URL path. ### JSON Request Body Schema
- `Name` `(string: <optional>)` - If specified, this field must be an exact match
with the `name` path parameter.
- `Description` `(string: "")` - Free form namespaces description. - `Description` `(string: "")` - Free form namespaces description.
@ -308,7 +310,7 @@ $ curl --request PUT \
http://127.0.0.1:8500/v1/namespace/team-1 http://127.0.0.1:8500/v1/namespace/team-1
``` ```
### SampleResponse ### Sample Response
```json ```json
{ {
@ -372,10 +374,9 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul namespace delete`](/commands/namespace/delete). The corresponding CLI command is [`consul namespace delete`](/commands/namespace/delete).
### Parameters ### Path Parameters
- `name` `(string: <required>)` - Specifies the namespace to delete. This - `name` `(string: <required>)` - Specifies the namespace to delete.
is required and is specified as part of the URL path.
### Sample Request ### Sample Request

59
website/content/api-docs/operator/area.mdx
View File

@ -47,11 +47,12 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator area create`](/commands/operator/area#create). The corresponding CLI command is [`consul operator area create`](/commands/operator/area#create).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### JSON Request Body Schema
- `PeerDatacenter` `(string: <required>)` - Specifies the name of the Consul - `PeerDatacenter` `(string: <required>)` - Specifies the name of the Consul
datacenter that will be joined the Consul servers in the current datacenter to datacenter that will be joined the Consul servers in the current datacenter to
@ -115,11 +116,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator area list`](/commands/operator/area#list). The corresponding CLI command is [`consul operator area list`](/commands/operator/area#list).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### Sample Request ### Sample Request
@ -160,11 +160,12 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator area update`](/commands/operator/area#update). The corresponding CLI command is [`consul operator area update`](/commands/operator/area#update).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### JSON Request Body Schema
- `UseTLS` `(bool: <optional>)` - Specifies whether gossip over this area should be - `UseTLS` `(bool: <optional>)` - Specifies whether gossip over this area should be
encrypted with TLS if possible. encrypted with TLS if possible.
@ -204,14 +205,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- | | ---------------- | ----------------- | ------------- | --------------- |
| `YES` | `all` | `none` | `operator:read` | | `YES` | `all` | `none` | `operator:read` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This - `uuid` `(string: <required>)` - Specifies the UUID of the area to list.
is specified as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### Sample Request ### Sample Request
@ -252,14 +253,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator area delete`](/commands/operator/area#delete). The corresponding CLI command is [`consul operator area delete`](/commands/operator/area#delete).
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to delete. This - `uuid` `(string: <required>)` - Specifies the UUID of the area to delete.
is specified as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### Sample Request ### Sample Request
@ -290,14 +291,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator area join`](/commands/operator/area#join). The corresponding CLI command is [`consul operator area join`](/commands/operator/area#join).
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to join. This - `uuid` `(string: <required>)` - Specifies the UUID of the area to join.
is specified as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### Sample Payload ### Sample Payload
@ -365,14 +366,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator area members`](/commands/operator/area#members). The corresponding CLI command is [`consul operator area members`](/commands/operator/area#members).
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This - `uuid` `(string: <required>)` - Specifies the UUID of the area to list.
is specified as part of the URL.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### Sample Request ### Sample Request

22
website/content/api-docs/operator/autopilot.mdx
View File

@ -35,11 +35,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator autopilot get-config`](/commands/operator/autopilot#get-config). The corresponding CLI command is [`consul operator autopilot get-config`](/commands/operator/autopilot#get-config).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query string.
- `stale` `(bool: false)` - If the cluster does not currently have a leader an - `stale` `(bool: false)` - If the cluster does not currently have a leader an
error will be returned. You can use the `?stale` query parameter to read the error will be returned. You can use the `?stale` query parameter to read the
@ -91,16 +90,17 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator autopilot set-config`](/commands/operator/autopilot#set-config). The corresponding CLI command is [`consul operator autopilot set-config`](/commands/operator/autopilot#set-config).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query string.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. The update will - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. The update will
only happen if the given index matches the `ModifyIndex` of the configuration only happen if the given index matches the `ModifyIndex` of the configuration
at the time of writing. at the time of writing.
### JSON Request Body Schema
- `CleanupDeadServers` `(bool: true)` - Specifies automatic removal of dead - `CleanupDeadServers` `(bool: true)` - Specifies automatic removal of dead
server nodes periodically and whenever a new server is added to the cluster. server nodes periodically and whenever a new server is added to the cluster.
@ -168,11 +168,10 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- | | ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `operator:read` | | `NO` | `none` | `none` | `operator:read` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query string.
### Sample Request ### Sample Request
@ -275,11 +274,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator autopilot state`](/commands/operator/autopilot#state). The corresponding CLI command is [`consul operator autopilot state`](/commands/operator/autopilot#state).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query string.
### Sample Request ### Sample Request

21
website/content/api-docs/operator/keyring.mdx
View File

@ -37,15 +37,15 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul keyring -list`](/commands/keyring#list). The corresponding CLI command is [`consul keyring -list`](/commands/keyring#list).
### Parameters ### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`. randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
- `local-only` `(bool: false)` - Setting `local-only` to true will force keyring - `local-only` `(bool: false)` - Setting `local-only` to true will force keyring
list queries to only hit local servers (no WAN traffic). This flag can only be set list queries to only hit local servers (no WAN traffic). This flag can only be set
for list queries. It is specified as part of the URL as a query parameter. for list queries.
### Sample Request ### Sample Request
@ -124,12 +124,13 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul keyring -install`](/commands/keyring#install). The corresponding CLI command is [`consul keyring -install`](/commands/keyring#install).
### Parameters ### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`. randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
### JSON Request Body Schema
- `Key` `(string: <required>)` - Specifies the encryption key to install into - `Key` `(string: <required>)` - Specifies the encryption key to install into
the cluster. the cluster.
@ -172,12 +173,13 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul keyring -use`](/commands/keyring#use). The corresponding CLI command is [`consul keyring -use`](/commands/keyring#use).
### Parameters ### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`. randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
### JSON Request Body Schema
- `Key` `(string: <required>)` - Specifies the encryption key to begin using as - `Key` `(string: <required>)` - Specifies the encryption key to begin using as
primary into the cluster. primary into the cluster.
@ -220,12 +222,13 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul keyring -remove`](/commands/keyring#remove). The corresponding CLI command is [`consul keyring -remove`](/commands/keyring#remove).
### Parameters ### Query Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a - `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`. randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
### JSON Request Body Schema
- `Key` `(string: <required>)` - Specifies the encryption key to delete. - `Key` `(string: <required>)` - Specifies the encryption key to delete.

9
website/content/api-docs/operator/license.mdx
View File

@ -33,11 +33,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul license get`](/commands/license#get). The corresponding CLI command is [`consul license get`](/commands/license#get).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter whose license should be retrieved. - `dc` `(string: "")` - Specifies the datacenter whose license should be retrieved.
This will default to the datacenter of the agent serving the HTTP request. This will default to the datacenter of the agent serving the HTTP request.
This is specified as a URL query parameter.
### Sample Request ### Sample Request
@ -100,11 +99,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul license put`](/commands/license#put). The corresponding CLI command is [`consul license put`](/commands/license#put).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter whose license should be updated. - `dc` `(string: "")` - Specifies the datacenter whose license should be updated.
This will default to the datacenter of the agent serving the HTTP request. This will default to the datacenter of the agent serving the HTTP request.
This is specified as a URL query parameter.
### Sample Payload ### Sample Payload
@ -172,11 +170,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul license reset`](/commands/license#reset). The corresponding CLI command is [`consul license reset`](/commands/license#reset).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter whose license should be updated. - `dc` `(string: "")` - Specifies the datacenter whose license should be updated.
This will default to the datacenter of the agent serving the HTTP request. This will default to the datacenter of the agent serving the HTTP request.
This is specified as a URL query parameter.
### Sample Request ### Sample Request

16
website/content/api-docs/operator/raft.mdx
View File

@ -32,11 +32,10 @@ The table below shows this endpoint's support for
| ---------------- | --------------------- | ------------- | --------------- | | ---------------- | --------------------- | ------------- | --------------- |
| `NO` | `default` and `stale` | `none` | `operator:read` | | `NO` | `default` and `stale` | `none` | `operator:read` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query.
the datacenter of the agent being queried. This is specified as part of the This parameter defaults to the datacenter of the agent being queried.
URL as a query string.
- `stale` `(bool: false)` - If the cluster does not currently have a leader an - `stale` `(bool: false)` - If the cluster does not currently have a leader an
error will be returned. You can use the `?stale` query parameter to read the error will be returned. You can use the `?stale` query parameter to read the
@ -132,14 +131,13 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator raft remove-peer`](/commands/operator/raft#remove-peer). The corresponding CLI command is [`consul operator raft remove-peer`](/commands/operator/raft#remove-peer).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query string.
- `id|address` `(string: <required>)` - Specifies the ID or address (IP:port) of the raft peer to remove. - `id|address` `(string: <required>)` - Specifies the ID or address (IP:port) of the raft peer to remove.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried.
### Sample Request ### Sample Request
```shell-session ```shell-session

5
website/content/api-docs/operator/segment.mdx
View File

@ -38,11 +38,10 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- | | ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `operator:read` | | `NO` | `none` | `none` | `operator:read` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query the datacenter of the agent being queried.
parameter.
### Sample Request ### Sample Request

64
website/content/api-docs/query.mdx
View File

@ -87,7 +87,7 @@ populate the query before it is executed. All of the string fields inside the
empty string. empty string.
- `${agent.segment}` <EnterpriseAlert inline /> - the network segment of the agent that - `${agent.segment}` <EnterpriseAlert inline /> - the network segment of the agent that
initiated the query. This can be used with the `NodeMeta` field to limit the results initiated the query. This varaible can be used with the `NodeMeta` field to limit the results
of a query to service instances within its own network segment: of a query to service instances within its own network segment:
```json ```json
@ -150,11 +150,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------- | | ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `query:write` | | `NO` | `none` | `none` | `query:write` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### JSON Request Body Schema
- `Name` `(string: "")` - Specifies an optional friendly name that can be used - `Name` `(string: "")` - Specifies an optional friendly name that can be used
to execute a query instead of using its ID. to execute a query instead of using its ID.
@ -315,11 +316,10 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `all` | `none` | `query:read` | | `NO` | `all` | `none` | `query:read` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Request ### Sample Request
@ -378,14 +378,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------- | | ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `query:write` | | `NO` | `none` | `none` | `query:write` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to update. - `uuid` `(string: <required>)` - Specifies the UUID of the query to update.
This is required and is specified as part of the URL path.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
The body is the same as is used to create a prepared query. Please see above for The body is the same as is used to create a prepared query. Please see above for
more information. more information.
@ -418,14 +418,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `all` | `none` | `query:read` | | `NO` | `all` | `none` | `query:read` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to read. - `uuid` `(string: <required>)` - Specifies the UUID of the query to read.
This is required and is specified as part of the URL path.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Request ### Sample Request
@ -458,14 +458,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------- | | ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `query:write` | | `NO` | `none` | `none` | `query:write` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to delete. - `uuid` `(string: <required>)` - Specifies the UUID of the query to delete.
This is required and is specified as part of the URL path.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Request ### Sample Request
@ -502,16 +502,16 @@ The table below shows this endpoint's support for
be used when executing the request. Otherwise, the client's supplied ACL Token will be used when executing the request. Otherwise, the client's supplied ACL Token will
be used. be used.
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to execute. - `uuid` `(string: <required>)` - Specifies the UUID of the query to execute.
This is required and is specified as part of the URL path. This can also be This parameter can also be the name of an existing prepared query,
the name of an existing prepared query, or a name that matches a prefix name or a name that matches a prefix name for a prepared query template.
for a prepared query template.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
- `near` `(string: "")` - Specifies to sort the resulting list in ascending - `near` `(string: "")` - Specifies to sort the resulting list in ascending
order based on the estimated round trip time from that node. Passing order based on the estimated round trip time from that node. Passing
@ -525,7 +525,7 @@ be used.
This is applied after any sorting or shuffling. This is applied after any sorting or shuffling.
- `connect` `(bool: false)` - If true, limit results to nodes that are - `connect` `(bool: false)` - If true, limit results to nodes that are
Connect-capable only. This can also be specified directly on the template Connect-capable only. This parameter can also be specified directly on the template
itself to force all executions of a query to be Connect-only. See the itself to force all executions of a query to be Connect-only. See the
template documentation for more information. template documentation for more information.
@ -627,16 +627,16 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `all` | `none` | `query:read` | | `NO` | `all` | `none` | `query:read` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to explain. - `uuid` `(string: <required>)` - Specifies the UUID of the query to explain.
This is required and is specified as part of the URL path. This can also be This parameter can also be the name of an existing prepared query,
the name of an existing prepared query, or a name that matches a prefix name or a name that matches a prefix name for a prepared query template.
for a prepared query template.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Request ### Sample Request

91
website/content/api-docs/session.mdx
View File

@ -27,22 +27,23 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- | | ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `session:write` | | `NO` | `none` | `none` | `session:write` |
### Parameters ### Query Parameters
<!-- What's the relationship to ServiceChecks[].Namespace (if any)? -->
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended. URL as a query parameter. Using this parameter across datacenters is not recommended.
### JSON Request Body Schema
- `LockDelay` `(string: "15s")` - Specifies the duration for the lock delay. This - `LockDelay` `(string: "15s")` - Specifies the duration for the lock delay. This
must be greater than `0`. must be greater than `0`.
- `Node` `(string: "<agent>")` - Specifies the name of the node. This must refer - `Node` `(string: "<agent>")` - Specifies the name of the node.
to a node that is already registered. This field must refer to a node that is already registered.
- `Name` `(string: "")` - Specifies a human-readable name for the session. - `Name` `(string: "")` - Specifies a human-readable name for the session.
@ -136,19 +137,19 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- | | ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `session:write` | | `NO` | `none` | `none` | `session:write` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to destroy. - `uuid` `(string: <required>)` - Specifies the UUID of the session to destroy.
This is required and is specified as part of the URL path. This is required and is specified as part of the URL path.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter. Using this across datacenters is not recommended. Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -182,19 +183,18 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- | | ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` | | `YES` | `all` | `none` | `session:read` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to read. - `uuid` `(string: <required>)` - Specifies the UUID of the session to read.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to ### Query Parameters
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended. - `dc` `(string: "")` - Specifies the datacenter to query.
This defaults to the datacenter of the agent being queried.
Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -246,21 +246,20 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- | | ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` | | `YES` | `all` | `none` | `session:read` |
### Parameters ### Path Parameters
- `node` `(string: <required>)` - Specifies the name or ID of the node to query. - `node` `(string: <required>)` - Specifies the name or ID of the node to query.
This is required and is specified as part of the URL path.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter. Using this across datacenters is not recommended. Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter
The namespace may be specified as '\*' and then results will be returned for all namespaces. The namespace may be specified as '\*' and then results will be returned for all namespaces.
Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -310,17 +309,16 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- | | ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` | | `YES` | `all` | `none` | `session:read` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter. Using this across datacenters is not recommended. Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the URL as a query parameter.
The namespace may be specified as '\*' and then results will be returned for all namespaces. The namespace may be specified as '\*' and then results will be returned for all namespaces.
Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -369,19 +367,18 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- | | ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `session:write` | | `NO` | `none` | `none` | `session:write` |
### Parameters ### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to renew. - `uuid` `(string: <required>)` - Specifies the UUID of the session to renew.
This is required and is specified as part of the URL path.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter. Using this across datacenters is not recommended. Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query. - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token, You can also [specify the namespace through other methods](#methods-to-specify-namespace).
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
### Sample Request ### Sample Request
@ -413,3 +410,13 @@ $ curl \
``` ```
-> **Note:** Consul may return a TTL value higher than the one specified during session creation. This indicates the server is under high load and is requesting clients renew less often. -> **Note:** Consul may return a TTL value higher than the one specified during session creation. This indicates the server is under high load and is requesting clients renew less often.
## Methods to Specify Namespace <EnterpriseAlert inline />
Session endpoints
support several methods for specifying the namespace of session resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace

18
website/content/api-docs/snapshot.mdx
View File

@ -41,11 +41,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul snapshot save`](/commands/snapshot/save). The corresponding CLI command is [`consul snapshot save`](/commands/snapshot/save).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default - `dc` `(string: "")` - Specifies the datacenter to query. This will default
to the datacenter of the agent being queried. This is specified as part of the to the datacenter of the agent being queried.
URL as a query parameter.
- `stale` `(bool: false)` - Specifies that any follower may reply. By default - `stale` `(bool: false)` - Specifies that any follower may reply. By default
requests are forwarded to the leader. Followers may be faster to respond, but requests are forwarded to the leader. Followers may be faster to respond, but
@ -80,9 +79,6 @@ intended to be used when recovering from a disaster, restoring into a fresh
cluster of Consul servers running the same version as the cluster from where the cluster of Consul servers running the same version as the cluster from where the
snapshot was taken. snapshot was taken.
The body of the request should be a snapshot archive returned from a previous
call to the `GET` method.
| Method | Path | Produces | | Method | Path | Produces |
| :----- | :---------- | ----------------------------- | | :----- | :---------- | ----------------------------- |
| `PUT` | `/snapshot` | `200 text/plain (empty body)` | | `PUT` | `/snapshot` | `200 text/plain (empty body)` |
@ -99,11 +95,15 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul snapshot restore`](/commands/snapshot/restore). The corresponding CLI command is [`consul snapshot restore`](/commands/snapshot/restore).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default - `dc` `(string: "")` - Specifies the datacenter to query. This will default
to the datacenter of the agent being queried. This is specified as part of the to the datacenter of the agent being queried.
URL as a query parameter.
### Request Body
The body of the request should be a snapshot archive returned by a previous
call to [generate snapshot](#generate-snapshot).
### Sample Request ### Sample Request

10
website/content/api-docs/status.mdx
View File

@ -32,11 +32,10 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ | | ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `none` | | `NO` | `none` | `none` | `none` |
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Request ### Sample Request
@ -72,11 +71,10 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul operator raft list-peers`](/commands/operator/raft#list-peers). The corresponding CLI command is [`consul operator raft list-peers`](/commands/operator/raft#list-peers).
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the the datacenter of the agent being queried.
URL as a query parameter.
### Sample Request ### Sample Request

8
website/content/api-docs/txn.mdx
View File

@ -51,12 +51,18 @@ The table below shows this endpoint's support for
<sup>2</sup> The ACL required depends on the operations in the transaction. <sup>2</sup> The ACL required depends on the operations in the transaction.
</p> </p>
### Parameters ### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default - `dc` `(string: "")` - Specifies the datacenter to query. This will default
to the datacenter of the agent being queried. This is specified as part of the to the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. URL as a query parameter.
### JSON Request Body Schema
A JSON array of operations objects, each with
a key of the operation name (`KV`, `Node`, `Service`, or `Check`), and
a value of an object specific to that operation.
- `KV` operations have the following fields: - `KV` operations have the following fields:
- `Verb` `(string: <required>)` - Specifies the type of operation to perform. - `Verb` `(string: <required>)` - Specifies the type of operation to perform.