diff --git a/website/source/api/config.html.md b/website/source/api/config.html.md index d377fc79aa..6a719751a3 100644 --- a/website/source/api/config.html.md +++ b/website/source/api/config.html.md @@ -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: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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 diff --git a/website/source/docs/agent/config_entries.html.md b/website/source/docs/agent/config_entries.html.md new file mode 100644 index 0000000000..8bb1077774 --- /dev/null +++ b/website/source/docs/agent/config_entries.html.md @@ -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 = "" +Name = "" +``` + +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. diff --git a/website/source/docs/agent/options.html.md b/website/source/docs/agent/options.html.md index 7daf14809f..5dadddf2a8 100644 --- a/website/source/docs/agent/options.html.md +++ b/website/source/docs/agent/options.html.md @@ -821,15 +821,14 @@ default will automatically work with some tooling. The following sub-keys are available: - * `bootstrap` - This object allows configuring centralized config entries to be bootstrapped - by the leader. These entries will be reloaded during an agent config reload. + * `bootstrap` + 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: - - * `proxy_defaults` - This object should contain a mapping of config entry names to an opaque proxy configuration mapping. - Currently the only supported name is `global` * `connect` 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. * `enable_central_service_config` - 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. - - * `enable_debug` When set, enables some additional debugging features. Currently, this is only used to access runtime profiling HTTP endpoints, which diff --git a/website/source/docs/commands/config.html.md b/website/source/docs/commands/config.html.md index aa64f830d0..1a95405f02 100644 --- a/website/source/docs/commands/config.html.md +++ b/website/source/docs/commands/config.html.md @@ -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 diff --git a/website/source/docs/commands/config/delete.html.md.erb b/website/source/docs/commands/config/delete.html.md.erb index 240cdf7e6a..99f99077c7 100644 --- a/website/source/docs/commands/config/delete.html.md.erb +++ b/website/source/docs/commands/config/delete.html.md.erb @@ -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 diff --git a/website/source/docs/commands/config/list.html.md.erb b/website/source/docs/commands/config/list.html.md.erb index 4091a64355..c72b67970f 100644 --- a/website/source/docs/commands/config/list.html.md.erb +++ b/website/source/docs/commands/config/list.html.md.erb @@ -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 diff --git a/website/source/docs/commands/config/read.html.md.erb b/website/source/docs/commands/config/read.html.md.erb index 8db78190c6..588ce5daee 100644 --- a/website/source/docs/commands/config/read.html.md.erb +++ b/website/source/docs/commands/config/read.html.md.erb @@ -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 } diff --git a/website/source/docs/commands/config/write.html.md.erb b/website/source/docs/commands/config/write.html.md.erb index c65c264681..bedd00e0da 100644 --- a/website/source/docs/commands/config/write.html.md.erb +++ b/website/source/docs/commands/config/write.html.md.erb @@ -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 - } } ``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 8b959e00d5..7607ba74ab 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -408,6 +408,9 @@ > Configuration + > + Configuration Entries + > Cloud Auto-join