)` - Specifies the destination service. This
is specified as part of the URL.
- This can take [several forms](/docs/commands/intention#source-and-destination-naming).
+ This can take [several forms](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` - Specifies the default
namespace to use when `source` or `destination` parameters lack namespaces.
- If not provided at all, the default namespace will be inherited from the
+ If not provided, the default namespace will be inherited from the
request's ACL token or will default to the `default` namespace.
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
@@ -508,12 +703,12 @@ The table below shows this endpoint's support for
[agent caching](/api/features/caching), and
[required ACLs](/api#authentication).
-| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
-| ---------------- | ----------------- | ------------- | ----------------------------- |
-| `NO` | `none` | `none` | `intentions:read`1 |
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
+| ---------------- | ----------------- | -------------------- | ----------------------------- |
+| `YES` | `all` | `background refresh` | `intentions:read`1 |
- 1 Intention ACL rules are specified as part of a `service` rule.
+ 1 Intention ACL rules are specified as part of a service rule.
See{' '}
Intention Management Permissions
@@ -528,11 +723,11 @@ The table below shows this endpoint's support for
- `name` `(string: )` - Specifies a name to match. This parameter
can be repeated for batching multiple matches.
- This can take [several forms](/docs/commands/intention#source-and-destination-naming).
+ This can take [several forms](/commands/intention#source-and-destination-naming).
- `ns` `(string: "")` - Specifies the default
namespace to use when `name` parameter lacks namespaces.
- If not provided at all, the default namespace will be inherited from the
+ If not provided, the default namespace will be inherited from the
request's ACL token or will default to the `default` namespace.
This value may be provided by either the `ns` URL query parameter or in the
`X-Consul-Namespace` header.
@@ -551,7 +746,6 @@ $ curl \
{
"web": [
{
- "ID": "ed16f6a6-d863-1bec-af45-96bbdcbe02be",
"Description": "",
"SourceNS": "default",
"SourceName": "web",
@@ -560,13 +754,10 @@ $ curl \
"SourceType": "consul",
"Action": "deny",
"Meta": {},
- "CreatedAt": "2018-05-21T16:41:33.296693825Z",
- "UpdatedAt": "2018-05-21T16:41:33.296694288Z",
"CreateIndex": 12,
"ModifyIndex": 12
},
{
- "ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
"Description": "",
"SourceNS": "default",
"SourceName": "web",
@@ -575,8 +766,6 @@ $ curl \
"SourceType": "consul",
"Action": "allow",
"Meta": {},
- "CreatedAt": "2018-05-21T16:41:27.977155457Z",
- "UpdatedAt": "2018-05-21T16:41:27.977157724Z",
"CreateIndex": 11,
"ModifyIndex": 11
}
diff --git a/website/pages/api-docs/discovery-chain.mdx b/website/pages/api-docs/discovery-chain.mdx
index 2090e214db..b9105476cd 100644
--- a/website/pages/api-docs/discovery-chain.mdx
+++ b/website/pages/api-docs/discovery-chain.mdx
@@ -17,7 +17,7 @@ The `/discovery-chain` endpoint returns the compiled [discovery
chain](/docs/internals/discovery-chain) for a service.
This will fetch all related [configuration
-entries](/docs/agent/config_entries) and render them into a form suitable
+entries](/docs/agent/config-entries) and render them into a form suitable
for use by a [connect proxy](/docs/connect/proxies) implementation. This
is a key component of [L7 Traffic
Management](/docs/connect/l7-traffic-management).
diff --git a/website/pages/api-docs/event.mdx b/website/pages/api-docs/event.mdx
index e93302b569..00c86eecd6 100644
--- a/website/pages/api-docs/event.mdx
+++ b/website/pages/api-docs/event.mdx
@@ -87,7 +87,7 @@ $ curl \
## List Events
This endpoint returns the most recent events (up to 256) known by the agent. As a
-consequence of how the [event command](/docs/commands/event) works, each
+consequence of how the [event command](/commands/event) works, each
agent may have a different view of the events. Events are broadcast using the
[gossip protocol](/docs/internals/gossip), so they have no global ordering
nor do they make a promise of delivery.
diff --git a/website/pages/api-docs/features/caching.mdx b/website/pages/api-docs/features/caching.mdx
index ea89727772..aa707a21d7 100644
--- a/website/pages/api-docs/features/caching.mdx
+++ b/website/pages/api-docs/features/caching.mdx
@@ -36,7 +36,7 @@ a 500 is returned as normal.
To allow clients to maintain fresh results in normal operation but allow stale
ones if the servers are unavailable, the `stale-if-error=` directive
may be additionally provided in the `Cache-Control` header. This will return the
-cached value anyway even it it's older than `max-age` (provided it's not older
+cached value anyway even if it's older than `max-age` (provided it's not older
than `stale-if-error`) rather than a 500. It must be provided along with a
`max-age` or `must-revalidate`. The `Age` response header, if larger than
`max-age` can be used to determine if the server was unreachable and a cached
diff --git a/website/pages/api-docs/health.mdx b/website/pages/api-docs/health.mdx
index f9a8663750..0f3ac434ff 100644
--- a/website/pages/api-docs/health.mdx
+++ b/website/pages/api-docs/health.mdx
@@ -47,7 +47,7 @@ The table below shows this endpoint's support for
- `ns` `(string: "")` - Specifies the namespace to list checks.
This value may be provided by either the `ns` URL query parameter or in the
- `X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
+ `X-Consul-Namespace` header. If not provided, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. To view
checks for multiple namespaces the `*` wildcard namespace may be used. Added in Consul 1.7.0.
@@ -152,7 +152,7 @@ The table below shows this endpoint's support for
- `ns` `(string: "")` - Specifies the namespace of the service.
This value may be provided by either the `ns` URL query parameter or in the
- `X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
+ `X-Consul-Namespace` header. If not provided, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
### Sample Request
@@ -251,7 +251,7 @@ The table below shows this endpoint's support for
- `ns` `(string: "")` - Specifies the namespace of the service.
This value may be provided by either the `ns` URL query parameter or in the
- `X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
+ `X-Consul-Namespace` header. If not provided, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
### Sample Request
@@ -460,7 +460,7 @@ The table below shows this endpoint's support for
- `ns` `(string: "")` - Specifies the namespace to query.
This value may be provided by either the `ns` URL query parameter or in the
- `X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
+ `X-Consul-Namespace` header. If not provided, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
### Sample Request
diff --git a/website/pages/api-docs/operator/index.mdx b/website/pages/api-docs/operator/index.mdx
index 1443081426..fe40266641 100644
--- a/website/pages/api-docs/operator/index.mdx
+++ b/website/pages/api-docs/operator/index.mdx
@@ -12,7 +12,7 @@ description: |-
The `/operator` endpoints provide cluster-level tools for Consul operators,
such as interacting with the Raft subsystem. For a CLI to perform these
operations manually, please check the documentation for the
-[`consul operator`](/docs/commands/operator) command.
+[`consul operator`](/commands/operator) command.
If ACLs are enabled then a token with operator privileges may be required in
order to use this interface. Check the [ACL Rules documentation](/docs/acl/acl-rules#operator-rules)
diff --git a/website/pages/commands/config/delete.mdx b/website/pages/commands/config/delete.mdx
index c897d0340d..928efe8a8e 100644
--- a/website/pages/commands/config/delete.mdx
+++ b/website/pages/commands/config/delete.mdx
@@ -9,7 +9,7 @@ sidebar_title: delete
Command: `consul config delete`
The `config delete` command deletes the configuration entry specified by the
-kind and name. See the [configuration entries docs](/docs/agent/config_entries)
+kind and name. See the [configuration entries docs](/docs/agent/config-entries)
for more details about configuration entries.
## Usage
diff --git a/website/pages/commands/config/index.mdx b/website/pages/commands/config/index.mdx
index 6abbc1ceb9..a969ecd8db 100644
--- a/website/pages/commands/config/index.mdx
+++ b/website/pages/commands/config/index.mdx
@@ -13,7 +13,7 @@ system. It exposes commands for creating, updating, reading, and deleting
different kinds of config entries. See the
[agent configuration](/docs/agent/options#enable_central_service_config)
for more information on how to enable this functionality for centrally
-configuring services and [configuration entries docs](/docs/agent/config_entries) for a description
+configuring services and [configuration entries docs](/docs/agent/config-entries) for a description
of the configuration entries content.
## Usage
diff --git a/website/pages/commands/config/list.mdx b/website/pages/commands/config/list.mdx
index 77670ff567..1930ec6482 100644
--- a/website/pages/commands/config/list.mdx
+++ b/website/pages/commands/config/list.mdx
@@ -9,7 +9,7 @@ sidebar_title: list
Command: `consul config list`
The `config list` command lists all given config entries of the given kind.
-See the [configuration entries docs](/docs/agent/config_entries) for more
+See the [configuration entries docs](/docs/agent/config-entries) for more
details about configuration entries.
## Usage
diff --git a/website/pages/commands/config/read.mdx b/website/pages/commands/config/read.mdx
index a36c599048..4fe07e1bd8 100644
--- a/website/pages/commands/config/read.mdx
+++ b/website/pages/commands/config/read.mdx
@@ -10,7 +10,7 @@ Command: `consul config read`
The `config read` command reads the config entry specified by the given
kind and name and outputs its JSON representation. See the
-[configuration entries docs](/docs/agent/config_entries) for more
+[configuration entries docs](/docs/agent/config-entries) for more
details about configuration entries.
## Usage
diff --git a/website/pages/commands/config/write.mdx b/website/pages/commands/config/write.mdx
index 034bd75ddd..429a69c956 100644
--- a/website/pages/commands/config/write.mdx
+++ b/website/pages/commands/config/write.mdx
@@ -9,7 +9,7 @@ sidebar_title: write
Command: `consul config write`
The `config write` command creates or updates a centralized config entry.
-See the [configuration entries docs](/docs/agent/config_entries) for more
+See the [configuration entries docs](/docs/agent/config-entries) for more
details about configuration entries.
## Usage
diff --git a/website/pages/commands/connect/proxy.mdx b/website/pages/commands/connect/proxy.mdx
index b5c644dc0e..7181f1122e 100644
--- a/website/pages/commands/connect/proxy.mdx
+++ b/website/pages/commands/connect/proxy.mdx
@@ -71,7 +71,7 @@ Usage: `consul connect proxy [options]`
- `-register-id` - Optional ID suffix for the service when `-register` is set to
disambiguate the service ID. By default the service ID is `-proxy`
where `` is the `-service` value. In most cases it is now preferable
- to use [`consul services register`](/docs/commands/services/register) to
+ to use [`consul services register`](/commands/services/register) to
register a fully configured proxy instance rather than specify config and
registration via this command.
diff --git a/website/pages/commands/exec.mdx b/website/pages/commands/exec.mdx
index 97154f2fc3..33253f5181 100644
--- a/website/pages/commands/exec.mdx
+++ b/website/pages/commands/exec.mdx
@@ -17,7 +17,7 @@ this can be used to run the `uptime` command across all machines providing
the `web` service.
Remote execution works by specifying a job, which is stored in the KV store.
-Agents are informed about the new job using the [event system](/docs/commands/event),
+Agents are informed about the new job using the [event system](/commands/event),
which propagates messages via the [gossip protocol](/docs/internals/gossip).
As a result, delivery is best-effort, and there is **no guarantee** of execution.
diff --git a/website/pages/commands/force-leave.mdx b/website/pages/commands/force-leave.mdx
index f676368fa9..cbb1ad27e0 100644
--- a/website/pages/commands/force-leave.mdx
+++ b/website/pages/commands/force-leave.mdx
@@ -14,13 +14,13 @@ Command: `consul force-leave`
The `force-leave` command forces a member of a Consul cluster to enter the
"left" state. The purpose of this method is to force-remove a node that has failed or
-was shutdown without a [graceful leave](/docs/commands/leave).
+was shutdown without a [graceful leave](/commands/leave).
Consul periodically tries to reconnect to "failed" nodes in case failure was due
to a network partition. After some configured amount of time (by default 72 hours),
Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave`
command can be used to transition the "failed" nodes to a "left" state more
-quickly, as reported by [`consul members`](/docs/commands/members).
+quickly, as reported by [`consul members`](/commands/members).
This can be particularly useful for a node that was running as a server,
as it will eventually be removed from the Raft configuration by the leader.
diff --git a/website/pages/commands/intention/check.mdx b/website/pages/commands/intention/check.mdx
index d49609154e..cb9723405a 100644
--- a/website/pages/commands/intention/check.mdx
+++ b/website/pages/commands/intention/check.mdx
@@ -15,14 +15,18 @@ Consul configuration.
This command requires less ACL permissions than other intention-related
tasks because no information about the intention is revealed. Therefore,
callers only need to have `service:read` access for the destination. Richer
-commands like [match](/docs/commands/intention/match) require full
+commands like [match](/commands/intention/match) require full
intention read permissions and don't evaluate the result.
+-> **Note:** This command will always treat intentions with `Permissions`
+defined as *deny* intentions during evaluation, as this endpoint is only suited
+for networking layer 4 (e.g. TCP) integration.
+
## Usage
Usage: `consul intention check [options] SRC DST`
-`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
+`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
#### API Options
diff --git a/website/pages/commands/intention/create.mdx b/website/pages/commands/intention/create.mdx
index 3cc698d449..2b2623d577 100644
--- a/website/pages/commands/intention/create.mdx
+++ b/website/pages/commands/intention/create.mdx
@@ -6,16 +6,22 @@ sidebar_title: create
# Consul Intention Create
+-> **Deprecated** - This command is deprecated in Consul 1.9.0 in favor of
+using the [config entry CLI command](/commands/config/write). To create an
+intention, create or modify a
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entry for the destination.
+
Command: `consul intention create`
-The `intention create` command creates or updates an intention.
+The `intention create` command creates or updates an L4 intention.
## Usage
-Usage: `consul intention create [options] SRC DST`
-Usage: `consul intention create [options] -f FILE...`
+- `consul intention create [options] SRC DST`
+- `consul intention create [options] -file FILE...`
-`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
+`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
#### API Options
diff --git a/website/pages/commands/intention/delete.mdx b/website/pages/commands/intention/delete.mdx
index 2a5ce032a8..a5cedd8a0b 100644
--- a/website/pages/commands/intention/delete.mdx
+++ b/website/pages/commands/intention/delete.mdx
@@ -10,6 +10,11 @@ Command: `consul intention delete`
The `intention delete` command deletes a matching intention.
+-> **Deprecated** - The one argument form of this command is deprecated in
+Consul 1.9.0. Intentions no longer need IDs when represented as
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entries.
+
## Usage
Usage:
@@ -17,7 +22,7 @@ Usage:
- `consul intention delete [options] SRC DST`
- `consul intention delete [options] ID`
-`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
+`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
#### API Options
diff --git a/website/pages/commands/intention/get.mdx b/website/pages/commands/intention/get.mdx
index c961fc580a..85862d2152 100644
--- a/website/pages/commands/intention/get.mdx
+++ b/website/pages/commands/intention/get.mdx
@@ -10,6 +10,11 @@ Command: `consul intention get`
The `intention get` command shows a single intention.
+-> **Deprecated** - The one argument form of this command is deprecated in
+Consul 1.9.0. Intentions no longer need IDs when represented as
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entries.
+
## Usage
Usage:
@@ -17,7 +22,7 @@ Usage:
- `consul intention get [options] SRC DST`
- `consul intention get [options] ID`
-`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
+`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
#### API Options
diff --git a/website/pages/commands/intention/index.mdx b/website/pages/commands/intention/index.mdx
index c26a269268..0c0073df29 100644
--- a/website/pages/commands/intention/index.mdx
+++ b/website/pages/commands/intention/index.mdx
@@ -13,7 +13,10 @@ The `intention` command is used to interact with Connect
creating, updating, reading, deleting, checking, and managing intentions.
This command is available in Consul 1.2 and later.
-Intentions may also be managed via the [HTTP API](/api/connect/intentions).
+Intentions are managed primarily via
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entries after Consul 1.9. Intentions may also be managed via the [HTTP
+API](/api/connect/intentions).
## Usage
diff --git a/website/pages/commands/intention/match.mdx b/website/pages/commands/intention/match.mdx
index b94b56c761..4b2cea4e28 100644
--- a/website/pages/commands/intention/match.mdx
+++ b/website/pages/commands/intention/match.mdx
@@ -12,14 +12,14 @@ The `intention match` command shows the list of intentions that match
a given source or destination. The list of intentions is listed in evaluation
order: the first intention that matches a request would be evaluated.
-The [check](/docs/commands/intention/check) command can be used to
-check whether a connection would be authorized between any two services.
+The [check](/commands/intention/check) command can be used to
+check whether an L4 connection would be authorized between any two services.
## Usage
Usage: `consul intention match [options] SRC_OR_DST`
-`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
+`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
#### API Options
@@ -40,5 +40,6 @@ Usage: `consul intention match [options] SRC_OR_DST`
```shell-session
$ consul intention match -source web
web => db (deny)
+web => api (2 permissions)
web => * (allow)
```
diff --git a/website/pages/commands/kv/index.mdx b/website/pages/commands/kv/index.mdx
index ece8859323..3b5fa1742a 100644
--- a/website/pages/commands/kv/index.mdx
+++ b/website/pages/commands/kv/index.mdx
@@ -40,11 +40,11 @@ Subcommands:
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar or one of the links below:
-- [delete](/docs/commands/kv/delete)
-- [export](/docs/commands/kv/export)
-- [get](/docs/commands/kv/get)
-- [import](/docs/commands/kv/import)
-- [put](/docs/commands/kv/put)
+- [delete](/commands/kv/delete)
+- [export](/commands/kv/export)
+- [get](/commands/kv/get)
+- [import](/commands/kv/import)
+- [put](/commands/kv/put)
## Basic Examples
diff --git a/website/pages/commands/kv/put.mdx b/website/pages/commands/kv/put.mdx
index 50093e88f2..fef21e8ee4 100644
--- a/website/pages/commands/kv/put.mdx
+++ b/website/pages/commands/kv/put.mdx
@@ -141,5 +141,5 @@ Success! Lock released on: redis/lock/update
~> **Warning!** If you are trying to build a locking mechanism with these
low-level primitives, you may want to look at the [consul
-lock](/docs/commands/lock) command. It provides higher-level
+lock](/commands/lock) command. It provides higher-level
functionality without exposing the internal APIs of Consul.
diff --git a/website/pages/commands/operator/index.mdx b/website/pages/commands/operator/index.mdx
index 9b89e7322c..caefab5441 100644
--- a/website/pages/commands/operator/index.mdx
+++ b/website/pages/commands/operator/index.mdx
@@ -43,6 +43,6 @@ Subcommands:
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar or one of the links below:
-- [area](/docs/commands/operator/area)
-- [autopilot](/docs/commands/operator/autopilot)
-- [raft](/docs/commands/operator/raft)
+- [area](/commands/operator/area)
+- [autopilot](/commands/operator/autopilot)
+- [raft](/commands/operator/raft)
diff --git a/website/pages/commands/operator/raft.mdx b/website/pages/commands/operator/raft.mdx
index 8c17297316..725b19abe2 100644
--- a/website/pages/commands/operator/raft.mdx
+++ b/website/pages/commands/operator/raft.mdx
@@ -69,9 +69,9 @@ There are rare cases where a peer may be left behind in the Raft configuration
even though the server is no longer present and known to the cluster. This command
can be used to remove the failed server so that it is no longer affects the
Raft quorum. If the server still shows in the output of the
-[`consul members`](/docs/commands/members) command, it is preferable to
+[`consul members`](/commands/members) command, it is preferable to
clean up by simply running
-[`consul force-leave`](/docs/commands/force-leave)
+[`consul force-leave`](/commands/force-leave)
instead of this command.
Usage: `consul operator raft remove-peer -address="IP:port"`
diff --git a/website/pages/commands/services/deregister.mdx b/website/pages/commands/services/deregister.mdx
index 35df89dd47..bc476749e6 100644
--- a/website/pages/commands/services/deregister.mdx
+++ b/website/pages/commands/services/deregister.mdx
@@ -15,7 +15,7 @@ be paired with `services register`.
This is just one method for service deregistration. If the service was
registered with a configuration file, then deleting that file and
-[reloading](/docs/commands/reload) Consul is the correct method to
+[reloading](/commands/reload) Consul is the correct method to
deregister. See [Service Definition](/docs/agent/services) for more
information about registering services generally.
diff --git a/website/pages/commands/services/index.mdx b/website/pages/commands/services/index.mdx
index 13f41bca06..e33513387b 100644
--- a/website/pages/commands/services/index.mdx
+++ b/website/pages/commands/services/index.mdx
@@ -13,7 +13,7 @@ registered with the [local agent](/docs/agent/basics). These provide
useful commands such as `register` and `deregister` for easily registering
services in scripts, dev mode, etc.
To view all services in the catalog, instead of only agent-local services,
-see the [`catalog services`](/docs/commands/catalog/services) command.
+see the [`catalog services`](/commands/catalog/services) command.
## Usage
diff --git a/website/pages/commands/services/register.mdx b/website/pages/commands/services/register.mdx
index 3c38bba6d3..f626bda297 100644
--- a/website/pages/commands/services/register.mdx
+++ b/website/pages/commands/services/register.mdx
@@ -16,7 +16,7 @@ scripts, in dev mode, etc.
This is just one method of service registration. Services can also be
registered by placing a [service definition](/docs/agent/services)
in the Consul agent configuration directory and issuing a
-[reload](/docs/commands/reload). This approach is easiest for
+[reload](/commands/reload). This approach is easiest for
configuration management systems that other systems that have access to
the configuration directory. Clients may also use the
[HTTP API](/api/agent/service) directly.
diff --git a/website/pages/commands/snapshot/agent.mdx b/website/pages/commands/snapshot/agent.mdx
index 7cfa1a8ae4..4820fb694c 100644
--- a/website/pages/commands/snapshot/agent.mdx
+++ b/website/pages/commands/snapshot/agent.mdx
@@ -10,9 +10,9 @@ Command: `consul snapshot agent`
-~> The [`agent`](/docs/commands/snapshot/agent) subcommand described here is
+~> The [`agent`](/commands/snapshot/agent) subcommand described here is
available only in [Consul Enterprise](https://www.hashicorp.com/products/consul/)
-version 0.7.1 and later. All other [snapshot subcommands](/docs/commands/snapshot)
+version 0.7.1 and later. All other [snapshot subcommands](/commands/snapshot)
are available in the open source version of Consul.
The `snapshot agent` subcommand starts a process that takes snapshots of the
@@ -49,7 +49,7 @@ in the file name when using local storage, or in the object key when using
remote storage.
Snapshots can be restored using the
-[`consul snapshot restore`](/docs/commands/snapshot/restore) command, or
+[`consul snapshot restore`](/commands/snapshot/restore) command, or
the [HTTP API](/api/snapshot).
If ACLs are enabled the following privileges are required:
diff --git a/website/pages/commands/snapshot/index.mdx b/website/pages/commands/snapshot/index.mdx
index 0abe51af33..1967375d2a 100644
--- a/website/pages/commands/snapshot/index.mdx
+++ b/website/pages/commands/snapshot/index.mdx
@@ -38,10 +38,10 @@ Subcommands:
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar or one of the links below:
-- [agent](/docs/commands/snapshot/agent)
-- [inspect](/docs/commands/snapshot/inspect)
-- [restore](/docs/commands/snapshot/restore)
-- [save](/docs/commands/snapshot/save)
+- [agent](/commands/snapshot/agent)
+- [inspect](/commands/snapshot/inspect)
+- [restore](/commands/snapshot/restore)
+- [save](/commands/snapshot/save)
## Basic Examples
diff --git a/website/pages/docs/agent/config-entries/index.mdx b/website/pages/docs/agent/config-entries/index.mdx
index 10e102377c..cd5e3c7da9 100644
--- a/website/pages/docs/agent/config-entries/index.mdx
+++ b/website/pages/docs/agent/config-entries/index.mdx
@@ -34,6 +34,9 @@ The supported `Kind` names for configuration entries are:
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
defaults for all the instances of a given service
+- [`service-intentions`](/docs/agent/config-entries/service-intentions) Beta - defines
+ the [intentions](/docs/connect/intentions) for a destination service
+
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
service instances with a specific Connect upstream discovery requests
@@ -49,7 +52,7 @@ The supported `Kind` names for configuration entries are:
## Managing Configuration Entries
Configuration entries should be managed with the Consul
-[CLI](/docs/commands/config) or [API](/api/config). Additionally, as a
+[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)
@@ -58,7 +61,7 @@ specified in all of the Consul servers's
#### Creating or Updating a Configuration Entry
-The [`consul config write`](/docs/commands/config/write) command is used to
+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.
@@ -88,7 +91,7 @@ overwriting other unknown modifications.
#### Reading a Configuration Entry
-The [`consul config read`](/docs/commands/config/read) command is used to
+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.
@@ -106,7 +109,7 @@ $ consul config read -kind service-defaults -name web
#### Listing Configuration Entries
-The [`consul config list`](/docs/commands/config/list) command is used to
+The [`consul config list`](/commands/config/list) command is used to
list out all the configuration entries for a given kind.
Example:
@@ -120,7 +123,7 @@ db
#### Deleting Configuration Entries
-The [`consul config delete`](/docs/commands/config/delete) command is used
+The [`consul config delete`](/commands/config/delete) command is used
to delete an entry by specifying both its `kind` and `name`.
Example:
diff --git a/website/pages/docs/agent/config-entries/ingress-gateway.mdx b/website/pages/docs/agent/config-entries/ingress-gateway.mdx
index 9604a57b10..cfa06f7aba 100644
--- a/website/pages/docs/agent/config-entries/ingress-gateway.mdx
+++ b/website/pages/docs/agent/config-entries/ingress-gateway.mdx
@@ -636,8 +636,7 @@ Routes = [
## ACLs
-Configuration entries may be protected by
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Configuration entries may be protected by [ACLs](/docs/security/acl).
Reading an `ingress-gateway` config entry requires `service:read` on the `Name`
field of the config entry.
diff --git a/website/pages/docs/agent/config-entries/proxy-defaults.mdx b/website/pages/docs/agent/config-entries/proxy-defaults.mdx
index f91ced8fd1..1fee5d94ac 100644
--- a/website/pages/docs/agent/config-entries/proxy-defaults.mdx
+++ b/website/pages/docs/agent/config-entries/proxy-defaults.mdx
@@ -86,8 +86,7 @@ Config {
## ACLs
-Configuration entries may be protected by
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Configuration entries may be protected by [ACLs](/docs/security/acl).
Reading a `proxy-defaults` config entry requires no specific privileges.
diff --git a/website/pages/docs/agent/config-entries/service-defaults.mdx b/website/pages/docs/agent/config-entries/service-defaults.mdx
index 390e9f1dc3..511702602d 100644
--- a/website/pages/docs/agent/config-entries/service-defaults.mdx
+++ b/website/pages/docs/agent/config-entries/service-defaults.mdx
@@ -36,8 +36,10 @@ Protocol = "http"
- `Protocol` `(string: "tcp")` - Sets the protocol of the service. This is used
by Connect proxies for things like observability features and to unlock usage
of the [`service-splitter`](/docs/agent/config-entries/service-splitter) and
- [`service-router`](/docs/agent/config-entries/service-router) config
- entries for a service. Supported values are one of `tcp`, `http`, `http2`, or `grpc`.
+ [`service-router`](/docs/agent/config-entries/service-router) config entries
+ for a service. It also unlocks the ability to define L7 intentions via
+ [`service-intentions`](/docs/agent/config-entries/service-intentions).
+ Supported values are one of `tcp`, `http`, `http2`, or `grpc`.
- `MeshGateway` `(MeshGatewayConfig: )` - Controls the default
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration)
@@ -74,10 +76,9 @@ Protocol = "http"
## ACLs
-Configuration entries may be protected by
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-Reading a `service-defaults` config entry requires `service:read` on itself.
+Reading a `service-defaults` config entry requires `service:read` on the resource.
Creating, updating, or deleting a `service-defaults` config entry requires
-`service:write` on itself.
+`service:write` on the resource.
diff --git a/website/pages/docs/agent/config-entries/service-intentions.mdx b/website/pages/docs/agent/config-entries/service-intentions.mdx
new file mode 100644
index 0000000000..f254a6004a
--- /dev/null
+++ b/website/pages/docs/agent/config-entries/service-intentions.mdx
@@ -0,0 +1,329 @@
+---
+layout: docs
+page_title: 'Configuration Entry Kind: Service Intentions (beta)'
+sidebar_title: service-intentions Beta
+description: >-
+ The service-intentions config entry kind controls Connect traffic
+ authorization for both networking layer 4 (e.g. TCP) and networking layer 7
+ (e.g. HTTP).
+---
+
+# Service Intentions ((#service-intentions)) Beta
+
+-> **1.9.0+:** This config entry is available in Consul versions 1.9.0 and newer.
+
+The `service-intentions` config entry kind controls Connect traffic
+authorization for both networking layer 4 (e.g. TCP) and networking layer 7
+(e.g. HTTP).
+
+Service intentions config entries represent a collection of
+[intentions](/docs/connect/intentions) sharing a specific destination. All
+intentions governing access to a specific destination are stored in a single
+`service-intentions` config entry.
+
+A single config entry may define a mix of both L4 and L7 style intentions, but
+for a specific source L4 and L7 intentions are mutually exclusive. Only one
+will apply at a time. Default behavior for L4 is configurable (regardless of
+global setting) by defining a low precedence intention for that destination.
+
+## Interaction with other Config Entries
+
+L7 intentions within a config entry are restricted to only destination services
+that define their protocol as HTTP-based via a corresponding
+[`service-defaults`](/docs/agent/config-entries/service-defaults) config entry
+or globally via [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
+
+## Sample Config Entries
+
+Grant some clients more REST access than others:
+
+```hcl
+Kind = "service-intentions"
+Name = "api"
+Sources = [
+ {
+ Name = "admin-dashboard"
+ Permissions = [
+ {
+ Action = "allow"
+ HTTP {
+ PathPrefix = "/v2"
+ Methods = ["GET", "PUT", "POST", "DELETE", "HEAD"]
+ }
+ }
+ ]
+ },
+ {
+ Name = "report-generator"
+ Permissions = [
+ {
+ Action = "allow"
+ HTTP {
+ PathPrefix = "/v2/widgets"
+ Methods = ["GET"]
+ }
+ }
+ ]
+ }
+ # NOTE: a default catch-all based on the default ACL policy will apply to
+ # unmatched connections and requests. Typically this will be DENY.
+]
+```
+
+Selectively deny some gRPC service methods. Since gRPC method calls [are
+HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can
+use an HTTP path match rule to control traffic:
+
+```hcl
+Kind = "service-intentions"
+Name = "billing"
+Sources = [
+ {
+ Name = "frontend-web"
+ Permissions = [
+ # The frontend website can execute all billing service methods except
+ # issuing refunds.
+ {
+ Action = "deny"
+ HTTP {
+ PathExact = "/mycompany.BillingService/IssueRefund"
+ }
+ },
+ {
+ Action = "allow"
+ HTTP {
+ PathPrefix = "/mycompany.BillingService/"
+ }
+ }
+ ]
+ },
+ {
+ Name = "support-portal"
+ Permissions = [
+ # But the support team portal page can execute all methods.
+ {
+ Action = "allow"
+ HTTP {
+ PathPrefix = "/mycompany.BillingService/"
+ }
+ }
+ ]
+ }
+ # NOTE: a default catch-all based on the default ACL policy will apply to
+ # unmatched connections and requests. Typically this will be DENY.
+]
+```
+
+You can mix and match L4 and L7 intentions per source:
+
+```hcl
+Kind = "service-intentions"
+Name = "api"
+Sources = [
+ {
+ Name = "hackathon-project"
+ Action = "deny"
+ },
+ {
+ Name = "web"
+ Action = "allow"
+ },
+ {
+ Name = "nightly-reconciler"
+ Permissions = [
+ {
+ Action = "allow"
+ HTTP {
+ PathExact = "/v1/reconcile-data"
+ Methods = ["POST"]
+ }
+ }
+ ]
+ },
+ # NOTE: a default catch-all based on the default ACL policy will apply to
+ # unmatched connections and requests. Typically this will be DENY.
+]
+```
+
+## Available Fields
+
+- `Kind` - Must be set to `service-intentions`.
+
+- `Name` `(string: )` - The destination of all intentions defined in
+ this config entry. This may be set to the wildcard character (`*`) to match
+ all services that don't otherwise have intentions defined.
+
+- `Namespace` `(string: "default")` - Specifies the namespace the config entry will apply to.
+ This may be set to the wildcard character (`*`) to match
+ all services in all namespaces that don't otherwise have intentions defined.
+
+- `Meta` `(map: nil)` - Specifies arbitrary KV metadata pairs.
+
+- `Sources` `(array)` - The list of all [intention sources and
+ the authorization granted to those sources](#sourceintention). The order of
+ this list does not matter, but out of convenience Consul will always store
+ this reverse sorted by intention precedence, as that is the order that they
+ will be evaluated at enforcement time.
+
+### `SourceIntention`
+
+- `Name` `(string: )` - The source of the intention.
+ For a `Type` of `consul` this is the name of a Consul service. The service
+ doesn't need to be registered.
+
+- `Namespace` `(string: "default")` - The namespace
+ for the `Name` parameter.
+
+- `Action` `(string: "")` - For an L4 intention this is required, and should be
+ set to one of `"allow"` or `"deny"` for the action that should be taken if
+ this intention matches a request.
+
+ This should be omitted for an L7 intention as it is mutually exclusive with
+ the `Permissions` field.
+
+- `Permissions` `(array)` - The list of all [additional L7
+ attributes](#intentionpermission) that extend the intention match criteria.
+
+ Permission precedence is applied top to bottom. For any given request the
+ first permission to match in the list is terminal and stops further
+ evaluation. As with L4 intentions, traffic that fails to match any of the
+ provided permissions in this intention will be subject to the default
+ intention behavior is defined by the default [ACL
+ policy](/docs/agent/options#acl_default_policy).
+
+ This should be omitted for an L4 intention as it is mutually exclusive with
+ the `Action` field.
+
+- `Precedence` `(int: )` - An [integer precedence
+ value](/docs/connect/intentions#precedence-and-match-order) computed from the
+ source and destination naming components.
+
+- `Type` `(string: "")` - The type for the `Name` value. This can be
+ only "consul" today to represent a Consul service. If not provided, this
+ will be defaulted to "consul".
+
+- `Description` `(string: "")` - Description for the intention. This is not
+ used by Consul, but is presented in API responses to assist tooling.
+
+- `LegacyID` `(string: )` - This is the UUID to uniquely identify
+ this intention in the system. Cannot be set directly and is exposed here as
+ an artifact of the config entry migration and is primarily used to allow
+ legacy intention [API](/api-docs/connect/intentions#update-intention-by-id)
+ [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
+ continue to function for a period of time after [upgrading to
+ 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
+
+- `LegacyMeta` `(map: )` - Specified arbitrary KV
+ metadata pairs attached to the intention, rather than to the enclosing config
+ entry. Cannot be set directly and is exposed here as an artifact of the
+ config entry migration and is primarily used to allow legacy intention
+ [API](/api-docs/connect/intentions#update-intention-by-id)
+ [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
+ continue to function for a period of time after [upgrading to
+ 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
+
+- `LegacyCreateTime` `(time: optional)` - The timestamp that this intention was
+ created. Cannot be set directly and is exposed here as an artifact of the
+ config entry migration and is primarily used to allow legacy intention
+ [API](/api-docs/connect/intentions#update-intention-by-id)
+ [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
+ continue to function for a period of time after [upgrading to
+ 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
+
+- `LegacyUpdateTime` `(time: optional)` - The timestamp that this intention was
+ last updated. Cannot be set directly and is exposed here as an artifact of
+ the config entry migration and is primarily used to allow legacy intention
+ [API](/api-docs/connect/intentions#update-intention-by-id)
+ [endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
+ continue to function for a period of time after [upgrading to
+ 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
+
+### `IntentionPermission`
+
+- `Action` `(string: )` - This is one of "allow" or "deny" for
+ the action that should be taken if this permission matches a request.
+
+- `HTTP` `(IntentionHTTPPermission: )` - A set of
+ [HTTP-specific authorization criteria](#intentionhttppermission).
+
+### `IntentionHTTPPermission`
+
+- `PathExact` `(string: "")` - Exact path to match on the HTTP request path.
+
+ At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
+
+- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.
+
+ At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
+
+- `PathRegex` `(string: "")` - Regular expression to match on the HTTP
+ request path.
+
+ The syntax is [described below](#regular-expression-syntax).
+
+ At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
+
+- `Methods` `(array)` - A list of HTTP methods for which this match
+ applies. If unspecified all HTTP methods are matched.
+ If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).
+
+- `Header` `(array)` - A set of criteria that can
+ match on HTTP request headers. If more than one is configured all must match
+ for the overall match to apply.
+
+ - `Name` `(string: )` - Name of the header to match.
+
+ - `Present` `(bool: false)` - Match if the header with the given name is
+ present with any value.
+
+ At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
+ may be configured.
+
+ - `Exact` `(string: "")` - Match if the header with the given name is this
+ value.
+
+ At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
+ may be configured.
+
+ - `Prefix` `(string: "")` - Match if the header with the given name has
+ this prefix.
+
+ At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
+ may be configured.
+
+ - `Suffix` `(string: "")` - Match if the header with the given name has
+ this suffix.
+
+ At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
+ may be configured.
+
+ - `Regex` `(string: "")` - Match if the header with the given name matches
+ this pattern.
+
+ The syntax is [described below](#regular-expression-syntax).
+
+ At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
+ may be configured.
+
+ - `Invert` `(bool: false)` - Inverts the logic of the match.
+
+## ACLs
+
+Configuration entries may be protected by [ACLs](/docs/security/acl).
+
+Reading a `service-intentions` config entry requires `intentions:read` on the resource.
+
+Creating, updating, or deleting a `service-intentions` config entry requires
+`intentions:write` on the resource.
+
+Intention ACL rules are specified as part of a `service` rule. See [Intention
+Management Permissions](/docs/connect/intentions#intention-management-permissions) for
+more details.
+
+## Regular Expression Syntax
+
+The actual syntax of the regular expression fields described here is entirely
+proxy-specific.
+
+When using [Envoy](/docs/connect/proxies/envoy) as a proxy, the syntax for
+these fields is [RE2](https://github.com/google/re2/wiki/Syntax).
diff --git a/website/pages/docs/agent/config-entries/service-resolver.mdx b/website/pages/docs/agent/config-entries/service-resolver.mdx
index 1b89d90a86..427e49f66d 100644
--- a/website/pages/docs/agent/config-entries/service-resolver.mdx
+++ b/website/pages/docs/agent/config-entries/service-resolver.mdx
@@ -241,13 +241,12 @@ referenced by their names throughout the other configuration entry kinds.
## ACLs
-Configuration entries may be protected by
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-Reading a `service-resolver` config entry requires `service:read` on itself.
+Reading a `service-resolver` config entry requires `service:read` on the resource.
Creating, updating, or deleting a `service-resolver` config entry requires
-`service:write` on itself and `service:read` on any other service referenced by
+`service:write` on the resource and `service:read` on any other service referenced by
name in these fields:
- [`Redirect.Service`](#service)
diff --git a/website/pages/docs/agent/config-entries/service-router.mdx b/website/pages/docs/agent/config-entries/service-router.mdx
index ff6aba1031..5cd4e3617b 100644
--- a/website/pages/docs/agent/config-entries/service-router.mdx
+++ b/website/pages/docs/agent/config-entries/service-router.mdx
@@ -24,7 +24,7 @@ service of the same name.
Management](/docs/connect/l7-traffic-management).
- Service router config entries are restricted to only services that define
- their protocol as http-based via a corresponding
+ their protocol as HTTP-based via a corresponding
[`service-defaults`](/docs/agent/config-entries/service-defaults) config
entry or globally via
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
@@ -102,7 +102,7 @@ Routes = [
```
Re-route a gRPC method to another service. Since gRPC method calls [are
-HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic:
+HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic:
```hcl
Kind = "service-router"
@@ -142,7 +142,7 @@ Routes = [
match incoming L7 requests. If empty or omitted it acts as a catch-all.
- `HTTP` `(ServiceRouteHTTPMatch: )` - A set of
- [http-specific match criteria](#serviceroutehttpmatch).
+ [HTTP-specific match criteria](#serviceroutehttpmatch).
- `Destination` `(ServiceRouteDestination: )` - Controls [how to
proxy](#serviceroutedestination) the matching request(s) to a
@@ -156,7 +156,7 @@ Routes = [
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.
- At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
+ At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
- `PathRegex` `(string: "")` - Regular expression to match on the HTTP
request path.
@@ -165,6 +165,10 @@ Routes = [
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
+- `Methods` `(array)` - A list of HTTP methods for which this match
+ applies. If unspecified all HTTP methods are matched.
+ If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).
+
- `Header` `(array)` - A set of criteria that can
match on HTTP request headers. If more than one is configured all must match
for the overall match to apply.
@@ -228,9 +232,6 @@ Routes = [
At most only one of `Exact`, `Regex`, or `Present` may be configured.
-- `Methods` `(array)` - A list of HTTP methods for which this match
- applies. If unspecified all http methods are matched.
-
### `ServiceRouteDestination`
- `Service` `(string: "")` - The service to resolve instead of the default
@@ -258,18 +259,17 @@ Routes = [
- `RetryOnConnectFailure` `(bool: false)` - Allows for connection failure
errors to trigger a retry.
-- `RetryOnStatusCodes` `(array)` - A flat list of http response status
- codes that are eligible for retry.
+- `RetryOnStatusCodes` `(array)` - A list of HTTP response status codes
+ that are eligible for retry.
## ACLs
-Configuration entries may be protected by
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-Reading a `service-router` config entry requires `service:read` on itself.
+Reading a `service-router` config entry requires `service:read` on the resource.
Creating, updating, or deleting a `service-router` config entry requires
-`service:write` on itself and `service:read` on any other service referenced by
+`service:write` on the resource and `service:read` on any other service referenced by
name in these fields:
- [`Routes[].Destination.Service`](#service)
diff --git a/website/pages/docs/agent/config-entries/service-splitter.mdx b/website/pages/docs/agent/config-entries/service-splitter.mdx
index b164d34cb6..f22be3729d 100644
--- a/website/pages/docs/agent/config-entries/service-splitter.mdx
+++ b/website/pages/docs/agent/config-entries/service-splitter.mdx
@@ -105,13 +105,12 @@ Splits = [
## ACLs
-Configuration entries may be protected by
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-Reading a `service-splitter` config entry requires `service:read` on itself.
+Reading a `service-splitter` config entry requires `service:read` on the resource.
Creating, updating, or deleting a `service-splitter` config entry requires
-`service:write` on itself and `service:read` on any other service referenced by
+`service:write` on the resource and `service:read` on any other service referenced by
name in these fields:
- [`Splits[].Service`](#service)
diff --git a/website/pages/docs/agent/config-entries/terminating-gateway.mdx b/website/pages/docs/agent/config-entries/terminating-gateway.mdx
index c7e2a339a9..8c6be6a43e 100644
--- a/website/pages/docs/agent/config-entries/terminating-gateway.mdx
+++ b/website/pages/docs/agent/config-entries/terminating-gateway.mdx
@@ -439,8 +439,7 @@ and configure default certificates for mutual TLS. Also override the SNI and CA
## ACLs
-Configuration entries may be protected by
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Configuration entries may be protected by [ACLs](/docs/security/acl).
Reading a `terminating-gateway` config entry requires `service:read` on the `Name`
field of the config entry.
diff --git a/website/pages/docs/agent/index.mdx b/website/pages/docs/agent/index.mdx
index 0a02c0b659..d7e153c72b 100644
--- a/website/pages/docs/agent/index.mdx
+++ b/website/pages/docs/agent/index.mdx
@@ -26,7 +26,7 @@ operations and maintain very little state of their own.
## Running an Agent
-The agent is started with the [`consul agent`](/docs/commands/agent) command.
+The agent is started with the [`consul agent`](/commands/agent) command.
This command blocks, running forever or until told to quit. You can test a
local agent by following the
[Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-install?utm_source=consul.io&utm_medium=docs).
@@ -35,7 +35,7 @@ The agent command takes a variety of
[`configuration options`](/docs/agent/options#command-line-options), but most
have sane defaults.
-When running [`consul agent`](/docs/commands/agent), you should see output
+When running [`consul agent`](/commands/agent), you should see output
similar to this:
```shell-session
@@ -55,7 +55,7 @@ $ consul agent -data-dir=/tmp/consul
```
There are several important messages that
-[`consul agent`](/docs/commands/agent) outputs:
+[`consul agent`](/commands/agent) outputs:
- **Node name**: This is a unique name for the agent. By default, this
is the hostname of the machine, but you may customize it using the
@@ -80,7 +80,7 @@ There are several important messages that
This includes the ports for the HTTP and DNS interfaces. By default, this
binds only to localhost. If you change this address or port, you'll have to
specify a `-http-addr` whenever you run commands such as
- [`consul members`](/docs/commands/members) to indicate how to reach the
+ [`consul members`](/commands/members) to indicate how to reach the
agent. Other applications can also use the HTTP address and port
[to control Consul](/api).
@@ -112,7 +112,7 @@ cluster that the node has _left_.
When a Server is gracefully exited, the server will not be marked as _left_.
This is to minimally impact the consensus quorum. Instead, the Server will be
marked as _failed_. To remove a server from the cluster, the
-[`force-leave`](/docs/commands/force-leave) command is used. Using
+[`force-leave`](/commands/force-leave) command is used. Using
`force-leave` will put the server instance in a _left_ state so long as the
Server agent is not alive.
@@ -139,7 +139,7 @@ with a cluster and how the cluster treats a node.
When an agent is first started, it does not know about any other node in the
cluster.
To discover its peers, it must _join_ the cluster. This is done with the
-[`join`](/docs/commands/join)
+[`join`](/commands/join)
command or by providing the proper configuration to auto-join on start. Once a
node joins, this information is gossiped to the entire cluster, meaning all
nodes will eventually be aware of each other. If the agent is a server,
diff --git a/website/pages/docs/agent/options.mdx b/website/pages/docs/agent/options.mdx
index 80bd573152..c31069c2c0 100644
--- a/website/pages/docs/agent/options.mdx
+++ b/website/pages/docs/agent/options.mdx
@@ -37,7 +37,7 @@ Consul also supports reloading configuration when it receives the
SIGHUP signal. Not all changes are respected, but those that are
documented below in the
[Reloadable Configuration](#reloadable-configuration) section. The
-[reload command](/docs/commands/reload) can also be used to trigger a
+[reload command](/commands/reload) can also be used to trigger a
configuration reload.
You can test the following configuration options by following the
@@ -235,7 +235,7 @@ The options below are all specified on the command-line.
- `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption
of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The
- easiest way to create an encryption key is to use [`consul keygen`](/docs/commands/keygen).
+ easiest way to create an encryption key is to use [`consul keygen`](/commands/keygen).
All nodes within a cluster must share the same encryption key to communicate. The
provided key is automatically persisted to the data directory and loaded automatically
whenever the agent is restarted. This means that to encrypt Consul's gossip protocol,
@@ -381,7 +381,7 @@ The options below are all specified on the command-line.
- `-log-level` ((#\_log_level)) - The level of logging to show after the
Consul agent has started. This defaults to "info". The available log levels are
"trace", "debug", "info", "warn", and "err". You can always connect to an agent
- via [`consul monitor`](/docs/commands/monitor) and use any log level. Also,
+ via [`consul monitor`](/commands/monitor) and use any log level. Also,
the log level can be changed during a config reload.
- `-log-json` ((#\_log_json)) - This flag enables the agent to output logs
@@ -899,7 +899,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
Consul servers. When these keys are provided as configuration, they will only be
respected on bootstrapping. If they are not provided, the defaults will be used.
In order to change the value of these options after bootstrapping, you will need
- to use the [Consul Operator Autopilot](/docs/commands/operator/autopilot)
+ to use the [Consul Operator Autopilot](/commands/operator/autopilot)
command. For more information about Autopilot, review the [Autopilot tutorial](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations).
The following sub-keys are available:
@@ -1191,7 +1191,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
the Consul server gains leadership. This option is only applicable to server
nodes. Each bootstrap entry will be created only if it does not exist. When reloading,
any new entries that have been added to the configuration will be processed.
- See the [configuration entry docs](/docs/agent/config_entries) for more
+ See the [configuration entry docs](/docs/agent/config-entries) for more
details about the contents of each entry.
- `connect` This object allows setting options for the Connect feature.
diff --git a/website/pages/docs/agent/telemetry.mdx b/website/pages/docs/agent/telemetry.mdx
index a598fd10ad..c5d842519b 100644
--- a/website/pages/docs/agent/telemetry.mdx
+++ b/website/pages/docs/agent/telemetry.mdx
@@ -289,7 +289,7 @@ These metrics give insight into the health of the cluster as a whole.
| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options#ports). | flaps / interval | counter |
| `consul.serf.member.join` | This increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter |
| `consul.serf.member.left` | This increments when an agent leaves the cluster. | leaves / interval | counter |
-| `consul.serf.events` | This increments when an agent processes an [event](/docs/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter |
+| `consul.serf.events` | This increments when an agent processes an [event](/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter |
| `consul.autopilot.failure_tolerance` | This tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge |
| `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. | boolean | gauge |
| `consul.session_ttl.active` | This tracks the active number of sessions being tracked. | sessions | gauge |
diff --git a/website/pages/docs/architecture/coordinates.mdx b/website/pages/docs/architecture/coordinates.mdx
index a6c7187b58..eed59fff8e 100644
--- a/website/pages/docs/architecture/coordinates.mdx
+++ b/website/pages/docs/architecture/coordinates.mdx
@@ -23,7 +23,7 @@ with some enhancements based on other research. There are more details about
Network coordinates manifest in several ways inside Consul:
-- The [`consul rtt`](/docs/commands/rtt) command can be used to query for the
+- The [`consul rtt`](/commands/rtt) command can be used to query for the
network round trip time between any two nodes.
- The [Catalog endpoints](/api/catalog) and
diff --git a/website/pages/docs/connect/ca/index.mdx b/website/pages/docs/connect/ca/index.mdx
index 5e91a0354e..3af7f0e6a1 100644
--- a/website/pages/docs/connect/ca/index.mdx
+++ b/website/pages/docs/connect/ca/index.mdx
@@ -50,7 +50,7 @@ Root certificates can be queried with the
With this endpoint, you can see the list of currently trusted root certificates.
When a cluster first initializes, this will only list one trusted root. Multiple
roots may appear as part of
-[rotation](#).
+[rotation](#root-certificate-rotation).
```shell-session
$ curl http://localhost:8500/v1/connect/ca/roots
diff --git a/website/pages/docs/connect/configuration.mdx b/website/pages/docs/connect/configuration.mdx
index 1e501865ee..104bdb9539 100644
--- a/website/pages/docs/connect/configuration.mdx
+++ b/website/pages/docs/connect/configuration.mdx
@@ -54,7 +54,7 @@ gRPC](/docs/agent/options#grpc_port).
Additionally if you plan on using the observability features of Connect, it can
be convenient to configure your proxies and services using [configuration
-entries](/docs/agent/config_entries) which you can interact with using the
+entries](/docs/agent/config-entries) which you can interact with using the
CLI or API, or by creating configuration entry files. You will want to enable
[centralized service
configuration](/docs/agent/options#enable_central_service_config) on
@@ -71,7 +71,7 @@ needed for a secure deployment.
To account for common Connect use cases where you have many instances of the
same service, and many colocated sidecar proxies, Consul allows you to customize
the settings for all of your proxies or all the instances of a given service at
-once using [Configuration Entries](/docs/agent/config_entries).
+once using [Configuration Entries](/docs/agent/config-entries).
You can override centralized configurations for individual proxy instances in
their
@@ -100,5 +100,5 @@ configure Connect on Nomad by reading the
The Consul Helm chart can automate much of Consul Connect's configuration, and
makes it easy to automatically inject Envoy sidecars into new pods when they are
deployed. Learn about the [Helm chart](/docs/platform/k8s/helm) in general,
-or if you are already familiar with it, check out it's
+or if you are already familiar with it, check out its
[connect specific configurations](/docs/platform/k8s/connect).
diff --git a/website/pages/docs/connect/connect-internals.mdx b/website/pages/docs/connect/connect-internals.mdx
index ef4eb6a0b6..40b8b1bf61 100644
--- a/website/pages/docs/connect/connect-internals.mdx
+++ b/website/pages/docs/connect/connect-internals.mdx
@@ -37,13 +37,15 @@ to this, the client provides its own client certificate to show its
identity to the destination service. If the connection handshake succeeds,
the connection is encrypted and authorized.
-The destination service verifies the client certificate
-against the [public CA bundle](/api/connect/ca#list-ca-root-certificates).
-After verifying the certificate, it must also call the
-[authorization API](/api/agent/connect#authorize) to authorize
-the connection against the configured set of Consul [intentions](/docs/connect/intentions).
-If the authorization API responds successfully, the connection is established.
-Otherwise, the connection is rejected.
+The destination service verifies the client certificate against the [public CA
+bundle](/api/connect/ca#list-ca-root-certificates). After verifying the
+certificate, the next step depends upon the configured application protocol of
+the destination service. TCP (L4) services must authorize incoming _connections_
+against the configured set of Consul [intentions](/docs/connect/intentions),
+whereas HTTP (L7) services must authorize incoming _requests_ against those same
+intentions. If the intention check responds successfully, the
+connection/request is established. Otherwise the connection/request is
+rejected.
To generate and distribute certificates, Consul has a built-in CA that
requires no other dependencies, and
@@ -59,12 +61,12 @@ in-memory data.
## Agent Caching and Performance
-To enable fast responses on [agent Connect API
-endpoints](/api/agent/connect), the Consul agent locally caches most
-Connect-related data and sets up background [blocking
-queries](/api/features/blocking) against the server to update the cache in
-the background. This allows most API calls such as retrieving certificates or
-authorizing connections to use in-memory data and respond very quickly.
+To enable fast responses on endpoints such as the [agent Connect
+API](/api/agent/connect), the Consul agent locally caches most Connect-related
+data and sets up background [blocking queries](/api/features/blocking) against
+the server to update the cache in the background. This allows most API calls
+such as retrieving certificates or authorizing connections to use in-memory
+data and respond very quickly.
All data cached locally by the agent is populated on demand. Therefore, if
Connect is not used at all, the cache does not store any data. On first request,
@@ -94,16 +96,16 @@ a long period of inactivity (3 days by default), the cache will empty itself.
## Connections Across Datacenters
-Sidecar proxy's [upstream configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
+A sidecar proxy's [upstream configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
may specify an alternative datacenter or a prepared query that can address services
in multiple datacenters (such as the [geo failover](https://learn.hashicorp.com/tutorials/consul/automate-geo-failover) pattern).
[Intentions](/docs/connect/intentions) verify connections between services by
source and destination name seamlessly across datacenters.
-Connections can be made via gateways to enable when communicating across
-network topologies allowing connections between services in each datacenter
-without externally routable IPs at the service level.
+Connections can be made via gateways to enable communicating across network
+topologies, allowing connections between services in each datacenter without
+externally routable IPs at the service level.
## Intention Replication
diff --git a/website/pages/docs/connect/dev.mdx b/website/pages/docs/connect/dev.mdx
index 86cbc75f46..2d9909c036 100644
--- a/website/pages/docs/connect/dev.mdx
+++ b/website/pages/docs/connect/dev.mdx
@@ -15,7 +15,7 @@ description: >-
It is often necessary to connect to a service for development or debugging.
If a service only exposes a Connect listener, then we need a way to establish
a mutual TLS connection to the service. The
-[`consul connect proxy` command](/docs/commands/connect/proxy) can be used
+[`consul connect proxy` command](/commands/connect/proxy) can be used
for this task on any machine with access to a Consul agent (local or remote).
Restricting access to services only via Connect ensures that the only way to
diff --git a/website/pages/docs/connect/gateways/terminating-gateway.mdx b/website/pages/docs/connect/gateways/terminating-gateway.mdx
index 889dd1db97..3ec70c2562 100644
--- a/website/pages/docs/connect/gateways/terminating-gateway.mdx
+++ b/website/pages/docs/connect/gateways/terminating-gateway.mdx
@@ -44,7 +44,7 @@ from the gateway to the destination service.
When certificates for linked services are rotated, the gateway must be restarted to pick up the new certificates from disk.
To avoid downtime, perform a rolling restart to reload the certificates. Registering multiple terminating gateway instances
-with the same [name](https://www.consul.io/docs/commands/connect/envoy#service) provides additional fault tolerance
+with the same [name](/commands/connect/envoy#service) provides additional fault tolerance
as well as the ability to perform rolling restarts.
-> **Note:** If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS.
@@ -99,12 +99,12 @@ must also provide `agent:read` for its node's name in order to discover the agen
Linking services to a terminating gateway is done with a `terminating-gateway`
[configuration entry](/docs/agent/config-entries/terminating-gateway). This config entry can be applied via the
-[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).
+[CLI](/commands/config/write) or [API](/api/config#apply-configuration).
Gateways with the same name in Consul's service catalog are configured with a single configuration entry.
This means that additional gateway instances registered with the same name will determine their routing based on the existing configuration entry.
Adding replicas of a gateway that routes to a particular set of services requires running the
-[envoy subcommand](/docs/commands/connect/envoy#terminating-gateways) on additional hosts and specifying
+[envoy subcommand](/commands/connect/envoy#terminating-gateways) on additional hosts and specifying
the same gateway name with the `service` flag.
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
diff --git a/website/pages/docs/connect/intentions-legacy.mdx b/website/pages/docs/connect/intentions-legacy.mdx
new file mode 100644
index 0000000000..8d8d84c4e4
--- /dev/null
+++ b/website/pages/docs/connect/intentions-legacy.mdx
@@ -0,0 +1,193 @@
+---
+layout: docs
+page_title: Service-to-service permissions - Intentions (Legacy Mode)
+sidebar_title: Service-to-service permissions - Intentions (Legacy Mode)
+description: >-
+ Intentions define access control for services via Connect and are used to
+ control which services may establish connections. Intentions can be managed
+ via the API, CLI, or UI.
+---
+
+# Intentions in Legacy Mode
+
+~> **1.8.x and earlier:** This document only applies in Consul versions 1.8.x
+and before. If you are using version 1.9.0 or later please use the updated
+documentation [here](/docs/connect/intentions).
+
+Intentions define access control for services via Connect and are used
+to control which services may establish connections. Intentions can be
+managed via the API, CLI, or UI.
+
+Intentions are enforced by the [proxy](/docs/connect/proxies)
+or [natively integrated application](/docs/connect/native) on
+inbound connections. After verifying the TLS client certificate, the
+[authorize API endpoint](/api-docs/agent/connect#authorize) is called which verifies the connection
+is allowed by testing the intentions. If authorize returns false the
+connection must be terminated.
+
+The default intention behavior is defined by the default [ACL
+policy](/docs/agent/options#acl_default_policy). If the default ACL policy is
+"allow all", then all Connect connections are allowed by default. If the
+default ACL policy is "deny all", then all Connect connections are denied by
+default.
+
+## Intention Basics
+
+Intentions can be managed via the [API](/api-docs/connect/intentions),
+[CLI](/commands/intention), or UI. Please see the respective documentation for
+each for full details on options, flags, etc. Below is an example of a basic
+intention to show the basic attributes of an intention. The full data model of
+an intention can be found in the [API
+documentation](/api-docs/connect/intentions).
+
+```shell-session
+$ consul intention create -deny web db
+Created: web => db (deny)
+```
+
+The intention above is a deny intention with a source of "web" and
+destination of "db". This says that connections from web to db are not
+allowed and the connection will be rejected.
+
+When an intention is modified, existing connections will not be affected.
+This means that changing a connection from "allow" to "deny" today
+_will not_ kill the connection. Addressing this shortcoming is on
+the near term roadmap for Consul.
+
+### Wildcard Intentions
+
+An intention source or destination may also be the special wildcard
+value `*`. This matches _any_ value and is used as a catch-all. Example:
+
+```shell-session
+$ consul intention create -deny web '*'
+Created: web => * (deny)
+```
+
+This example says that the "web" service cannot connect to _any_ service.
+
+### Metadata
+
+Arbitrary string key/value data may be associated with intentions. This
+is unused by Consul but can be used by external systems or for visibility
+in the UI.
+
+```shell-session
+$ consul intention create \
+ -deny \
+ -meta description='Hello there' \
+ web db
+...
+
+$ consul intention get web db
+Source: web
+Destination: db
+Action: deny
+ID: 31449e02-c787-f7f4-aa92-72b5d9b0d9ec
+Meta[description]: Hello there
+Created At: Friday, 25-May-18 02:07:51 CEST
+```
+
+## Precedence and Match Order
+
+Intentions are matched in an implicit order based on specificity, preferring
+deny over allow. Specificity is determined by whether a value is an exact
+specified value or is the wildcard value `*`.
+The full precedence table is shown below and is evaluated
+top to bottom, with larger numbers being evaluated first.
+
+| Source Namespace | Source Name | Destination Namespace | Destination Name | Precedence |
+| ---------------- | ----------- | --------------------- | ---------------- | ---------- |
+| Exact | Exact | Exact | Exact | 9 |
+| Exact | `*` | Exact | Exact | 8 |
+| `*` | `*` | Exact | Exact | 7 |
+| Exact | Exact | Exact | `*` | 6 |
+| Exact | `*` | Exact | `*` | 5 |
+| `*` | `*` | Exact | `*` | 4 |
+| Exact | Exact | `*` | `*` | 3 |
+| Exact | `*` | `*` | `*` | 2 |
+| `*` | `*` | `*` | `*` | 1 |
+
+The precedence value can be read from the [API](/api/connect/intentions)
+after an intention is created.
+Precedence cannot be manually overridden today. This is a feature that will
+be added in a later version of Consul.
+
+In the case the two precedence values match, Consul will evaluate
+intentions based on lexicographical ordering of the destination then
+source name. In practice, this is a moot point since authorizing a connection
+has an exact source and destination value so its impossible for two
+valid non-wildcard intentions to match.
+
+The numbers in the table above are not stable. Their ordering will remain
+fixed but the actual number values may change in the future.
+
+-> **Consul Enterprise** - Namespaces are an Enterprise feature. In Consul OSS any of the rows in
+the table with a `*` for either the source namespace or destination namespace are not applicable.
+
+## Intention Management Permissions
+
+Intention management can be protected by [ACLs](/docs/security/acl).
+Permissions for intentions are _destination-oriented_, meaning the ACLs
+for managing intentions are looked up based on the destination value
+of the intention, not the source.
+
+Intention permissions are by default implicitly granted at `read` level
+when granting `service:read` or `service:write`. This is because a
+service registered that wants to use Connect needs `intentions:read`
+for its own service name in order to know whether or not to authorize
+connections. The following ACL policy will implicitly grant `intentions:read`
+(note _read_) for service `web`.
+
+```hcl
+service "web" {
+ policy = "write"
+}
+```
+
+It is possible to explicitly specify intention permissions. For example,
+the following policy will allow a service to be discovered without granting
+access to read intentions for it.
+
+```hcl
+service "web" {
+ policy = "read"
+ intentions = "deny"
+}
+```
+
+Note that `intentions:read` is required for a token that a Connect-enabled
+service uses to register itself or its proxy. If the token used does not
+have `intentions:read` then the agent will be unable to resolve intentions
+for the service and so will not be able to authorize any incoming connections.
+
+~> **Security Note:** Explicitly allowing `intentions:write` on the token you
+provide to a service instance at registration time opens up a significant
+additional vulnerability. Although you may trust the service _team_ to define
+which inbound connections they accept, using a combined token for registration
+allows a compromised instance to to redefine the intentions which allows many
+additional attack vectors and may be hard to detect. We strongly recommend only
+delegating `intentions:write` using tokens that are used by operations teams or
+orchestrators rather than spread via application config, or only manage
+intentions with management tokens.
+
+## Performance and Intention Updates
+
+The intentions for services registered with a Consul agent are cached
+locally on that agent. They are then updated via a background blocking query
+against the Consul servers.
+
+Connect connection attempts require only local agent
+communication for authorization and generally only impose microseconds
+of latency to the connection. All actions in the data path of connections
+require only local data to ensure minimal performance overhead.
+
+Updates to intentions are propagated nearly instantly to agents since agents
+maintain a continuous blocking query in the background for intention updates
+for registered services.
+
+Because all the intention data is cached locally, the agents can fail static.
+Even if the agents are severed completely from the Consul servers, inbound
+connection authorization continues to work for a configured amount of time.
+Changes to intentions will not be picked up until the partition heals, but
+will then automatically take effect when connectivity is restored.
diff --git a/website/pages/docs/connect/intentions.mdx b/website/pages/docs/connect/intentions.mdx
index a2c46cf264..39d7d7b87c 100644
--- a/website/pages/docs/connect/intentions.mdx
+++ b/website/pages/docs/connect/intentions.mdx
@@ -4,85 +4,141 @@ page_title: Service-to-service permissions - Intentions
sidebar_title: Service-to-service permissions - Intentions
description: >-
Intentions define access control for services via Connect and are used to
- control which services may establish connections. Intentions can be managed
- via the API, CLI, or UI.
+ control which services may establish connections or make requests.
---
# Intentions
-Intentions define access control for services via Connect and are used
-to control which services may establish connections. Intentions can be
-managed via the API, CLI, or UI.
+-> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and
+later. The documentation for the legacy intentions system is
+[here](/docs/connect/intentions-legacy).
-Intentions are enforced by the [proxy](/docs/connect/proxies)
-or [natively integrated application](/docs/connect/native) on
-inbound connections. After verifying the TLS client certificate, the
-[authorize API endpoint](/api-docs/agent/connect#authorize) is called which verifies the connection
-is allowed by testing the intentions. If authorize returns false the
-connection must be terminated.
+Intentions define access control for services via Connect and are used to
+control which services may establish connections or make requests. Intentions
+can be managed via the API, CLI, or UI.
-The default intention behavior is defined by the default
-[ACL policy](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). If the default ACL policy is "allow all",
-then all Connect connections are allowed by default. If the default ACL policy
-is "deny all", then all Connect connections are denied by default.
+Intentions are enforced on inbound connections or requests by the
+[proxy](/docs/connect/proxies) or within a [natively integrated
+application](/docs/connect/native).
+
+Depending upon the [protocol] in use by the destination service, you can define
+intentions to control Connect traffic authorization either at networking layer
+4 (e.g. TCP) and networking layer 7 (e.g. HTTP):
+
+* **Identity-based** - All intentions may enforce access based on identities
+ encoded within [TLS
+ certificates](/docs/connect/connect-internals#mutual-transport-layer-security-mtls).
+ This allows for coarse all-or-nothing access control between pairs of
+ services. These work with for services with any [protocol] as they only
+ require awareness of the TLS handshake that wraps the opaque TCP connection.
+ These can also be thought of as **L4 intentions**.
+
+* **Application-aware** - Some intentions may additionally enforce access based
+ on [L7 request
+ attributes](/docs/agent/config-entries/service-intentions#permissions) in
+ addition to connection identity. These may only be defined for services with
+ a [protocol] that is HTTP-based. These can also be thought of as **L7
+ intentions**.
+
+At any given point in time, between any pair of services **only one intention
+controls authorization**. This may be either an L4 intention or an L7
+intention, but at any given point in time only one of those applies.
+
+The [intention match API](/api/connect/intentions#list-matching-intentions)
+should be periodically called to retrieve all relevant intentions for the
+target destination. After verifying the TLS client certificate, the cached
+intentions should be consulted for each incoming connection/request to
+determine if it should be accepted or rejected.
+
+The default intention behavior is defined by the default [ACL
+policy](/docs/agent/options#acl_default_policy). If the default ACL policy is
+"allow all", then all Connect connections are allowed by default. If the
+default ACL policy is "deny all", then all Connect connections or requests are
+denied by default.
## Intention Basics
-Intentions can be managed via the [API](#), [CLI](#),
-or UI. Please see the respective documentation for each for full details
-on options, flags, etc.
-Below is an example of a basic intention to show the basic attributes
-of an intention. The full data model of an intention can be found in the
-[API documentation](#).
+Intentions are managed primarily via
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entries or the UI. Some simpler tasks can also be achieved with the older
+[API](/api-docs/connect/intentions) or [CLI](/commands/intention). Please see
+the respective documentation for each for full details on options, flags, etc.
-```shell-session
-$ consul intention create -deny web db
-Created: web => db (deny)
+Below is an example of a basic
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entry representing two simple intentions. The full data model complete with
+more examples can be found in the
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entry documentation.
+
+```hcl
+Kind = "service-intentions"
+Name = "db"
+Sources = [
+ {
+ Name = "web"
+ Action = "deny"
+ },
+ {
+ Name = "api"
+ Action = "allow"
+ }
+]
```
-The intention above is a deny intention with a source of "web" and
-destination of "db". This says that connections from web to db are not
-allowed and the connection will be rejected.
-
-When an intention is modified, existing connections will not be affected.
-This means that changing a connection from "allow" to "deny" today
-_will not_ kill the connection. Addressing this shortcoming is on
-the near term roadmap for Consul.
+This config entry defines two intentions with a common destination of "db". The
+first intention above is a deny intention with a source of "web". This says
+that connections from web to db are not allowed and the connection will be
+rejected. The second intention is an allow intention with a source of "api".
+This says that connections from api to db are allowed and connections will be
+accepted.
### Wildcard Intentions
An intention source or destination may also be the special wildcard
-value `*`. This matches _any_ value and is used as a catch-all. Example:
+value `*`. This matches _any_ value and is used as a catch-all.
-```shell-session
-$ consul intention create -deny web '*'
-Created: web => * (deny)
+This example says that the "web" service cannot connect to _any_ service:
+
+```hcl
+Kind = "service-intentions"
+Name = "*"
+Sources = [
+ {
+ Name = "web"
+ Action = "deny"
+ }
+]
```
-This example says that the "web" service cannot connect to _any_ service.
+And this example says that _no_ service can connect to the "db" service:
-### Metadata
-
-Arbitrary string key/value data may be associated with intentions. This
-is unused by Consul but can be used by external systems or for visibility
-in the UI.
-
-```shell-session
-$ consul intention create \
- -deny \
- -meta description='Hello there' \
- web db
-...
-
-$ consul intention get web db
-Source: web
-Destination: db
-Action: deny
-ID: 31449e02-c787-f7f4-aa92-72b5d9b0d9ec
-Meta[description]: Hello there
-Created At: Friday, 25-May-18 02:07:51 CEST
+```hcl
+Kind = "service-intentions"
+Name = "db"
+Sources = [
+ {
+ Name = "*"
+ Action = "deny"
+ }
+]
```
+### Enforcement
+
+For services that define their [protocol] as TCP, intentions mediate the
+ability to **establish new connections**. When an intention is modified,
+existing connections will not be affected. This means that changing a
+connection from "allow" to "deny" today _will not_ kill the connection.
+
+For services that define their protocol as HTTP-based, intentions mediate the
+ability to **issue new requests**.
+
+When an intention is modified, requests received after the modification will
+use the latest intention rules to enforce access. This means that though
+changing a connection from "allow" to "deny" today will not kill the
+connection, it will correctly block new requests from being processed.
+
## Precedence and Match Order
Intentions are matched in an implicit order based on specificity, preferring
@@ -103,26 +159,21 @@ top to bottom, with larger numbers being evaluated first.
| Exact | `*` | `*` | `*` | 2 |
| `*` | `*` | `*` | `*` | 1 |
-The precedence value can be read from the [API](/api/connect/intentions)
-after an intention is created.
-Precedence cannot be manually overridden today. This is a feature that will
-be added in a later version of Consul.
-
-In the case the two precedence values match, Consul will evaluate
-intentions based on lexicographical ordering of the destination then
-source name. In practice, this is a moot point since authorizing a connection
-has an exact source and destination value so its impossible for two
-valid non-wildcard intentions to match.
+The precedence value can be read from a
+[field](/docs/agent/config-entries/service-intentions#precedence) on the
+`service-intentions` config entry after it is modified. Precedence cannot be
+manually overridden today.
The numbers in the table above are not stable. Their ordering will remain
fixed but the actual number values may change in the future.
--> **Consul Enterprise** - Namespaces are an Enterprise feature. In Consul OSS any of the rows in
-the table with a `*` for either the source namespace or destination namespace are not applicable.
+-> - Namespaces are an Enterprise feature. In Consul
+OSS the only allowable value for either namespace field is `"default"`. Other
+rows in this table are not applicable.
## Intention Management Permissions
-Intention management can be protected by [ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
+Intention management can be protected by [ACLs](/docs/security/acl).
Permissions for intentions are _destination-oriented_, meaning the ACLs
for managing intentions are looked up based on the destination value
of the intention, not the source.
@@ -152,7 +203,7 @@ service "web" {
```
Note that `intentions:read` is required for a token that a Connect-enabled
-service uses to register itself or it's proxy. If the token used does not
+service uses to register itself or its proxy. If the token used does not
have `intentions:read` then the agent will be unable to resolve intentions
for the service and so will not be able to authorize any incoming connections.
@@ -172,17 +223,23 @@ The intentions for services registered with a Consul agent are cached
locally on that agent. They are then updated via a background blocking query
against the Consul servers.
-Connect connection attempts require only local agent
-communication for authorization and generally impose only impose microseconds
-of latency to the connection. All actions in the data path of connections
-require only local data to ensure minimal performance overhead.
+Supported [proxies] (such as [Envoy]) also cache this data within their own
+configuration so that inbound connections or requests require no Consul agent
+involvement during authorization. All actions in the data path of connections
+happen within the proxy.
Updates to intentions are propagated nearly instantly to agents since agents
maintain a continuous blocking query in the background for intention updates
-for registered services.
+for registered services. Proxies similarly use blocking queries to update
+their local configurations quickly.
-Because all the intention data is cached locally, the agents can fail static.
-Even if the agents are severed completely from the Consul servers, inbound
-connection authorization continues to work for a configured amount of time.
-Changes to intentions will not be picked up until the partition heals, but
-will then automatically take effect when connectivity is restored.
+Because all the intention data is cached locally, the agents or proxies can
+fail static. Even if the agents are severed completely from the Consul servers,
+or the proxies are severed completely from their local Consul agent, inbound
+connection authorization continues to work indefinitely. Changes to intentions
+will not be picked up until the partition heals, but will then automatically
+take effect when connectivity is restored.
+
+[protocol]: /docs/agent/config-entries/service-defaults#protocol
+[proxies]: /docs/connect/proxies
+[Envoy]: /docs/connect/proxies/envoy
diff --git a/website/pages/docs/connect/l7-traffic/discovery-chain.mdx b/website/pages/docs/connect/l7-traffic/discovery-chain.mdx
index f42d52bb22..16c51efd53 100644
--- a/website/pages/docs/connect/l7-traffic/discovery-chain.mdx
+++ b/website/pages/docs/connect/l7-traffic/discovery-chain.mdx
@@ -19,7 +19,7 @@ integrations](/docs/connect/proxies/integrate).
The service discovery process can be modeled as a "discovery chain" which
passes through three distinct stages: routing, splitting, and resolution. Each
of these stages is controlled by a set of [configuration
-entries](/docs/agent/config_entries). By configuring different phases of
+entries](/docs/agent/config-entries). By configuring different phases of
the discovery chain a user can control how proxy upstreams are ultimately
resolved to specific instances for load balancing.
diff --git a/website/pages/docs/connect/l7-traffic/index.mdx b/website/pages/docs/connect/l7-traffic/index.mdx
index c5978201e1..afd80979eb 100644
--- a/website/pages/docs/connect/l7-traffic/index.mdx
+++ b/website/pages/docs/connect/l7-traffic/index.mdx
@@ -37,7 +37,7 @@ traffic.
Each stage of this discovery process can be dynamically reconfigured via various
-[configuration entries](/docs/agent/config_entries). When a configuration
+[configuration entries](/docs/agent/config-entries). When a configuration
entry is missing, that stage will fall back on reasonable default behavior.
### Routing
diff --git a/website/pages/docs/connect/native/go.mdx b/website/pages/docs/connect/native/go.mdx
index 02d0ced963..ba77be4673 100644
--- a/website/pages/docs/connect/native/go.mdx
+++ b/website/pages/docs/connect/native/go.mdx
@@ -11,6 +11,10 @@ description: >-
# Connect-Native Integration with Go
+-> **Note:** When calling `ConnectAuthorize()` on incoming connections this library
+will return *deny* if `Permissions` are defined on the matching intention.
+The method is currently only suited for networking layer 4 (e.g. TCP) integration.
+
We provide a library that makes it drop-in simple to integrate Connect
with most [Go](https://golang.org/) applications. This page shows examples
of integrating this library for accepting or establishing Connect-based
@@ -178,7 +182,7 @@ the following specific limitations:
- `.query[.].consul` to discover an instance via
[Prepared Query](/api/query).
- The top-level domain _must_ be `.consul` even if your cluster has a custom
- `domain` configured for it's DNS interface. This might be relaxed in the
+ `domain` configured for its DNS interface. This might be relaxed in the
future.
- Tag filters for services are not currently supported (i.e.
`tag1.web.service.consul`) however the same behaviour can be achieved using a
@@ -194,8 +198,8 @@ return the `net.Conn`. This connection can then be used as desired.
Example:
-````go
-import(
+```go
+import (
"context"
"github.com/hashicorp/consul/api"
@@ -241,4 +245,3 @@ The Go library provides two built-in resolvers:
* `*connect.ConsulResolver` which resolves services and prepared queries
via the Consul API. This also automatically determines the expected
cert URI SAN.
-````
diff --git a/website/pages/docs/connect/native/index.mdx b/website/pages/docs/connect/native/index.mdx
index 94bcb138bb..e4ad134140 100644
--- a/website/pages/docs/connect/native/index.mdx
+++ b/website/pages/docs/connect/native/index.mdx
@@ -35,7 +35,8 @@ to integrate with Connect.
The primary work involved in natively integrating with Connect is
[acquiring the proper TLS certificate](/api/agent/connect#service-leaf-certificate),
[verifying TLS certificates](/api/agent/connect#certificate-authority-ca-roots),
-and [authorizing inbound connections](/api/agent/connect#authorize).
+and [authorizing inbound connections or requests](/api/connect/intentions#list-matching-intentions).
+
All of this is done using the Consul HTTP APIs linked above.
An overview of the sequence is shown below. The diagram and the following
@@ -44,6 +45,9 @@ an API call to verify the incoming client certificate.
+-> **Note:** This diagram depicts the simpler networking layer 4 (e.g. TCP) [integration
+mechanism](/api/agent/connect#authorize).
+
Details on the steps are below:
- **Service discovery** - This is normal service discovery using Consul,
@@ -61,20 +65,32 @@ Details on the steps are below:
a Connect-based connection and there are no further steps!
- **Authorization** - As a server accepting connections, verify the client
- certificate against the
- [public CA roots](/api/agent/connect#certificate-authority-ca-roots).
- After verifying the certificate, parse some basic fields from it and call
- the [authorizing API](/api/agent/connect#authorize) against the local
- agent. If this returns successfully, complete the TLS handshake and establish
- the connection. If authorization fails, close the connection.
+ certificate against the [public CA
+ roots](/api/agent/connect#certificate-authority-ca-roots). After verifying
+ the certificate, parse some basic fields from it and use those to determine
+ if the connection should be allowed. How this is done is dependent on
+ the level of integration desired:
--> **A note on performance:** The only API call in the connection path is
-the [authorization API](/api/agent/connect#authorize). The other API
-calls to acquire the leaf certificate and CA roots are expected to be done
-out of band and reused. The authorize API call should be called against the
-local Consul agent. The agent uses locally cached
-data to authorize the connection and typically responds in microseconds.
-Therefore, the impact to the TLS handshake is typically microseconds.
+ - **Simple integration (TCP-only)** - Call the [authorizing
+ API](/api/agent/connect#authorize) against the local agent. If this returns
+ successfully, complete the TLS handshake and establish the connection. If
+ authorization fails, close the connection.
+
+ -> **NOTE:** This API call is expected to be called in the connection path,
+ so if the local Consul agent is down or unresponsive it will effect the
+ success rate of new connections. The agent uses locally cached data to
+ authorize the connection and typically responds in microseconds. Therefore,
+ the impact to the TLS handshake is typically microseconds.
+
+ - **Complete integration** - Like how the calls to acquire the leaf
+ certificate and CA roots are expected to be done out of band and reused, so
+ should the [intention match
+ API](/api/connect/intentions#list-matching-intentions). With all of the
+ relevant intentions cached for the destination, all enforcement operations
+ can be done entirely by the service without calling any Consul APIs in the
+ connection or request path. If the service is networking layer 7 (e.g.
+ HTTP) aware it can safely enforce intentions per _request_ instead of the
+ coarser per _connection_ model.
## Updating Certificates and Certificate Roots
diff --git a/website/pages/docs/connect/proxies/built-in.mdx b/website/pages/docs/connect/proxies/built-in.mdx
index f48b3e8cfb..730b6dd6da 100644
--- a/website/pages/docs/connect/proxies/built-in.mdx
+++ b/website/pages/docs/connect/proxies/built-in.mdx
@@ -53,10 +53,10 @@ for the built-in proxy.
All fields are optional with a sane default.
-- `bind_address` - The address the proxy will bind it's
+- `bind_address` - The address the proxy will bind its
_public_ mTLS listener to. It defaults to the same address the agent binds to.
-- `bind_port` - The port the proxy will bind it's _public_
+- `bind_port` - The port the proxy will bind its _public_
mTLS listener to. If not provided, the agent will attempt to assign one from its
[configured proxy port range](/docs/agent/options#sidecar_min_port) if available.
By default the range is [20000, 20255] and the port is selected at random from
@@ -69,7 +69,7 @@ All fields are optional with a sane default.
dial the proxy over loopback. For more complex configurations where agent and proxy
communicate over a bridge for example, this configuration can be used to specify
a different _address_ (but not port) for the agent to use for health checks if
- it can't talk to the proxy over localhost or it's publicly advertised port. The
+ it can't talk to the proxy over localhost or its publicly advertised port. The
check always uses the same port that the proxy is bound to.
- `disable_tcp_check` - If true, this disables a
diff --git a/website/pages/docs/connect/proxies/envoy.mdx b/website/pages/docs/connect/proxies/envoy.mdx
index fa452c7afa..8ba5ad605b 100644
--- a/website/pages/docs/connect/proxies/envoy.mdx
+++ b/website/pages/docs/connect/proxies/envoy.mdx
@@ -13,19 +13,19 @@ optionally exposing a gRPC service on the local agent that serves [Envoy's xDS
configuration
API](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol).
-Consul can configure Envoy sidecars to proxy http/1.1, http2 or gRPC traffic at
+Consul can configure Envoy sidecars to proxy http/1.1, http2, or gRPC traffic at
L7 or any other tcp-based protocol at L4. Prior to Consul 1.5.0 Envoy proxies
could only proxy tcp at L4.
Configuration of some [L7 features](/docs/connect/l7-traffic-management)
-is possible via [configuration entries](/docs/agent/config_entries). If
+is possible via [configuration entries](/docs/agent/config-entries). If
you wish to use an Envoy feature not currently exposed through these config
entries as an interim solution, you can add [custom Envoy
configuration](#advanced-configuration) in the [proxy service
definition](/docs/connect/registration/service-registration) allowing you
to use the more powerful features of Envoy.
-~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/docs/commands/connect/envoy)
+~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/commands/connect/envoy)
Envoy must be run with the `--max-obj-name-len` option set to `256` or greater for Envoy versions prior to 1.11.0.
## Supported Versions
@@ -33,22 +33,27 @@ Envoy must be run with the `--max-obj-name-len` option set to `256` or greater f
Consul's Envoy support was added in version 1.3.0. The following table shows
compatible Envoy versions.
-| Consul Version | Compatible Envoy Versions |
-| ------------------- | -------------------------------- |
-| 1.9.x | 1.15.0, 1.14.4, 1.13.4, 1.12.6 |
-| 1.8.x | 1.14.4, 1.13.4, 1.12.6, 1.11.2 |
-| 1.7.x | 1.13.1, 1.12.3, 1.11.2, 1.10.0\* |
-| 1.5.2, 1.5.3, 1.6.x | 1.11.1, 1.10.0, 1.9.1, 1.8.0† |
-| 1.5.0, 1.5.1 | 1.9.1, 1.8.0† |
-| 1.3.x, 1.4.x | 1.9.1, 1.8.0†, 1.7.0† |
+| Consul Version | Compatible Envoy Versions |
+| ------------------- | --------------------------------- |
+| 1.9.x | 1.15.0, 1.14.4‡, 1.13.4‡, 1.12.6‡ |
+| 1.8.x | 1.14.4, 1.13.4, 1.12.6, 1.11.2 |
+| 1.7.x | 1.13.1, 1.12.3, 1.11.2, 1.10.0\* |
+| 1.6.x, 1.5.3, 1.5.2 | 1.11.1, 1.10.0, 1.9.1, 1.8.0† |
+| 1.5.1, 1.5.0 | 1.9.1, 1.8.0† |
+| 1.4.x, 1.3.x | 1.9.1, 1.8.0†, 1.7.0† |
-~> † Envoy versions lower than 1.9.1 are vulnerable to
+~> ‡ To ensure that intention enforcement is updated as quickly as possible
+after any changes, it is advised to run Consul 1.9.0 with Envoy 1.15.0+ due to a
+[listener update improvement](https://github.com/envoyproxy/envoy/pull/10662).
+† Envoy versions lower than 1.9.1 are vulnerable to
[CVE-2019-9900](https://github.com/envoyproxy/envoy/issues/6434) and
[CVE-2019-9901](https://github.com/envoyproxy/envoy/issues/6435). Both are
related to HTTP request parsing and so only affect Consul Connect users if they
-have configured HTTP routing rules via the ["escape
-hatch"](#escape-hatch-overrides). Still, we recommend that you use the most
-recent supported Envoy for your Consul version where possible.
\* Envoy 1.10.0 requires setting [`-envoy-version`](/docs/commands/connect/envoy#envoy-version) in the `consul connect envoy` command. This was introduced in Consul 1.7.0.
+have configured HTTP routing rules. Still, we recommend that you use the most
+recent supported Envoy for your Consul version where possible.
+\* Envoy 1.10.0 requires setting
+[`-envoy-version`](/commands/connect/envoy#envoy-version) in the `consul
+connect envoy` command. This was introduced in Consul 1.7.0.
## Getting Started
@@ -62,14 +67,15 @@ configuration_ and dynamic configuration that is discovered from a "management
server", in this case Consul.
The bootstrap configuration at a minimum needs to configure the proxy with an
-identity (node id) and the location of it's local Consul agent from which it
-discovers all of it's dynamic configuration. See [Bootstrap
+identity (node id) and the location of its local Consul agent from which it
+discovers all of its dynamic configuration. See [Bootstrap
Configuration](#bootstrap-configuration) for more details.
The dynamic configuration Consul Connect provides to each Envoy instance includes:
- TLS certificates and keys to enable mutual authentication and keep certificates
rotating.
+- [Intentions] to enforce service-to-service authorization rules.
- Service-discovery results for upstreams to enable each sidecar proxy to load-balance
outgoing connections.
- L7 configuration including timeouts and protocol-specific options.
@@ -87,11 +93,21 @@ users to provide low-level raw Envoy config syntax for some sub-components in ea
Envoy instance. This allows operators to have full control over and
responsibility for correctly configuring Envoy and ensuring version support etc.
+## Intention Enforcement
+
+[Intentions] are enforced using Envoy's RBAC filters. Depending upon the
+configured [protocol] of the proxied service these are either enforced
+per-connection (L4) using a network filter or per-request (L7) using an HTTP
+filter.
+
+-> **Note:** Prior to Consul 1.9.0 intentions were exclusively enforced
+per-connection (L4) using an `ext_authz` network filter.
+
## Bootstrap Configuration
Envoy requires an initial bootstrap configuration file. The easiest way to
create this is using the [`consul connect envoy`
-command](/docs/commands/connect/envoy). The command can either output the
+command](/commands/connect/envoy). The command can either output the
bootstrap configuration directly to stdout or can generate it and then `exec`
the Envoy binary as a convenience wrapper.
@@ -179,7 +195,7 @@ definition](/docs/connect/registration/service-registration) that is
actually registered.
To learn about other options that can be configured centrally see the
-[Configuration Entries](/docs/agent/config_entries) docs.
+[Configuration Entries](/docs/agent/config-entries) docs.
### Proxy Config Options
@@ -461,12 +477,12 @@ definition](/docs/connect/registration/service-registration) or
is used in place of [the default
template](https://github.com/hashicorp/consul/blob/b64bda880843afaaf44591c3200f921626716849/command/connect/envoy/bootstrap_tpl.go#L87)
when generating bootstrap via [`consul connect envoy`
- command](/docs/commands/connect/envoy). The variables that are available
+ command](/commands/connect/envoy). The variables that are available
to be interpolated are [documented
here](https://github.com/hashicorp/consul/blob/b64bda880843afaaf44591c3200f921626716849/command/connect/envoy/bootstrap_tpl.go#L5).
This offers complete control of the proxy's bootstrap although major
deviations from the default template may break Consul's ability to correctly
- manage the proxy or enforce it's security model.
+ manage the proxy or enforce its security model.
- `envoy_public_listener_json` - Specifies a complete
[Listener](https://www.envoyproxy.io/docs/envoy/v1.10.0/api-v2/api/v2/lds.proto)
to be delivered in place of the main public listener that the proxy used to
@@ -510,3 +526,7 @@ warning.
to be delivered in place of the discovered upstream cluster. This allows
customization of timeouts, circuit breaking, rate limits, load balancing
strategy etc.
+
+[protocol]: /docs/agent/config-entries/service-defaults#protocol
+[intentions]: /docs/connect/intentions
+[Intentions]: /docs/connect/intentions
diff --git a/website/pages/docs/connect/proxies/integrate.mdx b/website/pages/docs/connect/proxies/integrate.mdx
index 96849862e8..4114572eba 100644
--- a/website/pages/docs/connect/proxies/integrate.mdx
+++ b/website/pages/docs/connect/proxies/integrate.mdx
@@ -11,46 +11,130 @@ description: >-
# Connect Custom Proxy Integration
Any proxy can be extended to support Connect. Consul ships with a built-in
-proxy for a good development and out of the box experience, but understand
-that production users will require other proxy solutions.
+proxy for a good development and out of the box experience, but production
+users will require other proxy solutions.
A proxy must serve one or both of the following two roles: it must accept
inbound connections or establish outbound connections identified as a
-particular service. One or both of these may be implemented depending on
-the case, although generally both must be supported.
+particular service. One or both of these may be implemented depending on the
+case, although generally both must be supported for full sidecar functionality.
+
+There are also two different levels of compatibility as a sidecar: L4 or L7.
+L4 integration is simpler and adequate to secure all traffic but treats all
+traffic as TCP so no advanced routing or metrics features can be supported.
+Full L7 support is built on top of L4 support and includes supporting most or
+all of the L7 traffic routing features in Connect by dynamically configuring
+routing, retries and more L7 features. Currently The built-in proxy only
+supports L4 while Envoy supports the full L7 feature set.
+
+Places where the integration approach diverges for L4/L7 support is indicated
+below.
## Accepting Inbound Connections
For inbound connections, the proxy must accept TLS connections on some port.
-The certificate served should be created by the
-[`/v1/agent/connect/ca/leaf/`](/api/agent/connect) API endpoint.
-The client certificate should be validated against the root certificates
-provided by the
-[`/v1/agent/connect/ca/roots`](/api/agent/connect) endpoint.
-After validating the client certificate from the caller, the proxy should
-call the
-[`/v1/agent/connect/authorize`](/api/agent/connect) endpoint to
-authorize the connection.
+The certificate served should be obtained from the
+[`/v1/agent/connect/ca/leaf/`] API endpoint. The client certificate should be
+validated against the root certificates provided by the
+[`/v1/agent/connect/ca/roots`] endpoint. After validating the client
+certificate from the caller, depending upon the [protocol] of the proxied
+service service the proxy must either authorize the entire connection (L4) or
+each request (L7).
-All of these API endpoints operate on agent-local data that is updated
-in the background. The leaf and roots should be updated in the background
-by the proxy, but the authorize endpoint is expected to be called in the
-connection path. The endpoints introduce only microseconds of additional
-latency on the connection.
+Connection authorization can be performed one of two ways:
-The leaf and root cert endpoints support blocking queries. These should be
-used if possible to get near-immediate updates for root cert rotations,
-leaf expiry, etc.
+1. The first is by calling the
+ [`/v1/agent/connect/authorize`](/api/agent/connect) endpoint. The authorize
+ endpoint is expected to be called in the connection path, so if the local
+ Consul agent is down or unresponsive it will impact the success rate of new
+ connections. The agent uses locally cached data to authorize the connection
+ and typically responds in microseconds. Therefore, the impact to the TLS
+ handshake is typically microseconds.
+
+ ~> **Note:** This endpoint is only suited for networking layer 4 (e.g. TCP)
+ integration. The endpoint will always treat intentions with Permissions
+ defined (i.e., layer 7 criteria) as deny intentions during evaluation.
+
+2. Alternatively, proxies may list intentions that match the destination by
+ querying the [intention match
+ API](/api/connect/intentions#list-matching-intentions) endpoint, and
+ represent them in the native configuration of the proxy itself (such as RBAC
+ for Envoy). For performance and reliability reasons this is the desirable
+ method for implementing intention enforcement. The cached intentions should
+ be consulted for each incoming connection (L4) or request (L7) to determine
+ if the should be accepted or rejected.
+
+All of these API endpoints operate on agent-local data that is updated in the
+background. The leaf, roots, and intentions should be updated in the background
+by the proxy.
+
+The leaf cert, root cert, and intentions endpoints support [blocking
+queries](/api/features/blocking), which should be used to get near-immediate
+updates for root key rotations, new leaf certs before expiry, and intention
+changes.
+
+Although Consul follows the SPIFFE spec for certificates, some currently
+supported CA providers don't allow strict adherence. For example, CA
+certificates may not have the correct trust-domain SPIFFE URI SAN for the
+cluster. If SPIFFE validation is performed in the proxy, be aware that it
+should be possible to opt out, otherwise certain CA providers supported by
+Consul will not be compatible with the use of that proxy. Currently neither
+Envoy nor the built-in proxy validate the SPIFFE URI of the chain beyond the
+leaf certificate.
+
+### Connection Authorization
+
+Authentication is based on "service identity" (TLS), and is implemented at the
+transport layer. Depending upon the [protocol] of the proxied service,
+authorization is performed either on a per-connection (L4) or per-request (L7)
+basis.
+
+-> **Note:** Features like (local) rate limiting or max connections are
+configurations that we expect to push into proxies and have them enforce
+separately to the AuthZ call based on the state they already have about request
+rates etc.
+
+#### Persistent TCP Connections and Intentions
+
+For a proxied service configured with a [protocol] of TCP, potentially
+long-lived TCP connections will be authorized only when they are established.
+Since many services (e.g. databases) typically use persistent connection pools,
+a change in intentions that newly denies access currently does not terminate
+existing connections in violation of the updated intention. In this case it may
+appear as if the intention is not being enforced.
+
+Consul eventually may support a mechanism for tracking specific connections in
+the agent and then allow the agent to tell the proxy to close those connections
+when their authorization state changes, but for now that is not on the roadmap.
+
+It is recommended therefore to do one of the following:
+
+1. Have connections terminate after a configurable maximum lifetime of say
+ several hours. This balances the overhead of establishing new connections
+ while keeping an upper bound on how long after Intention changes existing
+ connections remain open.
+2. Periodically re-authorize every open connection. The AuthZ call itself is
+ not expensive and should be a local, in-memory operation so authorizing
+ thousands of open connections once every minute or so is likely to be
+ negligible overhead, but enforces a tighter upper bound on how long it takes
+ to enforce Intention changes without affecting protocol efficiency of
+ persistent connections.
+
+#### Certificate Serial in AuthZ
+
+Intentions currently utilize TLS' URI Subject Alternative Name (SAN) for
+enforcement. In the future, Consul will support revoking specific certificates
+by serial number. The AuthZ API in the Go SDK has a field to pass the serial
+number ([`consul/connect/tls.go`]). Proxies may provide this value during
+authorization.
## Establishing Outbound Connections
-For outbound connections, the proxy should communicate to a
-Connect-capable endpoint for a service and provide a client certificate
-from the
-[`/v1/agent/connect/ca/leaf/`](/api/agent/connect) API endpoint.
-The certificate served by the remote endpoint can be verified against the
-root certificates from the
-[`/v1/agent/connect/ca/roots`](/api/agent/connect) endpoint.
+For outbound connections, the proxy should communicate to a Connect-capable
+endpoint for a service and provide a client certificate from the
+[`/v1/agent/connect/ca/leaf/`] API endpoint. The certificate served by the
+remote endpoint may be verified against the root certificates from the
+[`/v1/agent/connect/ca/roots`] endpoint.
## Configuration Discovery
@@ -59,11 +143,102 @@ instance using the
[`/v1/agent/service/:service_id`](/api/agent/service#get-service-configuration)
API endpoint.
-The [discovery chain](/docs/internals/discovery-chain) for each upstream
-service should be fetched from the
-[`/v1/discovery-chain/:service_id`](/api/discovery-chain) API endpoint.
+This endpoint supports hash-based blocking, enabling long-polling for changes
+to the registration/configuration. Any changes to the registration/config will
+result in the new config being returned immediately. An example implementation
+may be found in our [built-in proxy](/docs/connect/proxies/built-in) which
+utilizes our Go SDK, and uses the HTTP "pull" API (via our `watch` package):
+[`consul/connect/proxy/config.go`].
-For each [target](/docs/internals/discovery-chain#targets) in the
-resulting discovery chain, a list of healthy endpoints can be fetched from the
-[`/v1/health/connect/:service_id`](/api/health#list-nodes-for-connect-capable-service)
-API endpoint.
+The [discovery chain] for each upstream service should be fetched from the
+[`/v1/discovery-chain/:service_id`](/api/discovery-chain#read-compiled-discovery-chain)
+API endpoint. This will return a compiled graph of configurations needed by
+sidecars for a particular upstream service. If you are only implementing L4
+support in your proxy, set the
+[`OverrideProtocol`](/api/discovery-chain#overrideprotocol) value to "tcp" when
+fetching the discovery chain so that L7 features such as HTTP routing rules are
+not returned.
+
+For each [target](/docs/internals/discovery-chain#targets) in the resulting
+discovery chain, a list of healthy, Connect-capable endpoints may be fetched
+from the [`/v1/health/connect/:service_id`] API endpoint per the [Service
+Discovery](#service-discovery) section below.
+
+The rest of the nodes in the chain include configurations that should be
+translated into the nearest equivalent for things like HTTP routing, connection
+timeouts, connection pool settings, rate limits, etc. See the full [discovery
+chain] documentation and relevant [config entry](/docs/agent/config-entries)
+documentation for details of supported configuration parameters.
+
+We expect config here to evolve reasonably rapidly. While we do not intend to
+make backwards incompatible API changes, there are likely to be new
+configurations and features added regularly. Some proxies may not be able to
+support all features or may have differing semantics with the way they support
+them. We intend to find a suitable format to document the behavior differences
+between proxy implementations as they mature.
+
+### Service Discovery
+
+Proxies can use Consul's service discovery API
+[`/v1/health/connect/:service_id`] to return all available, Connect-capable
+endpoints for a given service. This endpoint supports a `?cached` parameter
+which makes use of [agent caching](/api/features/caching) and thus has
+performance benefits. The API package provides a [`UseCache`] query option to
+leverage this. In addition to performance improvements, use of the cache makes
+the mesh more resilient to Consul server outages - the mesh "fails static" with
+the last known set of service instances still used rather than errors on new
+connections.
+
+Proxies can decide whether to perform just-in-time queries to the API when a
+new connection needs to be routed, or to use blocking queries to load the
+current set of endpoints for a service and keep that list updated. The SDK and
+built-in proxy currently use just-in-time resolution however many existing
+proxies are likely to find it easier to integrate by pulling the set of
+endpoints and maintaining it in local memory using blocking queries.
+
+Upstreams can be defined with Prepared Query target types. These upstreams
+should use Consul's [prepared query](/api/query) API. It's worth noting that
+the PreparedQuery API does not support blocking, so proxies choosing to
+populate endpoints in memory will need to poll the endpoint at a suitable and
+ideally configurable frequency.
+
+-> **Note:** Long-term the [`service-resolver` config
+entries](/docs/agent/config-entries/service-resolver) are intended to replace
+Prepared Queries in Consul entirely, but for now these are still used in some
+configurations.
+
+## Sidecar instantiation
+
+Consul does not start or manage sidecar proxies processes. Proxies running on a
+physical host or VM are designed to be started and run by process supervisor
+systems such as init, systemd, supervisord, etc. Or, if deployed within a
+cluster scheduler (Kubernetes, Nomad) running as a sidecar container in the
+same namespace.
+
+The proxy will use the [`CONSUL_HTTP_TOKEN`](/commands#consul_http_token) and
+[`CONSUL_HTTP_ADDR`](/commands#consul_http_addr) environment variables to
+contact Consul to fetch certificates, provided the `CONSUL_HTTP_TOKEN`
+environment variable contains a Consul ACL that has the necessary permissions
+to read configuration for that service. If you use our Go [`api` package] then
+those environment variables will be read and the client configured for you
+automatically.
+
+The ID of the proxy service comes from the user. See [`consul connect
+envoy`](/commands/connect/envoy) as an example. You may start it with the
+`-proxy-id` flag and pass the ID of the proxy service you registered elsewhere.
+A nicer UX is available for end-users using the `-sidecar-for=`
+argument, which causes the command to query Consul for a proxy that is
+registered as a sidecar for the specified ``. If there is exactly one
+such proxy, that ID will be used to start the proxy. Your controller only needs
+to accept `-proxy-id` as an argument; the Consul CLI will handle resolving the
+ID for the name specified in `-sidecar-for`.
+
+[`/v1/agent/connect/ca/leaf/`]: /api/agent/connect#service-leaf-certificate
+[`/v1/agent/connect/ca/roots`]: /api/agent/connect#certificate-authority-ca-roots
+[`/v1/health/connect/:service_id`]: /api/health#list-nodes-for-connect-capable-service
+[`api` package]: https://github.com/hashicorp/consul/tree/master/api
+[`consul/connect/proxy/config.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/proxy/config.go#L187
+[`consul/connect/tls.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/tls.go#L232-L237
+[discovery chain]: /docs/connect/l7-traffic/discovery-chain
+[`UseCache`]: https://github.com/hashicorp/consul/blob/v1.8.3/api/api.go#L99-L102
+[protocol]: /docs/agent/config-entries/service-defaults#protocol
diff --git a/website/pages/docs/connect/proxies/managed-deprecated.mdx b/website/pages/docs/connect/proxies/managed-deprecated.mdx
index c5d704ae39..3f4e1c3b65 100644
--- a/website/pages/docs/connect/proxies/managed-deprecated.mdx
+++ b/website/pages/docs/connect/proxies/managed-deprecated.mdx
@@ -2,7 +2,7 @@
layout: docs
page_title: Connect - Deprecated Managed Proxies
description: |-
- Consul 1.2 launched it's Connect Beta period with a feature named Managed
+ Consul 1.2 launched its Connect Beta period with a feature named Managed
Proxies which are now deprecated. This page describes how they worked and why
they are no longer supported.
---
@@ -89,7 +89,7 @@ from the agent so if the agent crashes or is restarted for an upgrade, the
managed proxy instances will _not_ be stopped.
Note that this behaviour while desirable in production might leave proxy
-processes running indefinitely if you manually stop the agent and clear it's
+processes running indefinitely if you manually stop the agent and clear its
data dir during testing.
To terminate a managed proxy cleanly you need to deregister the service that
@@ -269,7 +269,7 @@ Managed proxies have both stdout and stderr captured in log files in the agent's
`data_dir`. They can be found in
`/proxy/logs/-std{err,out}.log`.
-The built-in proxy will inherit it's log level from the agent so if the agent is
+The built-in proxy will inherit its log level from the agent so if the agent is
configured with `log_level = DEBUG`, a proxy it starts will also output `DEBUG`
level logs showing service discovery, certificate and authorization information.
diff --git a/website/pages/docs/connect/registration/sidecar-service.mdx b/website/pages/docs/connect/registration/sidecar-service.mdx
index 23f0fac765..ad791d9536 100644
--- a/website/pages/docs/connect/registration/sidecar-service.mdx
+++ b/website/pages/docs/connect/registration/sidecar-service.mdx
@@ -180,7 +180,7 @@ service's ID. This enables the following behavior.
- If a service registration removes the nested `sidecar_service` then the
previously registered sidecar for that service will be deregistered
automatically.
-- When reloading the configuration files, if a service definition changes it's
+- When reloading the configuration files, if a service definition changes its
ID, then a new service instance _and_ a new sidecar instance will be
registered. The old ones will be removed since they are no longer found in
the config files.
diff --git a/website/pages/docs/discovery/services.mdx b/website/pages/docs/discovery/services.mdx
index 7d9e0fa319..cb90f2abe6 100644
--- a/website/pages/docs/discovery/services.mdx
+++ b/website/pages/docs/discovery/services.mdx
@@ -369,7 +369,7 @@ delimit service tags.
## Service Definition Parameter Case
For historical reasons Consul's API uses `CamelCased` parameter names in
-responses, however it's configuration file uses `snake_case` for both HCL and
+responses, however its configuration file uses `snake_case` for both HCL and
JSON representations. For this reason the registration _HTTP APIs_ accept both
name styles for service definition parameters although APIs will return the
listings using `CamelCase`.
diff --git a/website/pages/docs/dynamic-app-config/kv.mdx b/website/pages/docs/dynamic-app-config/kv.mdx
index e0e8098cf3..f9d3527037 100644
--- a/website/pages/docs/dynamic-app-config/kv.mdx
+++ b/website/pages/docs/dynamic-app-config/kv.mdx
@@ -29,7 +29,7 @@ Learn.
## Accessing the KV store
The KV store can be accessed by the [consul kv CLI
-subcommands](/docs/commands/kv), [HTTP API](/api/kv), and Consul UI.
+subcommands](/commands/kv), [HTTP API](/api/kv), and Consul UI.
To restrict access, enable and configure
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
Once the ACL system has been bootstrapped, users and services, will need a
@@ -41,7 +41,7 @@ application.
The datastore itself is located on the Consul servers in the [data
directory](/docs/agent/options#_data_dir). To ensure data is not lost in
-the event of a complete outage, use the [`consul snapshot`](/docs/commands/snapshot/restore) feature to backup the data.
+the event of a complete outage, use the [`consul snapshot`](/commands/snapshot/restore) feature to backup the data.
## Using Consul KV
diff --git a/website/pages/docs/dynamic-app-config/watches.mdx b/website/pages/docs/dynamic-app-config/watches.mdx
index 333a1b19f6..fb2898c98b 100644
--- a/website/pages/docs/dynamic-app-config/watches.mdx
+++ b/website/pages/docs/dynamic-app-config/watches.mdx
@@ -25,7 +25,7 @@ Watches can be configured as part of the [agent's configuration](/docs/agent/opt
causing them to run once the agent is initialized. Reloading the agent configuration
allows for adding or removing watches dynamically.
-Alternatively, the [watch command](/docs/commands/watch) enables a watch to be
+Alternatively, the [watch command](/commands/watch) enables a watch to be
started outside of the agent. This can be used by an operator to inspect data in Consul
or to easily pipe data into processes without being tied to the agent lifecycle.
@@ -422,7 +422,7 @@ An example of the output of this command:
### Type: event ((#event))
The "event" watch type is used to monitor for custom user
-events. These are fired using the [consul event](/docs/commands/event) command.
+events. These are fired using the [consul event](/commands/event) command.
It takes only a single optional "name" parameter which restricts
the watch to only events with the given name.
diff --git a/website/pages/docs/enterprise/backups.mdx b/website/pages/docs/enterprise/backups.mdx
index 5ca332eeb2..fa264e1d9d 100644
--- a/website/pages/docs/enterprise/backups.mdx
+++ b/website/pages/docs/enterprise/backups.mdx
@@ -36,4 +36,4 @@ datacenter backups include (but are not limited to):
For more experience leveraging Consul's snapshot functionality, we suggest you look through our HashiCorp
Learn tutorial for [Datacenter Backups in Consul](https://learn.hashicorp.com/tutorials/consul/backup-and-restore).
For detailed configuration information on configuring the Consul Enterprise's snapshot agent, review the
-[Consul Snapshot Agent documentation](/docs/commands/snapshot/agent).
+[Consul Snapshot Agent documentation](/commands/snapshot/agent).
diff --git a/website/pages/docs/enterprise/index.mdx b/website/pages/docs/enterprise/index.mdx
index 37518712a2..f3c15c6702 100644
--- a/website/pages/docs/enterprise/index.mdx
+++ b/website/pages/docs/enterprise/index.mdx
@@ -54,7 +54,7 @@ forwarded to the leading server via the RPC forwarding functionality.
Below are your two options for setting the license file.
You can set the license via the
-[API](/api/operator/license) or the [CLI](/docs/commands/license). When
+[API](/api/operator/license) or the [CLI](/commands/license). When
you first start Consul, a 30-minute temporary license is available to allow you
time to license the datacenter. You should set the license within ten minutes of
starting the first Consul process to allow time for the license to propagate.
diff --git a/website/pages/docs/enterprise/namespaces.mdx b/website/pages/docs/enterprise/namespaces.mdx
index 938946bece..770f88d7fd 100644
--- a/website/pages/docs/enterprise/namespaces.mdx
+++ b/website/pages/docs/enterprise/namespaces.mdx
@@ -25,7 +25,7 @@ For more information on how to use namespaces with Consul Enterprise please revi
## Namespace Definition
-Namespaces are managed exclusively through the [HTTP API](/api/namespaces) and the [Consul CLI](/docs/commands/namespace).
+Namespaces are managed exclusively through the [HTTP API](/api/namespaces) and the [Consul CLI](/commands/namespace).
The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL.
An example namespace definition looks like the following:
diff --git a/website/pages/docs/enterprise/network-segments.mdx b/website/pages/docs/enterprise/network-segments.mdx
index 209be69168..6c9bfd2cfa 100644
--- a/website/pages/docs/enterprise/network-segments.mdx
+++ b/website/pages/docs/enterprise/network-segments.mdx
@@ -17,7 +17,7 @@ description: |-
Consul Network Segments enables operators to create separate LAN gossip segments
in one Consul cluster. Agents in a segment are only able to join and communicate
-with other agents in it's network segment. This functionality is useful for
+with other agents in its network segment. This functionality is useful for
clusters that have multiple tenants that should not be able to communicate
with each other.
diff --git a/website/pages/docs/enterprise/redundancy.mdx b/website/pages/docs/enterprise/redundancy.mdx
index 433c1e1501..e8f611c561 100644
--- a/website/pages/docs/enterprise/redundancy.mdx
+++ b/website/pages/docs/enterprise/redundancy.mdx
@@ -31,4 +31,4 @@ capabilities.
For more information, review the HashiCorp Learn tutorial on
[Redundancy Zones](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#redundancy-zones),
-as well as the documentation for [Consul Autopilot](/docs/commands/operator/autopilot).
+as well as the documentation for [Consul Autopilot](/commands/operator/autopilot).
diff --git a/website/pages/docs/enterprise/upgrades.mdx b/website/pages/docs/enterprise/upgrades.mdx
index c82ee5ab95..9ea447ce9a 100644
--- a/website/pages/docs/enterprise/upgrades.mdx
+++ b/website/pages/docs/enterprise/upgrades.mdx
@@ -21,4 +21,4 @@ currently in a cluster. When an equal amount of new server nodes are joined runn
will be demoted to non voting members. Demotion of legacy server nodes will not occur until the voting members on the new version match.
Once this demotion occurs, the previous versioned servers can be removed from the cluster safely.
-You can review more information about this functionality in the [Consul operator autopilot](/docs/commands/operator/autopilot) documentation as well as on the HashiCorp Learn [Automated Upgrade](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#upgrade-migrations) tutorial.
+You can review more information about this functionality in the [Consul operator autopilot](/commands/operator/autopilot) documentation as well as on the HashiCorp Learn [Automated Upgrade](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#upgrade-migrations) tutorial.
diff --git a/website/pages/docs/guides/acl-legacy.mdx b/website/pages/docs/guides/acl-legacy.mdx
index 575a4b782f..ec12fb5103 100644
--- a/website/pages/docs/guides/acl-legacy.mdx
+++ b/website/pages/docs/guides/acl-legacy.mdx
@@ -230,7 +230,7 @@ The [`acl_agent_token`](/docs/agent/options#acl_agent_token) is a special token
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
-3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
+3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
@@ -738,7 +738,7 @@ Event rules are keyed by the event name prefix they apply to, using the longest
In the example above, the rules allow read-only access to any event, and firing of any event that
starts with "deploy".
-The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
+The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
diff --git a/website/pages/docs/guides/connect-gateways.mdx b/website/pages/docs/guides/connect-gateways.mdx
index 5451757444..1079d45677 100644
--- a/website/pages/docs/guides/connect-gateways.mdx
+++ b/website/pages/docs/guides/connect-gateways.mdx
@@ -112,7 +112,7 @@ restart during
upgrades](/docs/upgrading#standard-upgrades).
Stop the first server by running the following [leave
-command](/docs/commands/leave).
+command](/commands/leave).
```shell-session
$ consul leave
@@ -234,7 +234,7 @@ $ consul connect envoy -mesh-gateway -register \
### Configure Sidecar Proxies to use Gateways
Next, create a [centralized
-configuration](/docs/agent/config_entries/proxy-defaults)
+configuration](/docs/agent/config-entries/proxy-defaults)
file for all the sidecar proxies in both datacenters called
`proxy-defaults.json`. This file will instruct the sidecar proxies to send all
their inter-datacenter traffic through the gateways. It should contain the
diff --git a/website/pages/docs/guides/connect-services.mdx b/website/pages/docs/guides/connect-services.mdx
index 802842c16a..4a55f39e0d 100644
--- a/website/pages/docs/guides/connect-services.mdx
+++ b/website/pages/docs/guides/connect-services.mdx
@@ -434,7 +434,7 @@ environment.
[img-screenshot2]: /static/img/consul/connect-getting-started/screenshot2.png
[intention]: https://www.consul.io/docs/connect/intentions
[services-api]: https://www.consul.io/api/agent/service#register-service
-[services-cli]: https://www.consul.io/docs/commands/services
+[services-cli]: https://www.consul.io/commands/services
[services-config]: https://www.consul.io/docs/agent/services#service-definition
[services-nomad]: https://www.nomadproject.io/docs/job-specification/service
[sidecar]: https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar
diff --git a/website/pages/docs/guides/containers-guide.mdx b/website/pages/docs/guides/containers-guide.mdx
index 59aa0794b2..b272c0ba0b 100644
--- a/website/pages/docs/guides/containers-guide.mdx
+++ b/website/pages/docs/guides/containers-guide.mdx
@@ -278,7 +278,7 @@ When a previously stopped server container is restarted using `docker start consul snapshot save backup.snap
@@ -290,7 +290,7 @@ This will leave the `backup.snap` snapshot file inside of your container. If you
$ docker cp :backup.snap ./
```
-Users running the Consul Enterprise Docker containers can run the [consul snapshot agent](/docs/commands/snapshot/agent) to save backups automatically. Consul Enterprise's snapshot agent also allows you to save snapshots to Amazon S3 and Azure Blob Storage.
+Users running the Consul Enterprise Docker containers can run the [consul snapshot agent](/commands/snapshot/agent) to save backups automatically. Consul Enterprise's snapshot agent also allows you to save snapshots to Amazon S3 and Azure Blob Storage.
### Environment Variables
diff --git a/website/pages/docs/guides/kubernetes-observability.mdx b/website/pages/docs/guides/kubernetes-observability.mdx
index 6ec78f73b5..df4be2b34f 100644
--- a/website/pages/docs/guides/kubernetes-observability.mdx
+++ b/website/pages/docs/guides/kubernetes-observability.mdx
@@ -366,4 +366,4 @@ To learn more about the configuration options in Consul that enable layer 7
metrics collection with or without Kubernetes, refer to [our
documentation](/docs/connect/proxies/envoy). For more information on
centrally configuring Consul, take a look at the [centralized configuration
-documentation](/docs/agent/config_entries).
+documentation](/docs/agent/config-entries).
diff --git a/website/pages/docs/guides/production-acls.mdx b/website/pages/docs/guides/production-acls.mdx
index d81e5432ef..1392675859 100644
--- a/website/pages/docs/guides/production-acls.mdx
+++ b/website/pages/docs/guides/production-acls.mdx
@@ -222,7 +222,7 @@ the clients.
First, create the policy that will grant write privileges to only the
"dashboard" service. This means the "dashboard" service can register
-itself, update it's health checks, and write any of the fields in the [service
+itself, update its health checks, and write any of the fields in the [service
definition](/docs/agent/services).
```shell
@@ -448,4 +448,4 @@ node_prefix "" {
In this guide you bootstrapped the ACL system for consul and applied tokens to agents and services. You assigned tokens for DNS, Consul KV, and the Consul UI.
-To learn more about Consul’s security model read the [internals documentation](/docs/internals/security). You can find commands relating to ACLs in our [reference documentation](/docs/commands/acl).
+To learn more about Consul’s security model read the [internals documentation](/docs/internals/security). You can find commands relating to ACLs in our [reference documentation](/commands/acl).
diff --git a/website/pages/docs/install/bootstrapping.mdx b/website/pages/docs/install/bootstrapping.mdx
index 8797decd6a..a313811c7a 100644
--- a/website/pages/docs/install/bootstrapping.mdx
+++ b/website/pages/docs/install/bootstrapping.mdx
@@ -93,10 +93,10 @@ Since a join operation is symmetric, it does not matter which node initiates it.
### Verifying the Cluster and Connect the Clients
-As a sanity check, the [`consul info`](/docs/commands/info) command
+As a sanity check, the [`consul info`](/commands/info) command
is a useful tool. It can be used to verify the `raft.num_peers`
and to view the latest log index under `raft.last_log_index`. When
-running [`consul info`](/docs/commands/info) on the followers, you
+running [`consul info`](/commands/info) on the followers, you
should see `raft.last_log_index` converge to the same value once the
leader begins replication. That value represents the last log entry that
has been stored on disk.
diff --git a/website/pages/docs/install/cloud-auto-join.mdx b/website/pages/docs/install/cloud-auto-join.mdx
index 51addbeed8..4a2b24222f 100644
--- a/website/pages/docs/install/cloud-auto-join.mdx
+++ b/website/pages/docs/install/cloud-auto-join.mdx
@@ -103,7 +103,7 @@ $ consul agent -retry-join "provider=azure tag_key=... tag_value=... tenant_id=.
- `provider` (required) - the name of the provider ("azure" in this case).
- `tenant_id` (required) - the tenant to join machines in.
- `client_id` (required) - the client to authenticate with.
-- `secret_access_key` (required) - the secret client key. **NOTE** This value often may have an equals sign in it's value, especially if generated from the Azure Portal, so is important to wrap in single quotes eg. `secret_access_key='fpOfcHQJAQBczjAxiVpeyLmX1M0M0KPBST+GU2GvEN4='`
+- `secret_access_key` (required) - the secret client key. **NOTE** This value often may have an equals sign in its value, especially if generated from the Azure Portal, so is important to wrap in single quotes eg. `secret_access_key='fpOfcHQJAQBczjAxiVpeyLmX1M0M0KPBST+GU2GvEN4='`
Variables can also be provided by environmental variables:
diff --git a/website/pages/docs/integrate/partnerships.mdx b/website/pages/docs/integrate/partnerships.mdx
index 8af20a4064..44b2745a5c 100644
--- a/website/pages/docs/integrate/partnerships.mdx
+++ b/website/pages/docs/integrate/partnerships.mdx
@@ -58,7 +58,7 @@ Here are links to resources, documentation, examples and best practices to guide
**Firewall**
- [Consul Connect Intentions](/docs/connect/intentions)
-- [Consul Connect Intentions Command Line](/docs/commands/intention)
+- [Consul Connect Intentions Command Line](/commands/intention)
- [Consul Connect Intentions API](/api/connect/intentions)
**API Gateway**
@@ -92,7 +92,7 @@ Here are links to resources, documentation, examples and best practices to guide
**Logging**
-- [Consul Monitor Command Line](/docs/commands/monitor)
+- [Consul Monitor Command Line](/commands/monitor)
- [Enable syslog via CLI](/docs/agent/options#enable_syslog)
- [Enable syslog via config file](/docs/agent/options#_syslog)
diff --git a/website/pages/docs/k8s/connect/ambassador.mdx b/website/pages/docs/k8s/connect/ambassador.mdx
index 02e2ed1343..7939d2c943 100644
--- a/website/pages/docs/k8s/connect/ambassador.mdx
+++ b/website/pages/docs/k8s/connect/ambassador.mdx
@@ -290,6 +290,6 @@ If you have tried the above troubleshooting steps and are still stuck, DataWire
[install]: https://www.getambassador.io/user-guide/consul-connect-ambassador/
[ambassador-service.yaml]: https://www.getambassador.io/yaml/ambassador/ambassador-service.yaml
[request access]: https://d6e.co/slack
-[intention-check]: /docs/commands/intention/check
+[intention-check]: /commands/intention/check
[install consul]: /docs/install
[enable connect]: /docs/connect#getting-started-with-connect
diff --git a/website/pages/docs/k8s/connect/connect-ca-provider.mdx b/website/pages/docs/k8s/connect/connect-ca-provider.mdx
index fdee4db04c..af28c41d21 100644
--- a/website/pages/docs/k8s/connect/connect-ca-provider.mdx
+++ b/website/pages/docs/k8s/connect/connect-ca-provider.mdx
@@ -177,7 +177,7 @@ then you will need to manually renew or rotate the Vault token before it expires
Once the cluster is running, subsequent changes to the `ca_provider` config are **ignored**–even if `consul reload` is run or the servers are restarted.
-To update any settings under this key, you must use Consul's [Update CA Configuration](/api/connect/ca#update-ca-configuration) API or the [`consul connect ca set-config`](https://www.consul.io/docs/commands/connect/ca#set-config) command.
+To update any settings under this key, you must use Consul's [Update CA Configuration](/api/connect/ca#update-ca-configuration) API or the [`consul connect ca set-config`](/commands/connect/ca#set-config) command.
#### Renewing Vault Token
diff --git a/website/pages/docs/k8s/connect/index.mdx b/website/pages/docs/k8s/connect/index.mdx
index 9f2ad33d43..174550d380 100644
--- a/website/pages/docs/k8s/connect/index.mdx
+++ b/website/pages/docs/k8s/connect/index.mdx
@@ -161,7 +161,7 @@ $ kubectl exec static-client -- curl -s http://127.0.0.1:1234/
```
We can control access to the server using [intentions](/docs/connect/intentions).
-If you use the Consul UI or [CLI](/docs/commands/intention/create) to
+If you use the Consul UI or [CLI](/commands/intention/create) to
create a deny [intention](/docs/connect/intentions) between
"static-client" and "static-server", connections are immediately rejected
without updating either of the running pods. You can then remove this
@@ -249,7 +249,7 @@ Annotations can be used to configure the injection behavior.
```
- `consul.hashicorp.com/connect-service-protocol` - For pods that will be
- registered with Consul's [central configuration](/docs/agent/config_entries)
+ registered with Consul's [central configuration](/docs/agent/config-entries)
feature, information about the protocol the service uses is required. Users
can define the protocol directly using this annotation on the pod spec, or by
defining a default value for all services using the Helm chart's
diff --git a/website/pages/docs/k8s/helm.mdx b/website/pages/docs/k8s/helm.mdx
index 52d34ca706..382036891d 100644
--- a/website/pages/docs/k8s/helm.mdx
+++ b/website/pages/docs/k8s/helm.mdx
@@ -541,7 +541,7 @@ and consider if they're appropriate for your deployment.
type: RollingUpdate
```
- - `snapshotAgent` ((#v-client-snapshotagent)) - Values for setting up and running [snapshot agents](/docs/commands/snapshot/agent)
+ - `snapshotAgent` ((#v-client-snapshotagent)) - Values for setting up and running [snapshot agents](/commands/snapshot/agent)
within the Consul clusters. They are required to be co-located with Consul clients,
so will inherit the clients' nodeSelector, tolerations and affinity.
@@ -552,7 +552,7 @@ and consider if they're appropriate for your deployment.
to run.
- `configSecret` ((#v-client-snapshotagent-configsecret)) - A Kubernetes secret that should be
- manually created to contain the entire config to be used on the snapshot agent. This is the preferred method of configuration since there are usually storage credentials present. Please see [Snapshot agent config](/docs/commands/snapshot/agent#config-file-options) for details.
+ manually created to contain the entire config to be used on the snapshot agent. This is the preferred method of configuration since there are usually storage credentials present. Please see [Snapshot agent config](/commands/snapshot/agent#config-file-options) for details.
- secretName ((#v-client-snapshotagent-configsecret-secretname)) `(string: null)` - The name of the Kubernetes secret.
@@ -828,7 +828,7 @@ and consider if they're appropriate for your deployment.
- `secretKey` ((#v-connectinject-aclinjecttoken-secretkey)) `(string: null)` - The key within the Kubernetes secret that holds the acl token.
- - `centralConfig` ((#v-connectinject-centralconfig)) - Values that configure Consul's [central configuration](/docs/agent/config_entries)
+ - `centralConfig` ((#v-connectinject-centralconfig)) - Values that configure Consul's [central configuration](/docs/agent/config-entries)
feature (requires Consul v1.5+ and consul-k8s v0.8.1+).
- `enabled` ((#v-connectinject-centralconfig-enabled)) (`boolean: true`) - Turns on the central
diff --git a/website/pages/docs/security/acl/acl-legacy.mdx b/website/pages/docs/security/acl/acl-legacy.mdx
index 1889e218a8..8bf808630e 100644
--- a/website/pages/docs/security/acl/acl-legacy.mdx
+++ b/website/pages/docs/security/acl/acl-legacy.mdx
@@ -11,7 +11,7 @@ description: >-
# ACL System in Legacy Mode
--> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system)
+-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system).
~> **Alert: Deprecation Notice**
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
@@ -242,7 +242,7 @@ The [`acl_agent_token`](/docs/agent/options#acl_agent_token) is a special token
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
-3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
+3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
@@ -750,7 +750,7 @@ Event rules are keyed by the event name prefix they apply to, using the longest
In the example above, the rules allow read-only access to any event, and firing of any event that
starts with "deploy".
-The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
+The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
diff --git a/website/pages/docs/security/acl/acl-migrate-tokens.mdx b/website/pages/docs/security/acl/acl-migrate-tokens.mdx
index c31b5f04a1..505d0e46e0 100644
--- a/website/pages/docs/security/acl/acl-migrate-tokens.mdx
+++ b/website/pages/docs/security/acl/acl-migrate-tokens.mdx
@@ -84,7 +84,7 @@ have.
The simplest and most automatic strategy is to create one new policy for every
existing token. This is easy to automate, but may result in a lot of policies
with exactly the same rules and with non-human-readable names which will make
-managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/docs/commands/acl/policy/create) command with
+managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/commands/acl/policy/create) command with
`-from-token` option.
| Pros | Cons |
@@ -113,7 +113,7 @@ semantics of the old ACL system.
To assist with this approach, there is a CLI tool and corresponding API that can
translate a legacy ACL token's rules into a new ACL policy that is exactly
-equivalent. See [`consul acl translate-rules`](/docs/commands/acl/translate-rules).
+equivalent. See [`consul acl translate-rules`](/commands/acl/translate-rules).
| Pros | Cons |
| ------------------------------------------------- | ------------------------------------------------------------------ |
@@ -129,7 +129,7 @@ needed for a legacy token, you can update the token via the CLI or API to use
those policies.
After updating, the token is no longer considered "legacy" and will have all the
-properties of a new token, however it keeps it's `SecretID` (the secret part of
+properties of a new token, however it keeps its `SecretID` (the secret part of
the token used in API calls) so clients already using that token will continue
to work. It is assumed that the policies you attach continue to grant the
necessary access for existing clients; this is up to the operator to ensure.
@@ -142,7 +142,7 @@ endpoint. Specifically, ensure that the `Rules` field is omitted or empty. Empty
#### Update via CLI
-Use the [`consul acl token update`](/docs/commands/acl/token/update)
+Use the [`consul acl token update`](/commands/acl/token/update)
command to update the token. Specifically you need to use `-upgrade-legacy`
which will ensure that legacy rules are removed as well as the new policies
added.
diff --git a/website/pages/docs/security/acl/acl-rules.mdx b/website/pages/docs/security/acl/acl-rules.mdx
index 96c9d57d30..db168e9219 100644
--- a/website/pages/docs/security/acl/acl-rules.mdx
+++ b/website/pages/docs/security/acl/acl-rules.mdx
@@ -11,7 +11,7 @@ description: >-
# ACL Rules
--> **1.4.0 and later:** This document only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy)
+-> **1.4.0 and later:** This document only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy).
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. To learn more about Consul's ACL review the
@@ -214,7 +214,7 @@ event "deploy" {
Event rules are segmented by the event name they apply to. In the example above, the rules allow
read-only access to any event, and firing of the "deploy" event.
-The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
+The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
diff --git a/website/pages/docs/security/acl/acl-system.mdx b/website/pages/docs/security/acl/acl-system.mdx
index a0a0579c96..7380e8e531 100644
--- a/website/pages/docs/security/acl/acl-system.mdx
+++ b/website/pages/docs/security/acl/acl-system.mdx
@@ -11,7 +11,7 @@ description: >-
# ACL System
--> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy)
+-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy).
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs.
The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which
@@ -58,7 +58,7 @@ may benefit from additional components in the ACL system:
ACL tokens, policies, roles, auth methods, and binding rules are managed by
Consul operators via Consul's [ACL API](/api/acl/acl),
-[ACL CLI](/docs/commands/acl), or systems like
+[ACL CLI](/commands/acl), or systems like
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul).
If the ACL system becomes inoperable, you can follow the
@@ -316,7 +316,7 @@ The [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) is a special toke
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
-3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
+3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
diff --git a/website/pages/docs/security/acl/auth-methods/oidc.mdx b/website/pages/docs/security/acl/auth-methods/oidc.mdx
index 35d5789282..7ac39d3a15 100644
--- a/website/pages/docs/security/acl/auth-methods/oidc.mdx
+++ b/website/pages/docs/security/acl/auth-methods/oidc.mdx
@@ -119,7 +119,7 @@ applied.
## OIDC Authentication
Consul includes two built-in OIDC login flows: the Consul UI, and the CLI using
-[`consul login`](/docs/commands/login).
+[`consul login`](/commands/login).
### Redirect URIs
@@ -172,7 +172,7 @@ These are typically not required to be set:
The callback listener defaults to listen on `localhost:8550`. If you want to
customize that use the optional flag
-[`-oidc-callback-listen-addr=`](/docs/commands/login#oidc-callback-listen-addr).
+[`-oidc-callback-listen-addr=`](/commands/login#oidc-callback-listen-addr).
## OIDC Configuration Troubleshooting
diff --git a/website/pages/docs/security/encryption.mdx b/website/pages/docs/security/encryption.mdx
index 2a98d1171a..8d9a34137a 100644
--- a/website/pages/docs/security/encryption.mdx
+++ b/website/pages/docs/security/encryption.mdx
@@ -26,7 +26,7 @@ starting the Consul agent. The key can be set via the `encrypt` parameter.
~> **WAN Joined Datacenters Note:** If using multiple WAN joined datacenters, be sure to use _the same encryption key_ in all datacenters.
The key must be 32-bytes, Base64 encoded. As a convenience, Consul provides the
-[`consul keygen`](/docs/commands/keygen) command to generate a
+[`consul keygen`](/commands/keygen) command to generate a
cryptographically suitable key:
```shell-session
@@ -35,7 +35,7 @@ pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
```
With that key, you can enable encryption on the agent. If encryption is enabled,
-the output of [`consul agent`](/docs/commands/agent) will include "Encrypt: true":
+the output of [`consul agent`](/commands/agent) will include "Encrypt: true":
```shell-session
$ cat encrypt.json
diff --git a/website/pages/docs/security/index.mdx b/website/pages/docs/security/index.mdx
index 74ddfbc5bd..bf234978e8 100644
--- a/website/pages/docs/security/index.mdx
+++ b/website/pages/docs/security/index.mdx
@@ -91,7 +91,7 @@ non-default options that potentially present additional security risks.
1.1.1, and 1.2.4 [as described here](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations).
- **Remote exec enabled.** Consul includes a [`consul exec`
- feature](/docs/commands/exec) allowing execution of arbitrary commands
+ feature](/commands/exec) allowing execution of arbitrary commands
across the cluster. This is disabled by default since 0.8.0. We recommend
leaving it disabled. If enabled, extreme care must be taken to ensure correct
ACLs restrict access, for example any management token grants access to
diff --git a/website/pages/docs/troubleshoot/common-errors.mdx b/website/pages/docs/troubleshoot/common-errors.mdx
index cbba27674c..48a8114ea4 100644
--- a/website/pages/docs/troubleshoot/common-errors.mdx
+++ b/website/pages/docs/troubleshoot/common-errors.mdx
@@ -150,7 +150,7 @@ You have installed an Enterprise version of Consul. If you are an Enterprise cus
[troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting
[node_name]: /docs/agent/options#node_name
[retry_join]: /docs/agent/options#retry-join
-[license]: /docs/commands/license
+[license]: /commands/license
[releases]: https://releases.hashicorp.com/consul/
[files]: https://easyengine.io/tutorials/linux/increase-open-files-limit
[certificates]: https://learn.hashicorp.com/consul/advanced/day-1-operations/certificates
diff --git a/website/pages/docs/upgrading/instructions/general-process.mdx b/website/pages/docs/upgrading/instructions/general-process.mdx
index bcebb94dc9..9090739018 100644
--- a/website/pages/docs/upgrading/instructions/general-process.mdx
+++ b/website/pages/docs/upgrading/instructions/general-process.mdx
@@ -72,7 +72,7 @@ Version 1
This will ensure you have a safe fallback option in case something goes wrong. Store
this snapshot somewhere safe. More documentation on snapshot usage is available here:
-- https://www.consul.io/docs/commands/snapshot
+- https://www.consul.io/commands/snapshot
- https://learn.hashicorp.com/tutorials/consul/backup-and-restore
**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/options.html#_log_level)
diff --git a/website/pages/docs/upgrading/upgrade-specific.mdx b/website/pages/docs/upgrading/upgrade-specific.mdx
index 570e291ce9..47835104c8 100644
--- a/website/pages/docs/upgrading/upgrade-specific.mdx
+++ b/website/pages/docs/upgrading/upgrade-specific.mdx
@@ -20,8 +20,62 @@ upgrade flow.
The [`enable_central_service_config`](/docs/agent/options#enable_central_service_config)
configuration now defaults to `true`.
+### Changes to Intentions
+
+#### Migration
+
+Upgrading to Consul 1.9.0 will trigger a one-time background migration of
+[intentions](/docs/connect/intentions) into an equivalent set of
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entries. This process will wait until all of the Consul servers in the primary
+datacenter are running Consul 1.9.0+.
+
+All write requests via either the [Intentions
+API](/api-docs/connect/intentions) endpoints or [Config Entry
+API](/api-docs/config) endpoints for a `service-intentions` kind will be
+blocked until the migration process is complete after the upgrade. Reads will
+function normally throughout the migration, so authorization enforcement will
+be unaffected.
+
+Secondary datacenters will perform their own one-time migration operations
+after the primary datacenter completes its migration and all of the Consul
+servers in the secondary datacenter are running Consul 1.9.0+. It is safe to
+upgrade the datacenters in any order.
+
+#### Deprecated Fields
+
+All old ID-based [Intentions API](/api-docs/connect/intentions) CRUD endpoints
+will retain all of their prior fields _as long as those endpoints are
+exclusively used to edit intentions_. Once the underlying config entry
+representation is edited it will transition the intention into the newer format
+where some fields are no longer present. Once this transition occurs those
+intentions can no longer be used with the ID-based endpoints unless they are
+re-created via the old endpoints. Fields that are being removed or changing
+behavior:
+
+- `Intention.ID` after migration is stored in the
+ [`LegacyID`](/docs/agent/config-entries/service-intentions#legacyid) field.
+ After transitioning this field is cleared.
+
+- `Intention.CreatedAt` after migration is stored in the
+ [`LegacyCreateTime`](/docs/agent/config-entries/service-intentions#legacycreatetime)
+ field. After transitioning this field is cleared.
+
+- `Intention.UpdatedAt` after migration is stored in the
+ [`LegacyUpdateTime`](/docs/agent/config-entries/service-intentions#legacyupdatetime)
+ field. After transitioning this field is cleared.
+
+- `Intention.Meta` after migration is stored in the
+ [`LegacyMeta`](/docs/agent/config-entries/service-intentions#legacymeta)
+ field. To complete the transition, this field **must be cleared manually**
+ and the metadata moved up to the enclosing config entry's
+ [`Meta`](/docs/agent/config-entries/service-intentions#meta) field. This is
+ not done automatically since it is potentially a lossy operation.
+
## Consul 1.8.0
+#### Removal of Deprecated Features
+
The [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8)
configuration has been removed (with version 8 ACL support by being on by
default).
@@ -125,7 +179,7 @@ procedure](/docs/upgrading#standard-upgrades).
When a 1.4.0 server first starts, it runs in "Legacy ACL mode". In this mode,
bootstrap requests and new ACL APIs will not be functional yet and will return
-an error. The server advertises it's ability to support 1.4.0 ACLs via gossip
+an error. The server advertises its ability to support 1.4.0 ACLs via gossip
and waits.
In the primary datacenter, the servers all wait in legacy ACL mode until they
@@ -282,7 +336,7 @@ soon as they are stable, allowing Autopilot to remove old servers in a safer
way.
When upgrading from Consul 1.0, you may need to manually
-[force-leave](/docs/commands/force-leave) old servers as part of a rolling
+[force-leave](/commands/force-leave) old servers as part of a rolling
update to Consul 1.0.1.
## Consul 1.0
@@ -584,7 +638,7 @@ agents would have to wait to contact a Consul server before learning that.
The default for
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) was
changed to "true", so now operators need to opt-in to having agents support
-running commands remotely via [`consul exec`](/docs/commands/exec).
+running commands remotely via [`consul exec`](/commands/exec).
#### Raft Protocol Version Compatibility
diff --git a/website/pages/intro/getting-started/agent.mdx b/website/pages/intro/getting-started/agent.mdx
index 0fa1a4f27e..2f97788303 100644
--- a/website/pages/intro/getting-started/agent.mdx
+++ b/website/pages/intro/getting-started/agent.mdx
@@ -77,7 +77,7 @@ the name of your node with the `-node` flag.
## Cluster Members
-If you run [`consul members`](/docs/commands/members) in another terminal, you
+If you run [`consul members`](/commands/members) in another terminal, you
can see the members of the Consul cluster. We'll cover joining clusters in the next
section, but for now, you should only see one member (yourself):
@@ -91,7 +91,7 @@ The output shows our own node, the address it is running on, its
health state, its role in the cluster, and some version information.
Additional metadata can be viewed by providing the `-detailed` flag.
-The output of the [`members`](/docs/commands/members) command is based on
+The output of the [`members`](/commands/members) command is based on
the [gossip protocol](/docs/internals/gossip) and is eventually consistent.
That is, at any point in time, the view of the world as seen by your local
agent may not exactly match the state on the servers. For a strongly consistent
diff --git a/website/pages/intro/getting-started/connect.mdx b/website/pages/intro/getting-started/connect.mdx
index bae3cef3ff..d0d7d92206 100644
--- a/website/pages/intro/getting-started/connect.mdx
+++ b/website/pages/intro/getting-started/connect.mdx
@@ -140,7 +140,7 @@ machine is always encrypted.
We previously established a connection by directly running `consul connect proxy` in developer mode. Realistically, services need to establish connections
to dependencies over Connect. Let's register a service "web" that registers
-"socat" as an upstream dependency in it's sidecar registration:
+"socat" as an upstream dependency in its sidecar registration:
```shell-session
$ cat <