mirror of https://github.com/status-im/consul.git
301 lines
10 KiB
Plaintext
301 lines
10 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/config/config-files#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-docs/api-structure#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).
|
|
|
|
### 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. 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 of the config entry you apply.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### 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-docs/api-structure#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).
|
|
|
|
### Path Parameters
|
|
|
|
- `kind` `(string: <required>)` - Specifies the kind of the entry to read.
|
|
|
|
- `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`.
|
|
|
|
### 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
|
|
|
|
```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-docs/api-structure#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).
|
|
|
|
### Path Parameters
|
|
|
|
- `kind` `(string: <required>)` - Specifies the kind of the entry to list.
|
|
|
|
### 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 entries you lookup.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### 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-docs/api-structure#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).
|
|
|
|
### Path Parameters
|
|
|
|
- `kind` `(string: <required>)` - Specifies the kind of the entry to delete.
|
|
|
|
- `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`.
|
|
|
|
### 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.
|
|
|
|
- `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
|
|
|
|
```shell-session
|
|
$ 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
|