Config Entry docs (#5734)
* Add api docs for the config entry endpoints * Add enable_central_service_config field to agent docs * Add docs for config entry CLI operations * Fix wording and links in config entry docs * Add links to the central service config option * Update the central service config setting description.
This commit is contained in:
Kyle Havlovitz
Jack Pearkes
parent
9c77f2c52a
commit
1de73ff037
|
|
@ -0,0 +1,249 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Config - HTTP API
|
||||
sidebar_current: api-config
|
||||
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.html#enable_central_service_config)
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services.
|
||||
|
||||
## 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.html),
|
||||
[consistency modes](/api/features/consistency.html),
|
||||
[agent caching](/api/features/caching.html), and
|
||||
[required ACLs](/api/index.html#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 updated:
|
||||
|
||||
| Config Entry Kind | Required ACL |
|
||||
| ----------------- | ---------------- |
|
||||
| service-defaults | `service:write` |
|
||||
| proxy-defaults | `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.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
|
||||
```javascript
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```sh
|
||||
$ 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.html),
|
||||
[consistency modes](/api/features/consistency.html),
|
||||
[agent caching](/api/features/caching.html), and
|
||||
[required ACLs](/api/index.html#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 |
|
||||
| ----------------- | ---------------- |
|
||||
| service-defaults | `service:read` |
|
||||
| proxy-defaults | `<none>` |
|
||||
|
||||
### 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.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```sh
|
||||
$ curl \
|
||||
--request GET \
|
||||
http://127.0.0.1:8500/v1/config/service-defaults/web
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": true
|
||||
},
|
||||
"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.html),
|
||||
[consistency modes](/api/features/consistency.html),
|
||||
[agent caching](/api/features/caching.html), and
|
||||
[required ACLs](/api/index.html#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 |
|
||||
| ----------------- | ---------------- |
|
||||
| service-defaults | `service:read` |
|
||||
| proxy-defaults | `<none>` |
|
||||
|
||||
### 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.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```sh
|
||||
$ curl \
|
||||
--request GET \
|
||||
http://127.0.0.1:8500/v1/config/service-defaults
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
"Name": "db",
|
||||
"Protocol": "tcp",
|
||||
"Connect": {
|
||||
"SidecarProxy": false
|
||||
},
|
||||
"CreateIndex": 16,
|
||||
"ModifyIndex": 16
|
||||
},
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": true
|
||||
},
|
||||
"CreateIndex": 13,
|
||||
"ModifyIndex": 13
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Delete Configuration
|
||||
|
||||
This endpoint creates or updates 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.html),
|
||||
[consistency modes](/api/features/consistency.html),
|
||||
[agent caching](/api/features/caching.html), and
|
||||
[required ACLs](/api/index.html#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 |
|
||||
| ----------------- | ---------------- |
|
||||
| service-defaults | `service:write` |
|
||||
| proxy-defaults | `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.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```sh
|
||||
$ curl \
|
||||
--request DELETE \
|
||||
http://127.0.0.1:8500/v1/config/service-defaults/web
|
||||
```
|
||||
|
|
@ -1110,6 +1110,14 @@ default will automatically work with some tooling.
|
|||
`server_name`) to set up the client for HTTP or gRPC health checks. This allows services requiring 2-way TLS to
|
||||
be checked using the agent's credentials. This was added in Consul 1.0.1 and defaults to false.
|
||||
|
||||
* <a name="enable_central_service_config"></a><a href="#enable_central_service_config">`enable_central_service_config`</a>
|
||||
When set, the Consul agent will look for any centralized service configurations that match a registering service instance.
|
||||
If it finds any, the agent will merge the centralized defaults with the service instance configuration. This allows for
|
||||
things like service protocol or proxy configuration to be defined centrally and inherited by any
|
||||
affected service registrations.
|
||||
|
||||
|
||||
|
||||
* <a name="enable_debug"></a><a href="#enable_debug">`enable_debug`</a> When set, enables some
|
||||
additional debugging features. Currently, this is only used to access runtime profiling HTTP endpoints, which
|
||||
are available with an `operator:read` ACL regardles of the value of `enable_debug`.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Config"
|
||||
sidebar_current: "docs-commands-config"
|
||||
---
|
||||
|
||||
# Consul Config
|
||||
|
||||
Command: `consul config`
|
||||
|
||||
The `config` command is used to interact with Consul's central configuration
|
||||
system. It exposes commands for creating, updating, reading, and deleting
|
||||
different kinds of config entries. See the
|
||||
[agent configuration](/docs/agent/options.html#enable_central_service_config)
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul config <subcommand>`
|
||||
|
||||
For the exact documentation for your Consul version, run `consul config -h` to view
|
||||
the complete list of subcommands.
|
||||
|
||||
```text
|
||||
Usage: consul config <subcommand> [options] [args]
|
||||
|
||||
This command has subcommands for interacting with Consul's centralized
|
||||
configuration system. Here are some simple examples, and more detailed
|
||||
examples are available in the subcommands or the documentation.
|
||||
|
||||
Write a config:
|
||||
|
||||
$ consul config write web.serviceconf.hcl
|
||||
|
||||
Read a config:
|
||||
|
||||
$ consul config read -kind service-defaults -name web
|
||||
|
||||
List all configs for a type:
|
||||
|
||||
$ consul config list -kind service-defaults
|
||||
|
||||
Delete a config:
|
||||
|
||||
$ consul config delete -kind service-defaults -name web
|
||||
|
||||
For more examples, ask for subcommand help or view the documentation.
|
||||
```
|
||||
|
||||
For more information, examples, and usage about a subcommand, click on the name
|
||||
of the subcommand in the sidebar.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Config Delete"
|
||||
sidebar_current: "docs-commands-config-delete"
|
||||
---
|
||||
|
||||
# Consul Config Delete
|
||||
|
||||
Command: `consul config delete`
|
||||
|
||||
The `config delete` command deletes the configuration entry
|
||||
specified by the kind and name. See the
|
||||
[agent configuration](/docs/agent/options.html#enable_central_service_config)
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul config delete [options]`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### Config Delete Options
|
||||
|
||||
* `-kind` - Specifies the kind of the config entry to read.
|
||||
|
||||
* `-name` - Specifies the name of the config entry to read.
|
||||
|
||||
## Examples
|
||||
|
||||
$ consul config delete -kind service-defaults -name web
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Config List"
|
||||
sidebar_current: "docs-commands-config-list"
|
||||
---
|
||||
|
||||
# Consul Config List
|
||||
|
||||
Command: `consul config list`
|
||||
|
||||
The `config list` command lists all given config entries of the given kind.
|
||||
See the
|
||||
[agent configuration](/docs/agent/options.html#enable_central_service_config)
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul config list [options]`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### Config List Options
|
||||
|
||||
* `-kind` - Specifies the kind of the config entry to read.
|
||||
|
||||
## Examples
|
||||
|
||||
$ consul config list -kind service-defaults
|
||||
billing
|
||||
db
|
||||
web
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Config Read"
|
||||
sidebar_current: "docs-commands-config-read"
|
||||
---
|
||||
|
||||
# Consul Config Read
|
||||
|
||||
Command: `consul config read`
|
||||
|
||||
The `config read` command reads the config entry specified by the given
|
||||
kind and name and outputs its JSON representation. See the
|
||||
[agent configuration](/docs/agent/options.html#enable_central_service_config)
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul config read [options]`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### Config Read Options
|
||||
|
||||
* `-kind` - Specifies the kind of the config entry to read.
|
||||
|
||||
* `-name` - Specifies the name of the config entry to read.
|
||||
|
||||
## Examples
|
||||
|
||||
$ consul config read -kind service-defaults -name web
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": false
|
||||
},
|
||||
"CreateIndex": 13,
|
||||
"ModifyIndex": 13
|
||||
}
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Config Write"
|
||||
sidebar_current: "docs-commands-config-write"
|
||||
---
|
||||
|
||||
# Consul Config Write
|
||||
|
||||
Command: `consul config write`
|
||||
|
||||
The `config write` command creates or updates a centralized config entry.
|
||||
See the
|
||||
[agent configuration](/docs/agent/options.html#enable_central_service_config)
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul config write [options] FILE`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### Config Write Options
|
||||
|
||||
* `-cas` - 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.
|
||||
|
||||
## Examples
|
||||
|
||||
From file:
|
||||
|
||||
$ consul config write web-defaults.json
|
||||
|
||||
From stdin:
|
||||
|
||||
$ consul config write -
|
||||
|
||||
|
||||
### Config Entry examples
|
||||
|
||||
All config entries must have a `Kind` when registered. Currently, the only
|
||||
supported types are `service-defaults` and `proxy-defaults`.
|
||||
|
||||
#### Service defaults
|
||||
|
||||
Service defaults control default global values for a service, such as the
|
||||
protocol and Connect fields.
|
||||
|
||||
```json
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* `Name` - Sets the name of the config entry. For service defaults, this must be
|
||||
the name of the service being configured.
|
||||
|
||||
* `Protocol` - Sets the protocol of the service. This is used by Connect proxies
|
||||
for things like observability features.
|
||||
|
||||
* `Connect` - This block contains Connect-related fields for the service.
|
||||
|
||||
* `SidecarProxy` - Sets whether or not instances of this service should get a
|
||||
sidecar proxy by default.
|
||||
|
||||
#### Proxy defaults
|
||||
|
||||
Proxy defaults allow for configuring global config defaults across all services
|
||||
for Connect proxy config. Currently, only one global entry is supported.
|
||||
|
||||
```json
|
||||
{
|
||||
"Kind": "proxy-defaults",
|
||||
"Name": "global",
|
||||
"Config": {
|
||||
"foo": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* `Name` - Sets the name of the config entry. Currently, only a single `proxy-defaults`
|
||||
entry with the name `global` is supported.
|
||||
|
||||
|
||||
* `Config` - An arbitrary map of configuration values used by Connect proxies.
|
||||
|
|
@ -55,6 +55,9 @@
|
|||
<li<%= sidebar_current("api-catalog") %>>
|
||||
<a href="/api/catalog.html">Catalog</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-config") %>>
|
||||
<a href="/api/config.html">Config</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-connect") %>>
|
||||
<a href="/api/connect.html">Connect</a>
|
||||
<ul class="nav">
|
||||
|
|
|
|||
|
|
@ -101,6 +101,23 @@
|
|||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-config") %>>
|
||||
<a href="/docs/commands/config.html">config</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-commands-config-delete") %>>
|
||||
<a href="/docs/commands/config/delete.html">delete</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-config-list") %>>
|
||||
<a href="/docs/commands/config/list.html">list</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-config-read") %>>
|
||||
<a href="/docs/commands/config/read.html">read</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-config-write") %>>
|
||||
<a href="/docs/commands/config/write.html">write</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-connect") %>>
|
||||
<a href="/docs/commands/connect.html">connect</a>
|
||||
<ul class="nav">
|
||||
|
|
|
|||
Loading…
Reference in New Issue