---
layout: docs
page_title: How to Use Configuration Entries
description: >-
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.
---
Configuration entries can be created to provide cluster-wide defaults for 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:
Kind
and Name
. Those two fields are used to uniquely identify a
configuration entry. Configuration entries specified as HCL or JSON objects
use either snake_case
or CamelCase
for key names.
Kind = "<supported kind>"
Name = "<name of entry>"
On Kubernetes, Kind
is set as the custom resource kind
and Name
is set
as metadata.name
:
apiVersion: consul.hashicorp.com/v1alpha1
kind: <supported kind>
metadata:
name: <name of entry>
See Service Mesh - Config Entries for the list of supported config entries.
See Kubernetes Custom Resource Definitions.
Configuration entries outside of Kubernetes should be managed with the Consul CLI or API. Additionally, as a convenience for initial cluster bootstrapping, configuration entries can be specified in all of the Consul servers's configuration files
The consul config write
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:
Kind = "proxy-defaults"
Name = "global"
Config {
local_connect_timeout_ms = 1000
handshake_timeout_ms = 10000
}
Then to apply this configuration, run:
$ 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.
The consul config read
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:
$ consul config read -kind service-defaults -name web
{
"Kind": "service-defaults",
"Name": "web",
"Protocol": "http"
}
The consul config list
command is used to
list out all the configuration entries for a given kind.
Example:
$ consul config list -kind service-defaults
web
api
db
The consul config delete
command is used
to delete an entry by specifying both its kind
and name
.
Example:
$ consul config delete -kind service-defaults -name web
This command will not output anything when the deletion is successful.
Configuration entry operations support passing a namespace in order to isolate the entry to affect only operations within that namespace. This was added in Consul 1.7.0.
Example:
$ consul config write service-defaults.hcl -namespace foo
$ consul config list -kind service-defaults -namespace foo
web
api
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.