207 lines
6.8 KiB
Plaintext
207 lines
6.8 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Configuration Entry Definitions
|
|
sidebar_title: Configuration 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.
|
|
|
|
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.
|
|
|
|
Example:
|
|
|
|
```hcl
|
|
Kind = "<supported kind>"
|
|
Name = "<name of entry>"
|
|
```
|
|
|
|
On Kubernetes, `Kind` is set as the custom resource `kind` and `Name` is set
|
|
as `metadata.name`:
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: <supported kind>
|
|
metadata:
|
|
name: <name of entry>
|
|
```
|
|
|
|
The supported `Kind`/`kind` names for configuration entries are:
|
|
|
|
- [`ingress-gateway`](/docs/agent/config-entries/ingress-gateway) - defines the
|
|
configuration for an ingress gateway
|
|
|
|
- Kubernetes kind: [`IngressGateway`](/docs/agent/config-entries/ingress-gateway)
|
|
|
|
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls
|
|
proxy configuration
|
|
|
|
- Kubernetes kind: [`ProxyDefaults`](/docs/agent/config-entries/proxy-defaults)
|
|
|
|
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
|
|
defaults for all the instances of a given service
|
|
|
|
- Kubernetes kind: [`ServiceDefaults`](/docs/agent/config-entries/service-defaults)
|
|
|
|
- [`service-intentions`](/docs/agent/config-entries/service-intentions) - defines
|
|
the [intentions](/docs/connect/intentions) for a destination service
|
|
|
|
- Kubernetes kind: [`ServiceIntentions`](/docs/agent/config-entries/service-intentions)
|
|
|
|
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
|
|
service instances with a specific Connect upstream discovery requests
|
|
|
|
- Kubernetes kind: [`ServiceResolver`](/docs/agent/config-entries/service-resolver)
|
|
|
|
- [`service-router`](/docs/agent/config-entries/service-router) - defines
|
|
where to send layer 7 traffic based on the HTTP route
|
|
|
|
- Kubernetes kind: [`ServiceRouter`](/docs/agent/config-entries/service-router)
|
|
|
|
- [`service-splitter`](/docs/agent/config-entries/service-splitter) - defines
|
|
how to divide requests for a single HTTP route based on percentages
|
|
|
|
- Kubernetes kind: [`ServiceSplitter`](/docs/agent/config-entries/service-splitter)
|
|
|
|
- [`terminating-gateway`](/docs/agent/config-entries/terminating-gateway) - defines the
|
|
services associated with terminating gateway
|
|
- Kubernetes kind: [`TerminatingGateway`](/docs/agent/config-entries/terminating-gateway)
|
|
|
|
## 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/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/options#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 - `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:
|
|
|
|
```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/options#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.
|
|
|
|
## Using Configuration Entries For Service Defaults
|
|
|
|
Outside of Kubernetes, when the agent is
|
|
[configured](/docs/agent/options#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.
|