status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/api-docs/config.mdx

302 lines
11 KiB
Plaintext
Raw Blame History

---
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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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` |
The corresponding CLI command is [`consul config write`](/commands/config/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
```json
{
"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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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` |
The corresponding CLI command is [`consul config read`](/commands/config/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.
@include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces |
| ------ | --------------- | ------------------ |
| `GET` | `/config/:kind` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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` |
The corresponding CLI command is [`consul config list`](/commands/config/list).
### 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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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 ` |
The corresponding CLI command is [`consul config delete`](/commands/config/delete).
### 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.
- `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.
### Sample Request
```shell-session
$ curl \
--request DELETE \
http://127.0.0.1:8500/v1/config/service-defaults/web
```
Reference in New Issue View Git Blame Copy Permalink