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 2019-05-01 11:21:11 -07:00 committed by Jack Pearkes
parent 69f902608c
commit 7b16fe3436
9 changed files with 537 additions and 0 deletions

View File

@ -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
```

View File

@ -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 `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. 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 * <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 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`. are available with an `operator:read` ACL regardles of the value of `enable_debug`.

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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
}

View File

@ -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.

View File

@ -55,6 +55,9 @@
<li<%= sidebar_current("api-catalog") %>> <li<%= sidebar_current("api-catalog") %>>
<a href="/api/catalog.html">Catalog</a> <a href="/api/catalog.html">Catalog</a>
</li> </li>
<li<%= sidebar_current("api-config") %>>
<a href="/api/config.html">Config</a>
</li>
<li<%= sidebar_current("api-connect") %>> <li<%= sidebar_current("api-connect") %>>
<a href="/api/connect.html">Connect</a> <a href="/api/connect.html">Connect</a>
<ul class="nav"> <ul class="nav">

View File

@ -101,6 +101,23 @@
</li> </li>
</ul> </ul>
</li> </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") %>> <li<%= sidebar_current("docs-commands-connect") %>>
<a href="/docs/commands/connect.html">connect</a> <a href="/docs/commands/connect.html">connect</a>
<ul class="nav"> <ul class="nav">