Merge pull request #12074 from hashicorp/agent-docs-updates
Update Web Components for Agent pages
This commit is contained in:
Anthony
GitHub
commit
2ee084969b
|
|
@ -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:
|
||||
<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>
|
||||
|
|
@ -37,6 +41,8 @@ metadata:
|
|||
name: <name of entry>
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
## Supported Config Entries
|
||||
|
||||
See [Service Mesh - Config Entries](/docs/connect/config-entries) for the list
|
||||
|
|
|
|||
|
|
@ -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 <options>
|
||||
$ consul agent <options>
|
||||
```
|
||||
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<CodeBlockConfig>
|
||||
<CodeBlockConfig heading="Using a static network interface name">
|
||||
|
||||
```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
|
||||
<CodeBlockConfig heading="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
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="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
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="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" }}'
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `-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
|
||||
<CodeBlockConfig heading="Using a DNS entry">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "consul.domain.internal"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using IPv4
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using IPv4">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "10.0.4.67"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using a non-default Serf LAN port
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using a non-default Serf LAN port">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "192.0.2.10:8304"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using IPv6
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using IPv6">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "[::1]:8301"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Using multiple addresses
|
||||
</CodeBlockConfig>
|
||||
|
||||
<CodeBlockConfig heading="Using multiple addresses">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "consul.domain.internal" -retry-join "10.0.4.67"
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
### 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
|
||||
<CodeBlockConfig heading="Using Cloud Auto-Joining">
|
||||
|
||||
```shell-session
|
||||
$ consul agent -retry-join "provider=aws tag_key=..."
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `-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
|
||||
<CodeBlockConfig heading="Example Configuration File">
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -601,6 +627,8 @@ definitions support being updated during a reload.
|
|||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
#### 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)) <EnterpriseAlert inline /> - An
|
||||
array of ACL tokens used by Consul managed service providers for cluster operations.
|
||||
|
||||
<CodeBlockConfig heading="Example managed_service_provider configuration">
|
||||
|
||||
```json
|
||||
"managed_service_provider": [
|
||||
{
|
||||
|
|
@ -745,6 +775,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
]
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `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` <EnterpriseAlert inline /> - 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).
|
||||
|
||||
<CodeBlockConfig heading="Example audit configuration">
|
||||
|
||||
```hcl
|
||||
audit {
|
||||
enabled = true
|
||||
|
|
@ -898,6 +932,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
|||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
<CodeBlockConfig heading="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'."
|
|||
]
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
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:
|
||||
|
||||
<CodeBlockConfig heading="Enable CORS on the HTTP API endpoints">
|
||||
|
||||
```json
|
||||
{
|
||||
"http_config": {
|
||||
|
|
@ -1672,6 +1714,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `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.
|
||||
|
||||
<CodeBlockConfig heading="Example node_meta configuration">
|
||||
|
||||
```json
|
||||
{
|
||||
"node_meta": {
|
||||
|
|
@ -1726,6 +1772,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `partition` <EnterpriseAlert inline /> - 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:
|
||||
|
||||
<CodeBlockConfig heading="Example prefix_filter configuration">
|
||||
|
||||
```json
|
||||
["+consul.raft.apply", "-consul.http", "+consul.http.GET"]
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
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.
|
||||
|
||||
<CodeBlockConfig heading="Example Prometheus configuration">
|
||||
|
||||
```yaml
|
||||
metrics_path: '/v1/agent/metrics'
|
||||
params:
|
||||
format: ['prometheus']
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `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.
|
||||
|
||||
<CodeBlockConfig heading="Example configuration with TLS" lineNumbers highlight="10-12">
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
</CodeBlockConfig>
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<CodeBlockConfig heading="Ensure values written during KV updates end in 'dc1'">
|
||||
|
||||
```go
|
||||
key "datacenter_name" {
|
||||
policy = "write"
|
||||
sentinel {
|
||||
|
|
@ -34,6 +36,8 @@ EOF
|
|||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
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"
|
||||
<CodeBlockConfig heading="Any values stored under the key 'dc1' end with 'dev'">
|
||||
|
||||
```text
|
||||
```go
|
||||
key "dc1" {
|
||||
policy = "write"
|
||||
sentinel {
|
||||
|
|
@ -72,11 +76,13 @@ EOF
|
|||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
### Restricted Update Time
|
||||
|
||||
The key "haproxy_version" can only be updated during business hours.
|
||||
<CodeBlockConfig heading="The key 'haproxy_version' can only be updated during business hours">
|
||||
|
||||
```text
|
||||
```go
|
||||
key "haproxy_version" {
|
||||
policy = "write"
|
||||
sentinel {
|
||||
|
|
@ -87,3 +93,5 @@ EOF
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
<CodeBlockConfig heading="Sample output of 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
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
# 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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue