luxolus/open-consul
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-consul/website/content/api-docs/config.mdx
Jared Kirschner daf5e3ea10 docs: split HTTP API params into sections by type 
Path parameters, query parameters, and request body parameters are now shown in
separate sections rather than combined into one general parameters section.
This makes it much easier to understand quickly where a parameter should be
provided.
2022-05-25 14:45:47 -07:00

301 lines
10 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/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#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#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#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#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
Reference in a new issue View git blame Copy permalink