luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #12074 from hashicorp/agent-docs-updates 

Update Web Components for Agent pages
This commit is contained in:
Anthony 2022-01-13 17:10:15 -05:00 committed by GitHub
parent 1971a58b29 b003fd93d7
commit 2ee084969b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 112 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/docs/agent/config-entries.mdx
View File

@ -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

8
website/content/docs/agent/index.mdx
View File

@ -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).

116
website/content/docs/agent/options.mdx
View File

@ -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

18
website/content/docs/agent/sentinel.mdx
View File

@ -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>

4
website/content/docs/agent/telemetry.mdx
View File

@ -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)