docs: all intention documentation updates (#8869)

website/data/docs-navigation.js

@@ -60,6 +60,7 @@ export default [
         content: ['service-registration', 'sidecar-service'],
       },
       'intentions',
+      'intentions-legacy',
       'observability',
       {
         category: 'l7-traffic',
@@ -195,6 +196,7 @@ export default [
           'ingress-gateway',
           'proxy-defaults',
           'service-defaults',
+          'service-intentions',
           'service-resolver',
           'service-router',
           'service-splitter',

website/pages/api-docs/acl/auth-methods.mdx

@@ -73,7 +73,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
   create the auth method within. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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.
 
 - `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
@@ -252,7 +252,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the auth method to update. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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.
 
 - `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set

website/pages/api-docs/acl/binding-rules.mdx

@@ -101,7 +101,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
   create the binding rule. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload
@@ -281,7 +281,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the binding rule to update. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload

website/pages/api-docs/acl/index.mdx

@@ -7,7 +7,7 @@ description: The /acl endpoints manage the Consul's ACL system.
 
 # ACL HTTP API
 
--> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
+-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy).
 
 The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens) and [policies](/api/acl/policies) with the `/acl` endpoints.
 
@@ -306,7 +306,7 @@ replication enabled.
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the Auth Method to use for Login. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload
@@ -434,7 +434,7 @@ replication enabled.
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the Auth Method to use for Login. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  If not provided, the namespace will be inherited from the request's ACL
   token, or will default to the `default` namespace.
 
   This must match the namespace provided on the [OIDC Callback](#oidc-callback).
@@ -518,7 +518,7 @@ replication enabled.
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the Auth Method to use for Login. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  If not provided, the namespace will be inherited from the request's ACL
   token, or will default to the `default` namespace.
 
   This must match the namespace provided on the [OIDC Callback](#oidc-callback).

website/pages/api-docs/acl/policies.mdx

@@ -7,7 +7,7 @@ description: The /acl/policy endpoints manage Consul's ACL policies.
 
 # ACL Policy HTTP API
 
--> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
+-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy).
 
 The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy),
 [update](#update-a-policy), [list](#list-policies) and
@@ -52,7 +52,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
   create the policy. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload
@@ -229,7 +229,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the policy to update. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload

website/pages/api-docs/acl/roles.mdx

@@ -77,7 +77,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
   create the role. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload
@@ -342,7 +342,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the role to update. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload

website/pages/api-docs/acl/tokens.mdx

@@ -7,7 +7,7 @@ description: The /acl/token endpoints manage Consul's ACL Tokens.
 
 # ACL Token HTTP API
 
--> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
+-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy).
 
 The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
 [update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.
@@ -103,7 +103,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
   create the token. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload
@@ -364,7 +364,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the token to update. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload
@@ -452,7 +452,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the token to be cloned. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload

website/pages/api-docs/agent/connect.mdx

@@ -18,6 +18,14 @@ to optimize performance of Connect without having to make requests to the server
 
 ## Authorize
 
+-> **Note:** This endpoint 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. 
+For performance and reliability reasons it is desirable to implement intention
+enforcement by listing [intentions that match the
+destination](/api/connect/intentions#list-matching-intentions) and representing
+them in the native configuration of the proxy itself (such as RBAC for Envoy).
+
 This endpoint tests whether a connection attempt is authorized between
 two services. This is the primary API that must be implemented by
 [proxies](/docs/connect/proxies) or
@@ -61,7 +69,7 @@ The table below shows this endpoint's support for
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
   the target service. If not provided in the JSON body, the value of
   the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payload

website/pages/api-docs/catalog.mdx

@@ -92,7 +92,7 @@ The table below shows this endpoint's support for
   service and checks will be registered. This value may be provided by either the
   `ns` URL query parameter or in the `X-Consul-Namespace` header. Additionally,
   the namespace may be provided within the `Service` or `Check` fields but if
-  present in multiple places, they must all be the same. If not provided at all,
+  present in multiple places, they must all be the same. 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.
 
@@ -204,7 +204,7 @@ The behavior of the endpoint depends on what keys are provided.
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which the
   service and checks will be deregistered. If not provided in the JSON body, the value of
   the `ns` URL query parameter or the `X-Consul-Namespace` header will be used.
-  If not provided at all, the namespace will be inherited from the request's ACL
+  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 Payloads
@@ -404,7 +404,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
   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
@@ -473,7 +473,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to use for the
   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
@@ -677,7 +677,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
   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
@@ -804,7 +804,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
   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. The `*`
   wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
 
@@ -933,7 +933,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the gateway.
   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. The `*`
   wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
 

website/pages/api-docs/config.mdx

@@ -13,7 +13,7 @@ The `/config` endpoints create, update, delete and query central configuration
 entries registered with Consul. 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.
 
 ## Apply Configuration
@@ -39,10 +39,11 @@ The table below shows this endpoint's support for
 </p>
 
 | Config Entry Kind   | Required ACL       |
-| ------------------- | ---------------- |
+| ------------------- | ------------------ |
 | ingress-gateway     | `operator:write`   |
 | proxy-defaults      | `operator:write`   |
 | service-defaults    | `service:write`    |
+| service-intentions  | `intentions:write` |
 | service-resolver    | `service:write`    |
 | service-router      | `service:write`    |
 | service-splitter    | `service:write`    |
@@ -61,7 +62,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace the config
   entry will apply to. This value may be provided by either the `ns` URL query
-  parameter or in the `X-Consul-Namespace` header. If not provided at all,
+  parameter or in the `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.
 
@@ -105,10 +106,11 @@ The table below shows this endpoint's support for
 <sup>1</sup> The ACL required depends on the config entry kind being read:
 
 | Config Entry Kind   | Required ACL      |
-| ------------------- | -------------- |
+| ------------------- | ----------------- |
 | ingress-gateway     | `service:read`    |
 | proxy-defaults      | `<none>`          |
 | service-defaults    | `service:read`    |
+| service-intentions  | `intentions:read` |
 | service-resolver    | `service:read`    |
 | service-router      | `service:read`    |
 | service-splitter    | `service:read`    |
@@ -128,7 +130,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - 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 from
+  `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
@@ -172,10 +174,11 @@ The table below shows this endpoint's support for
 <sup>1</sup> The ACL required depends on the config entry kind being read:
 
 | Config Entry Kind   | Required ACL      |
-| ------------------- | -------------- |
+| ------------------- | ----------------- |
 | ingress-gateway     | `service:read`    |
 | proxy-defaults      | `<none>`          |
 | service-defaults    | `service:read`    |
+| service-intentions  | `intentions:read` |
 | service-resolver    | `service:read`    |
 | service-router      | `service:read`    |
 | service-splitter    | `service:read`    |
@@ -192,7 +195,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - 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 from
+  `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
@@ -249,10 +252,11 @@ The table below shows this endpoint's support for
 | ingress-gateway     | `operator:write`   |
 | proxy-defaults      | `operator:write`   |
 | service-defaults    | `service:write`    |
+| service-intentions  | `intentions:write` |
 | service-resolver    | `service:write`    |
 | service-router      | `service:write`    |
 | service-splitter    | `service:write`    |
-| terminating-gateway | `operator:write` |
+| terminating-gateway | `operator:write  ` |
 
 ### Parameters
 
@@ -268,7 +272,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to delete from.
   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

website/pages/api-docs/connect/intentions.mdx

@@ -12,7 +12,127 @@ description: |-
 The `/connect/intentions` endpoint provide tools for managing
 [intentions](/docs/connect/intentions).
 
-## Create Intention
+-> **1.9.0 and later:** Reading and writing intentions has been
+migrated to the
+[`service-intentions`](/docs/agent/config-entries/service-intentions)
+config entry kind.
+
+## Upsert Intention by Name ((#upsert-intention-by-name)) <sup>Beta</sup>
+
+-> **1.9.0+:** This API is available in Consul versions 1.9.0 and later.
+
+This endpoint creates a new intention and returns `true` if it was created
+successfully.
+
+The name and destination pair must be unique. If another intention matches the
+name and destination, the creation will replace the previous intention.
+
+~> The intentions created by this endpoint will not be assigned the following
+fields: `ID`, `CreatedAt`, `UpdatedAt`. Additionally, the `Meta` field cannot
+be persisted using this endpoint and will require editing the enclosing
+`service-intentions` config entry for the destination.
+
+| Method | Path                        | Produces           |
+| ------ | --------------------------- | ------------------ |
+| `PUT`  | `/connect/intentions/exact` | `application/json` |
+
+The table below shows this endpoint's support for
+[blocking queries](/api/features/blocking),
+[consistency modes](/api/features/consistency),
+[agent caching](/api/features/caching), and
+[required ACLs](/api#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
+| ---------------- | ----------------- | ------------- | ------------------------------ |
+| `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |
+
+<p>
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
+  See{' '}
+  <a href="/docs/connect/intentions#intention-management-permissions">
+    Intention Management Permissions
+  </a>{' '}
+  for more details.
+</p>
+
+### URL Parameters
+
+- `source` `(string: <required>)` - Specifies the source service. This
+  is specified as part of the URL.
+  This can take [several forms](/commands/intention#source-and-destination-naming).
+
+- `destination` `(string: <required>)` - Specifies the destination service. This
+  is specified as part of the URL.
+  This can take [several forms](/commands/intention#source-and-destination-naming).
+
+- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
+  namespace to use when `source` or `destination` parameters lack namespaces.
+  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.
+  Added in Consul 1.9.0.
+
+### PUT Body Parameters
+
+- `SourceType` `(string: "")` - The type for the `SourceName` value.
+  This can be only "consul" today to represent a Consul service. If not
+  provided, this will be defaulted to "consul".
+
+- `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<IntentionPermission>)` - The list of all [additional L7
+  attributes](/docs/agent/config-entries/service-intentions#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.
+
+- `Description` `(string: "")` - Description for the intention. This is not
+  used by Consul, but is presented in API responses to assist tooling.
+
+### Sample Payload
+
+```json
+{
+  "SourceType": "consul",
+  "Action": "allow"
+}
+```
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --request PUT \
+    --data @payload.json \
+    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
+```
+
+### Sample Response
+
+```json
+true
+```
+
+## Create Intention with ID
+
+-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
+[upserting by name](#upsert-intention-by-name) or editing the
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entry for the destination.
 
 This endpoint creates a new intention and returns its ID if it was created
 successfully.
@@ -36,7 +156,7 @@ The table below shows this endpoint's support for
 | `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -44,7 +164,17 @@ The table below shows this endpoint's support for
   for more details.
 </p>
 
-### Parameters
+### URL Parameters
+
+- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
+  namespace to use when `SourceNS` or `DestinationNS` are omitted or empty.
+  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.
+  Added in Consul 1.9.0.
+
+### POST Body Parameters
 
 - `SourceName` `(string: <required>)` - The source of the intention.
   For a `SourceType` of `consul` this is the name of a Consul service. The
@@ -60,26 +190,18 @@ The table below shows this endpoint's support for
 - `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
   `DestinationName` parameter.
 
-- `SourceType` `(string: <required>)` - The type for the `SourceName` value.
+- `SourceType` `(string: "")` - The type for the `SourceName` value.
-  This can be only "consul" today to represent a Consul service.
+  This can be only "consul" today to represent a Consul service. If not
+  provided, this will be defaulted to "consul".
 
 - `Action` `(string: <required>)` - This is one of "allow" or "deny" for
   the action that should be taken if this intention matches a request.
 
 - `Description` `(string: "")` - Description for the intention. This is not
-  used for anything by Consul, but is presented in API responses to assist
+  used by Consul, but is presented in API responses to assist tooling.
-  tooling.
 
 - `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
 
-- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
-  namespace to use when `SourceNS` or `DestinationNS` are omitted or empty.
-  If not provided at all, 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.
-  Added in Consul 1.9.0.
-
 ### Sample Payload
 
 ```json
@@ -108,13 +230,18 @@ $ curl \
 }
 ```
 
-## Read Specific Intention
+## Update Intention by ID
 
-This endpoint reads a specific intention.
+-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
+[upserting by name](#upsert-intention-by-name) or editing the
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entry for the destination.
+
+This endpoint updates an intention with the given values.
 
 | Method | Path                        | Produces           |
 | ------ | --------------------------- | ------------------ |
-| `GET`  | `/connect/intentions/:uuid` | `application/json` |
+| `PUT`  | `/connect/intentions/:uuid` | `application/json` |
 
 The table below shows this endpoint's support for
 [blocking queries](/api/features/blocking),
@@ -123,11 +250,11 @@ The table below shows this endpoint's support for
 [required ACLs](/api#authentication).
 
 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
-| ---------------- | ----------------- | ------------- | ----------------------------- |
+| ---------------- | ----------------- | ------------- | ------------------------------ |
-| `YES`            | `all`             | `none`        | `intentions:read`<sup>1</sup> |
+| `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -137,38 +264,32 @@ The table below shows this endpoint's support for
 
 ### Parameters
 
-- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
+- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update. This
   is specified as part of the URL.
 
+- Other parameters are identical to creating an intention.
+
+### Sample Payload
+
+```json
+{
+  "SourceName": "web",
+  "DestinationName": "other-db",
+  "SourceType": "consul",
+  "Action": "allow"
+}
+```
+
 ### Sample Request
 
 ```shell-session
 $ curl \
+    --request PUT \
+    --data @payload.json \
     http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
 ```
 
-### Sample Response
+## Read Specific Intention by Name ((##read-specific-intention-by-name)) <sup>Beta</sup>
-
-```json
-{
-  "ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
-  "Description": "",
-  "SourceNS": "default",
-  "SourceName": "web",
-  "DestinationNS": "default",
-  "DestinationName": "db",
-  "SourceType": "consul",
-  "Action": "allow",
-  "Meta": {},
-  "Precedence": 9,
-  "CreatedAt": "2018-05-21T16:41:27.977155457Z",
-  "UpdatedAt": "2018-05-21T16:41:27.977157724Z",
-  "CreateIndex": 11,
-  "ModifyIndex": 11
-}
-```
-
-## Read Specific Intention by Name
 
 This endpoint reads a specific intention by its unique source and destination.
 
@@ -187,7 +308,7 @@ The table below shows this endpoint's support for
 | `YES`            | `all`             | `none`        | `intentions:read`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -199,15 +320,15 @@ The table below shows this endpoint's support for
 
 - `source` `(string: <required>)` - Specifies the source 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).
 
 - `destination` `(string: <required>)` - 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: "")` <EnterpriseAlert inline /> - 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.
@@ -222,6 +343,68 @@ $ curl \
 
 ### Sample Response
 
+```json
+{
+  "Description": "",
+  "SourceNS": "default",
+  "SourceName": "web",
+  "DestinationNS": "default",
+  "DestinationName": "db",
+  "SourceType": "consul",
+  "Action": "allow",
+  "Meta": {},
+  "Precedence": 9,
+  "CreateIndex": 11,
+  "ModifyIndex": 11
+}
+```
+
+## Read Specific Intention by ID
+
+-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of 
+[reading by name](#read-specific-intention-by-name) or by viewing the 
+[`service-intentions`](/docs/agent/config-entries/service-intentions)
+config entry for the destination.
+
+This endpoint reads a specific intention.
+
+| Method | Path                        | Produces           |
+| ------ | --------------------------- | ------------------ |
+| `GET`  | `/connect/intentions/:uuid` | `application/json` |
+
+The table below shows this endpoint's support for
+[blocking queries](/api/features/blocking),
+[consistency modes](/api/features/consistency),
+[agent caching](/api/features/caching), and
+[required ACLs](/api#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                  |
+| ---------------- | ----------------- | ------------- | ----------------------------- |
+| `YES`            | `all`             | `none`        | `intentions:read`<sup>1</sup> |
+
+<p>
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
+  See{' '}
+  <a href="/docs/connect/intentions#intention-management-permissions">
+    Intention Management Permissions
+  </a>{' '}
+  for more details.
+</p>
+
+### Parameters
+
+- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
+  is specified as part of the URL.
+
+### Sample Request
+
+```shell-session
+$ curl \
+    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
+```
+
+### Sample Response
+
 ```json
 {
   "ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
@@ -260,7 +443,7 @@ The table below shows this endpoint's support for
 | `YES`            | `all`             | `none`        | `intentions:read`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -276,7 +459,7 @@ The table below shows this endpoint's support for
 - `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the
   namespace to list intentions from.
   The `*` wildcard may be used to list intentions from all 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.
@@ -294,7 +477,6 @@ $ curl \
 ```json
 [
   {
-    "ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
     "Description": "",
     "SourceNS": "default",
     "SourceName": "web",
@@ -304,8 +486,6 @@ $ curl \
     "Action": "allow",
     "Meta": {},
     "Precedence": 9,
-    "CreatedAt": "2018-05-21T16:41:27.977155457Z",
-    "UpdatedAt": "2018-05-21T16:41:27.977157724Z",
     "CreateIndex": 11,
     "ModifyIndex": 11
   }
@@ -331,13 +511,15 @@ the following selectors and filter operations being supported:
 | `SourceName`      | Equal, Not Equal, In, Not In, Matches, Not Matches |
 | `SourceType`      | Equal, Not Equal, In, Not In, Matches, Not Matches |
 
-## Update Intention
+## Delete Intention by Name ((#delete-intention-by-name)) <sup>Beta</sup>
 
-This endpoint updates an intention with the given values.
+-> **1.9.0+:** This API is available in Consul versions 1.9.0 and later.
+
+This endpoint deletes a specific intention by its unique source and destination.
 
 | Method   | Path                        | Produces           |
-| ------ | --------------------------- | ------------------ |
+| -------- | --------------------------- | ------------------ |
-| `PUT`  | `/connect/intentions/:uuid` | `application/json` |
+| `DELETE` | `/connect/intentions/exact` | `application/json` |
 
 The table below shows this endpoint's support for
 [blocking queries](/api/features/blocking),
@@ -346,11 +528,11 @@ The table below shows this endpoint's support for
 [required ACLs](/api#authentication).
 
 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required                  |
-| ---------------- | ----------------- | ------------- | ------------------------------ |
+| ---------------- | ----------------- | ------------- | ----------------------------- |
 | `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -360,32 +542,36 @@ The table below shows this endpoint's support for
 
 ### Parameters
 
-- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update. This
+- `source` `(string: <required>)` - Specifies the source service. This
   is specified as part of the URL.
+  This can take [several forms](/commands/intention#source-and-destination-naming).
 
-- Other parameters are identical to creating an intention.
+- `destination` `(string: <required>)` - Specifies the destination service. This
+  is specified as part of the URL.
+  This can take [several forms](/commands/intention#source-and-destination-naming).
 
-### Sample Payload
+- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
-
+  namespace to use when `source` or `destination` parameters lack namespaces.
-```json
+  If not provided, the default namespace will be inherited from the
-{
+  request's ACL token or will default to the `default` namespace.
-  "SourceName": "web",
+  This value may be provided by either the `ns` URL query parameter or in the
-  "DestinationName": "other-db",
+  `X-Consul-Namespace` header.
-  "SourceType": "consul",
+  Added in Consul 1.9.0.
-  "Action": "allow"
-}
-```
 
 ### Sample Request
 
 ```shell-session
 $ curl \
-    --request PUT \
+    --request DELETE \
-    --data @payload.json \
+    http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
-    http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
 ```
 
-## Delete Intention
+## Delete Intention by ID
+
+-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
+[deleting by name](#delete-intention-by-name) or editing the
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
+entry for the destination.
 
 This endpoint deletes a specific intention.
 
@@ -404,7 +590,7 @@ The table below shows this endpoint's support for
 | `NO`             | `none`            | `none`        | `intentions:write`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -428,8 +614,17 @@ $ curl \
 ## Check Intention Result
 
 This endpoint evaluates the intentions for a specific source and destination
-and returns whether the connection would be authorized or not given the
+and returns whether the connection would be authorized or not given the current
-current Consul configuration and set of intentions.
+Consul configuration and set of intentions.
+
+-> **Note:** This endpoint will always evaulate intentions with `Permissions`
+defined as *deny* intentions during. This endpoint is only suited for
+networking layer 4 (e.g. TCP) integration.
+
+For performance and reliability reasons it is desirable to implement intention
+enforcement by listing [intentions that match the
+destination](/api/connect/intentions#list-matching-intentions) and representing
+them in the native configuration of the proxy itself (such as RBAC for Envoy).
 
 This endpoint will work even if the destination service has
 `intention = "deny"` specifically set, because the resulting API response
@@ -450,7 +645,7 @@ The table below shows this endpoint's support for
 | `NO`             | `none`            | `none`        | `intentions:read`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -462,15 +657,15 @@ The table below shows this endpoint's support for
 
 - `source` `(string: <required>)` - Specifies the source 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).
 
 - `destination` `(string: <required>)` - 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: "")` <EnterpriseAlert inline /> - 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.
@@ -509,11 +704,11 @@ The table below shows this endpoint's support for
 [required ACLs](/api#authentication).
 
 | Blocking Queries | Consistency Modes | Agent Caching        | ACL Required                  |
-| ---------------- | ----------------- | ------------- | ----------------------------- |
+| ---------------- | ----------------- | -------------------- | ----------------------------- |
-| `NO`             | `none`            | `none`        | `intentions:read`<sup>1</sup> |
+| `YES`            | `all`             | `background refresh` | `intentions:read`<sup>1</sup> |
 
 <p>
-  <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
+  <sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
   See{' '}
   <a href="/docs/connect/intentions#intention-management-permissions">
     Intention Management Permissions
@@ -528,11 +723,11 @@ The table below shows this endpoint's support for
 
 - `name` `(string: <required>)` - 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: "")` <EnterpriseAlert inline /> - 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
     }

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

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.

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=<seconds>` 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

website/pages/api-docs/health.mdx

@@ -47,7 +47,7 @@ The table below shows this endpoint's support for
 
 - `ns` `(string: "")` <EnterpriseAlert inline /> - 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: "")` <EnterpriseAlert inline /> - 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: "")` <EnterpriseAlert inline /> - 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: "")` <EnterpriseAlert inline /> - 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

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)

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

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

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

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

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

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 `<service>-proxy`
   where `<service>` 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.
 

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.
 

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.

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
 

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`
+- `consul intention create [options] SRC DST`
-Usage: `consul intention create [options] -f FILE...`
+- `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
 

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
 

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
 

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
 

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
+The [check](/commands/intention/check) command can be used to
-check whether a connection would be authorized between any two services.
+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)
 ```

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)
+- [delete](/commands/kv/delete)
-- [export](/docs/commands/kv/export)
+- [export](/commands/kv/export)
-- [get](/docs/commands/kv/get)
+- [get](/commands/kv/get)
-- [import](/docs/commands/kv/import)
+- [import](/commands/kv/import)
-- [put](/docs/commands/kv/put)
+- [put](/commands/kv/put)
 
 ## Basic Examples
 

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 [<tt>consul
-lock</tt>](/docs/commands/lock) command. It provides higher-level
+lock</tt>](/commands/lock) command. It provides higher-level
 functionality without exposing the internal APIs of Consul.

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) <EnterpriseAlert inline />
+- [area](/commands/operator/area) <EnterpriseAlert inline />
-- [autopilot](/docs/commands/operator/autopilot)
+- [autopilot](/commands/operator/autopilot)
-- [raft](/docs/commands/operator/raft)
+- [raft](/commands/operator/raft)

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"`

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.
 

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
 

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.

website/pages/commands/snapshot/agent.mdx

@@ -10,9 +10,9 @@ Command: `consul snapshot agent`
 
 <EnterpriseAlert />
 
-~> 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:

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) <EnterpriseAlert inline />
+- [agent](/commands/snapshot/agent) <EnterpriseAlert inline />
-- [inspect](/docs/commands/snapshot/inspect)
+- [inspect](/commands/snapshot/inspect)
-- [restore](/docs/commands/snapshot/restore)
+- [restore](/commands/snapshot/restore)
-- [save](/docs/commands/snapshot/save)
+- [save](/commands/snapshot/save)
 
 ## Basic Examples
 

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) <sup>Beta</sup> - 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:

website/pages/docs/agent/config-entries/ingress-gateway.mdx

@@ -636,8 +636,7 @@ Routes = [
 
 ## ACLs
 
-Configuration entries may be protected by
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
 
 Reading an `ingress-gateway` config entry requires `service:read` on the `Name`
 field of the config entry.

website/pages/docs/agent/config-entries/proxy-defaults.mdx

@@ -86,8 +86,7 @@ Config {
 
 ## ACLs
 
-Configuration entries may be protected by
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
 
 Reading a `proxy-defaults` config entry requires no specific privileges.
 

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
+  [`service-router`](/docs/agent/config-entries/service-router) config entries
-  entries for a service. Supported values are one of `tcp`, `http`, `http2`, or `grpc`.
+  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: <optional>)` - 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
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
 
-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.

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 <sup>Beta</sup>
+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)) <sup>Beta</sup>
+
+-> **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: <required>)` - 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")` <EnterpriseAlert inline /> - 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<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
+
+- `Sources` `(array<SourceIntention>)` - 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: <required>)` - 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")` <EnterpriseAlert inline /> - 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<IntentionPermission>)` - 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: <read-only>)` - 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: <read-only>)` - 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<string|string>: <read-only>)` - 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: <required>)` - This is one of "allow" or "deny" for
+  the action that should be taken if this permission matches a request.
+
+- `HTTP` `(IntentionHTTPPermission: <required>)` - 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<string>)` - 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<IntentionHTTPHeaderPermission>)` - 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: <required>)` - 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).

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
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
 
-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)

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: <optional>)` - A set of
-      [http-specific match criteria](#serviceroutehttpmatch).
+      [HTTP-specific match criteria](#serviceroutehttpmatch).
 
   - `Destination` `(ServiceRouteDestination: <optional>)` - Controls [how to
     proxy](#serviceroutedestination) the matching request(s) to a
@@ -165,6 +165,10 @@ Routes = [
 
   At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
 
+- `Methods` `(array<string>)` - 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<ServiceRouteHTTPMatchHeader>)` - 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<string>)` - 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<int>)` - A flat list of http response status
+- `RetryOnStatusCodes` `(array<int>)` - A list of HTTP response status codes
-  codes that are eligible for retry.
+  that are eligible for retry.
 
 ## ACLs
 
-Configuration entries may be protected by
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
 
-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)

website/pages/docs/agent/config-entries/service-splitter.mdx

@@ -105,13 +105,12 @@ Splits = [
 
 ## ACLs
 
-Configuration entries may be protected by
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
 
-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)

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
+Configuration entries may be protected by [ACLs](/docs/security/acl).
-[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
 
 Reading a `terminating-gateway` config entry requires `service:read` on the `Name`
 field of the config entry.

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,

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.

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   |

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

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

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

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
+The destination service verifies the client certificate against the [public CA
-against the [public CA bundle](/api/connect/ca#list-ca-root-certificates).
+bundle](/api/connect/ca#list-ca-root-certificates). After verifying the
-After verifying the certificate, it must also call the
+certificate, the next step depends upon the configured application protocol of
-[authorization API](/api/agent/connect#authorize) to authorize
+the destination service. TCP (L4) services must authorize incoming _connections_
-the connection against the configured set of Consul [intentions](/docs/connect/intentions).
+against the configured set of Consul [intentions](/docs/connect/intentions),
-If the authorization API responds successfully, the connection is established.
+whereas HTTP (L7) services must authorize incoming _requests_ against those same
-Otherwise, the connection is rejected.
+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
+To enable fast responses on endpoints such as the [agent Connect
-endpoints](/api/agent/connect), the Consul agent locally caches most
+API](/api/agent/connect), the Consul agent locally caches most Connect-related
-Connect-related data and sets up background [blocking
+data and sets up background [blocking queries](/api/features/blocking) against
-queries](/api/features/blocking) against the server to update the cache in
+the server to update the cache in the background. This allows most API calls
-the background. This allows most API calls such as retrieving certificates or
+such as retrieving certificates or authorizing connections to use in-memory
-authorizing connections to use in-memory data and respond very quickly.
+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
+Connections can be made via gateways to enable communicating across network
-network topologies allowing connections between services in each datacenter
+topologies, allowing connections between services in each datacenter without
-without externally routable IPs at the service level.
+externally routable IPs at the service level.
 
 ## Intention Replication
 

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

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

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.

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
+  control which services may establish connections or make requests.
-  via the API, CLI, or UI.
 ---
 
 # Intentions
 
-Intentions define access control for services via Connect and are used
+-> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and
-to control which services may establish connections. Intentions can be
+later. The documentation for the legacy intentions system is
-managed via the API, CLI, or UI.
+[here](/docs/connect/intentions-legacy).
 
-Intentions are enforced by the [proxy](/docs/connect/proxies)
+Intentions define access control for services via Connect and are used to
-or [natively integrated application](/docs/connect/native) on
+control which services may establish connections or make requests. Intentions
-inbound connections. After verifying the TLS client certificate, the
+can be managed via the API, CLI, or UI.
-[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
+Intentions are enforced on inbound connections or requests by the
-[ACL policy](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). If the default ACL policy is "allow all",
+[proxy](/docs/connect/proxies) or within a [natively integrated
-then all Connect connections are allowed by default. If the default ACL policy
+application](/docs/connect/native).
-is "deny all", then all Connect connections are denied by default.
+
+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](#),
+Intentions are managed primarily via
-or UI. Please see the respective documentation for each for full details
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
-on options, flags, etc.
+entries or the UI. Some simpler tasks can also be achieved with the older
-Below is an example of a basic intention to show the basic attributes
+[API](/api-docs/connect/intentions) or [CLI](/commands/intention). Please see
-of an intention. The full data model of an intention can be found in the
+the respective documentation for each for full details on options, flags, etc.
-[API documentation](#).
 
-```shell-session
+Below is an example of a basic
-$ consul intention create -deny web db
+[`service-intentions`](/docs/agent/config-entries/service-intentions) config
-Created: web => db (deny)
+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
+This config entry defines two intentions with a common destination of "db". The
-destination of "db". This says that connections from web to db are not
+first intention above is a deny intention with a source of "web". This says
-allowed and the connection will be rejected.
+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".
-When an intention is modified, existing connections will not be affected.
+This says that connections from api to db are allowed and connections will be
-This means that changing a connection from "allow" to "deny" today
+accepted.
-_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:
+value `*`. This matches _any_ value and is used as a catch-all.
 
-```shell-session
+This example says that the "web" service cannot connect to _any_ service:
-$ consul intention create -deny web '*'
+
-Created: web => * (deny)
+```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
+```hcl
-
+Kind = "service-intentions"
-Arbitrary string key/value data may be associated with intentions. This
+Name = "db"
-is unused by Consul but can be used by external systems or for visibility
+Sources = [
-in the UI.
+  {
-
+    Name   = "*"
-```shell-session
+    Action = "deny"
-$ 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
 ```
 
+### 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)
+The precedence value can be read from a
-after an intention is created.
+[field](/docs/agent/config-entries/service-intentions#precedence) on the
-Precedence cannot be manually overridden today. This is a feature that will
+`service-intentions` config entry after it is modified. Precedence cannot be
-be added in a later version of Consul.
+manually overridden today.
-
-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
+-> <EnterpriseAlert inline /> - Namespaces are an Enterprise feature. In Consul
-the table with a `*` for either the source namespace or destination namespace are not applicable.
+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
+Supported [proxies] (such as [Envoy]) also cache this data within their own
-communication for authorization and generally impose only impose microseconds
+configuration so that inbound connections or requests require no Consul agent
-of latency to the connection. All actions in the data path of connections
+involvement during authorization. All actions in the data path of connections
-require only local data to ensure minimal performance overhead.
+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.
+Because all the intention data is cached locally, the agents or proxies can
-Even if the agents are severed completely from the Consul servers, inbound
+fail static. Even if the agents are severed completely from the Consul servers,
-connection authorization continues to work for a configured amount of time.
+or the proxies are severed completely from their local Consul agent, inbound
-Changes to intentions will not be picked up until the partition heals, but
+connection authorization continues to work indefinitely. Changes to intentions
-will then automatically take effect when connectivity is restored.
+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

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.
 

website/pages/docs/connect/l7-traffic/index.mdx

@@ -37,7 +37,7 @@ traffic.
 ![diagram showing l7 traffic discovery stages: routing to splitting to resolution](/img/l7-traffic-stages.svg)
 
 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

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:
   - `<name>.query[.<datacenter>].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
+```go
-import(
+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.
-````

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.
 
 ![Native Integration Overview](/img/connect-native-overview.png)
 
+-> **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
+  certificate against the [public CA
-  [public CA roots](/api/agent/connect#certificate-authority-ca-roots).
+  roots](/api/agent/connect#certificate-authority-ca-roots). After verifying
-  After verifying the certificate, parse some basic fields from it and call
+  the certificate, parse some basic fields from it and use those to determine
-  the [authorizing API](/api/agent/connect#authorize) against the local
+  if the connection should be allowed. How this is done is dependent on
-  agent. If this returns successfully, complete the TLS handshake and establish
+  the level of integration desired:
-  the connection. If authorization fails, close the connection.
 
--> **A note on performance:** The only API call in the connection path is
+  - **Simple integration (TCP-only)** - Call the [authorizing
-the [authorization API](/api/agent/connect#authorize). The other API
+    API](/api/agent/connect#authorize) against the local agent. If this returns
-calls to acquire the leaf certificate and CA roots are expected to be done
+    successfully, complete the TLS handshake and establish the connection. If
-out of band and reused. The authorize API call should be called against the
+    authorization fails, close the connection.
-local Consul agent. The agent uses locally cached
+
-data to authorize the connection and typically responds in microseconds.
+    -> **NOTE:** This API call is expected to be called in the connection path,
-Therefore, the impact to the TLS handshake is typically microseconds.
+    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
 

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

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
@@ -34,21 +34,26 @@ 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.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.6.x, 1.5.3, 1.5.2 | 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.5.1, 1.5.0        | 1.9.1, 1.8.0†                     |
-| 1.3.x, 1.4.x        | 1.9.1, 1.8.0†, 1.7.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).<br/><br/>
+† 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
+have configured HTTP routing rules. Still, we recommend that you use the most
-hatch"](#escape-hatch-overrides). Still, we recommend that you use the most
+recent supported Envoy for your Consul version where possible.<br/><br/>
-recent supported Envoy for your Consul version where possible.<br/><br/>\* 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.
+\* 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
+identity (node id) and the location of its local Consul agent from which it
-discovers all of it's dynamic configuration. See [Bootstrap
+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

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
+proxy for a good development and out of the box experience, but production
-that production users will require other proxy solutions.
+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
+particular service. One or both of these may be implemented depending on the
-the case, although generally both must be supported.
+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
+The certificate served should be obtained from the
-[`/v1/agent/connect/ca/leaf/`](/api/agent/connect) API endpoint.
+[`/v1/agent/connect/ca/leaf/`] API endpoint. The client certificate should be
-The client certificate should be validated against the root certificates
+validated against the root certificates provided by the
-provided by the
+[`/v1/agent/connect/ca/roots`] endpoint. After validating the client
-[`/v1/agent/connect/ca/roots`](/api/agent/connect) endpoint.
+certificate from the caller, depending upon the [protocol] of the proxied
-After validating the client certificate from the caller, the proxy should
+service service the proxy must either authorize the entire connection (L4) or
-call the
+each request (L7).
-[`/v1/agent/connect/authorize`](/api/agent/connect) endpoint to
-authorize the connection.
 
-All of these API endpoints operate on agent-local data that is updated
+Connection authorization can be performed one of two ways:
-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.
 
-The leaf and root cert endpoints support blocking queries. These should be
+1. The first is by calling the
-used if possible to get near-immediate updates for root cert rotations,
+   [`/v1/agent/connect/authorize`](/api/agent/connect) endpoint. The authorize
-leaf expiry, etc.
+   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
+For outbound connections, the proxy should communicate to a Connect-capable
-Connect-capable endpoint for a service and provide a client certificate
+endpoint for a service and provide a client certificate from the
-from the
+[`/v1/agent/connect/ca/leaf/`] API endpoint. The certificate served by the
-[`/v1/agent/connect/ca/leaf/`](/api/agent/connect) API endpoint.
+remote endpoint may be verified against the root certificates from the
-The certificate served by the remote endpoint can be verified against the
+[`/v1/agent/connect/ca/roots`] endpoint.
-root certificates from the
-[`/v1/agent/connect/ca/roots`](/api/agent/connect) 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
+This endpoint supports hash-based blocking, enabling long-polling for changes
-service should be fetched from the
+to the registration/configuration. Any changes to the registration/config will
-[`/v1/discovery-chain/:service_id`](/api/discovery-chain) API endpoint.
+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
+The [discovery chain] for each upstream service should be fetched from the
-resulting discovery chain, a list of healthy endpoints can be fetched from the
+[`/v1/discovery-chain/:service_id`](/api/discovery-chain#read-compiled-discovery-chain)
-[`/v1/health/connect/:service_id`](/api/health#list-nodes-for-connect-capable-service)
+API endpoint. This will return a compiled graph of configurations needed by
-API endpoint.
+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=<service>`
+argument, which causes the command to query Consul for a proxy that is
+registered as a sidecar for the specified `<service>`. 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

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
 `<data_dir>/proxy/logs/<proxy_service_id>-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.
 

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.

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`.

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
 

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.
 

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

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.

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:

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.
 

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

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.

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`.

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

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

website/pages/docs/guides/containers-guide.mdx

@@ -278,7 +278,7 @@ When a previously stopped server container is restarted using `docker start <con
 
 ### Backing-up Data
 
-You can back-up your Consul datacenter using the [consul snapshot](/docs/commands/snapshot) command.
+You can back-up your Consul datacenter using the [consul snapshot](/commands/snapshot) command.
 
 ```shell-session
 $ docker exec <container_id> 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 <container_id>: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
 

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

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

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.

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:
 

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)
 

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

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
 

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

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)) <EnterpriseAlert inline /> - Values for setting up and running [snapshot agents](/docs/commands/snapshot/agent)
+  - `snapshotAgent` ((#v-client-snapshotagent)) <EnterpriseAlert inline /> - 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

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`.

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.

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`.

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`:
 

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=<host:port>`](/docs/commands/login#oidc-callback-listen-addr).
+[`-oidc-callback-listen-addr=<host:port>`](/commands/login#oidc-callback-listen-addr).
 
 ## OIDC Configuration Troubleshooting
 

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

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

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

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)

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