diff --git a/website/content/docs/agent/config-entries.mdx b/website/content/docs/agent/config-entries.mdx index 38025e67a..7a9dfa75d 100644 --- a/website/content/docs/agent/config-entries.mdx +++ b/website/content/docs/agent/config-entries.mdx @@ -20,16 +20,20 @@ Outside of Kubernetes, every configuration entry specified in HCL or JSON has at configuration entry. Configuration entries specified as HCL or JSON objects use either `snake_case` or `CamelCase` for key names. -Example: + ```hcl Kind = "" Name = "" ``` + + On Kubernetes, `Kind` is set as the custom resource `kind` and `Name` is set as `metadata.name`: + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: @@ -37,6 +41,8 @@ metadata: name: ``` + + ## Supported Config Entries See [Service Mesh - Config Entries](/docs/connect/config-entries) for the list diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx index 1d7c76987..c54c1b093 100644 --- a/website/content/docs/agent/index.mdx +++ b/website/content/docs/agent/index.mdx @@ -80,7 +80,7 @@ The [Datacenter Deploy tutorial](https://learn.hashicorp.com/tutorials/consul/re Start a Consul agent with the `consul` command and `agent` subcommand using the following syntax: ```shell-session -consul agent +$ consul agent ``` Consul ships with a `-dev` flag that configures the agent to run in server mode and several additional settings that enable you to quickly get started with Consul. @@ -99,7 +99,7 @@ This enables you to logically group configuration settings into separate files. The following example starts an agent in dev mode and stores agent state data in the `tmp/consul` directory: ```shell-session -consul agent -data-dir=tmp/consul -dev +$ consul agent -data-dir=tmp/consul -dev ``` Agents are highly configurable, which enables you to deploy Consul to any infrastructure. Many of the default options for the `agent` command are suitable for becoming familiar with a local instance of Consul. In practice, however, several additional configuration options must be specified for Consul to function as expected. Refer to [Agent Configuration](/docs/agent/options) topic for a complete list of configuration options. @@ -166,8 +166,8 @@ This is because clients are most commonly used to register services in the Consu The following example starts a Consul agent that takes configuration settings from a file called `server.json` located in the current working directory: -```shell-session -consul agent -config-file=server.json +```shell-session hideClipboard +$ consul agent -config-file=server.json ``` The configuration options necessary to successfully use Consul depend on several factors, including the type of agent you are configuring (client or server), the type of environment you are deploying to (e.g., on-premise, multi-cloud, etc.), and the security options you want to implement (ACLs, gRPC encryption). diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index d6bef6b96..405c8dcaa 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -66,10 +66,9 @@ The options below are all specified on the command-line. state as other nodes will treat the non-routability as a failure. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] template that is resolved at runtime. - + - ```shell - # Using a static network interface name + ```shell-session $ consul agent -advertise '{{ GetInterfaceIP "eth0" }}' ``` @@ -113,21 +112,30 @@ The options below are all specified on the command-line. both. If you have any firewalls, be sure to allow both protocols. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] template that must resolve at runtime to a single address. Some example templates: - ```shell - # Using address within a specific CIDR + + + ```shell-session $ consul agent -bind '{{ GetPrivateInterfaces | include "network" "10.0.0.0/8" | attr "address" }}' ``` - ```shell - # Using a static network interface name + + + + + ```shell-session $ consul agent -bind '{{ GetInterfaceIP "eth0" }}' ``` - ```shell - # Using regular expression matching for network interface name that is forwardable and up + + + + + ```shell-session $ consul agent -bind '{{ GetAllInterfaces | include "name" "^eth" | include "flags" "forwardable|up" | attr "address" }}' ``` + + - `-serf-wan-bind` ((#\_serf_wan_bind)) - The address that should be bound to for Serf WAN gossip communications. By default, the value follows the same rules as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind` @@ -362,31 +370,46 @@ The options below are all specified on the command-line. Here are some examples of using `-retry-join`: - ```shell - # Using a DNS entry + + + ```shell-session $ consul agent -retry-join "consul.domain.internal" ``` - ```shell - # Using IPv4 + + + + + ```shell-session $ consul agent -retry-join "10.0.4.67" ``` - ```shell - # Using a non-default Serf LAN port + + + + + ```shell-session $ consul agent -retry-join "192.0.2.10:8304" ``` - ```shell - # Using IPv6 + + + + + ```shell-session $ consul agent -retry-join "[::1]:8301" ``` - ```shell - # Using multiple addresses + + + + + ```shell-session $ consul agent -retry-join "consul.domain.internal" -retry-join "10.0.4.67" ``` + + ### Cloud Auto-Joining As of Consul 0.9.1, `retry-join` accepts a unified interface using the @@ -394,11 +417,14 @@ The options below are all specified on the command-line. automatic cluster joining using cloud metadata. For more information, see the [Cloud Auto-join page](/docs/agent/cloud-auto-join). - ```shell - # Using Cloud Auto-Joining + + + ```shell-session $ consul agent -retry-join "provider=aws tag_key=..." ``` + + - `-retry-interval` ((#\_retry_interval)) - Time to wait between join attempts. Defaults to 30s. @@ -580,7 +606,7 @@ They are documented separately under [check configuration](/docs/agent/checks) a [service configuration](/docs/agent/services) respectively. The service and check definitions support being updated during a reload. -#### Example Configuration File + ```json { @@ -601,6 +627,8 @@ definitions support being updated during a reload. } ``` + + #### Configuration Key Reference ((#config_key_reference)) -> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following @@ -736,6 +764,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `managed_service_provider` ((#acl_tokens_managed_service_provider)) - An array of ACL tokens used by Consul managed service providers for cluster operations. + + ```json "managed_service_provider": [ { @@ -745,6 +775,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ] ``` + + - `acl_datacenter` - **This field is deprecated in Consul 1.4.0. See the [`primary_datacenter`](#primary_datacenter) field instead.** This designates the datacenter which is authoritative for ACL information. It must be provided to enable ACLs. All servers and datacenters must agree on the ACL datacenter. Setting it on the servers is all you need for cluster-level enforcement, but for the APIs to forward properly from the clients, @@ -883,6 +915,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `audit` - Added in Consul 1.8, the audit object allow users to enable auditing and configure a sink and filters for their audit logs. For more information, review the [audit log tutorial](https://learn.hashicorp.com/tutorials/consul/audit-logging). + + ```hcl audit { enabled = true @@ -898,6 +932,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." } ``` + + The following sub-keys are available: - `enabled` - Controls whether Consul logs out each time a user @@ -1089,7 +1125,9 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." configurations when combined will ensure that the JWT `sub` matches the node name requested by the client. - ``` + + + ```hcl claim_mappings { sub = "node_name" } @@ -1098,6 +1136,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ] ``` + + The assertions are lightly templated using [HIL syntax](https://github.com/hashicorp/hil) to interpolate some values from the RPC request. The list of variables that can be interpolated are: @@ -1662,6 +1702,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `response_headers` This object allows adding headers to the HTTP API and UI responses. For example, the following config can be used to enable [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) on the HTTP API endpoints: + + ```json { "http_config": { @@ -1672,6 +1714,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr } ``` + + - `allow_write_http_from` This object is a list of networks in CIDR notation (eg "127.0.0.0/8") that are allowed to call the agent write endpoints. It defaults to an empty list, which means all networks are allowed. This is used to make the agent read-only, except for select ip ranges. - To block write calls from anywhere, use `[ "255.255.255.255/32" ]`. - To only allow write calls from localhost, use `[ "127.0.0.0/8" ]` - To only allow specific IPs, use `[ "10.0.0.1/32", "10.0.0.2/32" ]` - `use_cache` ((#http_config_use_cache)) Defaults to true. If disabled, the agent won't be using [agent caching](/api/features/caching) to answer the request. Even when the url parameter is provided. @@ -1718,6 +1762,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr - `node_meta` Available in Consul 0.7.3 and later, This object allows associating arbitrary metadata key/value pairs with the local node, which can then be used for filtering results from certain catalog endpoints. See the [`-node-meta` command-line flag](#_node_meta) for more information. + + ```json { "node_meta": { @@ -1726,6 +1772,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr } ``` + + - `partition` - This flag is used to set the name of the admin partition the agent belongs to. An agent can only join and communicate with other agents within its admin partition. Review the @@ -2071,10 +2119,14 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr This is a list of filter rules to apply for allowing/blocking metrics by prefix in the following format: + + ```json ["+consul.raft.apply", "-consul.http", "+consul.http.GET"] ``` + + A leading "**+**" will enable any metrics with the given prefix, and a leading "**-**" will block them. If there is overlap between two rules, the more specific rule will take precedence. Blocking will take priority if the same prefix is listed multiple times. - `prometheus_retention_time` ((#telemetry-prometheus_retention_time)) If the value is greater than `0s` (the default), this enables [Prometheus](https://prometheus.io/) @@ -2089,15 +2141,19 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr it is recommended to also enable the option [`disable_hostname`](#telemetry-disable_hostname) to avoid having prefixed metrics with hostname. Consul does not use the default Prometheus path, so Prometheus must be configured as follows. Note that using - ?format=prometheus in the path won't work as ? will be escaped, so it must be + `?format=prometheus` in the path won't work as ? will be escaped, so it must be specified as a parameter. + + ```yaml metrics_path: '/v1/agent/metrics' params: format: ['prometheus'] ``` + + - `statsd_address` ((#telemetry-statsd_address)) This provides the address of a statsd instance in the format `host:port`. If provided, Consul will send various telemetry information to that instance for aggregation. This can be used @@ -2407,6 +2463,10 @@ signed by the CA can be used to gain full access to Consul. encryption and authentication. Failing to set [`verify_incoming`](#verify_incoming) or [`verify_outgoing`](#verify_outgoing) will result in TLS not being enabled at all, even when specifying a [`ca_file`](#ca_file), [`cert_file`](#cert_file), and [`key_file`](#key_file). +See, especially, the use of the `ports` setting highlighted below. + + + ```json { "datacenter": "east-aws", @@ -2429,13 +2489,7 @@ will result in TLS not being enabled at all, even when specifying a [`ca_file`]( } ``` -See, especially, the use of the `ports` setting: - -```json -"ports": { - "https": 8501 -} -``` + Consul will not enable TLS for the HTTP API unless the `https` port has been assigned a port number `> 0`. We recommend using `8501` for `https` as this diff --git a/website/content/docs/agent/sentinel.mdx b/website/content/docs/agent/sentinel.mdx index 29b8f9b93..8344ee995 100644 --- a/website/content/docs/agent/sentinel.mdx +++ b/website/content/docs/agent/sentinel.mdx @@ -21,7 +21,9 @@ Sentinel policies are applied during writes to the KV Store. An optional `sentinel` field specifying code and enforcement level can be added to [ACL policy definitions](/docs/agent/acl-rules#sentinel-integration) for Consul KV. The following policy ensures that the value written during a KV update must end with "dc1". -```text + + +```go key "datacenter_name" { policy = "write" sentinel { @@ -34,6 +36,8 @@ EOF } ``` + + If the `enforcementlevel` property is not set, it defaults to "hard-mandatory". ## Imports @@ -58,9 +62,9 @@ The following are two examples of ACL policies with Sentinel rules. ### Required Key Suffix -Any values stored under the key prefix "dc1" must end with "dev" + -```text +```go key "dc1" { policy = "write" sentinel { @@ -72,11 +76,13 @@ EOF } ``` + + ### Restricted Update Time -The key "haproxy_version" can only be updated during business hours. + -```text +```go key "haproxy_version" { policy = "write" sentinel { @@ -87,3 +93,5 @@ EOF } } ``` + + diff --git a/website/content/docs/agent/telemetry.mdx b/website/content/docs/agent/telemetry.mdx index cb3c8e4f5..0c8ea8d01 100644 --- a/website/content/docs/agent/telemetry.mdx +++ b/website/content/docs/agent/telemetry.mdx @@ -39,7 +39,7 @@ This information can also be viewed with the [metrics endpoint](/api/agent#view-metrics) in JSON format or using [Prometheus](https://prometheus.io/) format. -Below is sample output of a telemetry dump: + ```log [2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.num_goroutines': 19.000 @@ -59,6 +59,8 @@ Below is sample output of a telemetry dump: [2014-01-29 10:56:50 -0800 PST][S] 'consul-agent.serf.queue.Event': Count: 10 Min: 0.000 Mean: 2.500 Max: 5.000 Stddev: 2.121 Sum: 25.000 ``` + + # Key Metrics These are some metrics emitted that can help you understand the health of your cluster at a glance. A [Grafana dashboard](https://grafana.com/grafana/dashboards/13396) is also available, which is maintained by the Consul team and displays these metrics for easy visualization. For a full list of metrics emitted by Consul, see [Metrics Reference](#metrics-reference)