bc6266cc76
Also document the name of these config entries in the API docs, so that users know how to query for them. And fix the name of mesh on the index page.
286 lines
9.8 KiB
Plaintext
286 lines
9.8 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Config - HTTP API
|
|
description: |-
|
|
The /config endpoints are for managing centralized configuration
|
|
in Consul.
|
|
---
|
|
|
|
# Config HTTP Endpoint
|
|
|
|
The `/config` endpoints create, update, delete and query central configuration
|
|
entries registered with Consul. See the
|
|
[agent configuration](/docs/agent/options#enable_central_service_config)
|
|
for more information on how to enable this functionality for centrally
|
|
configuring services and [configuration entries docs](/docs/agent/config-entries) for a description
|
|
of the configuration entries content.
|
|
|
|
## Apply Configuration
|
|
|
|
This endpoint creates or updates the given config entry.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------- | ------------------ |
|
|
| `PUT` | `/config` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
|
|
| `NO` | `none` | `none` | `service:write`<br />`operator:write`<sup>1</sup> |
|
|
|
|
<p>
|
|
<sup>1</sup> The ACL required depends on the config entry kind being updated:
|
|
</p>
|
|
|
|
| Config Entry Kind | Required ACL |
|
|
| ------------------- | ------------------ |
|
|
| ingress-gateway | `operator:write` |
|
|
| proxy-defaults | `operator:write` |
|
|
| service-defaults | `service:write` |
|
|
| service-intentions | `intentions:write` |
|
|
| service-resolver | `service:write` |
|
|
| service-router | `service:write` |
|
|
| service-splitter | `service:write` |
|
|
| terminating-gateway | `operator:write` |
|
|
|
|
### 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.
|
|
|
|
- `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.
|
|
|
|
### Sample Payload
|
|
|
|
```javascript
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "web",
|
|
"Protocol": "http"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
--data @payload \
|
|
http://127.0.0.1:8500/v1/config
|
|
```
|
|
|
|
## Get Configuration
|
|
|
|
This endpoint returns a specific config entry.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------- | ------------------ |
|
|
| `GET` | `/config/:kind/:name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | -------------------------- |
|
|
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
|
|
|
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
|
|
|
| Config Entry Kind | Required ACL |
|
|
| ------------------- | ----------------- |
|
|
| ingress-gateway | `service:read` |
|
|
| proxy-defaults | `<none>` |
|
|
| service-defaults | `service:read` |
|
|
| service-intentions | `intentions:read` |
|
|
| service-resolver | `service:read` |
|
|
| service-router | `service:read` |
|
|
| service-splitter | `service:read` |
|
|
| terminating-gateway | `service:read` |
|
|
|
|
### 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. 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
|
|
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.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request GET \
|
|
http://127.0.0.1:8500/v1/config/service-defaults/web
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "web",
|
|
"Protocol": "http",
|
|
"CreateIndex": 15,
|
|
"ModifyIndex": 35
|
|
}
|
|
```
|
|
|
|
## List Configurations
|
|
|
|
This endpoint returns all config entries of the given kind.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------- | ------------------ |
|
|
| `GET` | `/config/:kind` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | -------------------------- |
|
|
| `YES` | `all` | `none` | `service:read`<sup>1</sup> |
|
|
|
|
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
|
|
|
| Config Entry Kind | Required ACL |
|
|
| ------------------- | ----------------- |
|
|
| ingress-gateway | `service:read` |
|
|
| proxy-defaults | `<none>` |
|
|
| service-defaults | `service:read` |
|
|
| service-intentions | `intentions:read` |
|
|
| service-resolver | `service:read` |
|
|
| service-router | `service:read` |
|
|
| service-splitter | `service:read` |
|
|
| terminating-gateway | `service:read` |
|
|
|
|
### 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. This
|
|
is specified as part of the URL.
|
|
|
|
- `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.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request GET \
|
|
http://127.0.0.1:8500/v1/config/service-defaults
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "db",
|
|
"Protocol": "tcp",
|
|
"CreateIndex": 16,
|
|
"ModifyIndex": 16
|
|
},
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "web",
|
|
"Protocol": "http",
|
|
"CreateIndex": 13,
|
|
"ModifyIndex": 13
|
|
}
|
|
]
|
|
```
|
|
|
|
## Delete Configuration
|
|
|
|
This endpoint deletes the given config entry.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | --------------------- | ------------------ |
|
|
| `DELETE` | `/config/:kind/:name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
|
|
| `NO` | `none` | `none` | `service:write`<br />`operator:write`<sup>1</sup> |
|
|
|
|
<sup>1</sup> The ACL required depends on the config entry kind being deleted:
|
|
|
|
| Config Entry Kind | Required ACL |
|
|
| ------------------- | ------------------ |
|
|
| ingress-gateway | `operator:write` |
|
|
| proxy-defaults | `operator:write` |
|
|
| service-defaults | `service:write` |
|
|
| service-intentions | `intentions:write` |
|
|
| service-resolver | `service:write` |
|
|
| service-router | `service:write` |
|
|
| service-splitter | `service:write` |
|
|
| terminating-gateway | `operator:write ` |
|
|
|
|
### 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. 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
|
|
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.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
http://127.0.0.1:8500/v1/config/service-defaults/web
|
|
```
|