Skip to content

Commit 24bdf40

Browse files
authored
Consul: Manually migrate missing docs (#1474)
### Description After noticing that some changes merged into the Consul docs before the migration to UDR were missing, I went back and did a manual account of the histories for both the `main` and `release/v1.22.x` branches of the `hashicorp/consul` repo. As far as I can tell, changes merged into the repo in October were not migrated. This PR merges most of those missing changes. Redirect related fixes are being included in a dedicated redirect PR.
2 parents 503dc9d + f564255 commit 24bdf40

File tree

44 files changed

+1268
-717
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1268
-717
lines changed

content/consul/v1.22.x/content/api-docs/agent/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -660,7 +660,7 @@ The corresponding CLI command is [`consul join`](/consul/commands/join).
660660

661661
### Path Parameters
662662

663-
- `address` `(string: <required>)` - Specifies the address of the other agent to join.
663+
- `address` `(string: <required>)` - Specifies the address of the other agent to join. You can specifiy either an IPv4 or an IPv6 address.
664664

665665
### Query Parameters
666666

content/consul/v1.22.x/content/api-docs/agent/service.mdx

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -628,7 +628,12 @@ The `/agent/service/register` endpoint supports camel case and _snake case_ for
628628
This field takes precedence over the `ns` query parameter,
629629
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
630630

631-
- `Port` `(int: 0)` - Specifies the port of the service.
631+
- `Port` `(int: 0)` - Specifies the port of the service. This field is mutually exclusive with the `Ports` field. You can use this field in both service discovery and service mesh use cases.
632+
633+
- `Ports` `(array<Port>: nil)` - Specifies multiple ports for a service. This field is mutually exclusive with the `Port` field. Consul supports multi-port services for service discovery use cases only. For an example service definition, refer to [Multi-port service definition](#multi-port-service-definition). You can specify the following values:
634+
- `name` `(string: "")` - Specifies a name for the port. This value is addressable with Consul DNS.
635+
- `port` `(int: 0)` - Specifies a numeric port where the service is available.
636+
- `default` `(bool: false)` - Sets a port as the default service when a port is not included.
632637

633638
- `Kind` `(string: "")` - The kind of service. Defaults to `""`, which is a
634639
typical Consul service. You can specify the following values:
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
layout: api
3+
page_title: Audit - Operator - HTTP API
4+
description: |-
5+
The /operator/audit endpoints expose audit log information via Consul's HTTP API.
6+
---
7+
8+
# Audit logs - Operator HTTP API
9+
10+
<EnterpriseAlert />
11+
12+
The `/operator/audit` endpoints provide tools to interact with Consul's audit
13+
logging subsystem through Consul's HTTP API.
14+
15+
The audit logging functionality described here is available only in
16+
[Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.8.0 and
17+
later.
18+
19+
Refer to the [audit logging documentation](/consul/docs/monitor/log/audit) for workflow guidance and additional information.
20+
21+
## Calculate data hash
22+
23+
This endpoint calculates the hash of the data used by the audit log hash function and salt.
24+
25+
| Method | Path | Produces |
26+
| ------ | ------------------------------ | ------------------ |
27+
| `POST` | `/operator/audit-hash` | `application/json` |
28+
29+
The following table shows this endpoint's support for
30+
[blocking queries](/consul/api-docs/features/blocking),
31+
[consistency modes](/consul/api-docs/features/consistency),
32+
[agent caching](/consul/api-docs/features/caching), and
33+
[required ACLs](/consul/api-docs/api-structure#authentication).
34+
35+
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
36+
| ---------------- | ----------------- | ------------- | --------------- |
37+
| `NO` | `none` | `none` | `operator:read` |
38+
39+
The corresponding CLI command is [`consul operator audit hash`](/consul/commands/operator/audit#hash).
40+
41+
### JSON request body schema
42+
43+
- `Input` `(string: <required>)` - Specifies the input string to hash.
44+
45+
### Sample payload
46+
47+
```json
48+
{
49+
"Input": "test"
50+
}
51+
```
52+
53+
### Sample request
54+
55+
```shell-session
56+
$ curl \
57+
--request POST \
58+
--data @payload.json \
59+
http://127.0.0.1:8500/v1/operator/audit-hash
60+
```
61+
62+
### Sample response
63+
64+
```json
65+
{
66+
"Hash": "hmac_sha256:794c39dbc00d4714740199fe79982d02bbc5d303ab73149dfabc1244e3df3d4c"
67+
}
68+
```
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
layout: api
3+
page_title: Utilization - Operator - HTTP API
4+
description: |-
5+
The /operator/utilization endpoints generate a Consul utilization bundle for license reporting.
6+
---
7+
8+
# Utilization - Operator HTTP API
9+
10+
<EnterpriseAlert />
11+
12+
The `/operator/utilization` endpoints provide tools to generate a Consul utilization bundle for license reporting.
13+
14+
Refer to the [Manual license utilization reporting documentation](/consul/docs/enterprise/license/reporting#manual-license-utilization-reporting) for more information.
15+
16+
## Generate utilization bundle
17+
18+
This endpoint generates a Consul utilization bundle for license reporting.
19+
20+
| Method | Path | Produces |
21+
| ------ | ------------------------------ | ------------------ |
22+
| `GET` | `/operator/utilization` | `application/json` |
23+
24+
The following table shows this endpoint's support for
25+
[blocking queries](/consul/api-docs/features/blocking),
26+
[consistency modes](/consul/api-docs/features/consistency),
27+
[agent caching](/consul/api-docs/features/caching), and
28+
[required ACLs](/consul/api-docs/api-structure#authentication).
29+
30+
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
31+
| ---------------- | ----------------- | ------------- | --------------- |
32+
| `NO` | `none` | `none` | `operator:read` |
33+
34+
The corresponding CLI command is [`consul operator utilization`](/consul/commands/operator/utilization).
35+
36+
37+
### Query parameters
38+
39+
- `message` `(string: "")` - Optional context that is logged with the utilization export.
40+
41+
- `today_only` `(bool: false)` - Include only the most recent utilization snapshot.
42+
43+
- `send_report` `(bool: false)` - Automatically send the utilization report to HashiCorp.
44+
45+
### Sample request
46+
47+
```shell-session
48+
$ curl \
49+
http://127.0.0.1:8500/v1/operator/utilization
50+
```
51+
52+
### Sample response
53+
54+
```json
55+
{
56+
"version": "2",
57+
"mode": "manual",
58+
"timestamp": "2025-10-09T15:23:48.354524388Z",
59+
"signature": "9ea44420679b3776d1636acbe9ec1f636a58bd4a5b7f2b215cc2958084ded505",
60+
"checksum": 17512992959032736032,
61+
"snapshots": [
62+
{
63+
"snapshot_version": 2,
64+
"id": "0001MEFMW4B0G5JJHKQN4T9RCE",
65+
"timestamp": "2025-10-09T15:23:48.348542971Z",
66+
"schema_version": "2.0.0",
67+
"product": "consul",
68+
"process_id": "01K6FXJDTFBQQP5B3RAXRFRB1K",
69+
"metrics": {
70+
"consul.billable.nodes": {
71+
"key": "consul.billable.nodes",
72+
"value": 7,
73+
"mode": "write"
74+
},
75+
"consul.billable.service_instances": {
76+
"key": "consul.billable.service_instances",
77+
"value": 4,
78+
"mode": "write"
79+
}
80+
},
81+
"product_version": "1.22.0-rc1+ent",
82+
"license_id": "642088be-c801-c34a-bb5c-e70d4feb18fe",
83+
"checksum": 18094916709627403007,
84+
"metadata": {
85+
"billing_start": "2021-09-30T00:00:00Z",
86+
"cluster_id": "dc1"
87+
}
88+
}
89+
]
90+
}
91+
```
92+

content/consul/v1.22.x/content/commands/agent.mdx

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ information.
3737
a very large output in their checks. In order to completely disable check output
3838
capture, it is possible to use [`discard_check_output`](/consul/docs/reference/agent/configuration-file/general#discard_check_output).
3939

40-
- `-client` ((#\_client)) - The address to which Consul will bind client
40+
- `-client` ((#\_client)) - The IPV4 or IPv6 address to which Consul will bind client
4141
interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1",
4242
allowing only loopback connections. In Consul 1.0 and later this can be set to
4343
a space-separated list of addresses to bind to, or a [go-sockaddr]
@@ -203,11 +203,11 @@ information.
203203
## Address Bind Options
204204

205205
- `-bind` ((#\_bind)) - The address that should be bound to for internal
206-
cluster communications. This is an IP address that should be reachable by all other
207-
nodes in the cluster. By default, this is "0.0.0.0", meaning Consul will bind to
206+
cluster communications. This is an IPv4 or IPv6 address that should be reachable by all other
207+
nodes in the cluster. By default, this is `0.0.0.0`, meaning Consul will bind to
208208
all addresses on the local machine and will [advertise](#_advertise)
209-
the private IPv4 address to the rest of the cluster. If there are multiple private
210-
IPv4 addresses available, Consul will exit with an error at startup. If you specify
209+
the private IPv4 or IPv6 address to the rest of the cluster. If there are multiple private
210+
IPv4 or IPv6 addresses available, Consul will exit with an error at startup. If you specify
211211
`"[::]"`, Consul will [advertise](#_advertise) the public
212212
IPv6 address. If there are multiple public IPv6 addresses available, Consul will
213213
exit with an error at startup. Consul uses both TCP and UDP and the same port for
@@ -238,14 +238,14 @@ information.
238238

239239
</CodeBlockConfig>
240240

241-
- `-serf-wan-bind` ((#\_serf_wan_bind)) - The address that should be bound
241+
- `-serf-wan-bind` ((#\_serf_wan_bind)) - The IPv4 or IPv6 address that should be bound
242242
to for Serf WAN gossip communications. By default, the value follows the same rules
243243
as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind`
244244
option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
245245
template that is resolved at runtime.
246246

247247
- `-serf-lan-bind` ((#\_serf_lan_bind)) - The address that should be bound
248-
to for Serf LAN gossip communications. This is an IP address that should be reachable
248+
to for Serf LAN gossip communications. This is an IPv4 or IPv6 address that should be reachable
249249
by all other LAN nodes in the cluster. By default, the value follows the same rules
250250
as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind`
251251
option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
@@ -271,7 +271,7 @@ information.
271271
## Configuration File Options
272272

273273
- `-config-file` ((#\_config_file)) - A configuration file to load. For
274-
more information on the format of this file, read the [Configuration Files](/consul/docs/reference/agent)
274+
more information on the format of this file, read the [Configuration Files](/consul/docs/reference/agent/configuration-file)
275275
section. This option can be specified multiple times to load multiple configuration
276276
files. If it is specified multiple times, configuration files loaded later will
277277
merge with configuration files loaded earlier. During a config merge, single-value
@@ -284,7 +284,7 @@ information.
284284
the [`config-file`](#_config_file) option above. This option can be specified multiple
285285
times to load multiple directories. Sub-directories of the config directory are
286286
not loaded. For more information on the format of the configuration files, refer to
287-
the [Configuration Files](/consul/docs/reference/agent) section.
287+
the [Configuration Files](/consul/docs/reference/agent/configuration-file) section.
288288

289289
- `-config-format` ((#\_config_format)) - The format of the configuration
290290
files to load. Normally, Consul detects the format of the config files from the
@@ -295,7 +295,7 @@ information.
295295
## DNS and Domain Options
296296

297297
- `-dns-port` ((#\_dns_port)) - the DNS port to listen on. This overrides
298-
the default port 8600. This is available in Consul 0.7 and later.
298+
the default port `8600`. This is available in Consul 0.7 and later.
299299

300300
- `-domain` ((#\_domain)) - By default, Consul responds to DNS queries in
301301
the "consul." domain. This flag can be used to change that domain. All queries

content/consul/v1.22.x/content/commands/force-leave.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ consul force-leave ec2-001-staging
5757
```
5858

5959
When run on a server that is part of a
60-
[WAN gossip pool](/consul/tutorials/networking/federation-gossip-wan),
60+
[WAN gossip pool](/consul/docs/east-west/wan-federation/vms),
6161
`force-leave` can remove failed servers in other datacenters from the WAN pool.
6262

6363
The identifying node-name in a WAN pool is `[node-name].[datacenter]`.

content/consul/v1.22.x/content/commands/index.mdx

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -138,19 +138,35 @@ These environment variables and their purpose are described below:
138138

139139
### `CONSUL_HTTP_ADDR`
140140

141-
This is the HTTP API address to the _local_ Consul agent
142-
(not the remote server) specified as a URI with optional scheme:
141+
This variable specifies the IPv4 or IPv 6 address of the Consul agent you want to interact with locally, specified as a URI with optional scheme.
142+
143+
<Tabs>
144+
145+
<Tab heading="IPv4">
143146

144147
```
145148
CONSUL_HTTP_ADDR=127.0.0.1:8500
146149
```
147150

148-
or as a Unix socket path:
151+
</Tab>
152+
153+
<Tab heading="IPv6">
154+
155+
```
156+
CONSUL_HTTP_ADDR=2001:db8:3333:4444:5555:6666:7777:8888
157+
```
158+
159+
</Tab>
160+
161+
<Tab heading="Unix socket path">
149162

150163
```
151164
CONSUL_HTTP_ADDR=unix:///var/run/consul_http.sock
152165
```
153166

167+
</Tab>
168+
</Tabs>
169+
154170
If the `https://` scheme is used, `CONSUL_HTTP_SSL` is implied to be true.
155171

156172
### `CONSUL_HTTP_TOKEN`
@@ -240,7 +256,7 @@ CONSUL_TLS_SERVER_NAME=consulserver.domain
240256

241257
### `CONSUL_GRPC_ADDR`
242258

243-
Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the
259+
Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the IPv4 or IPv6 address the
244260
local agent is listening for gRPC requests. Currently gRPC is only used for
245261
integrating [Envoy proxy](/consul/docs/reference/proxy/envoy) and must be [enabled
246262
explicitly](/consul/docs/reference/agent/configuration-file/general#grpc_port) in agent configuration.

content/consul/v1.22.x/content/commands/join.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Command: `consul join`
1414

1515
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/join/:address](/consul/api-docs/agent#join-agent)
1616

17-
The `join` command tells a Consul agent to join an existing cluster.
17+
The `join` command tells a Consul agent to join an existing cluster at the indicated IPv4 or IPv6 address.
1818
A new Consul agent may join any node in the existing cluster. After joining
1919
with one member, the gossip communication will propagate the updated membership
2020
state across the cluster.
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
layout: commands
3+
page_title: 'Commands: Operator Audit'
4+
description: >
5+
Use the operator audit command to interact with Consul's audit logging subsystem.
6+
---
7+
8+
# Consul Operator Audit
9+
10+
Command: `consul operator audit`
11+
12+
<EnterpriseAlert />
13+
14+
Consul Enterprise audit logging captures a list of authenticated events that
15+
Consul processes through its HTTP API. Use the `operator audit` command to
16+
interact with Consul's audit logging subsystem.
17+
18+
Fore information and workflow guidance, refer to the [audit logging documentation](/consul/docs/monitor/log/audit).
19+
20+
```text
21+
Usage: consul operator audit <subcommand> [options]
22+
The Audit operator command is used to interact with Consul's Audit logging subsystem. The
23+
command can be used to calculate the audit log hash of a given string.
24+
25+
Subcommands:
26+
hash Computes the audit hash of a string
27+
```
28+
29+
If ACLs are enabled, the client must supply an ACL Token with `operator`
30+
read or write privileges to use these commands.
31+
32+
## hash
33+
34+
Corresponding HTTP API Endpoint: [\[POST\] /v1/operator/audit-hash](/consul/api-docs/operator/audit)
35+
36+
Computes the audit hash of a string. Optionally compare the computed hash to a specified hash.
37+
38+
The following table shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Commands do not support configuration of
39+
[blocking queries](/consul/api-docs/features/blocking) or [agent caching](/consul/api-docs/features/caching), but the corresponding HTTP endpoint may support that configuration.
40+
41+
| ACL Required |
42+
| ---------------- |
43+
| `operator:read` |
44+
45+
Usage: `consul operator audit hash -input INPUT [options]`
46+
47+
#### API options
48+
49+
@include 'legacy/http_api_options_client.mdx'
50+
51+
@include 'legacy/http_api_options_server.mdx'
52+
53+
#### Command options
54+
55+
- `-hash-to-match=<string>` - Optional. If specified, the command outputs whether this value matches the computed hash of the 'input' value. Should be in the format: `hmac_sha256:xxxx`
56+
57+
- `-input=<string>` - Specifies the input string to hash. This flag is required.
58+
59+
### Examples
60+
61+
This example displays the audit hash of the provided value.
62+
63+
```shell-session
64+
$ consul operator audit hash -input="my-value"
65+
```
66+
67+
This example compares the audit hash of a provided value.
68+
69+
```
70+
$ consul operator audit hash -input="my-value" -hash-to-match="hmac_sha256:37ed9ed..."
71+
```
72+

0 commit comments

Comments
 (0)