2019-05-08 20:19:37 +00:00
---
2020-04-07 18:55:19 +00:00
layout: docs
2022-09-13 19:45:42 +00:00
page_title: How to Use Configuration Entries
2020-04-07 18:55:19 +00:00
description: >-
2022-09-15 17:10:20 +00:00
Configuration entries define the behavior of Consul service mesh components. Learn how to use the `consul config` command to create, manage, and delete configuration entries.
2019-05-08 20:19:37 +00:00
---
2022-09-13 19:45:42 +00:00
# How to Use Configuration Entries
2019-05-08 20:19:37 +00:00
2019-06-14 05:52:50 +00:00
Configuration entries can be created to provide cluster-wide defaults for
2020-12-16 16:57:43 +00:00
various aspects of Consul.
Outside of Kubernetes, configuration entries can be specified in HCL or JSON using either
`snake_case` or `CamelCase` for key names. On Kubernetes, configuration
entries can be managed by custom resources in YAML.
Outside of Kubernetes, every configuration entry specified in HCL or JSON has at least two fields:
2019-06-14 05:52:50 +00:00
`Kind` and `Name`. Those two fields are used to uniquely identify a
2020-12-16 16:57:43 +00:00
configuration entry. Configuration entries specified as HCL or JSON objects
use either `snake_case` or `CamelCase` for key names.
2019-05-08 20:19:37 +00:00
2022-01-13 21:07:11 +00:00
<CodeBlockConfig heading="Example config specified outside of Kubernetes">
2019-05-08 20:19:37 +00:00
```hcl
Kind = "<supported kind>"
Name = "<name of entry>"
```
2022-01-13 21:07:11 +00:00
</CodeBlockConfig>
2020-12-16 16:57:43 +00:00
On Kubernetes, `Kind` is set as the custom resource `kind` and `Name` is set
as `metadata.name`:
2022-01-13 21:07:11 +00:00
<CodeBlockConfig heading="Example config specified on Kubernetes">
2020-12-16 16:57:43 +00:00
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: <supported kind>
metadata:
name: <name of entry>
```
2022-01-13 21:07:11 +00:00
</CodeBlockConfig>
2021-01-13 20:48:48 +00:00
## Supported Config Entries
2019-05-08 20:19:37 +00:00
2021-01-13 20:48:48 +00:00
See [Service Mesh - Config Entries](/docs/connect/config-entries) for the list
of supported config entries.
2020-12-16 16:57:43 +00:00
## Managing Configuration Entries In Kubernetes
See [Kubernetes Custom Resource Definitions](/docs/k8s/crds).
2019-05-08 20:19:37 +00:00
2020-12-16 16:57:43 +00:00
## Managing Configuration Entries Outside Of Kubernetes
2019-05-08 20:19:37 +00:00
2020-12-16 16:57:43 +00:00
Configuration entries outside of Kubernetes should be managed with the Consul
2022-03-30 21:16:26 +00:00
[CLI](/commands/config) or [API](/api-docs/config). Additionally, as a
2022-03-15 23:13:58 +00:00
convenience for initial cluster bootstrapping, configuration entries can be
2022-01-10 21:13:13 +00:00
specified in all of the Consul servers's
2022-01-11 01:30:50 +00:00
[configuration files](/docs/agent/config/config-files#config_entries_bootstrap)
2019-05-08 20:19:37 +00:00
### Managing Configuration Entries with the CLI
#### Creating or Updating a Configuration Entry
2020-10-14 15:23:05 +00:00
The [`consul config write`](/commands/config/write) command is used to
2019-06-14 05:52:50 +00:00
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.
2019-05-08 20:19:37 +00:00
2021-07-31 01:37:33 +00:00
Example HCL Configuration File:
<CodeBlockConfig filename="proxy-defaults.hcl">
2019-05-08 20:19:37 +00:00
```hcl
Kind = "proxy-defaults"
Name = "global"
Config {
local_connect_timeout_ms = 1000
handshake_timeout_ms = 10000
}
```
2021-07-31 01:37:33 +00:00
</CodeBlockConfig>
2019-05-08 20:19:37 +00:00
Then to apply this configuration, run:
2020-05-19 18:32:38 +00:00
```shell-session
2019-05-08 20:19:37 +00:00
$ consul config write proxy-defaults.hcl
```
2019-06-14 05:52:50 +00:00
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.
2019-05-08 20:19:37 +00:00
#### Reading a Configuration Entry
2020-10-14 15:23:05 +00:00
The [`consul config read`](/commands/config/read) command is used to
2019-06-14 05:52:50 +00:00
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.
2019-05-08 20:19:37 +00:00
Example:
2020-05-19 18:32:38 +00:00
```shell-session
2019-05-08 20:19:37 +00:00
$ consul config read -kind service-defaults -name web
{
"Kind": "service-defaults",
"Name": "web",
"Protocol": "http"
}
```
#### Listing Configuration Entries
2020-10-14 15:23:05 +00:00
The [`consul config list`](/commands/config/list) command is used to
2019-06-14 05:52:50 +00:00
list out all the configuration entries for a given kind.
2019-05-08 20:19:37 +00:00
Example:
2020-05-19 18:32:38 +00:00
```shell-session
2019-05-08 20:19:37 +00:00
$ consul config list -kind service-defaults
web
api
db
```
#### Deleting Configuration Entries
2020-10-14 15:23:05 +00:00
The [`consul config delete`](/commands/config/delete) command is used
2019-06-14 05:52:50 +00:00
to delete an entry by specifying both its `kind` and `name`.
2019-05-08 20:19:37 +00:00
Example:
2020-05-19 18:32:38 +00:00
```shell-session
2019-05-08 20:19:37 +00:00
$ consul config delete -kind service-defaults -name web
```
This command will not output anything when the deletion is successful.
2020-04-23 22:13:18 +00:00
#### Configuration Entry Management with Namespaces <EnterpriseAlert inline />
2020-02-07 20:01:04 +00:00
2020-04-23 22:13:18 +00:00
Configuration entry operations support passing a namespace in
2020-02-07 20:01:04 +00:00
order to isolate the entry to affect only operations within that namespace. This was
added in Consul 1.7.0.
2020-04-06 20:27:35 +00:00
Example:
2020-02-07 20:01:04 +00:00
2020-05-19 18:32:38 +00:00
```shell-session
2020-02-07 20:01:04 +00:00
$ consul config write service-defaults.hcl -namespace foo
```
2020-05-19 18:32:38 +00:00
```shell-session
2020-02-07 20:01:04 +00:00
$ consul config list -kind service-defaults -namespace foo
web
api
```
2019-05-08 20:19:37 +00:00
### Bootstrapping From A Configuration File
2019-09-17 16:22:27 +00:00
Configuration entries can be bootstrapped by adding them [inline to each Consul
2022-01-11 01:30:50 +00:00
server's configuration file](/docs/agent/config/config-files#config_entries). When a
2019-09-17 16:22:27 +00:00
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.