169 lines
4.9 KiB
Plaintext
169 lines
4.9 KiB
Plaintext
---
|
|
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.
|
|
---
|
|
|
|
# How to Use 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.
|
|
|
|
<CodeBlockConfig heading="Example config specified outside of Kubernetes">
|
|
|
|
```hcl
|
|
Kind = "<supported kind>"
|
|
Name = "<name of entry>"
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
On Kubernetes, `Kind` is set as the custom resource `kind` and `Name` is set
|
|
as `metadata.name`:
|
|
|
|
<CodeBlockConfig heading="Example config specified on Kubernetes">
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: <supported kind>
|
|
metadata:
|
|
name: <name of entry>
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
## Supported Config Entries
|
|
|
|
See [Service Mesh - Config Entries](/docs/connect/config-entries) for the list
|
|
of supported config entries.
|
|
|
|
## Managing Configuration Entries In Kubernetes
|
|
|
|
See [Kubernetes Custom Resource Definitions](/docs/k8s/crds).
|
|
|
|
## Managing Configuration Entries Outside Of Kubernetes
|
|
|
|
Configuration entries outside of Kubernetes should be managed with the Consul
|
|
[CLI](/commands/config) or [API](/api-docs/config). Additionally, as a
|
|
convenience for initial cluster bootstrapping, configuration entries can be
|
|
specified in all of the Consul servers's
|
|
[configuration files](/docs/agent/config/config-files#config_entries_bootstrap)
|
|
|
|
### Managing Configuration Entries with the CLI
|
|
|
|
#### Creating or Updating a Configuration Entry
|
|
|
|
The [`consul config write`](/commands/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:
|
|
|
|
<CodeBlockConfig filename="proxy-defaults.hcl">
|
|
|
|
```hcl
|
|
Kind = "proxy-defaults"
|
|
Name = "global"
|
|
Config {
|
|
local_connect_timeout_ms = 1000
|
|
handshake_timeout_ms = 10000
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
Then to apply this configuration, run:
|
|
|
|
```shell-session
|
|
$ 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`](/commands/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:
|
|
|
|
```shell-session
|
|
$ consul config read -kind service-defaults -name web
|
|
{
|
|
"Kind": "service-defaults",
|
|
"Name": "web",
|
|
"Protocol": "http"
|
|
}
|
|
```
|
|
|
|
#### Listing Configuration Entries
|
|
|
|
The [`consul config list`](/commands/config/list) command is used to
|
|
list out all the configuration entries for a given kind.
|
|
|
|
Example:
|
|
|
|
```shell-session
|
|
$ consul config list -kind service-defaults
|
|
web
|
|
api
|
|
db
|
|
```
|
|
|
|
#### Deleting Configuration Entries
|
|
|
|
The [`consul config delete`](/commands/config/delete) command is used
|
|
to delete an entry by specifying both its `kind` and `name`.
|
|
|
|
Example:
|
|
|
|
```shell-session
|
|
$ consul config delete -kind service-defaults -name web
|
|
```
|
|
|
|
This command will not output anything when the deletion is successful.
|
|
|
|
#### Configuration Entry Management with Namespaces <EnterpriseAlert inline />
|
|
|
|
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:
|
|
|
|
```shell-session
|
|
$ consul config write service-defaults.hcl -namespace foo
|
|
```
|
|
|
|
```shell-session
|
|
$ consul config list -kind service-defaults -namespace foo
|
|
web
|
|
api
|
|
```
|
|
|
|
### Bootstrapping From A Configuration File
|
|
|
|
Configuration entries can be bootstrapped by adding them [inline to each Consul
|
|
server's configuration file](/docs/agent/config/config-files#config_entries). 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.
|