Add some config entry docs (#5808)
* Add some config entry docs * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com> * Get rid of double negative * Some incremental updates * Update the config list docs to not point to service-default related things. * A few more doc updates to get rid of some service-defaults specific linking info in the cli docs * In progress update * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com> * Reword bootstrap section * Update example proxy-defaults config * Finish up the examples section for managing config entries with the CLI * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com> * Use $ for shell command start * Make it very clear that the normal way to manage things is via the API/CLI * Update website/source/docs/agent/options.html.md Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com>
This commit is contained in:
Matt Keeler
GitHub
parent
39a1fc62bb
commit
5385e31fc5
|
|
@ -12,8 +12,9 @@ description: |-
|
|||
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.
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services and [configuration entries docs](/docs/agent/config_entries.html) for a description
|
||||
of the configuration entries content.
|
||||
|
||||
## Apply Configuration
|
||||
|
||||
|
|
@ -46,9 +47,9 @@ The table below shows this endpoint's support for
|
|||
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`
|
||||
- `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
|
||||
|
|
@ -59,9 +60,6 @@ The table below shows this endpoint's support for
|
|||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -106,10 +104,10 @@ The table below shows this endpoint's support for
|
|||
URL as a query parameter.
|
||||
|
||||
- `kind` `(string: <required>)` - Specifies the kind of the entry to read. This
|
||||
is specified as part of the URL.
|
||||
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.
|
||||
is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
|
|
@ -126,9 +124,6 @@ $ curl \
|
|||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": true
|
||||
},
|
||||
"CreateIndex": 15,
|
||||
"ModifyIndex": 35
|
||||
}
|
||||
|
|
@ -166,7 +161,7 @@ The table below shows this endpoint's support for
|
|||
URL as a query parameter.
|
||||
|
||||
- `kind` `(string: <required>)` - Specifies the kind of the entry to list. This
|
||||
is specified as part of the URL.
|
||||
is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
|
|
@ -184,9 +179,6 @@ $ curl \
|
|||
"Kind": "service-defaults",
|
||||
"Name": "db",
|
||||
"Protocol": "tcp",
|
||||
"Connect": {
|
||||
"SidecarProxy": false
|
||||
},
|
||||
"CreateIndex": 16,
|
||||
"ModifyIndex": 16
|
||||
},
|
||||
|
|
@ -194,9 +186,6 @@ $ curl \
|
|||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": true
|
||||
},
|
||||
"CreateIndex": 13,
|
||||
"ModifyIndex": 13
|
||||
}
|
||||
|
|
@ -235,10 +224,10 @@ The table below shows this endpoint's support for
|
|||
URL as a query parameter.
|
||||
|
||||
- `kind` `(string: <required>)` - Specifies the kind of the entry to delete. This
|
||||
is specified as part of the URL.
|
||||
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.
|
||||
is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,160 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Entry Definitions"
|
||||
sidebar_current: "docs-agent-cfg_entries"
|
||||
description: |-
|
||||
Consul allows storing configuration entries centrally to be used as defaults for configuring other aspects of Consul.
|
||||
---
|
||||
|
||||
# Configuration Entries
|
||||
|
||||
Configuration entries can be created to provide cluster-wide defaults for various aspects of Consul. Every configuration
|
||||
entry has at least two fields: `Kind` and `Name`. Those two fields are used to uniquely identify a configuration entry.
|
||||
When put into configuration files, configuration entries can be specified as HCL or JSON objects.
|
||||
|
||||
Example:
|
||||
|
||||
```hcl
|
||||
Kind = "<supported kind>"
|
||||
Name = "<name of entry>"
|
||||
```
|
||||
|
||||
The two supported `Kind` configuration entries are detailed below.
|
||||
|
||||
## Configuration Entry Kinds
|
||||
|
||||
### Proxy Defaults - `proxy-defaults`
|
||||
|
||||
Proxy defaults allow for configuring global config defaults across all services for Connect proxy configuration. Currently,
|
||||
only one global entry is supported.
|
||||
|
||||
```hcl
|
||||
Kind = "proxy-defaults"
|
||||
Name = "global"
|
||||
Config {
|
||||
local_connect_timeout_ms = 1000
|
||||
handshake_timeout_ms = 10000
|
||||
}
|
||||
```
|
||||
|
||||
* `Kind` - Must be set to `proxy-defaults`
|
||||
|
||||
* `Name` - Must be set to `global`
|
||||
|
||||
* `Config` - An arbitrary map of configuration values used by Connect proxies. See
|
||||
|
||||
#### Proxy Configuration References
|
||||
|
||||
* [Consul's Builtin Proxy](/docs/connect/configuration.html#built-in-proxy-options)
|
||||
* [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration)
|
||||
|
||||
### Service Defaults - `service-defaults`
|
||||
|
||||
Service defaults control default global values for a service, such as its protocol.
|
||||
|
||||
```hcl
|
||||
Kind = "service-defaults"
|
||||
Name = "web"
|
||||
Protocol = "http"
|
||||
```
|
||||
|
||||
* `Kind` - Must be set to `service-defaults`
|
||||
|
||||
* `Name` - Set to 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.
|
||||
|
||||
## Managing Configuration Entries
|
||||
|
||||
Configuration entries should be managed with the Consul [CLI](/docs/commands/config.html) or [API](/api/config.html). Additionally,
|
||||
as a convenience for initial cluster bootstrapping, configuration entries can be specified in all of the Consul servers's
|
||||
[configuration files](/docs/agent/options.html#config_entries_bootstrap)
|
||||
|
||||
### Managing Configuration Entries with the CLI
|
||||
|
||||
#### Creating or Updating a Configuration Entry
|
||||
|
||||
The [`consul config write`](/docs/commands/config/write.html) command is used to create and update configuration entries. This command
|
||||
will load either a JSON or HCL file holding the configuration entry definition and then will push this configuration to Consul.
|
||||
|
||||
Example HCL Configuration File - `proxy-defaults.hcl`:
|
||||
|
||||
```hcl
|
||||
Kind = "proxy-defaults"
|
||||
Name = "global"
|
||||
Config {
|
||||
local_connect_timeout_ms = 1000
|
||||
handshake_timeout_ms = 10000
|
||||
}
|
||||
```
|
||||
|
||||
Then to apply this configuration, run:
|
||||
|
||||
```bash
|
||||
$ consul config write proxy-defaults.hcl
|
||||
```
|
||||
|
||||
If you need to make changes to a configuration entry, simple edit that file and then rerun the command.
|
||||
This command will not output anything unless there is an error in applying the configuration entry.
|
||||
The `write` command also supports a `-cas` option to enable performing a compare-and-swap operation to
|
||||
prevent overwriting other unknown modifications.
|
||||
|
||||
#### Reading a Configuration Entry
|
||||
|
||||
The [`consul config read`](/docs/commands/config/read.html) command is used to read the current value of a configuration entry. The
|
||||
configuration entry will be displayed in JSON form which is how its transmitted between the CLI client and Consul's HTTP API.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
$ consul config read -kind service-defaults -name web
|
||||
{
|
||||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http"
|
||||
}
|
||||
```
|
||||
|
||||
#### Listing Configuration Entries
|
||||
|
||||
The [`consul config list`](/docs/commands/config/list.html) command is used to list out all the configuration entries for a
|
||||
given kind.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
$ consul config list -kind service-defaults
|
||||
web
|
||||
api
|
||||
db
|
||||
```
|
||||
|
||||
|
||||
#### Deleting Configuration Entries
|
||||
|
||||
The [`consul config delete`](/docs/commands/config/delete.html) command is used to delete an entry by specifying both its
|
||||
`kind` and `name`.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
$ consul config delete -kind service-defaults -name web
|
||||
```
|
||||
|
||||
This command will not output anything when the deletion is successful.
|
||||
|
||||
### Bootstrapping From A Configuration File
|
||||
|
||||
|
||||
Configuration entries can be bootstrapped by adding them inline to each Consul server’s configuration file. When a server
|
||||
gains leadership, it will attempt to initialize the configuration entries. If a configuration entry does not already exist
|
||||
outside of the servers configuration, then it will create it. If a configuration entry does exist, that matches both `kind`
|
||||
and `name`, then the server will do nothing.
|
||||
|
||||
|
||||
## Using Configuration Entries For Service Defaults
|
||||
|
||||
When the agent is [configured](/docs/agent/options.html#enable_central_service_config) to enable central service configurations,
|
||||
it will look for service configuration defaults that match a registering service instance. If it finds any, the agent will merge
|
||||
those defaults with the service instance configuration. This allows for things like service protocol or proxy configuration to
|
||||
be defined globally and inherited by any affected service registrations.
|
||||
|
|
@ -821,15 +821,14 @@ default will automatically work with some tooling.
|
|||
|
||||
The following sub-keys are available:
|
||||
|
||||
* <a name="bootstrap"></a><a href="#config_entries_bootstrap">`bootstrap`</a>
|
||||
This object allows configuring centralized config entries to be bootstrapped
|
||||
by the leader. These entries will be reloaded during an agent config reload.
|
||||
* <a name="config_entries_bootstrap"></a><a href="#config_entries_bootstrap">`bootstrap`</a>
|
||||
This is a list of inlined config entries to insert into the state store when the Consul server
|
||||
gains leadership. This option is only applicable to server nodes. Each bootstrap
|
||||
entry will be created only if it does not exist. When reloading, any new entries
|
||||
that have been added to the configuration will be processed. See the
|
||||
[configuration entry docs](/docs/agent/config_entries.html) for more details about the
|
||||
contents of each entry.
|
||||
|
||||
The following sub-keys are available:
|
||||
|
||||
* <a name="proxy_defaults"></a><a href="#config_entries_bootstrap_proxy_defaults">`proxy_defaults`</a>
|
||||
This object should contain a mapping of config entry names to an opaque proxy configuration mapping.
|
||||
Currently the only supported name is `global`
|
||||
|
||||
* <a name="connect"></a><a href="#connect">`connect`</a>
|
||||
This object allows setting options for the Connect feature.
|
||||
|
|
@ -1120,12 +1119,10 @@ default will automatically work with some tooling.
|
|||
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -9,11 +9,12 @@ sidebar_current: "docs-commands-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
|
||||
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.
|
||||
for more information on how to enable this functionality for centrally
|
||||
configuring services and [configuration entries docs](/docs/agent/config_entries.html) for a description
|
||||
of the configuration entries content.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
|
|||
|
|
@ -8,11 +8,9 @@ sidebar_current: "docs-commands-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.
|
||||
The `config delete` command deletes the configuration entry specified by the
|
||||
kind and name. See the [configuration entries docs](/docs/agent/config_entries.html)
|
||||
for more details about configuration entries.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
|
|||
|
|
@ -9,10 +9,8 @@ sidebar_current: "docs-commands-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.
|
||||
See the [configuration entries docs](/docs/agent/config_entries.html) for more
|
||||
details about configuration entries.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
|
|||
|
|
@ -8,11 +8,10 @@ sidebar_current: "docs-commands-config-read"
|
|||
|
||||
Command: `consul config read`
|
||||
|
||||
The `config read` command reads the config entry specified by the given
|
||||
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.
|
||||
[configuration entries docs](/docs/agent/config_entries.html) for more
|
||||
details about configuration entries.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -35,9 +34,6 @@ Usage: `consul config read [options]`
|
|||
"Kind": "service-defaults",
|
||||
"Name": "web",
|
||||
"Protocol": "http",
|
||||
"Connect": {
|
||||
"SidecarProxy": false
|
||||
},
|
||||
"CreateIndex": 13,
|
||||
"ModifyIndex": 13
|
||||
}
|
||||
|
|
|
|||
|
|
@ -9,10 +9,8 @@ sidebar_current: "docs-commands-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.
|
||||
See the [configuration entries docs](/docs/agent/config_entries.html) for more
|
||||
details about configuration entries.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -24,9 +22,9 @@ Usage: `consul config write [options] FILE`
|
|||
|
||||
#### 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`
|
||||
* `-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
|
||||
|
|
@ -47,17 +45,14 @@ 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.
|
||||
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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -408,6 +408,9 @@
|
|||
<li<%= sidebar_current("docs-agent-config") %>>
|
||||
<a href="/docs/agent/options.html">Configuration</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-agent-cfg_entries") %>>
|
||||
<a href="/docs/agent/config_entries.html">Configuration Entries</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-agent-cloud-auto-join") %>>
|
||||
<a href="/docs/agent/cloud-auto-join.html">Cloud Auto-join</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue