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).
### 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 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
method documentation](/docs/security/acl/auth-methods).
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
create the auth method within. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the auth method you create. This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
read. This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to read.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
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,
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 auth method you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `Name` `(string: <required>)` - Specifies the name of the auth method to
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.
- `name` `(string: <required>)` - Specifies the name of the auth method you update.
### 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
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).
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the auth method to update. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
the auth method you update. This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
delete. This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to delete.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
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,
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 auth method you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list
the auth methods for. This value can be specified as the `ns` URL query
parameter or in 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the auth methods in the specified namespace.
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).
The namespace may be specified as '\*' and then
results will be returned for all namespaces.
## 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).
### 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.
@ -99,11 +104,9 @@ The corresponding CLI command is [`consul acl binding-rule create`](/commands/ac
prefixed-${serviceaccount.name}
```
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
create the binding rule. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you create.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule
to read. This is required and is specified as part of the URL path.
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to read.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
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,
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 binding rule you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `ID` `(string: <required>)` - Specifies the ID of the binding rule to 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.
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule you update.
### 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.
@ -283,11 +292,9 @@ The corresponding CLI command is [`consul acl binding-rule update`](/commands/ac
prefixed-${serviceaccount.name}
```
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the binding rule to update. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you update.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to
delete. This is required and is specified as part of the URL path.
- `id` `(string: <required>)` - Specifies the UUID of the binding rule you delete.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
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,
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 binding rule you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
## Parameters
## Query Parameters
- `authmethod` `(string: "")` - Filters the binding rule list to those binding
rules that are linked with the specific named auth method.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list
the binding rules 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the binding rules in the specified namespace.
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
@ -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` |
### 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 parameter.
the datacenter of the agent being queried.
### Sample Request
@ -302,7 +301,12 @@ replication enabled.
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.
@ -314,11 +318,9 @@ The corresponding CLI command is [`consul login`](/commands/login).
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the Auth Method to use for Login. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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
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
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
linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the Auth Method to use for Login. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
If not provided, the namespace will be inherited from the request's ACL
token, or will default to the `default` namespace.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
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
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
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
linked to the token. Can be useful to track origins.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the Auth Method to use for Login. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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).
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### Sample Payload
@ -581,3 +587,14 @@ $ curl \
"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).
### 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
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
those which do not yet exist but may in the future.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
create the policy. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you create.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to
read. This is required and is specified as part of the URL path.
- `id` `(string: <required>)` - Specifies the UUID of the policy you lookup.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the policy. 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.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL policy to
read. This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the name of the ACL policy to read.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the policy. 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.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `ID` `(string: <required>)` - Specifies the UUID of the policy to 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.
- `id` `(string: <required>)` - Specifies the UUID of the policy you update.
### 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
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
those which do not yet exist but may in the future.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the policy to update. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you update.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to
delete. This is required and is specified as part of the URL path.
- `id` `(string: <required>)` - Specifies the UUID of the policy you delete.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
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,
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 policy you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list
the Policies 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the auth methods in the specified namespace.
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
@ -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).
### 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
can contain alphanumeric characters, dashes `-`, and underscores `_`.
This name must be unique.
- `Description` `(string: "")` - Free form human readable description of the role.
- `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
will result in effective policy only being valid in that datacenter.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
create the role. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you create.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
read. This is required and is specified as part of the URL path.
- `id` `(string: <required>)` - Specifies the UUID of the role you lookup.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the role. 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.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the Name of the ACL role to
read. This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the name of the ACL role to read.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the role. 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.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `ID` `(string: <required>)` - Specifies the ID of the role to 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.
- `id` `(string: <required>)` - Specifies the UUID of the role you update.
### 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
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
applied to the role. Added in Consul 1.8.1.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the role to update. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you update.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
delete. This is required and is specified as part of the URL path.
- `id` `(string: <required>)` - Specifies the UUID of the role you delete.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
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,
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 role you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
## Parameters
### Query Parameters
- `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 /> - Specifies the namespace to list
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the roles in the specified namespace.
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
@ -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).
### 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.
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
24 hours. Added in Consul 1.5.0.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
create the token. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you create.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to
read. This is required and is specified as part of the URL path.
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the token you lookup.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the token. 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.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
- `expanded` `(bool: false)` - If this field is set, the contents of all policies and
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).
### Parameters
### Path Parameters
- `AccessorID` `(string: "")` - Specifies the accessor ID of the token being updated. 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. This field is immutable. If not present in
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the token you update.
### 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.
- `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
Consul.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the token to update. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you update.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `AccessorID` `(string: <required>)` - The accessor ID of the token to clone. This is required
in the URL path
- `AccessorID` `(string: <required>)` - The accessor ID of the token to clone.
### 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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the token to be cloned. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you clone.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to
delete. This is required and is specified as part of the URL path.
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to delete.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
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,
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 token you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
## Parameters
## Query Parameters
- `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
linked with the specific role ID.
linked with this specific role ID.
- `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
of the `authmethod` being used for token lookup. If not provided, the namespace
provided by the `ns` parameter will be used. If neither of those is provided
then the namespace will be inherited from the request's ACL token. Added in
Consul 1.7.0.
- `authmethod-ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
`authmethod` used for token lookup. If not provided, the namespace
provided by the `ns` parameter or [through other methods](#methods-to-specify-namespace) will be used.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list
the tokens 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the tokens in the specified namespace.
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
@ -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).
### 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.
- `Description` `(string: "")` - Free form partition description.
@ -56,7 +56,7 @@ $ curl ---request PUT \
http://127.0.0.1:8500/v1/partition
```
### SampleResponse
### Sample Response
```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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the partition to read. This
is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the partition to read.
### 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).
### Parameters
### Path Parameters
- `Name` `(string: <optional>)` - The partition name. This must be a valid
DNS hostname label. If present in the payload it must match what was given
in the URL path.
- `name` `(string: <required>)` - Specifies the partition to update.
This parameter must be a valid DNS hostname label.
### 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.
@ -157,7 +160,7 @@ $ curl --request PUT \
http://127.0.0.1:8500/v1/partition/na-west
```
### SampleResponse
### Sample Response
```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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the partition to delete. This
is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the partition to delete.
### 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` |
### Parameters
### Query Parameters
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
which to list checks. 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the checks in the specified namespace.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -118,7 +115,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- |
| `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.
@ -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
ID for uniqueness. This value will return in the response as `"CheckId"`.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
which to register the check. This parameter is only valid for service checks.
If not provided in the JSON body, the value of the `ns` URL query parameter or
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you register.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
- `Interval` `(string: "")` - Specifies the frequency at which to run this
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` |
### 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
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,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to deregister.
### 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
@ -351,19 +350,17 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Parameters
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
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.
- `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).
### Sample Request
@ -392,19 +389,17 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Parameters
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
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.
- `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).
### Sample Request
@ -432,19 +427,17 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Parameters
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
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.
- `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).
### Sample Request
@ -472,10 +465,16 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Parameters
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### 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
`"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
passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
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.
<!-- Are we missing a Namespace field here? -->
### Sample Payload
@ -506,3 +501,15 @@ $ curl \
--data @payload.json \
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` |
### 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
requested.
@ -65,10 +70,8 @@ The table below shows this endpoint's support for
number for the requesting client cert.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
the target service. If not provided in the JSON body, the value of
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
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.
the target service. This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### Sample Payload
@ -192,17 +195,15 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | -------------------- | --------------- |
| `YES` | `all` | `background refresh` | `service:write` |
### Parameters
### Path Parameters
- `Service` `(string: <required>)` - The name of the service for the leaf
certificate. This is specified in the URL. The service does not need to
exist in the catalog, but the proper ACL permissions must be available.
- `service` `(string: <required>)` - The name of the service for the leaf certificate.
The service does not need to exist in the catalog, but the proper ACL permissions must be available.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
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,
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 leaf certificate you request.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -244,3 +245,15 @@ $ curl \
- `ValidBefore` `(string)` - The time before which the certificate is valid.
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

52
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).
### Parameters
### Query Parameters
- `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
**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.
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).
### Parameters
### Query Parameters
- `enable` `(bool: <required>)` - Specifies whether to enable or disable
maintenance mode. This is specified as part of the URL as a query string
parameter.
maintenance mode.
- `reason` `(string: "")` - Specifies a text string explaining the reason for
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
specified as part of the URL as a query string parameter, and, as such, must
be URI-encoded.
If no reason is provided, a default value is used instead.
This parameter must be URI-encoded.
### Sample Request
@ -593,10 +591,11 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `agent:read` |
### Parameters
### Query Parameters
- `loglevel` `(string: "info")` - Specifies a text string containing a log level
to filter on, such as `info`.
- `logjson` `(bool: false)` - Specifies whether the logs will be output in JSON
format.
@ -639,14 +638,14 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul join`](/commands/join).
### Parameters
### Path Parameters
- `address` `(string: <required>)` - Specifies the address of the other agent to
join. This is specified as part of the URL.
- `address` `(string: <required>)` - Specifies the address of the other agent to join.
### Query Parameters
- `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
the URL as a query parameter
only optional for agents running in server mode.
### Sample Request
@ -697,16 +696,16 @@ LAN and WAN gossip pools. If a node fails unexpectedly, then it will be in a `fa
belonging to that node will not be cleaned up. Forcing a node into the `left`
state allows its old entries to be removed.
| Method | Path | Produces |
| ------ | -------------------------- | ------------------ |
| `PUT` | `/agent/force-leave/:node` | `application/json` |
| Method | Path | Produces |
| ------ | ------------------------------- | ------------------ |
| `PUT` | `/agent/force-leave/:node_name` | `application/json` |
Additionally, by specifying the `prune` flag, a node can be forcibly removed from
the list of members entirely.
| Method | Path | Produces |
| ------ | -------------------------------- | ------------------ |
| `PUT` | `/agent/force-leave/:node?prune` | `application/json` |
| Method | Path | Produces |
| ------ | ------------------------------------- | ------------------ |
| `PUT` | `/agent/force-leave/:node_name?prune` | `application/json` |
The table below shows this endpoint's support for
[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).
### 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.
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
gossip pool. This is specified as part of the URL as a query parameter. Added
in Consul 1.11.0.
gossip pool. Added in Consul 1.11.0.
### 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).
### Parameters
### JSON Request Body Schema
- `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` |
### Parameters
### Query Parameters
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which
to list services. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the services in the specified namespace.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -162,16 +159,14 @@ The table below shows this endpoint's support for
hash-based blocking
</a> only.
### Parameters
### Path Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to
fetch. This is specified as part of the URL.
- `service_id` `(string: <required>)` - Specifies the ID of the service to fetch.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the service's configuration. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### 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 Request
@ -262,17 +257,6 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- |
| `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
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
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
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).
### 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.
### 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)
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
linked to the service instance.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
which to register the service. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you register.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
- `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).
### Parameters
### Path Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to
deregister. This is specified as part of the URL.
- `service_id` `(string: <required>)` - Specifies the ID of the service to deregister.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which
to deregister the service. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service you deregister.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -812,26 +804,23 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` |
### Parameters
### Path Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to put
in maintenance mode. This is specified as part of the URL.
- `service_id` `(string: <required>)` - Specifies the ID of the service to put in maintenance mode.
### Query Parameters
- `enable` `(bool: <required>)` - Specifies whether to enable or disable
maintenance mode. This is specified as part of the URL as a query string
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
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
specified as part of the URL as a query string parameter, and, as such, must
be URI-encoded.
If no reason is provided, a default value is used instead.
This parameter must 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
@ -840,3 +829,15 @@ $ curl \
--request PUT \
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

176
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` |
### 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.
@ -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
exist, it will still be created.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which the
service and checks will be registered. This value may be provided by either the
`ns` URL query parameter or in the `X-Consul-Namespace` header. Additionally,
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you register.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
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.
@ -184,7 +185,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------------------- |
| `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.
@ -195,16 +201,16 @@ The behavior of the endpoint depends on what keys are provided.
- `Datacenter` `(string: "")` - Specifies the datacenter, which defaults to the
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
service and all associated checks will be removed.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which the
service and checks will be deregistered. If not provided in the JSON body, the value of
the `ns` URL query parameter or the `X-Consul-Namespace` header will be used.
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.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you deregister.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
You can also specify the namespace in the `Service` or `Check` fields;
if namespaces are specified in multiple places, they must all be the same.
### 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).
### 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 parameter.
- `dc` `(string: "")` - Specifies the datacenter to query.
This parameter defaults to the datacenter of the agent being queried.
- `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
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
`?near=_agent` uses the agent's node for the sort.
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Meta` selector instead.
This parameter will be removed in a future version of Consul.
Specifies a desired node metadata key/value pair
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
specified as part of the URL as a query parameter.
filters the results to nodes with the specified key/value pairs.
- `filter` `(string: "")` - Specifies the expression used to filter the
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).
### 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 parameter.
the datacenter of the agent being queried.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
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
specified as part of the URL as a query parameter.
filters the results to nodes with the specified key/value pairs.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
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 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 services you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -444,9 +443,9 @@ This endpoint returns the nodes providing a service in a given datacenter.
@include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `GET` | `/catalog/service/:service` | `application/json` |
| Method | Path | Produces |
| ------ | -------------------------------- | ------------------ |
| `GET` | `/catalog/service/:service_name` | `application/json` |
The table below shows this endpoint's support for
[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` |
### Parameters
### Path Parameters
- `service` `(string: <required>)` - Specifies the name of the service for which
to list nodes. This is specified as part of the URL.
- `service_name` `(string: <required>)` - Specifies the name of the service for which
to list nodes.
### 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 parameter.
the datacenter of the agent being queried.
- `tag` `(string: "")` **Deprecated** - Use `filter` with the `ServiceTags` selector instead.
This parameter will be removed in a future version of Consul.
Specifies the tag to filter on. This is specified as part of
the URL as a query parameter. Can be used multiple times for additional filtering,
Specifies the tag to filter on.
Can be used multiple times for additional filtering,
returning only the results that include all of the tag values provided.
- `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
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
`?near=_agent` uses the agent's node for the sort.
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `NodeMeta` selector instead.
This parameter will be removed in a future version of Consul.
Specifies a desired node metadata key/value pair
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
specified as part of the URL as a query parameter.
filters the results to nodes with the specified key/value pairs.
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to use for the
query. 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 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 services you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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` |
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
@ -672,9 +668,9 @@ This endpoint returns the node's registered services.
@include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces |
| ------ | --------------------- | ------------------ |
| `GET` | `/catalog/node/:node` | `application/json` |
| Method | Path | Produces |
| ------ | -------------------------- | ------------------ |
| `GET` | `/catalog/node/:node_name` | `application/json` |
The table below shows this endpoint's support for
[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` |
### Parameters
### Path Parameters
- `node` `(string: <required>)` - Specifies the name of the node for which
to list services. This is specified as part of the URL.
- `node_name` `(string: <required>)` - Specifies the name of the node to list services for.
### 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 parameter.
the datacenter of the agent being queried.
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
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 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 services you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -803,9 +797,9 @@ This endpoint returns the node's registered services.
@include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces |
| ------ | ------------------------------ | ------------------ |
| `GET` | `/catalog/node-services/:node` | `application/json` |
| Method | Path | Produces |
| ------ | ----------------------------------- | ------------------ |
| `GET` | `/catalog/node-services/:node_name` | `application/json` |
The table below shows this endpoint's support for
[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` |
### Parameters
### Path Parameters
- `node` `(string: <required>)` - Specifies the name of the node for which
to list services. This is specified as part of the URL.
- `node_name` `(string: <required>)` - Specifies the name of the node to list services for.
### 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 parameter.
the datacenter of the agent being queried.
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
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 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
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
@ -953,20 +945,18 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `service:read` |
### Parameters
### Path Parameters
- `gateway` `(string: <required>)` - Specifies the name of the node for which
to list services. This is specified as part of the URL.
- `gateway` `(string: <required>)` - Specifies the name of the node to list services for.
- `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 parameter.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the gateway.
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 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.
- `dc` `(string: "")` - Specifies the datacenter to query.
This parameter defaults to the datacenter of the agent being queried.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
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
@ -1075,3 +1065,15 @@ $ curl \
- `FromWildcard` determines whether the service was associated with the gateway by providing a wildcard specifier
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).
### 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 parameter.
- `dc` `(string: "")` - Specifies the datacenter to query.
This parameter defaults to the datacenter of the agent being queried.
- `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
non-zero, the entry is only set if the current index matches the `ModifyIndex`
of that entry.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace the config
entry will apply to. 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 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 entry you apply.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path 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 parameter.
- `kind` `(string: <required>)` - Specifies the kind of the entry to read.
- `kind` `(string: <required>)` - Specifies the kind of the entry to read. This
is specified as part of the URL.
- `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
- `name` `(string: <required>)` - Specifies the name of the entry to read.
The name of the `proxy-defaults` config entry
must be `global`, and the name of the `mesh` config entry must be `mesh`.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
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
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query.
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
@ -192,19 +186,17 @@ The table below shows this endpoint's support for
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
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.
- `kind` `(string: <required>)` - Specifies the kind of the entry to list. This
is specified as part of the URL.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
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
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
- `dc` `(string: "")` - Specifies the datacenter to query.
This parameter defaults to the datacenter of the agent being queried.
- `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
@ -268,29 +260,26 @@ The table below shows this endpoint's support for
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
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.
- `kind` `(string: <required>)` - Specifies the kind of the entry to delete. This
is specified as part of the URL.
- `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
- `name` `(string: <required>)` - Specifies the name of the entry to delete.
The name of the `proxy-defaults` config entry
must be `global`, and the name of the `mesh` config entry must be `mesh`.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to delete from.
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 the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query.
This parameter defaults to the datacenter of the agent being queried.
- `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
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
specified as part of the URL as a query parameter.
deleted if the index matches the `ModifyIndex` of that config entry.
- `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
@ -299,3 +288,13 @@ $ curl \
--request DELETE \
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` |
### Parameters
### Query Parameters
- `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
@ -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).
### Parameters
### JSON Request Body Schema
- `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).
### URL Parameters
### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `source` `(string: <required>)` - Specifies the source service
according to the [source naming conventions](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service
according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `source` or `destination` parameters lack namespaces.
If not provided, the default namespace will be inherited from the
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
to use when `source` or `destination` query parameters do not include a namespace
as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### PUT Body Parameters
### JSON Request Body Schema
- `SourceType` `(string: "")` - The type for the `SourceName` value.
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).
### URL Parameters
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `SourceNS` or `DestinationNS` are omitted or empty.
If not provided, the default namespace will be inherited from the
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
to use when `SourceNS` or `DestinationNS` request body parameters do not include a namespace
as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### POST Body Parameters
### JSON Request Body Schema
- `SourceName` `(string: <required>)` - The source of the intention.
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
`SourceName` parameter.
- `DestinationName` `(string: <required>)` - The destination of the intention.
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
`DestinationName` parameter.
@ -265,12 +257,12 @@ The table below shows this endpoint's support for
for more details.
</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
is specified as part of the URL.
### Path Parameters
- Other parameters are identical to creating an intention.
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update.
### 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).
### Parameters
### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `source` `(string: <required>)` - Specifies the source service
according to the [source naming conventions](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service
according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `source` or `destination` parameters lack namespaces.
If not provided, the default namespace will be inherited from the
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
to use when `source` or `destination` query parameters do not include a namespace
as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
is specified as part of the URL.
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read.
### 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).
### Parameters
### Query Parameters
- `filter` `(string: "")` - Specifies the expression used to filter the
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
namespace to list intentions from.
The `*` wildcard may be used to list intentions from all namespaces.
If not provided, the default namespace will be inherited from the
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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `source` `(string: <required>)` - Specifies the source service
according to the [source naming conventions](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service
according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `source` or `destination` parameters lack namespaces.
If not provided, the default namespace will be inherited from the
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
to use when `source` or `destination` query parameters do not include a namespace
as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to delete. This
is specified as part of the URL.
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to delete.
### 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).
### Parameters
### Query Parameters
- `source` `(string: <required>)` - Specifies the source service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `source` `(string: <required>)` - Specifies the source service
according to the [source naming conventions](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service. This
is specified as part of the URL.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `destination` `(string: <required>)` - Specifies the destination service
according to the [destination naming conventions](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `source` or `destination` parameters lack namespaces.
If not provided, the default namespace will be inherited from the
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
to use when `source` or `destination` query parameters do not include a namespace
as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### Parameters
### Query Parameters
- `by` `(string: <required>)` - Specifies whether to match the "name" value
by "source" or "destination".
- `name` `(string: <required>)` - Specifies a name to match. This parameter
can be repeated for batching multiple matches.
This can take [several forms](/commands/intention#source-and-destination-naming).
- `name` `(string: <required>)` - Specifies a name to match
according to the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
You can repeat this parameter for batching multiple matches.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
namespace to use when `name` parameter lacks namespaces.
If not provided, the default namespace will be inherited from the
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default namespace
to use when the `name` query parameter does not include a namespace
as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming).
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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

27
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).
### 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 parameter.
the datacenter of the agent being queried.
- `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
the agent's own segment when connecting to a client (clients can only be part of one
@ -139,9 +139,9 @@ segment.
This endpoint returns the LAN network coordinates for the given node.
| Method | Path | Produces |
| ------ | ------------------------ | ------------------ |
| `GET` | `/coordinate/node/:node` | `application/json` |
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `GET` | `/coordinate/node/:node_name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
@ -153,11 +153,15 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ |
| `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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
the datacenter of the agent being queried.
- `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
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` |
### 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 parameter.
the datacenter of the agent being queried.
### Sample Payload

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

@ -26,10 +26,10 @@ Management](/docs/connect/l7-traffic).
If overrides are needed they are passed as the JSON-encoded request body and
the `POST` method must be used, otherwise `GET` is sufficient.
| Method | Path | Produces |
| ------------------ | --------------------------- | ------------------ |
| `GET` | `/discovery-chain/:service` | `application/json` |
| `POST`<sup>1</sup> | `/discovery-chain/:service` | `application/json` |
| Method | Path | Produces |
| ------------------ | -------------------------------- | ------------------ |
| `GET` | `/discovery-chain/:service_name` | `application/json` |
| `POST`<sup>1</sup> | `/discovery-chain/:service_name` | `application/json` |
<p>
<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` |
### URL Parameters
### Path Parameters
- `service` `(string: <required>)` - Specifies the service to query when
compiling the discovery chain. This is provided as part of the URL.
- `service_name` `(string: <required>)` - Specifies the service to query when
compiling the discovery chain.
### Query Parameters
- `compile-dc` `(string: "")` - Specifies the datacenter to use as the basis of
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
configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
[`datacenter`](/docs/connect/registration/service-registration#datacenter)
parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the source namespace
to use as the basis of compilation. 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the source namespace you use as the basis of compilation.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### POST Body Parameters
### JSON Request Body Schema
- `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect
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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the event to fire. This
is specified as part of the URL. This name must not start with an underscore,
- `name` `(string: <required>)` - Specifies the name of the event to fire.
This name must not start with an underscore,
since those are reserved for Consul internally.
### 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 parameter.
the datacenter of the agent being queried.
- `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
name. This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service name.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag.
### Sample Payload
@ -109,19 +107,15 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `none` | `none` | `event:read` |
### Parameters
### Query Parameters
- `name` `(string: <required>)` - Specifies the name of the event to filter.
This is specified as part of the URL as a query parameter.
- `name` `(string: "")` - Specifies the name of the event to filter.
- `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
name. This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service name.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag.
### 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` |
### Parameters
### Path Parameters
- `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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
the datacenter of the agent being queried.
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list checks.
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 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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the checks you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -131,32 +128,30 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------------------ |
| `YES` | `all` | `none` | `node:read,service:read` |
### Parameters
### Path Parameters
- `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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
the datacenter of the agent being queried.
- `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
`?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.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
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.
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `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
`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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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>
</p>
### Parameters
### Path Parameters
- `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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
the datacenter of the agent being queried.
- `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
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter. **Note** that using `near` will ignore
`?near=_agent` uses the agent's node for the sort.
**Note** that using `near` will ignore
[`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
to the streaming backend.
- `tag` `(string: "")` **Deprecated** - Use `filter` with the `Service.Tags` selector instead.
This parameter will be removed in a future version of Consul.
Specifies the tag to filter the list. This is
specified as part of the URL as a query parameter. Can be used multiple times
for additional filtering, returning only the results that include all of the tag
values provided.
Specifies the tag to filter the list.
You can use this parameter multiple times to
return only the results that include all of the tag values provided.
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Node.Meta` selector instead.
This parameter will be removed in a future version of Consul.
Specifies a desired node metadata key/value pair
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
specified as part of the URL as a query parameter.
filters the results to nodes with the specified key/value pairs.
- `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
@ -267,9 +260,7 @@ The table below shows this endpoint's support for
queries results prior to returning the data.
- `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
`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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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
endpoint does not support the [streaming backend](/api-docs/features/blocking#streaming-backend).
## List Checks in State
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` |
### Parameters
### Path Parameters
- `state` `(string: <required>)` - Specifies the state to query. Supported states
are `any`, `passing`, `warning`, or `critical`. The `any` state is a wildcard
that can be used to return all checks.
### 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 parameter.
the datacenter of the agent being queried.
- `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
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
`?near=_agent` uses the agent's node for the sort.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
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
specified as part of the URL as a query parameter.
filters the results to nodes with the specified key/value pairs.
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
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 the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -546,3 +533,13 @@ the following selectors and filter operations being supported:
| `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
| `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).
### Parameters
### Path Parameters
- `key` `(string: "")` - Specifies the path of the key to read.
### 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 parameter.
the datacenter of the agent being queried.
- `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
part of the URL as a query parameter.
treat `key` as a prefix instead of a literal match.
- `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
a query parameter.
key, without any encoding or metadata.
- `keys` `(bool: false)` - Specifies to return only keys (no values or
metadata). Specifying this implies `recurse`. This is specified as part of the
URL as a query parameter.
metadata). Specifying this parameter implies `recurse`.
- `separator` `(string: "")` - Specifies the string to use as a separator
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.
This is specified as part of the URL as a query parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
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 '\*' and then results
will be returned for all namespaces. Added in Consul 1.7.0.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
For recursive lookups, the namespace may be specified as '\*'
to return results for all namespaces.
### Sample Request
@ -126,7 +122,7 @@ $ curl \
- `Key` is simply the full path of the 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.
@ -183,17 +179,18 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul kv put`](/commands/kv/put).
### Parameters
### Path Parameters
- `key` `(string: "")` - Specifies the path of the key.
- `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 parameter.
### Query Parameters
- `flags` `(int: 0)` - Specifies an unsigned value between `0` and `(2^64)-1`.
Clients can choose to use this however makes sense for their application. This
is specified as part of the URL as a query parameter.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried.
- `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
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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).
### 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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter, and gives "No path to datacenter" error when dc is
invalid.
the datacenter of the agent being queried. If the DC is invalid,
the error "No path to datacenter" is returned.
- `recurse` `(bool: false)` - Specifies to delete all keys which have the
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -306,3 +302,13 @@ $ curl \
```json
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).
### Parameters
### JSON Request Body Schema
- `Name` `(string: <required>)` - The namespaces name. This must be a valid
DNS hostname label.
- `Name` `(string: <required>)` - The namespace's name.
This field must be a valid DNS hostname label.
- `Description` `(string: "")` - Free form namespaces description.
@ -106,7 +106,7 @@ $ curl --request PUT \
http://127.0.0.1:8500/v1/namespace
```
### SampleResponse
### Sample Response
```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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the namespace to read. This
is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the namespace to read.
### 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
```
### SampleResponse
### Sample Response
```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).
### Parameters
### Path Parameters
- `Name` `(string: <optional>)` - The namespaces name. This must be a valid
DNS hostname label. If present in the payload it must match what was given
in the URL path.
- `name` `(string: <required>)` - The namespaces name. This must be a valid DNS hostname label.
### 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.
@ -308,7 +310,7 @@ $ curl --request PUT \
http://127.0.0.1:8500/v1/namespace/team-1
```
### SampleResponse
### Sample Response
```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).
### Parameters
### Path Parameters
- `name` `(string: <required>)` - Specifies the namespace to delete. This
is required and is specified as part of the URL path.
- `name` `(string: <required>)` - Specifies the namespace to delete.
### 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).
### 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 a URL query
parameter.
the datacenter of the agent being queried.
### JSON Request Body Schema
- `PeerDatacenter` `(string: <required>)` - Specifies the name of the Consul
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).
### 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 a URL query
parameter.
the datacenter of the agent being queried.
### 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).
### 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 a URL query
parameter.
the datacenter of the agent being queried.
### JSON Request Body Schema
- `UseTLS` `(bool: <optional>)` - Specifies whether gossip over this area should be
encrypted with TLS if possible.
@ -204,14 +205,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- |
| `YES` | `all` | `none` | `operator:read` |
### Parameters
### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This
is specified as part of the URL.
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list.
### Query Parameters
- `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
parameter.
the datacenter of the agent being queried.
### 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).
### Parameters
### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to delete. This
is specified as part of the URL.
- `uuid` `(string: <required>)` - Specifies the UUID of the area to delete.
### Query Parameters
- `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
parameter.
the datacenter of the agent being queried.
### 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).
### Parameters
### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to join. This
is specified as part of the URL.
- `uuid` `(string: <required>)` - Specifies the UUID of the area to join.
### Query Parameters
- `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
parameter.
the datacenter of the agent being queried.
### 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).
### Parameters
### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This
is specified as part of the URL.
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list.
### Query Parameters
- `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
parameter.
the datacenter of the agent being queried.
### 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).
### 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.
the datacenter of the agent being queried.
- `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
@ -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).
### 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.
the datacenter of the agent being queried.
- `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
at the time of writing.
### JSON Request Body Schema
- `CleanupDeadServers` `(bool: true)` - Specifies automatic removal of dead
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` |
### 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.
the datacenter of the agent being queried.
### 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).
### 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.
the datacenter of the agent being queried.
### 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).
### Parameters
### Query Parameters
- `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
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
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
@ -124,12 +124,13 @@ The table below shows this endpoint's support for
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
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`.
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
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).
### Parameters
### Query Parameters
- `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
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
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).
### Parameters
### Query Parameters
- `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
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.

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).
### Parameters
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter whose license should be retrieved.
This will default to the datacenter of the agent serving the HTTP request.
This is specified as a URL query parameter.
### 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).
### Parameters
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter whose license should be updated.
This will default to the datacenter of the agent serving the HTTP request.
This is specified as a URL query parameter.
### 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).
### Parameters
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter whose license should be updated.
This will default to the datacenter of the agent serving the HTTP request.
This is specified as a URL query parameter.
### 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` |
### 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.
- `dc` `(string: "")` - Specifies the datacenter to query.
This parameter defaults to the datacenter of the agent being queried.
- `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
@ -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).
### 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.
### Query Parameters
- `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
```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` |
### 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 a URL query
parameter.
the datacenter of the agent being queried.
### 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.
- `${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:
```json
@ -150,11 +150,12 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `query:write` |
### 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 parameter.
the datacenter of the agent being queried.
### JSON Request Body Schema
- `Name` `(string: "")` - Specifies an optional friendly name that can be used
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` |
### 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 parameter.
the datacenter of the agent being queried.
### Sample Request
@ -378,14 +378,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `query:write` |
### Parameters
### Path Parameters
- `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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
the datacenter of the agent being queried.
The body is the same as is used to create a prepared query. Please see above for
more information.
@ -418,14 +418,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `all` | `none` | `query:read` |
### Parameters
### Path Parameters
- `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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
the datacenter of the agent being queried.
### Sample Request
@ -458,14 +458,14 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `query:write` |
### Parameters
### Path Parameters
- `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
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
the datacenter of the agent being queried.
### 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.
### Parameters
### Path Parameters
- `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
the name of an existing prepared query, or a name that matches a prefix name
for a prepared query template.
This parameter can also be the name of an existing prepared query,
or a name that matches a prefix name for a prepared query template.
### 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 parameter.
the datacenter of the agent being queried.
- `near` `(string: "")` - Specifies to sort the resulting list in ascending
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.
- `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
template documentation for more information.
@ -627,16 +627,16 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `all` | `none` | `query:read` |
### Parameters
### Path Parameters
- `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
the name of an existing prepared query, or a name that matches a prefix name
for a prepared query template.
This parameter can also be the name of an existing prepared query,
or a name that matches a prefix name for a prepared query template.
### 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 parameter.
the datacenter of the agent being queried.
### 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` |
### Parameters
### Query Parameters
<!-- What's the relationship to ServiceChecks[].Namespace (if any)? -->
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
- `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 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
must be greater than `0`.
- `Node` `(string: "<agent>")` - Specifies the name of the node. This must refer
to a node that is already registered.
- `Node` `(string: "<agent>")` - Specifies the name of the node.
This field must refer to a node that is already registered.
- `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` |
### Parameters
### Path Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to destroy.
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
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.
the datacenter of the agent being queried.
Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -182,19 +183,18 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` |
### Parameters
### Path Parameters
- `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
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.
### Query Parameters
- `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.
If not provided, the namespace will be inferred from the request's ACL token,
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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
@ -246,21 +246,20 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` |
### Parameters
### Path Parameters
- `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
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.
the datacenter of the agent being queried.
Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
The namespace may be specified as '\*' and then results will be returned for all namespaces.
Added in Consul 1.7.0.
### Sample Request
@ -310,17 +309,16 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` |
### 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 parameter. Using this across datacenters is not recommended.
the datacenter of the agent being queried.
Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
or will default to the `default` namespace. This is specified as part of the URL as a query parameter.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
The namespace may be specified as '\*' and then results will be returned for all namespaces.
Added in Consul 1.7.0.
### Sample Request
@ -369,19 +367,18 @@ The table below shows this endpoint's support for
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `session:write` |
### Parameters
### Path Parameters
- `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
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.
the datacenter of the agent being queried.
Using this parameter across datacenters is not recommended.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
If not provided, the namespace will be inferred from the request's ACL token,
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.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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.
## 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).
### 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 parameter.
to the datacenter of the agent being queried.
- `stale` `(bool: false)` - Specifies that any follower may reply. By default
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
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 |
| :----- | :---------- | ----------------------------- |
| `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).
### 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 parameter.
to the datacenter of the agent being queried.
### Request Body
The body of the request should be a snapshot archive returned by a previous
call to [generate snapshot](#generate-snapshot).
### 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` |
### 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 parameter.
the datacenter of the agent being queried.
### 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).
### 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 parameter.
the datacenter of the agent being queried.
### 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.
</p>
### 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 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:
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.