From 282c8dccf075cbdfcd7a638507a94912db884e5f Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Mon, 29 Nov 2021 17:56:57 -0500
Subject: [PATCH 01/98] Remove demo directory

This demo setups are no longer maintained. See https://github.com/hashicorp/demo-consul-101
for a maintained demo.
---
 .../docker-compose-cluster/docker-compose.yml | 34 -----------
 demo/vagrant-cluster/README.md                | 57 -------------------
 demo/vagrant-cluster/Vagrantfile              | 56 ------------------
 3 files changed, 147 deletions(-)
 delete mode 100644 demo/docker-compose-cluster/docker-compose.yml
 delete mode 100644 demo/vagrant-cluster/README.md
 delete mode 100644 demo/vagrant-cluster/Vagrantfile

diff --git a/demo/docker-compose-cluster/docker-compose.yml b/demo/docker-compose-cluster/docker-compose.yml
deleted file mode 100644
index d9b022b3b9..0000000000
--- a/demo/docker-compose-cluster/docker-compose.yml
+++ /dev/null
@@ -1,34 +0,0 @@
-version: '3'
-
-services:
-
-  consul-agent-1: &consul-agent
-    image: consul:latest
-    networks:
-      - consul-demo
-    command: "agent -retry-join consul-server-bootstrap -client 0.0.0.0"
-
-  consul-agent-2:
-    <<: *consul-agent
-
-  consul-agent-3:
-    <<: *consul-agent
-
-  consul-server-1: &consul-server
-    <<: *consul-agent
-    command: "agent -server -retry-join consul-server-bootstrap -client 0.0.0.0"
-
-  consul-server-2:
-    <<: *consul-server
-
-  consul-server-bootstrap:
-    <<: *consul-agent
-    ports:
-      - "8400:8400"
-      - "8500:8500"
-      - "8600:8600"
-      - "8600:8600/udp"
-    command: "agent -server -bootstrap-expect 3 -ui -client 0.0.0.0"
-
-networks:
-  consul-demo:
diff --git a/demo/vagrant-cluster/README.md b/demo/vagrant-cluster/README.md
deleted file mode 100644
index 6b5405861b..0000000000
--- a/demo/vagrant-cluster/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Vagrant Consul Demo
-
-This demo provides a very simple `Vagrantfile` that creates two Consul
-server nodes, one at *172.20.20.10* and another at *172.20.20.11*. Both are
-running a standard Debian * distribution, and *the latest version* of Consul
-is pre-installed.
-
-To get started, you can start the nodes by just doing:
-
-```
-vagrant up
-```
-
-> NOTE: If you prefer a different Vagrant box, you can set the `DEMO_BOX_NAME`
-> environment variable before starting `vagrant` like this: 
-> `DEMO_BOX_NAME="ubuntu/xenial64" vagrant up`
-
-Once it is finished, you should be able to see the following:
-
-```
-vagrant status
-Current machine states:
-
-n1                        running (virtualbox)
-n2                        running (virtualbox)
-```
-
-At this point the two nodes are running and you can SSH in to play with them:
-
-```
-vagrant ssh n1
-consul version
-Consul v0.7.5
-Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)
-exit
-```
-
-and
-
-```
-vagrant ssh n2
-consul version
-Consul v0.7.5
-Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)
-exit
-```
-
-> NOTE: This demo will query the HashiCorp Checkpoint service to determine
-> the latest Consul release version and install that version by default,
-> but if you need a different Consul version, set the `CONSUL_DEMO_VERSION`
-> environment variable before `vagrant up` like this:
-> `CONSUL_DEMO_VERSION=0.6.4 vagrant up`
-
-## Where to Next?
-
-To learn more about starting Consul, joining nodes into a cluster, and
-interacting with the agent, check out the [Getting Started guide](https://www.consul.io/intro/getting-started/install.html).
diff --git a/demo/vagrant-cluster/Vagrantfile b/demo/vagrant-cluster/Vagrantfile
deleted file mode 100644
index 0ac0f199c3..0000000000
--- a/demo/vagrant-cluster/Vagrantfile
+++ /dev/null
@@ -1,56 +0,0 @@
-# -*- mode: ruby -*-
-# vi: set ft=ruby :
-
-$script = <<SCRIPT
-
-echo "Installing dependencies ..."
-sudo apt-get update
-sudo apt-get install -y unzip curl jq dnsutils
-
-echo "Determining Consul version to install ..."
-CHECKPOINT_URL="https://checkpoint-api.hashicorp.com/v1/check"
-if [ -z "$CONSUL_DEMO_VERSION" ]; then
-    CONSUL_DEMO_VERSION=$(curl -s "${CHECKPOINT_URL}"/consul | jq .current_version | tr -d '"')
-fi
-
-echo "Fetching Consul version ${CONSUL_DEMO_VERSION} ..."
-cd /tmp/
-curl -s https://releases.hashicorp.com/consul/${CONSUL_DEMO_VERSION}/consul_${CONSUL_DEMO_VERSION}_linux_amd64.zip -o consul.zip
-
-echo "Installing Consul version ${CONSUL_DEMO_VERSION} ..."
-unzip consul.zip
-sudo chmod +x consul
-sudo mv consul /usr/bin/consul
-
-sudo mkdir /etc/consul.d
-sudo chmod a+w /etc/consul.d
-
-SCRIPT
-
-# Specify a Consul version
-CONSUL_DEMO_VERSION = ENV['CONSUL_DEMO_VERSION']
-
-# Specify a custom Vagrant box for the demo
-DEMO_BOX_NAME = ENV['DEMO_BOX_NAME'] || "debian/stretch64"
-
-# Vagrantfile API/syntax version.
-# NB: Don't touch unless you know what you're doing!
-VAGRANTFILE_API_VERSION = "2"
-
-Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
-  config.vm.box = DEMO_BOX_NAME
-
-  config.vm.provision "shell",
-                          inline: $script,
-                          env: {'CONSUL_DEMO_VERSION' => CONSUL_DEMO_VERSION}
-
-  config.vm.define "n1" do |n1|
-      n1.vm.hostname = "n1"
-      n1.vm.network "private_network", ip: "172.20.20.10"
-  end
-
-  config.vm.define "n2" do |n2|
-      n2.vm.hostname = "n2"
-      n2.vm.network "private_network", ip: "172.20.20.11"
-  end
-end

From b3496a337af058fd3af05777d3f30e5b5506b757 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 5 Jan 2022 18:45:00 -0800
Subject: [PATCH 02/98] initial commit/draft of the API gateway docs

---
 .../content/docs/k8s/connect/api-gateway.mdx  | 171 ++++++++++++++++++
 website/data/docs-nav-data.json               |   4 +
 2 files changed, 175 insertions(+)
 create mode 100644 website/content/docs/k8s/connect/api-gateway.mdx

diff --git a/website/content/docs/k8s/connect/api-gateway.mdx b/website/content/docs/k8s/connect/api-gateway.mdx
new file mode 100644
index 0000000000..732bed8689
--- /dev/null
+++ b/website/content/docs/k8s/connect/api-gateway.mdx
@@ -0,0 +1,171 @@
+---
+layout: docs
+page_title: API Gateway
+description: Using Consul API gateway functionality
+---
+
+# Consul API Gateway
+
+This topic describes how to use the Consul API Gateway module, which enables applications and services running in a datacenter to be accessed by network clients outside the datacenter. This type of network traffic is commonly referred to as "north-south" network traffic.
+
+## Introduction
+
+Consul API Gateway is an implementation of the Kubernetes Gateway API Specification (https://gateway-api.sigs.k8s.io/). The specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes.
+
+## Requirements
+
+Your datacenter must meet the following requirements prior to configuring the Consul API Gateway:
+
+- A Kubernetes cluster must be running
+- Consul 1.11.0+
+
+## Installation
+
+1. Create a values file for your Consul server agents that contains the following parameters:
+
+   ```yaml
+   global:
+     name: consul
+     image: 'hashicorp/consul:1.11.0'
+     tls:
+       enabled: true
+   connectInject:
+     enabled: true
+   controller:
+     enabled: true
+   ```
+
+1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
+
+```shell-session
+helm install consul hashicorp/consul --version 0.37.0 -f values.yaml
+```
+
+The following components will be installed:
+
+    - Gateway controller
+    - CRDs required by the Kubernetes Gateway API specification
+    - `kustomize` manifests for completing the installation
+
+1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster.
+
+```shell-session
+kubectl apply -k "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-techpreview"
+kubectl apply -k "github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-techpreview"
+```
+
+## Usage
+
+1. Verify that the [requirements](#requirements) have been met.
+1. Verify that the Consul API Gateway software has been installed and applied (see [Installation](#installation)).
+1. Configure the gateway, listener(s), and route(s) as described in [Configuration](#configuration)
+1. Issue the `kubectl apply` command to implement the configurations, e.g.:
+
+```shell-session
+kubectl apply -f gateway-configuration.yaml
+```
+
+### Using the Consul API Gateway Binary
+
+You can manually start the Consul API Gateway control plane server using the binary located in the home directory to issue the `server` command:
+
+```shell-session
+./consul-api-gateway server <options>
+```
+
+The following options are supported:
+
+| Option                                                                                                     | Description                                                                                                                                                                           | Required                                        | Default                                                   |
+| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------ |
+| `-ca-file`                                                                                                 | String value that specifies the path to the CA for the Consul server.                                                                                                                 | Required                                        | none                                                      |
+| `-ca-secret`                                                                                               | String value that specifies the CA secret for the Consul server.                                                                                                                      | Required                                        | none                                                      |
+| `-ca-secret-namespace` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | String value that specifies the CA secret namespace for the Consul server.                                                                                                            | Required                                        | none                                                      |
+| `-k8-context`                                                                                              | String value that specifies the Kubernetes context to use when starting the Consul server.                                                                                            | Optional                                        | current context                                           |
+| `-k8-namespace`                                                                                            | String value that specifies the Kubernetes namespace to use when starting the Consul server.                                                                                          | Optional                                        | `default`                                                 |
+| `-log-json`                                                                                                | Boolean value that enables or disables JSON format for the log output.                                                                                                                | Required                                        | `false`                                                   |
+| `-log-level`                                                                                               | String value that specifies the logging level. The following values are supported: <br/>- `trace` (highest level of detail) <br/>- `debug` <br/>- `info` <br/>- `warn` <br/>- `error` | context to use when starting the Consul server. | Required                                                  | `info` |
+| `-metrics-port`                                                                                            | Integer value that specifies the port number for collecting metrics.                                                                                                                  | Optional                                        | none                                                      |
+| `-pprof`                                                                                                   | Integer value that specifies the Go pprof port number for collecting metrics.                                                                                                         | Optional                                        | none                                                      |
+| `-sds-server-host`                                                                                         | String value that specifies the host server for the secret discovery service (SDS).                                                                                                   | Optional                                        | `consul-api-gateway-controller.default.svc.cluster.local` |
+| `-sds-server-host`                                                                                         | Integer value that specifies the port number for the secret discovery service (SDS).                                                                                                  | Optional                                        | `9090`                                                    |
+
+You can also issue the `version` command to print the Consul API Gateway version to the console:
+
+```shell-session
+./consul-api-gateway version
+consul-api-gateway 0.1.0-dev
+```
+
+## Configuration
+
+Create the following artifacts to configure the API Gateway:
+
+- [Gateway](#gateway): Defines the gateway properties, including listeners.
+- [Listeners](#listeners): Defines listener properties, such as protocol, port, and namespace.
+- [Routes](#routes): Specifies the path from the client to the listener.
+
+### Gateway
+
+The gateway object contains gateway listeners.
+Add the `kind: Gateway` option to the configuration file to declare a gateway.
+The following example creates a gateway called `example-gateway` that includes a listener called `https` (see Listeners for details about the `listener` configuration).
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: Gateway
+metadata:
+  name: example-gateway
+  annotations:
+    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
+spec:
+  gatewayClassName: default-consul-gateway-class
+  listeners:
+    - protocol: HTTPS
+      hostname: DNS_HOSTNAME
+      port: 443
+      name: https
+      allowedRoutes:
+        namespaces:
+          from: Same
+      tls:
+        certificateRefs:
+          - name: gateway-production-certificate
+```
+
+Refer to the Kubernetes Gateway API documentation for details about configuring gateways:
+https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway
+
+### Listener
+
+Listeners are the logical endpoints bound to the gateway's addresses.
+Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener:
+
+- `hostname`: Hostname specifies the virtual hostname to match for protocol types.
+- `port`: Specifies the network port.
+- `protocol`: Specifies the network protocol expected by the listener.
+
+Refer to the Kubernetes Gateway API documentation for details about configuring listeners:
+https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener
+
+In the example included the [Gateway](#gateway) description, a listener named `https` that listens over `HTTPS` is configured to listen on port `443`
+
+### Route
+
+Routes are independent configuration objects that are associated with a specific listener.
+Use the `kind: HTTPRoute` option to declare a route and use the `spec` option to specify the route details.
+The following example creates a route named `example-route` associated with a listener defined in `example-gateway`.
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: HTTPRoute
+metadata:
+  name: example-route
+spec:
+  parentRefs:
+    - name: example-gateway
+  rules:
+    - backendRefs:
+        - kind: Service
+          name: echo
+          port: 8080
+```
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 77a5ef1ffe..f16ce4f4ff 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -475,6 +475,10 @@
             "title": "Transparent Proxy",
             "href": "/docs/connect/transparent-proxy"
           },
+          {
+            "title": "Consul API Gateway",
+            "path": "k8s/connect/api-gateway"
+          },
           {
             "title": "Ingress Gateways",
             "path": "k8s/connect/ingress-gateways"

From 7121c78d34dd346a3aeb2c300c40d4b63281a53c Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 25 Nov 2021 13:24:35 -0500
Subject: [PATCH 03/98] ca: update godoc

To clarify what to expect from the data stored in this field, and the
behaviour of this function.
---
 agent/consul/leader_connect_ca.go | 10 ++++++----
 agent/structs/connect_ca.go       | 23 ++++++++++++++++-------
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/agent/consul/leader_connect_ca.go b/agent/consul/leader_connect_ca.go
index 0a6b0b47a4..2cf6fce970 100644
--- a/agent/consul/leader_connect_ca.go
+++ b/agent/consul/leader_connect_ca.go
@@ -602,10 +602,12 @@ func (c *CAManager) getLeafSigningCertFromRoot(root *structs.CARoot) string {
 	return root.IntermediateCerts[len(root.IntermediateCerts)-1]
 }
 
-// secondaryInitializeIntermediateCA runs the routine for generating an intermediate CA CSR and getting
-// it signed by the primary DC if the root CA of the primary DC has changed since the last
-// intermediate. It should only be called while the state lock is held by setting the state
-// to non-ready.
+// secondaryInitializeIntermediateCA generates a Certificate Signing Request (CSR)
+// for the intermediate CA that is used to sign leaf certificates in the secondary.
+// The CSR is signed by the primary DC and then persisted in the state store.
+//
+// This method should only be called while the state lock is held by setting the
+// state to non-ready.
 func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, config *structs.CAConfiguration) error {
 	activeIntermediate, err := provider.ActiveIntermediate()
 	if err != nil {
diff --git a/agent/structs/connect_ca.go b/agent/structs/connect_ca.go
index f3d175d350..4b4549b7ae 100644
--- a/agent/structs/connect_ca.go
+++ b/agent/structs/connect_ca.go
@@ -76,9 +76,14 @@ type CARoot struct {
 	// SerialNumber is the x509 serial number of the certificate.
 	SerialNumber uint64
 
-	// SigningKeyID is the ID of the public key that corresponds to the private
-	// key used to sign leaf certificates. Is is the HexString format of the
-	// raw AuthorityKeyID bytes.
+	// SigningKeyID is the connect.HexString encoded id of the public key that
+	// corresponds to the private key used to sign leaf certificates in the
+	// local datacenter.
+	//
+	// The value comes from x509.Certificate.SubjectKeyId of the local leaf
+	// signing cert.
+	//
+	// See https://www.rfc-editor.org/rfc/rfc3280#section-4.2.1.1 for more detail.
 	SigningKeyID string
 
 	// ExternalTrustDomain is the trust domain this root was generated under. It
@@ -192,10 +197,14 @@ type IssuedCert struct {
 	// This is encoded in standard hex separated by :.
 	SerialNumber string
 
-	// CertPEM and PrivateKeyPEM are the PEM-encoded certificate and private
-	// key for that cert, respectively. This should not be stored in the
-	// state store, but is present in the sign API response.
-	CertPEM       string `json:",omitempty"`
+	// CertPEM is a PEM encoded bundle of a leaf certificate, optionally followed
+	// by one or more intermediate certificates that will form a chain of trust
+	// back to a root CA.
+	//
+	// This field is not persisted in the state store, but is present in the
+	// sign API response.
+	CertPEM string `json:",omitempty"`
+	// PrivateKeyPEM is the PEM encoded private key associated with CertPEM.
 	PrivateKeyPEM string `json:",omitempty"`
 
 	// Service is the name of the service for which the cert was issued.

From d0578c6dfc2709ce1e21d4443a1f4498762b78ef Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 25 Nov 2021 16:15:09 -0500
Subject: [PATCH 04/98] ca: extract the lookup of the active primary CA

This method had only one caller, which always looked for the active
root. This commit moves the lookup into the method to reduce the logic
in the one caller.

This is being done in preparation for a larger change. Keeping this
separate so it is easier to see.

The `storedRootID != primaryRoots.ActiveRootID` is being removed because
these can never be different.

The `storedRootID` comes from `provider.ActiveRoot`, the
`primaryRoots.ActiveRootID` comes from the store `CARoot` from the
primary. In both cases the source of the data is the primary DC.

Technically they could be different if someone modified the provider
outside of Consul, but that would break many things, so is not a
supported flow.

If these were out of sync because of ordering of events then the
secondary will soon receive an update to `primaryRoots` and everything
will be sorted out again.
---
 agent/consul/leader_connect_ca.go | 33 +++++++++++++++----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/agent/consul/leader_connect_ca.go b/agent/consul/leader_connect_ca.go
index 2cf6fce970..6a6a2a7023 100644
--- a/agent/consul/leader_connect_ca.go
+++ b/agent/consul/leader_connect_ca.go
@@ -197,11 +197,18 @@ func (c *CAManager) secondarySetPrimaryRoots(newRoots structs.IndexedCARoots) {
 	c.primaryRoots = newRoots
 }
 
-func (c *CAManager) secondaryGetPrimaryRoots() structs.IndexedCARoots {
+func (c *CAManager) secondaryGetActivePrimaryCARoot() (*structs.CARoot, error) {
 	// TODO: this could be a different lock, as long as its the same lock in secondarySetPrimaryRoots
 	c.stateLock.Lock()
-	defer c.stateLock.Unlock()
-	return c.primaryRoots
+	primaryRoots := c.primaryRoots
+	c.stateLock.Unlock()
+
+	for _, root := range primaryRoots.Roots {
+		if root.ID == primaryRoots.ActiveRootID && root.Active {
+			return root, nil
+		}
+	}
+	return nil, fmt.Errorf("primary datacenter does not have an active root CA for Connect")
 }
 
 // initializeCAConfig is used to initialize the CA config if necessary
@@ -658,25 +665,17 @@ func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, conf
 		}
 	}
 
-	// Determine which of the provided PRIMARY representations of roots is the
-	// active one. We'll use this as a template to generate any new root
-	// representations meant for this secondary.
-	var newActiveRoot *structs.CARoot
-	primaryRoots := c.secondaryGetPrimaryRoots()
-	for _, root := range primaryRoots.Roots {
-		if root.ID == primaryRoots.ActiveRootID && root.Active {
-			newActiveRoot = root
-			break
-		}
-	}
-	if newActiveRoot == nil {
-		return fmt.Errorf("primary datacenter does not have an active root CA for Connect")
+	newActiveRoot, err := c.secondaryGetActivePrimaryCARoot()
+	if err != nil {
+		return err
 	}
 
+	_ = storedRootID // TODO: will be removed in the next commit
+
 	// Get a signed intermediate from the primary DC if the provider
 	// hasn't been initialized yet or if the primary's root has changed.
 	needsNewIntermediate := false
-	if activeIntermediate == "" || storedRootID != primaryRoots.ActiveRootID {
+	if activeIntermediate == "" {
 		needsNewIntermediate = true
 	}
 

From 0de7efb31687511855827cb52298efa5361f6bdf Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 25 Nov 2021 16:33:48 -0500
Subject: [PATCH 05/98] ca: remove unused provider.ActiveRoot call

In the previous commit the single use of this storedRoot was removed.

In this commit the original objective is completed. The
Provider.ActiveRoot is being removed because

1. the secondary should get the active root from the Consul primary DC,
   not the provider, so that secondary DCs do not need to communicate
   with a provider instance in a different DC.
2. so that the Provider.ActiveRoot interface can be changed without
   impacting other code paths.
---
 agent/consul/leader_connect_ca.go | 61 +++++++------------------------
 testrpc/wait.go                   |  1 +
 2 files changed, 14 insertions(+), 48 deletions(-)

diff --git a/agent/consul/leader_connect_ca.go b/agent/consul/leader_connect_ca.go
index 6a6a2a7023..75ac1df5d4 100644
--- a/agent/consul/leader_connect_ca.go
+++ b/agent/consul/leader_connect_ca.go
@@ -621,48 +621,22 @@ func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, conf
 		return err
 	}
 
-	var (
-		storedRootID         string
-		expectedSigningKeyID string
-		currentSigningKeyID  string
-		activeSecondaryRoot  *structs.CARoot
-	)
-	if activeIntermediate != "" {
-		// In the event that we already have an intermediate, we must have
-		// already replicated some primary root information locally, so check
-		// to see if we're up to date by fetching the rootID and the
-		// signingKeyID used in the secondary.
-		//
-		// Note that for the same rootID the primary representation of the root
-		// will have a different SigningKeyID field than the secondary
-		// representation of the same root. This is because it's derived from
-		// the intermediate which is different in all datacenters.
-		storedRoot, err := provider.ActiveRoot()
-		if err != nil {
-			return err
-		}
-
-		storedRootID, err = connect.CalculateCertFingerprint(storedRoot)
-		if err != nil {
-			return fmt.Errorf("error parsing root fingerprint: %v, %#v", err, storedRoot)
-		}
+	_, activeRoot, err := c.delegate.State().CARootActive(nil)
+	if err != nil {
+		return err
+	}
+	var currentSigningKeyID string
+	if activeRoot != nil {
+		currentSigningKeyID = activeRoot.SigningKeyID
+	}
 
+	var expectedSigningKeyID string
+	if activeIntermediate != "" {
 		intermediateCert, err := connect.ParseCert(activeIntermediate)
 		if err != nil {
 			return fmt.Errorf("error parsing active intermediate cert: %v", err)
 		}
 		expectedSigningKeyID = connect.EncodeSigningKeyID(intermediateCert.SubjectKeyId)
-
-		// This will fetch the secondary's exact current representation of the
-		// active root. Note that this data should only be used if the IDs
-		// match, otherwise it's out of date and should be regenerated.
-		_, activeSecondaryRoot, err = c.delegate.State().CARootActive(nil)
-		if err != nil {
-			return err
-		}
-		if activeSecondaryRoot != nil {
-			currentSigningKeyID = activeSecondaryRoot.SigningKeyID
-		}
 	}
 
 	newActiveRoot, err := c.secondaryGetActivePrimaryCARoot()
@@ -670,12 +644,10 @@ func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, conf
 		return err
 	}
 
-	_ = storedRootID // TODO: will be removed in the next commit
-
 	// Get a signed intermediate from the primary DC if the provider
 	// hasn't been initialized yet or if the primary's root has changed.
-	needsNewIntermediate := false
-	if activeIntermediate == "" {
+	needsNewIntermediate := activeIntermediate == ""
+	if activeRoot != nil && newActiveRoot.ID != activeRoot.ID {
 		needsNewIntermediate = true
 	}
 
@@ -694,14 +666,7 @@ func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, conf
 	} else {
 		// Discard the primary's representation since our local one is
 		// sufficiently up to date.
-		newActiveRoot = activeSecondaryRoot
-	}
-
-	// Update the roots list in the state store if there's a new active root.
-	state := c.delegate.State()
-	_, activeRoot, err := state.CARootActive(nil)
-	if err != nil {
-		return err
+		newActiveRoot = activeRoot
 	}
 
 	// Determine whether a root update is needed, and persist the roots/config accordingly.
diff --git a/testrpc/wait.go b/testrpc/wait.go
index a872668cea..230f2f38a8 100644
--- a/testrpc/wait.go
+++ b/testrpc/wait.go
@@ -144,6 +144,7 @@ func WaitForTestAgent(t *testing.T, rpc rpcFn, dc string, options ...waitOption)
 // raft leadership is gained so WaitForLeader isn't sufficient to be sure that
 // the CA is fully initialized.
 func WaitForActiveCARoot(t *testing.T, rpc rpcFn, dc string, expect *structs.CARoot) {
+	t.Helper()
 	retry.Run(t, func(r *retry.R) {
 		args := &structs.DCSpecificRequest{
 			Datacenter: dc,

From d57dec587801a7305eac3151706df3bbdeaec7d0 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 25 Nov 2021 18:09:23 -0500
Subject: [PATCH 06/98] ca: remove unnecessary var, and slightly reduce cyclo
 complexity

`newIntermediate` is always equal to `needsNewIntermediate`, so we can
remove the extra variable and use the original directly.

Also remove the `activeRoot.ID != newActiveRoot.ID` case from an if,
because that case is already checked above, and `needsNewIntermediate` will
already be true in that case.

This condition now reads a lot better:

> Persist a new root if we did not have one before, or if generated a new intermediate.
---
 agent/consul/leader_connect_ca.go | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/agent/consul/leader_connect_ca.go b/agent/consul/leader_connect_ca.go
index 75ac1df5d4..51525f507e 100644
--- a/agent/consul/leader_connect_ca.go
+++ b/agent/consul/leader_connect_ca.go
@@ -657,12 +657,10 @@ func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, conf
 		needsNewIntermediate = true
 	}
 
-	newIntermediate := false
 	if needsNewIntermediate {
 		if err := c.secondaryRenewIntermediate(provider, newActiveRoot); err != nil {
 			return err
 		}
-		newIntermediate = true
 	} else {
 		// Discard the primary's representation since our local one is
 		// sufficiently up to date.
@@ -671,7 +669,7 @@ func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, conf
 
 	// Determine whether a root update is needed, and persist the roots/config accordingly.
 	var newRoot *structs.CARoot
-	if activeRoot == nil || activeRoot.ID != newActiveRoot.ID || newIntermediate {
+	if activeRoot == nil || needsNewIntermediate {
 		newRoot = newActiveRoot
 	}
 	if err := c.persistNewRootAndConfig(provider, newRoot, config); err != nil {

From d893c9261e95621073a7ee44044b99777bd5081c Mon Sep 17 00:00:00 2001
From: Krastin Krastev <krastin@hashicorp.com>
Date: Mon, 10 Jan 2022 17:37:38 +0100
Subject: [PATCH 07/98] adding JSON examples to
 /docs/connect/observability/ui-visualization

---
 .../observability/ui-visualization.mdx        | 101 ++++++++++++++++++
 1 file changed, 101 insertions(+)

diff --git a/website/content/docs/connect/observability/ui-visualization.mdx b/website/content/docs/connect/observability/ui-visualization.mdx
index e21631a482..9a9056ff07 100644
--- a/website/content/docs/connect/observability/ui-visualization.mdx
+++ b/website/content/docs/connect/observability/ui-visualization.mdx
@@ -66,6 +66,9 @@ service named `prometheus-server` so each Consul agent can reach it on
 
 A full configuration to enable Prometheus is given below.
 
+<Tabs>
+<Tab heading="HCL">
+
 ```hcl
 ui_config {
   enabled = true
@@ -76,6 +79,28 @@ ui_config {
 }
 ```
 
+</Tab>
+<Tab heading="JSON">
+
+```json
+{
+  "ui_config": [
+    {
+      "enabled": true,
+      "metrics_provider": "prometheus",
+      "metrics_proxy": [
+        {
+          "base_url": "http://prometheus-server"
+        }
+      ]
+    }
+  ]
+}
+```
+
+</Tab>
+</Tabs>
+
 Similarly, to configure the UI on Kubernetes, use this [reference](/docs/k8s/connect/observability/metrics).
 
 ## Configuring Dashboard URLs
@@ -114,6 +139,31 @@ ui_config {
 without horizontal scrolling in the example above however this needs to be a
 normal single-line string value in an HCL configuration file.
 
+</Tab>
+<Tab heading="JSON">
+
+```json
+{
+  "ui_config": [
+    {
+      "dashboard_url_templates": [
+        {
+          "service": "https://grafana.example.com/d/lDlaj-NGz/
+            service-overview?orgId=1\u0026var-service={{Service.Name}}\u0026
+            var-namespace={{Service.Namespace}}\u0026
+            var-partition={{Service.Partition}}\u0026var-dc={{Datacenter}}"
+        }
+      ],
+      "enabled": true
+    }
+  ]
+}
+```
+
+-> **Note**: the URL is wrapped over multiple lines to make it easier to read
+without horizontal scrolling in the example above however this needs to be a
+normal single-line string value in a JSON configuration file.
+
 </Tab>
 <Tab heading="Kubernetes YAML">
 
@@ -235,6 +285,9 @@ visible to Consul operators in the configuration file while UI users can query
 the metrics they need without separately obtaining a token for that provider or
 having a token exposed to them that they might be able to use elsewhere.
 
+<Tabs>
+<Tab heading="HCL">
+
 ```hcl
 ui_config {
   enabled = true
@@ -251,6 +304,34 @@ ui_config {
 }
 ```
 
+</Tab>
+<Tab heading="JSON">
+
+```json
+{
+  "ui_config": [
+    {
+      "enabled": true,
+      "metrics_provider": "example-apm",
+      "metrics_proxy": [
+        {
+          "add_headers": [
+            {
+              "name": "Authorization",
+              "value": "Bearer \u003ctoken\u003e"
+            }
+          ],
+          "base_url": "https://example-apm.com/api/v1/metrics"
+        }
+      ]
+    }
+  ]
+}
+```
+
+</Tab>
+</Tabs>
+
 ## Custom Metrics Providers
 
 Consul 1.9.0 includes a built-in provider for fetching metrics from
@@ -484,6 +565,9 @@ named `example-provider`, which is defined in
 have been specified in the call to `consul.registerMetricsProvider` as in the
 code listing in the last section.
 
+<Tabs>
+<Tab heading="HCL">
+
 ```hcl
 ui_config {
   enabled = true
@@ -497,6 +581,23 @@ ui_config {
 }
 ```
 
+</Tab>
+<Tab heading="JSON">
+
+```json
+{
+  "ui_config": {
+    "enabled": true,
+    "metrics_provider": "example-provider",
+    "metrics_provide_files": ["/usr/local/bin/example-metrics-provider.js"],
+    "metrics_provider_options_json": "{\"foo\":\"bar\"}"
+  }
+}
+```
+
+</Tab>
+</Tabs>
+
 More than one JavaScript file may be specified in
 [`metrics_provider_files`](/docs/agent/options#ui_config_metrics_provider_files)
 and all we be served allowing flexibility if needed to include dependencies.

From 66ac665925701f4a7ab82996788f8c75e2093af2 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 12 Jan 2022 11:19:15 -0800
Subject: [PATCH 08/98] applied feedback

---
 .../content/docs/k8s/connect/api-gateway.mdx  | 54 +++++++++----------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/website/content/docs/k8s/connect/api-gateway.mdx b/website/content/docs/k8s/connect/api-gateway.mdx
index 732bed8689..9e06730c5f 100644
--- a/website/content/docs/k8s/connect/api-gateway.mdx
+++ b/website/content/docs/k8s/connect/api-gateway.mdx
@@ -10,14 +10,14 @@ This topic describes how to use the Consul API Gateway module, which enables app
 
 ## Introduction
 
-Consul API Gateway is an implementation of the Kubernetes Gateway API Specification (https://gateway-api.sigs.k8s.io/). The specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes.
+Consul API Gateway is an implementation of the Kubernetes Gateway [API Specification](https://gateway-api.sigs.k8s.io/). The specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes.
 
 ## Requirements
 
 Your datacenter must meet the following requirements prior to configuring the Consul API Gateway:
 
 - A Kubernetes cluster must be running
-- Consul 1.11.0+
+- Consul 1.11.1+
 
 ## Installation
 
@@ -38,20 +38,16 @@ Your datacenter must meet the following requirements prior to configuring the Co
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
 ```shell-session
-helm install consul hashicorp/consul --version 0.37.0 -f values.yaml
+$ helm install consul hashicorp/consul --version 0.39.0 -f values.yaml
 ```
 
-The following components will be installed:
-
-    - Gateway controller
-    - CRDs required by the Kubernetes Gateway API specification
-    - `kustomize` manifests for completing the installation
+The following components will be installed: - Gateway controller - CRDs required by the Kubernetes Gateway API specification - `kustomize` manifests for completing the installation
 
 1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster.
 
 ```shell-session
-kubectl apply -k "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-techpreview"
-kubectl apply -k "github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-techpreview"
+$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-techpreview"
+$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-techpreview"
 ```
 
 ## Usage
@@ -62,7 +58,7 @@ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-tech
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
 ```shell-session
-kubectl apply -f gateway-configuration.yaml
+$ kubectl apply -f gateway-configuration.yaml
 ```
 
 ### Using the Consul API Gateway Binary
@@ -75,24 +71,24 @@ You can manually start the Consul API Gateway control plane server using the bin
 
 The following options are supported:
 
-| Option                                                                                                     | Description                                                                                                                                                                           | Required                                        | Default                                                   |
-| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------ |
-| `-ca-file`                                                                                                 | String value that specifies the path to the CA for the Consul server.                                                                                                                 | Required                                        | none                                                      |
-| `-ca-secret`                                                                                               | String value that specifies the CA secret for the Consul server.                                                                                                                      | Required                                        | none                                                      |
-| `-ca-secret-namespace` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | String value that specifies the CA secret namespace for the Consul server.                                                                                                            | Required                                        | none                                                      |
-| `-k8-context`                                                                                              | String value that specifies the Kubernetes context to use when starting the Consul server.                                                                                            | Optional                                        | current context                                           |
-| `-k8-namespace`                                                                                            | String value that specifies the Kubernetes namespace to use when starting the Consul server.                                                                                          | Optional                                        | `default`                                                 |
-| `-log-json`                                                                                                | Boolean value that enables or disables JSON format for the log output.                                                                                                                | Required                                        | `false`                                                   |
-| `-log-level`                                                                                               | String value that specifies the logging level. The following values are supported: <br/>- `trace` (highest level of detail) <br/>- `debug` <br/>- `info` <br/>- `warn` <br/>- `error` | context to use when starting the Consul server. | Required                                                  | `info` |
-| `-metrics-port`                                                                                            | Integer value that specifies the port number for collecting metrics.                                                                                                                  | Optional                                        | none                                                      |
-| `-pprof`                                                                                                   | Integer value that specifies the Go pprof port number for collecting metrics.                                                                                                         | Optional                                        | none                                                      |
-| `-sds-server-host`                                                                                         | String value that specifies the host server for the secret discovery service (SDS).                                                                                                   | Optional                                        | `consul-api-gateway-controller.default.svc.cluster.local` |
-| `-sds-server-host`                                                                                         | Integer value that specifies the port number for the secret discovery service (SDS).                                                                                                  | Optional                                        | `9090`                                                    |
+| Option                 | Description                                                                                                                                                                           | Required                                        | Default                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | ------ |
+| `-ca-file`             | String value that specifies the path to the CA for the Consul server.                                                                                                                 | Required                                        | none                                                                    |
+| `-ca-secret`           | String value that specifies the CA secret for the Consul server.                                                                                                                      | Required                                        | none                                                                    |
+| `-ca-secret-namespace` | String value that specifies the CA secret namespace for the Consul server.                                                                                                            | Required                                        | none                                                                    |
+| `-k8-context`          | String value that specifies the Kubernetes context to use when starting the Consul server.                                                                                            | Optional                                        | current context                                                         |
+| `-k8-namespace`        | String value that specifies the Kubernetes namespace to use when starting the Consul server.                                                                                          | Optional                                        | `default`                                                               |
+| `-log-json`            | Boolean value that enables or disables JSON format for the log output.                                                                                                                | Required                                        | `false`                                                                 |
+| `-log-level`           | String value that specifies the logging level. The following values are supported: <br/>- `trace` (highest level of detail) <br/>- `debug` <br/>- `info` <br/>- `warn` <br/>- `error` | context to use when starting the Consul server. | Required                                                                | `info` |
+| `-metrics-port`        | Integer value that specifies the port number for collecting metrics.                                                                                                                  | Optional                                        | none                                                                    |
+| `-pprof`               | Integer value that specifies the Go pprof port number for collecting metrics.                                                                                                         | Optional                                        | none                                                                    |
+| `-sds-server-host`     | String value that specifies the host server for the secret discovery service (SDS).                                                                                                   | Optional                                        | `consul-api-gateway-controller.default.`<br/>`svc.cluster.`<br/>`local` |
+| `-sds-server-host`     | Integer value that specifies the port number for the secret discovery service (SDS).                                                                                                  | Optional                                        | `9090`                                                                  |
 
 You can also issue the `version` command to print the Consul API Gateway version to the console:
 
 ```shell-session
-./consul-api-gateway version
+$ ./consul-api-gateway version
 consul-api-gateway 0.1.0-dev
 ```
 
@@ -108,7 +104,9 @@ Create the following artifacts to configure the API Gateway:
 
 The gateway object contains gateway listeners.
 Add the `kind: Gateway` option to the configuration file to declare a gateway.
-The following example creates a gateway called `example-gateway` that includes a listener called `https` (see Listeners for details about the `listener` configuration).
+The following example creates a gateway called `example-gateway` that includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration).
+
+<CodeBlockConfig lineNumbers highlight="2,4,9,13">
 
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1alpha2
@@ -132,10 +130,12 @@ spec:
           - name: gateway-production-certificate
 ```
 
+</CodeBlockConfig>
+
 Refer to the Kubernetes Gateway API documentation for details about configuring gateways:
 https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway
 
-### Listener
+### Listeners
 
 Listeners are the logical endpoints bound to the gateway's addresses.
 Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener:

From fb40ad05cf9fe2f209151dc596848a2059aff0a0 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 12 Jan 2022 11:23:22 -0800
Subject: [PATCH 09/98] forgot to update the image version

---
 website/content/docs/k8s/connect/api-gateway.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/docs/k8s/connect/api-gateway.mdx b/website/content/docs/k8s/connect/api-gateway.mdx
index 9e06730c5f..2d931ea758 100644
--- a/website/content/docs/k8s/connect/api-gateway.mdx
+++ b/website/content/docs/k8s/connect/api-gateway.mdx
@@ -26,7 +26,7 @@ Your datacenter must meet the following requirements prior to configuring the Co
    ```yaml
    global:
      name: consul
-     image: 'hashicorp/consul:1.11.0'
+     image: 'hashicorp/consul:1.11.1'
      tls:
        enabled: true
    connectInject:

From 3510430522f5a42a6987c93880f50db28719c2ac Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 12 Jan 2022 11:24:36 -0800
Subject: [PATCH 10/98] missed a cmd block when adding dollar signs

---
 website/content/docs/k8s/connect/api-gateway.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/docs/k8s/connect/api-gateway.mdx b/website/content/docs/k8s/connect/api-gateway.mdx
index 2d931ea758..a799535711 100644
--- a/website/content/docs/k8s/connect/api-gateway.mdx
+++ b/website/content/docs/k8s/connect/api-gateway.mdx
@@ -66,7 +66,7 @@ $ kubectl apply -f gateway-configuration.yaml
 You can manually start the Consul API Gateway control plane server using the binary located in the home directory to issue the `server` command:
 
 ```shell-session
-./consul-api-gateway server <options>
+$ ./consul-api-gateway server <options>
 ```
 
 The following options are supported:

From c67612e6edd9069a4d94f129651d2f4b91d5bb74 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 12 Jan 2022 11:32:32 -0800
Subject: [PATCH 11/98] added beta flag to nav link

---
 website/data/docs-nav-data.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index f16ce4f4ff..af3f213a37 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -476,7 +476,7 @@
             "href": "/docs/connect/transparent-proxy"
           },
           {
-            "title": "Consul API Gateway",
+            "title": "Consul API Gateway <sup>BETA</sup>",
             "path": "k8s/connect/api-gateway"
           },
           {

From c2c717df1b707599efe2899c23dd09a1f0f24497 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 12 Jan 2022 11:53:32 -0800
Subject: [PATCH 12/98] fixes to the params table

---
 .../content/docs/k8s/connect/api-gateway.mdx  | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/website/content/docs/k8s/connect/api-gateway.mdx b/website/content/docs/k8s/connect/api-gateway.mdx
index a799535711..ec00cda18b 100644
--- a/website/content/docs/k8s/connect/api-gateway.mdx
+++ b/website/content/docs/k8s/connect/api-gateway.mdx
@@ -71,19 +71,19 @@ $ ./consul-api-gateway server <options>
 
 The following options are supported:
 
-| Option                 | Description                                                                                                                                                                           | Required                                        | Default                                                                 |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | ------ |
-| `-ca-file`             | String value that specifies the path to the CA for the Consul server.                                                                                                                 | Required                                        | none                                                                    |
-| `-ca-secret`           | String value that specifies the CA secret for the Consul server.                                                                                                                      | Required                                        | none                                                                    |
-| `-ca-secret-namespace` | String value that specifies the CA secret namespace for the Consul server.                                                                                                            | Required                                        | none                                                                    |
-| `-k8-context`          | String value that specifies the Kubernetes context to use when starting the Consul server.                                                                                            | Optional                                        | current context                                                         |
-| `-k8-namespace`        | String value that specifies the Kubernetes namespace to use when starting the Consul server.                                                                                          | Optional                                        | `default`                                                               |
-| `-log-json`            | Boolean value that enables or disables JSON format for the log output.                                                                                                                | Required                                        | `false`                                                                 |
-| `-log-level`           | String value that specifies the logging level. The following values are supported: <br/>- `trace` (highest level of detail) <br/>- `debug` <br/>- `info` <br/>- `warn` <br/>- `error` | context to use when starting the Consul server. | Required                                                                | `info` |
-| `-metrics-port`        | Integer value that specifies the port number for collecting metrics.                                                                                                                  | Optional                                        | none                                                                    |
-| `-pprof`               | Integer value that specifies the Go pprof port number for collecting metrics.                                                                                                         | Optional                                        | none                                                                    |
-| `-sds-server-host`     | String value that specifies the host server for the secret discovery service (SDS).                                                                                                   | Optional                                        | `consul-api-gateway-controller.default.`<br/>`svc.cluster.`<br/>`local` |
-| `-sds-server-host`     | Integer value that specifies the port number for the secret discovery service (SDS).                                                                                                  | Optional                                        | `9090`                                                                  |
+| Option                 | Description                                                                                                                                                                           | Required | Default                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
+| `-ca-file`             | String value that specifies the path to the CA for the Consul server.                                                                                                                 | Required | none                                                                    |
+| `-ca-secret`           | String value that specifies the CA secret for the Consul server.                                                                                                                      | Required | none                                                                    |
+| `-ca-secret-namespace` | String value that specifies the CA secret namespace for the Consul server.                                                                                                            | Required | none                                                                    |
+| `-k8-context`          | String value that specifies the Kubernetes context to use when starting the Consul server.                                                                                            | Optional | current context                                                         |
+| `-k8-namespace`        | String value that specifies the Kubernetes namespace to use when starting the Consul server.                                                                                          | Optional | `default`                                                               |
+| `-log-json`            | Boolean value that enables or disables JSON format for the log output.                                                                                                                | Required | `false`                                                                 |
+| `-log-level`           | String value that specifies the logging level. The following values are supported: <br/>- `trace` (highest level of detail) <br/>- `debug` <br/>- `info` <br/>- `warn` <br/>- `error` | Optional | `info`                                                                  |
+| `-metrics-port`        | Integer value that specifies the port number for collecting metrics.                                                                                                                  | Optional | none                                                                    |
+| `-pprof`               | Integer value that specifies the Go pprof port number for collecting metrics.                                                                                                         | Optional | none                                                                    |
+| `-sds-server-host`     | String value that specifies the host server for the secret discovery service (SDS).                                                                                                   | Optional | `consul-api-gateway-controller.default.`<br/>`svc.cluster.`<br/>`local` |
+| `-sds-server-host`     | Integer value that specifies the port number for the secret discovery service (SDS).                                                                                                  | Optional | `9090`                                                                  |
 
 You can also issue the `version` command to print the Consul API Gateway version to the console:
 

From 0d35c303609c78a82fd742779a8bf592ad6a528c Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 12 Jan 2022 14:04:03 -0800
Subject: [PATCH 13/98] moved consul api gateway to top of nav hierarchy

---
 website/content/docs/{k8s/connect => }/api-gateway.mdx | 0
 website/data/docs-nav-data.json                        | 8 ++++----
 2 files changed, 4 insertions(+), 4 deletions(-)
 rename website/content/docs/{k8s/connect => }/api-gateway.mdx (100%)

diff --git a/website/content/docs/k8s/connect/api-gateway.mdx b/website/content/docs/api-gateway.mdx
similarity index 100%
rename from website/content/docs/k8s/connect/api-gateway.mdx
rename to website/content/docs/api-gateway.mdx
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index af3f213a37..fcd8697403 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -356,6 +356,10 @@
       }
     ]
   },
+  {
+    "title": "Consul API Gateway <sup>BETA</sup>",
+    "path": "api-gateway"
+  },
   {
     "title": "Kubernetes",
     "routes": [
@@ -475,10 +479,6 @@
             "title": "Transparent Proxy",
             "href": "/docs/connect/transparent-proxy"
           },
-          {
-            "title": "Consul API Gateway <sup>BETA</sup>",
-            "path": "k8s/connect/api-gateway"
-          },
           {
             "title": "Ingress Gateways",
             "path": "k8s/connect/ingress-gateways"

From f92dc11002c9697dcf1bd30fd9995ab5ce8f13b4 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Wed, 12 Jan 2022 17:46:12 -0500
Subject: [PATCH 14/98] rpc: refactor blocking query

To remove the TODO, and make it more readable.

In general this reduces the scope of variables, making them easier to reason about.
It also introduces more early returns so that we can see the flow from the structure
of the function.
---
 agent/consul/rpc.go | 105 ++++++++++++++++++++++----------------------
 1 file changed, 52 insertions(+), 53 deletions(-)

diff --git a/agent/consul/rpc.go b/agent/consul/rpc.go
index c8fa6846cd..ddf4299508 100644
--- a/agent/consul/rpc.go
+++ b/agent/consul/rpc.go
@@ -919,22 +919,26 @@ type queryFn func(memdb.WatchSet, *state.Store) error
 
 // blockingQuery is used to process a potentially blocking query operation.
 func (s *Server) blockingQuery(queryOpts structs.QueryOptionsCompat, queryMeta structs.QueryMetaCompat, fn queryFn) error {
-	var cancel func()
 	var ctx context.Context = &lib.StopChannelContext{StopCh: s.shutdownCh}
 
-	var queriesBlocking uint64
-	var queryTimeout time.Duration
-
-	// Instrument all queries run
 	metrics.IncrCounter([]string{"rpc", "query"}, 1)
 
 	minQueryIndex := queryOpts.GetMinQueryIndex()
-	// Fast path right to the non-blocking query.
+	// Perform a non-blocking query
 	if minQueryIndex == 0 {
-		goto RUN_QUERY
+		if queryOpts.GetRequireConsistent() {
+			if err := s.consistentRead(); err != nil {
+				return err
+			}
+		}
+
+		var ws memdb.WatchSet
+		err := fn(ws, s.fsm.State())
+		s.setQueryMeta(queryMeta, queryOpts.GetToken())
+		return err
 	}
 
-	queryTimeout = queryOpts.GetMaxQueryTime()
+	queryTimeout := queryOpts.GetMaxQueryTime()
 	// Restrict the max query time, and ensure there is always one.
 	if queryTimeout > s.config.MaxQueryTime {
 		queryTimeout = s.config.MaxQueryTime
@@ -946,64 +950,57 @@ func (s *Server) blockingQuery(queryOpts structs.QueryOptionsCompat, queryMeta s
 	queryTimeout += lib.RandomStagger(queryTimeout / structs.JitterFraction)
 
 	// wrap the base context with a deadline
-	ctx, cancel = context.WithDeadline(ctx, time.Now().Add(queryTimeout))
+	ctx, cancel := context.WithTimeout(ctx, queryTimeout)
 	defer cancel()
 
 	// instrument blockingQueries
 	// atomic inc our server's count of in-flight blockingQueries and store the new value
-	queriesBlocking = atomic.AddUint64(&s.queriesBlocking, 1)
+	queriesBlocking := atomic.AddUint64(&s.queriesBlocking, 1)
 	// atomic dec when we return from blockingQuery()
 	defer atomic.AddUint64(&s.queriesBlocking, ^uint64(0))
 	// set the gauge directly to the new value of s.blockingQueries
 	metrics.SetGauge([]string{"rpc", "queries_blocking"}, float32(queriesBlocking))
 
-RUN_QUERY:
-	// Setup blocking loop
-
-	// Validate
-	// If the read must be consistent we verify that we are still the leader.
-	if queryOpts.GetRequireConsistent() {
-		if err := s.consistentRead(); err != nil {
-			return err
+	for {
+		if queryOpts.GetRequireConsistent() {
+			if err := s.consistentRead(); err != nil {
+				return err
+			}
 		}
-	}
 
-	// Run query
-
-	// Operate on a consistent set of state. This makes sure that the
-	// abandon channel goes with the state that the caller is using to
-	// build watches.
-	state := s.fsm.State()
-
-	// We can skip all watch tracking if this isn't a blocking query.
-	var ws memdb.WatchSet
-	if minQueryIndex > 0 {
-		ws = memdb.NewWatchSet()
+		// Operate on a consistent set of state. This makes sure that the
+		// abandon channel goes with the state that the caller is using to
+		// build watches.
+		state := s.fsm.State()
 
+		ws := memdb.NewWatchSet()
 		// This channel will be closed if a snapshot is restored and the
 		// whole state store is abandoned.
 		ws.Add(state.AbandonCh())
-	}
 
-	// Execute the queryFn
-	err := fn(ws, state)
-
-	// Update the query metadata.
-	s.setQueryMeta(queryMeta, queryOpts.GetToken())
-
-	// Note we check queryOpts.MinQueryIndex is greater than zero to determine if
-	// blocking was requested by client, NOT meta.Index since the state function
-	// might return zero if something is not initialized and care wasn't taken to
-	// handle that special case (in practice this happened a lot so fixing it
-	// systematically here beats trying to remember to add zero checks in every
-	// state method). We also need to ensure that unless there is an error, we
-	// return an index > 0 otherwise the client will never block and burn CPU and
-	// requests.
-	if err == nil && queryMeta.GetIndex() < 1 {
-		queryMeta.SetIndex(1)
-	}
-	// block up to the timeout if we don't see anything fresh.
-	if err == nil && minQueryIndex > 0 && queryMeta.GetIndex() <= minQueryIndex {
+		err := fn(ws, state)
+		s.setQueryMeta(queryMeta, queryOpts.GetToken())
+		if err != nil {
+			return err
+		}
+
+		// Note we check queryOpts.MinQueryIndex is greater than zero to determine if
+		// blocking was requested by client, NOT meta.Index since the state function
+		// might return zero if something is not initialized and care wasn't taken to
+		// handle that special case (in practice this happened a lot so fixing it
+		// systematically here beats trying to remember to add zero checks in every
+		// state method). We also need to ensure that unless there is an error, we
+		// return an index > 0 otherwise the client will never block and burn CPU and
+		// requests.
+		if queryMeta.GetIndex() < 1 {
+			queryMeta.SetIndex(1)
+		}
+
+		if queryMeta.GetIndex() > minQueryIndex {
+			return nil
+		}
+
+		// block up to the timeout if we don't see anything fresh.
 		if err := ws.WatchCtx(ctx); err == nil {
 			// a non-nil error only occurs when the context is cancelled
 
@@ -1014,13 +1011,15 @@ RUN_QUERY:
 			// case.
 			select {
 			case <-state.AbandonCh():
+				return nil
 			default:
-				// loop back and look for an update again
-				goto RUN_QUERY
 			}
 		}
+
+		if ctx.Err() != nil {
+			return nil
+		}
 	}
-	return err
 }
 
 // setQueryMeta is used to populate the QueryMeta data for an RPC call

From 4b67d6c18b16b5f59bb1151509362564e38e348a Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Fri, 14 Jan 2022 18:53:31 -0500
Subject: [PATCH 15/98] rpc: add subtests to blockingQuery test

---
 agent/consul/rpc_test.go | 70 +++++++++++++++++-----------------------
 1 file changed, 29 insertions(+), 41 deletions(-)

diff --git a/agent/consul/rpc_test.go b/agent/consul/rpc_test.go
index bde9b4d9ea..0782cbadee 100644
--- a/agent/consul/rpc_test.go
+++ b/agent/consul/rpc_test.go
@@ -233,13 +233,10 @@ func TestRPC_blockingQuery(t *testing.T) {
 	defer os.RemoveAll(dir)
 	defer s.Shutdown()
 
-	require := require.New(t)
-	assert := assert.New(t)
-
 	// Perform a non-blocking query. Note that it's significant that the meta has
 	// a zero index in response - the implied opts.MinQueryIndex is also zero but
 	// this should not block still.
-	{
+	t.Run("non-blocking query", func(t *testing.T) {
 		var opts structs.QueryOptions
 		var meta structs.QueryMeta
 		var calls int
@@ -247,16 +244,13 @@ func TestRPC_blockingQuery(t *testing.T) {
 			calls++
 			return nil
 		}
-		if err := s.blockingQuery(&opts, &meta, fn); err != nil {
-			t.Fatalf("err: %v", err)
-		}
-		if calls != 1 {
-			t.Fatalf("bad: %d", calls)
-		}
-	}
+		err := s.blockingQuery(&opts, &meta, fn)
+		require.NoError(t, err)
+		require.Equal(t, 1, calls)
+	})
 
 	// Perform a blocking query that gets woken up and loops around once.
-	{
+	t.Run("blocking query - single loop", func(t *testing.T) {
 		opts := structs.QueryOptions{
 			MinQueryIndex: 3,
 		}
@@ -275,13 +269,10 @@ func TestRPC_blockingQuery(t *testing.T) {
 			calls++
 			return nil
 		}
-		if err := s.blockingQuery(&opts, &meta, fn); err != nil {
-			t.Fatalf("err: %v", err)
-		}
-		if calls != 2 {
-			t.Fatalf("bad: %d", calls)
-		}
-	}
+		err := s.blockingQuery(&opts, &meta, fn)
+		require.NoError(t, err)
+		require.Equal(t, 2, calls)
+	})
 
 	// Perform a blocking query that returns a zero index from blocking func (e.g.
 	// no state yet). This should still return an empty response immediately, but
@@ -292,7 +283,7 @@ func TestRPC_blockingQuery(t *testing.T) {
 	// covered by tests but eventually when hit in the wild causes blocking
 	// clients to busy loop and burn CPU. This test ensure that blockingQuery
 	// systematically does the right thing to prevent future bugs like that.
-	{
+	t.Run("blocking query with 0 modifyIndex from state func", func(t *testing.T) {
 		opts := structs.QueryOptions{
 			MinQueryIndex: 0,
 		}
@@ -311,9 +302,9 @@ func TestRPC_blockingQuery(t *testing.T) {
 			calls++
 			return nil
 		}
-		require.NoError(s.blockingQuery(&opts, &meta, fn))
-		assert.Equal(1, calls)
-		assert.Equal(uint64(1), meta.Index,
+		require.NoError(t, s.blockingQuery(&opts, &meta, fn))
+		assert.Equal(t, 1, calls)
+		assert.Equal(t, uint64(1), meta.Index,
 			"expect fake index of 1 to force client to block on next update")
 
 		// Simulate client making next request
@@ -322,19 +313,19 @@ func TestRPC_blockingQuery(t *testing.T) {
 
 		// This time we should block even though the func returns index 0 still
 		t0 := time.Now()
-		require.NoError(s.blockingQuery(&opts, &meta, fn))
+		require.NoError(t, s.blockingQuery(&opts, &meta, fn))
 		t1 := time.Now()
-		assert.Equal(2, calls)
-		assert.Equal(uint64(1), meta.Index,
+		assert.Equal(t, 2, calls)
+		assert.Equal(t, uint64(1), meta.Index,
 			"expect fake index of 1 to force client to block on next update")
-		assert.True(t1.Sub(t0) > 20*time.Millisecond,
+		assert.True(t, t1.Sub(t0) > 20*time.Millisecond,
 			"should have actually blocked waiting for timeout")
 
-	}
+	})
 
 	// Perform a query that blocks and gets interrupted when the state store
 	// is abandoned.
-	{
+	t.Run("blocking query interrupted by abandonCh", func(t *testing.T) {
 		opts := structs.QueryOptions{
 			MinQueryIndex: 3,
 		}
@@ -363,13 +354,10 @@ func TestRPC_blockingQuery(t *testing.T) {
 			calls++
 			return nil
 		}
-		if err := s.blockingQuery(&opts, &meta, fn); err != nil {
-			t.Fatalf("err: %v", err)
-		}
-		if calls != 1 {
-			t.Fatalf("bad: %d", calls)
-		}
-	}
+		err := s.blockingQuery(&opts, &meta, fn)
+		require.NoError(t, err)
+		require.Equal(t, 1, calls)
+	})
 
 	t.Run("ResultsFilteredByACLs is reset for unauthenticated calls", func(t *testing.T) {
 		opts := structs.QueryOptions{
@@ -382,13 +370,13 @@ func TestRPC_blockingQuery(t *testing.T) {
 		}
 
 		err := s.blockingQuery(&opts, &meta, fn)
-		require.NoError(err)
-		require.False(meta.ResultsFilteredByACLs, "ResultsFilteredByACLs should be reset for unauthenticated calls")
+		require.NoError(t, err)
+		require.False(t, meta.ResultsFilteredByACLs, "ResultsFilteredByACLs should be reset for unauthenticated calls")
 	})
 
 	t.Run("ResultsFilteredByACLs is honored for authenticated calls", func(t *testing.T) {
 		token, err := lib.GenerateUUID(nil)
-		require.NoError(err)
+		require.NoError(t, err)
 
 		opts := structs.QueryOptions{
 			Token: token,
@@ -400,8 +388,8 @@ func TestRPC_blockingQuery(t *testing.T) {
 		}
 
 		err = s.blockingQuery(&opts, &meta, fn)
-		require.NoError(err)
-		require.True(meta.ResultsFilteredByACLs, "ResultsFilteredByACLs should be honored for authenticated calls")
+		require.NoError(t, err)
+		require.True(t, meta.ResultsFilteredByACLs, "ResultsFilteredByACLs should be honored for authenticated calls")
 	})
 }
 

From fd0a9fd4f3af209dd4ae47c3d9c8a53e677e797e Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Mon, 17 Jan 2022 15:09:08 -0500
Subject: [PATCH 16/98] rpc: move the index defaulting to setQueryMeta.

This safeguard should be safe to apply in general. We are already
applying it to non-blocking queries that call blockingQuery, so it
should be fine to apply it to others.
---
 agent/consul/rpc.go               | 23 +++++++++++------------
 agent/consul/txn_endpoint_test.go |  1 +
 agent/structs/structs.go          |  4 +++-
 agent/txn_endpoint_test.go        |  6 ++++--
 4 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/agent/consul/rpc.go b/agent/consul/rpc.go
index ddf4299508..b536aad36b 100644
--- a/agent/consul/rpc.go
+++ b/agent/consul/rpc.go
@@ -984,18 +984,6 @@ func (s *Server) blockingQuery(queryOpts structs.QueryOptionsCompat, queryMeta s
 			return err
 		}
 
-		// Note we check queryOpts.MinQueryIndex is greater than zero to determine if
-		// blocking was requested by client, NOT meta.Index since the state function
-		// might return zero if something is not initialized and care wasn't taken to
-		// handle that special case (in practice this happened a lot so fixing it
-		// systematically here beats trying to remember to add zero checks in every
-		// state method). We also need to ensure that unless there is an error, we
-		// return an index > 0 otherwise the client will never block and burn CPU and
-		// requests.
-		if queryMeta.GetIndex() < 1 {
-			queryMeta.SetIndex(1)
-		}
-
 		if queryMeta.GetIndex() > minQueryIndex {
 			return nil
 		}
@@ -1034,6 +1022,17 @@ func (s *Server) setQueryMeta(m structs.QueryMetaCompat, token string) {
 		m.SetKnownLeader(s.raft.Leader() != "")
 	}
 	maskResultsFilteredByACLs(token, m)
+
+	// Always set a non-zero QueryMeta.Index. Generally we expect the
+	// QueryMeta.Index to be set to structs.RaftIndex.ModifyIndex. If the query
+	// returned no results we expect it to be set to the max index of the table,
+	// however we can't guarantee this always happens.
+	// To prevent a client from accidentally performing many non-blocking queries
+	// (which causes lots of unnecessary load), we always set a default value of 1.
+	// This is sufficient to prevent the unnecessary load in most cases.
+	if m.GetIndex() < 1 {
+		m.SetIndex(1)
+	}
 }
 
 // consistentRead is used to ensure we do not perform a stale
diff --git a/agent/consul/txn_endpoint_test.go b/agent/consul/txn_endpoint_test.go
index 9619dc8815..10178866a0 100644
--- a/agent/consul/txn_endpoint_test.go
+++ b/agent/consul/txn_endpoint_test.go
@@ -821,6 +821,7 @@ func TestTxn_Read(t *testing.T) {
 		},
 		QueryMeta: structs.QueryMeta{
 			KnownLeader: true,
+			Index:       1,
 		},
 	}
 	require.Equal(expected, out)
diff --git a/agent/structs/structs.go b/agent/structs/structs.go
index cb84f77d99..168c70efe1 100644
--- a/agent/structs/structs.go
+++ b/agent/structs/structs.go
@@ -370,7 +370,9 @@ func (q QueryBackend) String() string {
 // QueryMeta allows a query response to include potentially
 // useful metadata about a query
 type QueryMeta struct {
-	// Index in the raft log of the latest item returned by the query.
+	// Index in the raft log of the latest item returned by the query. If the
+	// query did not return any results the Index will be a value that will
+	// change when a new item is added.
 	Index uint64
 
 	// If AllowStale is used, this is time elapsed since
diff --git a/agent/txn_endpoint_test.go b/agent/txn_endpoint_test.go
index 1d6d3f01be..6b3a7c4680 100644
--- a/agent/txn_endpoint_test.go
+++ b/agent/txn_endpoint_test.go
@@ -10,11 +10,12 @@ import (
 	"testing"
 	"time"
 
+	"github.com/hashicorp/raft"
+	"github.com/stretchr/testify/assert"
+
 	"github.com/hashicorp/consul/agent/structs"
 	"github.com/hashicorp/consul/api"
 	"github.com/hashicorp/consul/testrpc"
-	"github.com/hashicorp/raft"
-	"github.com/stretchr/testify/assert"
 )
 
 func TestTxnEndpoint_Bad_JSON(t *testing.T) {
@@ -385,6 +386,7 @@ func TestTxnEndpoint_KV_Actions(t *testing.T) {
 				},
 				QueryMeta: structs.QueryMeta{
 					KnownLeader: true,
+					Index:       1,
 				},
 			}
 			assert.Equal(t, expected, txnResp)

From 72a733bed829e8fb03472c9efd36c9a5ffd3300a Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Mon, 17 Jan 2022 16:33:17 -0500
Subject: [PATCH 17/98] rpc: extract rpcQueryTimeout method

This helps keep the logic in blockingQuery more focused. In the future we
may have a separate struct for RPC queries which may allow us to move this
off of Server.
---
 agent/consul/rpc.go | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/agent/consul/rpc.go b/agent/consul/rpc.go
index b536aad36b..52168b4dbb 100644
--- a/agent/consul/rpc.go
+++ b/agent/consul/rpc.go
@@ -938,19 +938,8 @@ func (s *Server) blockingQuery(queryOpts structs.QueryOptionsCompat, queryMeta s
 		return err
 	}
 
-	queryTimeout := queryOpts.GetMaxQueryTime()
-	// Restrict the max query time, and ensure there is always one.
-	if queryTimeout > s.config.MaxQueryTime {
-		queryTimeout = s.config.MaxQueryTime
-	} else if queryTimeout <= 0 {
-		queryTimeout = s.config.DefaultQueryTime
-	}
-
-	// Apply a small amount of jitter to the request.
-	queryTimeout += lib.RandomStagger(queryTimeout / structs.JitterFraction)
-
-	// wrap the base context with a deadline
-	ctx, cancel := context.WithTimeout(ctx, queryTimeout)
+	timeout := s.rpcQueryTimeout(queryOpts.GetMaxQueryTime())
+	ctx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 
 	// instrument blockingQueries
@@ -1068,6 +1057,22 @@ func (s *Server) consistentRead() error {
 	return structs.ErrNotReadyForConsistentReads
 }
 
+// rpcQueryTimeout calculates the timeout for the query, ensures it is
+// constrained to the configured limit, and adds jitter to prevent multiple
+// blocking queries from all timing out at the same time.
+func (s *Server) rpcQueryTimeout(queryTimeout time.Duration) time.Duration {
+	// Restrict the max query time, and ensure there is always one.
+	if queryTimeout > s.config.MaxQueryTime {
+		queryTimeout = s.config.MaxQueryTime
+	} else if queryTimeout <= 0 {
+		queryTimeout = s.config.DefaultQueryTime
+	}
+
+	// Apply a small amount of jitter to the request.
+	queryTimeout += lib.RandomStagger(queryTimeout / structs.JitterFraction)
+	return queryTimeout
+}
+
 // maskResultsFilteredByACLs blanks out the ResultsFilteredByACLs flag if the
 // request is unauthenticated, to limit information leaking.
 //

From 71767f1b3ec02c6d17004f1a610209146d3a28b6 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Mon, 17 Jan 2022 16:43:56 -0500
Subject: [PATCH 18/98] rpc: cleanup exit and blocking condition logic in
 blockingQuery

Remove some unnecessary comments around query_blocking metric. The only
line that needs any comments in the atomic decrement.

Cleanup the block and return comments and logic. The old comment about
AbandonCh may have been relevant before, but it is expected behaviour
now.

The logic was simplified by inverting the err condition.
---
 agent/consul/rpc.go | 32 +++++++++++---------------------
 1 file changed, 11 insertions(+), 21 deletions(-)

diff --git a/agent/consul/rpc.go b/agent/consul/rpc.go
index 52168b4dbb..6a50781708 100644
--- a/agent/consul/rpc.go
+++ b/agent/consul/rpc.go
@@ -942,13 +942,10 @@ func (s *Server) blockingQuery(queryOpts structs.QueryOptionsCompat, queryMeta s
 	ctx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 
-	// instrument blockingQueries
-	// atomic inc our server's count of in-flight blockingQueries and store the new value
-	queriesBlocking := atomic.AddUint64(&s.queriesBlocking, 1)
-	// atomic dec when we return from blockingQuery()
+	count := atomic.AddUint64(&s.queriesBlocking, 1)
+	metrics.SetGauge([]string{"rpc", "queries_blocking"}, float32(count))
+	// decrement the count when the function returns.
 	defer atomic.AddUint64(&s.queriesBlocking, ^uint64(0))
-	// set the gauge directly to the new value of s.blockingQueries
-	metrics.SetGauge([]string{"rpc", "queries_blocking"}, float32(queriesBlocking))
 
 	for {
 		if queryOpts.GetRequireConsistent() {
@@ -977,24 +974,17 @@ func (s *Server) blockingQuery(queryOpts structs.QueryOptionsCompat, queryMeta s
 			return nil
 		}
 
-		// block up to the timeout if we don't see anything fresh.
-		if err := ws.WatchCtx(ctx); err == nil {
-			// a non-nil error only occurs when the context is cancelled
-
-			// If a restore may have woken us up then bail out from
-			// the query immediately. This is slightly race-ey since
-			// this might have been interrupted for other reasons,
-			// but it's OK to kick it back to the caller in either
-			// case.
-			select {
-			case <-state.AbandonCh():
-				return nil
-			default:
-			}
+		// block until something changes, or the timeout
+		if err := ws.WatchCtx(ctx); err != nil {
+			// exit if we've reached the timeout, or other cancellation
+			return nil
 		}
 
-		if ctx.Err() != nil {
+		// exit if the state store has been abandoned
+		select {
+		case <-state.AbandonCh():
 			return nil
+		default:
 		}
 	}
 }

From 203c5033c32c70fd8fa4e0f202c637847cbfe90c Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Tue, 18 Jan 2022 12:23:17 -0800
Subject: [PATCH 19/98] addressed feedback about binary

---
 website/content/docs/api-gateway.mdx | 53 +++++++++++++++++++---------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index ec00cda18b..0ee9ffa84d 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -17,23 +17,27 @@ Consul API Gateway is an implementation of the Kubernetes Gateway [API Specifica
 Your datacenter must meet the following requirements prior to configuring the Consul API Gateway:
 
 - A Kubernetes cluster must be running
-- Consul 1.11.1+
+- Consul 1.11.2+
 
 ## Installation
 
 1. Create a values file for your Consul server agents that contains the following parameters:
 
-   ```yaml
-   global:
-     name: consul
-     image: 'hashicorp/consul:1.11.1'
-     tls:
-       enabled: true
-   connectInject:
-     enabled: true
-   controller:
-     enabled: true
-   ```
+  <CodeBlockConfig hideClipboard filename="values.yaml">
+
+```yaml
+global:
+  name: consul
+  image: 'hashicorp/consul:1.11.2'
+  tls:
+    enabled: true
+connectInject:
+  enabled: true
+controller:
+  enabled: true
+```
+
+   </CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
@@ -46,8 +50,8 @@ The following components will be installed: - Gateway controller - CRDs required
 1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster.
 
 ```shell-session
-$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-techpreview"
-$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-techpreview"
+$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
+$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
 ```
 
 ## Usage
@@ -63,7 +67,22 @@ $ kubectl apply -f gateway-configuration.yaml
 
 ### Using the Consul API Gateway Binary
 
-You can manually start the Consul API Gateway control plane server using the binary located in the home directory to issue the `server` command:
+You can download the Consul API Gateway binary and use it to manually start the control plane server.
+
+1. Download the binary from the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway).
+1. Navigate to the `consul-api-gateway-main` directory and build the binary:
+
+```shell-session
+$ go build
+```
+
+1.  (Optional) Copy the binary to the execution path, e.g.:
+
+```shell-session
+$ cp consul-api-gateway /usr/bin
+```
+
+1.  Use the `server` command to interact with the Consul API Gateway binary:
 
 ```shell-session
 $ ./consul-api-gateway server <options>
@@ -89,7 +108,7 @@ You can also issue the `version` command to print the Consul API Gateway version
 
 ```shell-session
 $ ./consul-api-gateway version
-consul-api-gateway 0.1.0-dev
+consul-api-gateway 0.1.0
 ```
 
 ## Configuration
@@ -151,7 +170,7 @@ In the example included the [Gateway](#gateway) description, a listener named `h
 
 ### Route
 
-Routes are independent configuration objects that are associated with a specific listener.
+Routes are independent configuration objects that are associated with specific listeners.
 Use the `kind: HTTPRoute` option to declare a route and use the `spec` option to specify the route details.
 The following example creates a route named `example-route` associated with a listener defined in `example-gateway`.
 

From 6cda05a6df93176036405103a7f09f5b47864c72 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Tue, 18 Jan 2022 12:28:44 -0800
Subject: [PATCH 20/98] addressed feedback about binary - fixed bad formatting

---
 website/content/docs/api-gateway.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 0ee9ffa84d..1ce7f49813 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -37,7 +37,7 @@ controller:
   enabled: true
 ```
 
-   </CodeBlockConfig>
+  </CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 

From fe867ddf9c6d1f6cc12fd3a33c9dd9f447e23cae Mon Sep 17 00:00:00 2001
From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Date: Tue, 18 Jan 2022 14:30:35 -0800
Subject: [PATCH 21/98] Apply suggestions from code review

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
---
 website/content/docs/api-gateway.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 1ce7f49813..5a5b4f1a21 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -50,8 +50,8 @@ The following components will be installed: - Gateway controller - CRDs required
 1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster.
 
 ```shell-session
-$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
-$ kubectl apply -k "github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
+$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
+$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
 ```
 
 ## Usage

From 30032f434e89646e35756f942d8f625c7ae2c735 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Tue, 18 Jan 2022 15:06:55 -0800
Subject: [PATCH 22/98] fixed formatting

---
 website/content/docs/api-gateway.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 5a5b4f1a21..3327e80046 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -42,7 +42,7 @@ controller:
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
 ```shell-session
-$ helm install consul hashicorp/consul --version 0.39.0 -f values.yaml
+$ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
 ```
 
 The following components will be installed: - Gateway controller - CRDs required by the Kubernetes Gateway API specification - `kustomize` manifests for completing the installation
@@ -62,7 +62,7 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
 ```shell-session
-$ kubectl apply -f gateway-configuration.yaml
+$ kubectl apply --values gateway-configuration.yaml
 ```
 
 ### Using the Consul API Gateway Binary
@@ -152,7 +152,7 @@ spec:
 </CodeBlockConfig>
 
 Refer to the Kubernetes Gateway API documentation for details about configuring gateways:
-https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway
+<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway>
 
 ### Listeners
 
@@ -164,7 +164,7 @@ Add the `listener` object to the `gateway` configuration and specify the followi
 - `protocol`: Specifies the network protocol expected by the listener.
 
 Refer to the Kubernetes Gateway API documentation for details about configuring listeners:
-https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener
+<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener>
 
 In the example included the [Gateway](#gateway) description, a listener named `https` that listens over `HTTPS` is configured to listen on port `443`
 

From a4fe5362edff8d225c6c2752a7da86103587c5a3 Mon Sep 17 00:00:00 2001
From: Michele Degges <mdeggies@gmail.com>
Date: Fri, 21 Jan 2022 13:43:21 -0800
Subject: [PATCH 23/98] Add missing consul.env file for linux packaging

---
 .release/linux/package/etc/consul.d/consul.env | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 .release/linux/package/etc/consul.d/consul.env

diff --git a/.release/linux/package/etc/consul.d/consul.env b/.release/linux/package/etc/consul.d/consul.env
new file mode 100644
index 0000000000..e69de29bb2

From 8c2399a862aa75b025aa0e5788ac507e13d8aa08 Mon Sep 17 00:00:00 2001
From: Peter M <36747421+pcmccarron@users.noreply.github.com>
Date: Fri, 21 Jan 2022 16:14:45 -0700
Subject: [PATCH 24/98] Updated intro text

Jeff and I re-worded/expanded the text a bit here for the introduction section.
---
 website/content/docs/api-gateway.mdx | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 3327e80046..d2d44d4656 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -3,14 +3,16 @@ layout: docs
 page_title: API Gateway
 description: Using Consul API gateway functionality
 ---
-
 # Consul API Gateway
 
-This topic describes how to use the Consul API Gateway module, which enables applications and services running in a datacenter to be accessed by network clients outside the datacenter. This type of network traffic is commonly referred to as "north-south" network traffic.
+The Consul API Gateway add-on module helps users control access to services running within a Consul service mesh. Using the API Gateway, applications and services running in a Consul datacenter can be accessed by network clients residing outside of the datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol. 
 
 ## Introduction
 
-Consul API Gateway is an implementation of the Kubernetes Gateway [API Specification](https://gateway-api.sigs.k8s.io/). The specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes.
+Consul API Gateway is an implementation of the Kubernetes Gateway [API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. The Consul API gateway solves for two primary use cases:
+
+* **Controlling access at the point entry** - The Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g. VeriSign, Let’sEncrypt). 
+* **Simplifying traffic management** - The Consul API Gateway can be used to load balance requests across services and route traffic to the appropriate service based on matching one or more criteria such as hostname, path, header presence or value, and HTTP Method type (e.g. Get, Post, Patch).
 
 ## Requirements
 

From 65d750a84d0702d0ae8c07fc183eab511455ae8e Mon Sep 17 00:00:00 2001
From: Krastin Krastev <krastin@hashicorp.com>
Date: Mon, 24 Jan 2022 16:10:03 +0100
Subject: [PATCH 25/98] migrating <Tabs> to <CodeTabs> in
 /docs/connect/observability/ui-visualization

---
 .../observability/ui-visualization.mdx        | 80 ++++++++-----------
 1 file changed, 33 insertions(+), 47 deletions(-)

diff --git a/website/content/docs/connect/observability/ui-visualization.mdx b/website/content/docs/connect/observability/ui-visualization.mdx
index 9a9056ff07..63768ff6b8 100644
--- a/website/content/docs/connect/observability/ui-visualization.mdx
+++ b/website/content/docs/connect/observability/ui-visualization.mdx
@@ -66,8 +66,7 @@ service named `prometheus-server` so each Consul agent can reach it on
 
 A full configuration to enable Prometheus is given below.
 
-<Tabs>
-<Tab heading="HCL">
+<CodeTabs>
 
 ```hcl
 ui_config {
@@ -79,9 +78,6 @@ ui_config {
 }
 ```
 
-</Tab>
-<Tab heading="JSON">
-
 ```json
 {
   "ui_config": [
@@ -98,8 +94,7 @@ ui_config {
 }
 ```
 
-</Tab>
-</Tabs>
+</CodeTabs>
 
 Similarly, to configure the UI on Kubernetes, use this [reference](/docs/k8s/connect/observability/metrics).
 
@@ -120,27 +115,22 @@ to the relevant information.
 
 An example with Grafana is shown below.
 
-<Tabs>
-<Tab heading="HCL">
+<CodeTabs tabs={[ "HCL", "JSON", "YAML (Kubernetes)" ]}>
+
+<CodeBlockConfig>
 
 ```hcl
 ui_config {
   enabled = true
   dashboard_url_templates {
-    service = "https://grafana.example.com/d/lDlaj-NGz/
-      service-overview?orgId=1&var-service={{Service.Name}}&
-      var-namespace={{Service.Namespace}}&
-      var-partition={{Service.Partition}}&var-dc={{Datacenter}}"
+    service = "https://grafana.example.com/d/lDlaj-NGz/service-overview?orgId=1&var-service={{Service.Name}}&var-namespace={{Service.Namespace}}&var-partition={{Service.Partition}}&var-dc={{Datacenter}}"
   }
 }
 ```
 
--> **Note**: the URL is wrapped over multiple lines to make it easier to read
-without horizontal scrolling in the example above however this needs to be a
-normal single-line string value in an HCL configuration file.
+</CodeBlockConfig>
 
-</Tab>
-<Tab heading="JSON">
+<CodeBlockConfig>
 
 ```json
 {
@@ -148,10 +138,7 @@ normal single-line string value in an HCL configuration file.
     {
       "dashboard_url_templates": [
         {
-          "service": "https://grafana.example.com/d/lDlaj-NGz/
-            service-overview?orgId=1\u0026var-service={{Service.Name}}\u0026
-            var-namespace={{Service.Namespace}}\u0026
-            var-partition={{Service.Partition}}\u0026var-dc={{Datacenter}}"
+          "service": "https://grafana.example.com/d/lDlaj-NGz/service-overview?orgId=1\u0026var-service={{Service.Name}}\u0026var-namespace={{Service.Namespace}}\u0026var-partition={{Service.Partition}}\u0026var-dc={{Datacenter}}"
         }
       ],
       "enabled": true
@@ -160,17 +147,19 @@ normal single-line string value in an HCL configuration file.
 }
 ```
 
--> **Note**: the URL is wrapped over multiple lines to make it easier to read
-without horizontal scrolling in the example above however this needs to be a
-normal single-line string value in a JSON configuration file.
-
-</Tab>
-<Tab heading="Kubernetes YAML">
+</CodeBlockConfig>
 
-On Kubernetes, Consul Server configuration is set in your Helm config via the
-[`server.extraConfig`](/docs/k8s/helm#v-server-extraconfig) key as JSON:
+<CodeBlockConfig>
 
 ```yaml
+################################### Notes: ####################################
+# On Kubernetes, Consul Server configuration is set in your Helm config via   #
+# the server.extraConfig key as JSON.                                         #
+#                                                                             #
+# The `{{` characters in the URL must be escaped using `{{ "{{" }}` so that   #
+# Helm doesn't try to template them.                                          #
+###############################################################################
+
 # The UI is enabled by default so this stanza is not required.
 ui:
   enabled: true
@@ -185,10 +174,9 @@ server:
     }
 ```
 
--> **Note**: The `{{` characters in the URL must be escaped using `{{ "{{" }}` so that Helm doesn't try to template them.
+</CodeBlockConfig>
 
-</Tab>
-</Tabs>
+</CodeTabs>
 
 ![Consul UI Service Dashboard Link](/img/ui-dashboard-url-template.png)
 
@@ -221,6 +209,8 @@ un-authenticated workloads on the network**.
 With ACLs enabled, the proxy endpoint requires a valid token with read access
 to all nodes and services (across all namespaces in Enterprise):
 
+<CodeTabs>
+
 ```hcl
 # Consul OSS
 service_prefix "" {
@@ -241,6 +231,8 @@ namespace_prefix "" {
 }
 ```
 
+</CodeTabs>
+
 It's typical for most authenticated users to have this level of access in Consul
 as it's required for viewing the catalog or discovering services. If you use a
 [Single Sign-On integration](/docs/security/acl/auth-methods/oidc) (Consul
@@ -285,8 +277,7 @@ visible to Consul operators in the configuration file while UI users can query
 the metrics they need without separately obtaining a token for that provider or
 having a token exposed to them that they might be able to use elsewhere.
 
-<Tabs>
-<Tab heading="HCL">
+<CodeTabs>
 
 ```hcl
 ui_config {
@@ -304,9 +295,6 @@ ui_config {
 }
 ```
 
-</Tab>
-<Tab heading="JSON">
-
 ```json
 {
   "ui_config": [
@@ -329,8 +317,7 @@ ui_config {
 }
 ```
 
-</Tab>
-</Tabs>
+</CodeTabs>
 
 ## Custom Metrics Providers
 
@@ -347,6 +334,8 @@ feedback on [GitHub](https://github.com/hashicorp/consul) or
 
 The template for a complete provider JavaScript file is given below.
 
+<CodeTabs>
+
 ```JavaScript
 (function () {
   var provider = {
@@ -553,6 +542,8 @@ The template for a complete provider JavaScript file is given below.
 }());
 ```
 
+</CodeTabs>
+
 Additionally, the built in [Prometheus
 provider code](https://github.com/hashicorp/consul/blob/main/ui/packages/consul-ui/vendor/metrics-providers/prometheus.js)
 can be used as a reference.
@@ -565,8 +556,7 @@ named `example-provider`, which is defined in
 have been specified in the call to `consul.registerMetricsProvider` as in the
 code listing in the last section.
 
-<Tabs>
-<Tab heading="HCL">
+<CodeTabs>
 
 ```hcl
 ui_config {
@@ -581,9 +571,6 @@ ui_config {
 }
 ```
 
-</Tab>
-<Tab heading="JSON">
-
 ```json
 {
   "ui_config": {
@@ -595,8 +582,7 @@ ui_config {
 }
 ```
 
-</Tab>
-</Tabs>
+</CodeTabs>
 
 More than one JavaScript file may be specified in
 [`metrics_provider_files`](/docs/agent/options#ui_config_metrics_provider_files)

From 6765c0d9656d5fb3da4b97aa3ea3c12a268b58c9 Mon Sep 17 00:00:00 2001
From: Dao Thanh Tung <ttdao.2015@accountancy.smu.edu.sg>
Date: Mon, 24 Jan 2022 23:23:08 +0800
Subject: [PATCH 26/98] Add api changes to agent endpoint for part 2 (#12150)

---
 api/acl.go             | 34 +++++++++++++++++-----------------
 api/catalog.go         | 11 ++++++-----
 api/config_entry.go    |  7 ++++---
 api/coordinate.go      |  3 ++-
 api/discovery_chain.go |  3 ++-
 5 files changed, 31 insertions(+), 27 deletions(-)

diff --git a/api/acl.go b/api/acl.go
index 0f44494dda..c3038e3898 100644
--- a/api/acl.go
+++ b/api/acl.go
@@ -552,7 +552,7 @@ func (a *ACL) Update(acl *ACLEntry, q *WriteOptions) (*WriteMeta, error) {
 //
 // Deprecated: Use TokenDelete instead.
 func (a *ACL) Destroy(id string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("PUT", "/v1/acl/destroy/"+id)
+	r := a.c.newRequest("PUT", "/v1/acl/destroy/"+url.PathEscape(id))
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -571,7 +571,7 @@ func (a *ACL) Destroy(id string, q *WriteOptions) (*WriteMeta, error) {
 //
 // Deprecated: Use TokenClone instead.
 func (a *ACL) Clone(id string, q *WriteOptions) (string, *WriteMeta, error) {
-	r := a.c.newRequest("PUT", "/v1/acl/clone/"+id)
+	r := a.c.newRequest("PUT", "/v1/acl/clone/"+url.PathEscape(id))
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -594,7 +594,7 @@ func (a *ACL) Clone(id string, q *WriteOptions) (string, *WriteMeta, error) {
 //
 // Deprecated: Use TokenRead instead.
 func (a *ACL) Info(id string, q *QueryOptions) (*ACLEntry, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/info/"+id)
+	r := a.c.newRequest("GET", "/v1/acl/info/"+url.PathEscape(id))
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -696,7 +696,7 @@ func (a *ACL) TokenUpdate(token *ACLToken, q *WriteOptions) (*ACLToken, *WriteMe
 	if token.AccessorID == "" {
 		return nil, nil, fmt.Errorf("Must specify an AccessorID for Token Updating")
 	}
-	r := a.c.newRequest("PUT", "/v1/acl/token/"+token.AccessorID)
+	r := a.c.newRequest("PUT", "/v1/acl/token/"+url.PathEscape(token.AccessorID))
 	r.setWriteOptions(q)
 	r.obj = token
 	rtt, resp, err := a.c.doRequest(r)
@@ -725,7 +725,7 @@ func (a *ACL) TokenClone(tokenID string, description string, q *WriteOptions) (*
 		return nil, nil, fmt.Errorf("Must specify a tokenID for Token Cloning")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/token/"+tokenID+"/clone")
+	r := a.c.newRequest("PUT", "/v1/acl/token/"+url.PathEscape(tokenID)+"/clone")
 	r.setWriteOptions(q)
 	r.obj = struct{ Description string }{description}
 	rtt, resp, err := a.c.doRequest(r)
@@ -748,7 +748,7 @@ func (a *ACL) TokenClone(tokenID string, description string, q *WriteOptions) (*
 // TokenDelete removes a single ACL token. The tokenID parameter must be a valid
 // Accessor ID of an existing token.
 func (a *ACL) TokenDelete(tokenID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/token/"+tokenID)
+	r := a.c.newRequest("DELETE", "/v1/acl/token/"+url.PathEscape(tokenID))
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -766,7 +766,7 @@ func (a *ACL) TokenDelete(tokenID string, q *WriteOptions) (*WriteMeta, error) {
 // TokenRead retrieves the full token details. The tokenID parameter must be a valid
 // Accessor ID of an existing token.
 func (a *ACL) TokenRead(tokenID string, q *QueryOptions) (*ACLToken, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/token/"+tokenID)
+	r := a.c.newRequest("GET", "/v1/acl/token/"+url.PathEscape(tokenID))
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -871,7 +871,7 @@ func (a *ACL) PolicyUpdate(policy *ACLPolicy, q *WriteOptions) (*ACLPolicy, *Wri
 		return nil, nil, fmt.Errorf("Must specify an ID in Policy Update")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/policy/"+policy.ID)
+	r := a.c.newRequest("PUT", "/v1/acl/policy/"+url.PathEscape(policy.ID))
 	r.setWriteOptions(q)
 	r.obj = policy
 	rtt, resp, err := a.c.doRequest(r)
@@ -893,7 +893,7 @@ func (a *ACL) PolicyUpdate(policy *ACLPolicy, q *WriteOptions) (*ACLPolicy, *Wri
 
 // PolicyDelete deletes a policy given its ID.
 func (a *ACL) PolicyDelete(policyID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/policy/"+policyID)
+	r := a.c.newRequest("DELETE", "/v1/acl/policy/"+url.PathEscape(policyID))
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -910,7 +910,7 @@ func (a *ACL) PolicyDelete(policyID string, q *WriteOptions) (*WriteMeta, error)
 
 // PolicyRead retrieves the policy details including the rule set.
 func (a *ACL) PolicyRead(policyID string, q *QueryOptions) (*ACLPolicy, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/policy/"+policyID)
+	r := a.c.newRequest("GET", "/v1/acl/policy/"+url.PathEscape(policyID))
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1021,7 +1021,7 @@ func (a *ACL) RulesTranslate(rules io.Reader) (string, error) {
 // Deprecated: Support for the legacy syntax translation will be removed
 // when legacy ACL support is removed.
 func (a *ACL) RulesTranslateToken(tokenID string) (string, error) {
-	r := a.c.newRequest("GET", "/v1/acl/rules/translate/"+tokenID)
+	r := a.c.newRequest("GET", "/v1/acl/rules/translate/"+url.PathEscape(tokenID))
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
 		return "", err
@@ -1076,7 +1076,7 @@ func (a *ACL) RoleUpdate(role *ACLRole, q *WriteOptions) (*ACLRole, *WriteMeta,
 		return nil, nil, fmt.Errorf("Must specify an ID in Role Update")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/role/"+role.ID)
+	r := a.c.newRequest("PUT", "/v1/acl/role/"+url.PathEscape(role.ID))
 	r.setWriteOptions(q)
 	r.obj = role
 	rtt, resp, err := a.c.doRequest(r)
@@ -1098,7 +1098,7 @@ func (a *ACL) RoleUpdate(role *ACLRole, q *WriteOptions) (*ACLRole, *WriteMeta,
 
 // RoleDelete deletes a role given its ID.
 func (a *ACL) RoleDelete(roleID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/role/"+roleID)
+	r := a.c.newRequest("DELETE", "/v1/acl/role/"+url.PathEscape(roleID))
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1115,7 +1115,7 @@ func (a *ACL) RoleDelete(roleID string, q *WriteOptions) (*WriteMeta, error) {
 
 // RoleRead retrieves the role details (by ID). Returns nil if not found.
 func (a *ACL) RoleRead(roleID string, q *QueryOptions) (*ACLRole, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/role/"+roleID)
+	r := a.c.newRequest("GET", "/v1/acl/role/"+url.PathEscape(roleID))
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1365,7 +1365,7 @@ func (a *ACL) BindingRuleUpdate(rule *ACLBindingRule, q *WriteOptions) (*ACLBind
 		return nil, nil, fmt.Errorf("Must specify an ID in Binding Rule Update")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/binding-rule/"+rule.ID)
+	r := a.c.newRequest("PUT", "/v1/acl/binding-rule/"+url.PathEscape(rule.ID))
 	r.setWriteOptions(q)
 	r.obj = rule
 	rtt, resp, err := a.c.doRequest(r)
@@ -1387,7 +1387,7 @@ func (a *ACL) BindingRuleUpdate(rule *ACLBindingRule, q *WriteOptions) (*ACLBind
 
 // BindingRuleDelete deletes a binding rule given its ID.
 func (a *ACL) BindingRuleDelete(bindingRuleID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/binding-rule/"+bindingRuleID)
+	r := a.c.newRequest("DELETE", "/v1/acl/binding-rule/"+url.PathEscape(bindingRuleID))
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1404,7 +1404,7 @@ func (a *ACL) BindingRuleDelete(bindingRuleID string, q *WriteOptions) (*WriteMe
 
 // BindingRuleRead retrieves the binding rule details. Returns nil if not found.
 func (a *ACL) BindingRuleRead(bindingRuleID string, q *QueryOptions) (*ACLBindingRule, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/binding-rule/"+bindingRuleID)
+	r := a.c.newRequest("GET", "/v1/acl/binding-rule/"+url.PathEscape(bindingRuleID))
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
diff --git a/api/catalog.go b/api/catalog.go
index 80ae325eac..54fcce85f4 100644
--- a/api/catalog.go
+++ b/api/catalog.go
@@ -2,6 +2,7 @@ package api
 
 import (
 	"net"
+	"net/url"
 	"strconv"
 )
 
@@ -254,9 +255,9 @@ func (c *Catalog) ConnectMultipleTags(service string, tags []string, q *QueryOpt
 }
 
 func (c *Catalog) service(service string, tags []string, q *QueryOptions, connect bool) ([]*CatalogService, *QueryMeta, error) {
-	path := "/v1/catalog/service/" + service
+	path := "/v1/catalog/service/" + url.PathEscape(service)
 	if connect {
-		path = "/v1/catalog/connect/" + service
+		path = "/v1/catalog/connect/" + url.PathEscape(service)
 	}
 	r := c.c.newRequest("GET", path)
 	r.setQueryOptions(q)
@@ -287,7 +288,7 @@ func (c *Catalog) service(service string, tags []string, q *QueryOptions, connec
 
 // Node is used to query for service information about a single node
 func (c *Catalog) Node(node string, q *QueryOptions) (*CatalogNode, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/catalog/node/"+node)
+	r := c.c.newRequest("GET", "/v1/catalog/node/"+url.PathEscape(node))
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
@@ -314,7 +315,7 @@ func (c *Catalog) Node(node string, q *QueryOptions) (*CatalogNode, *QueryMeta,
 // a map of service ids to services. This different structure allows for using the wildcard specifier
 // '*' for the Namespace in the QueryOptions.
 func (c *Catalog) NodeServiceList(node string, q *QueryOptions) (*CatalogNodeServiceList, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/catalog/node-services/"+node)
+	r := c.c.newRequest("GET", "/v1/catalog/node-services/"+url.PathEscape(node))
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
@@ -338,7 +339,7 @@ func (c *Catalog) NodeServiceList(node string, q *QueryOptions) (*CatalogNodeSer
 
 // GatewayServices is used to query the services associated with an ingress gateway or terminating gateway.
 func (c *Catalog) GatewayServices(gateway string, q *QueryOptions) ([]*GatewayService, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/catalog/gateway-services/"+gateway)
+	r := c.c.newRequest("GET", "/v1/catalog/gateway-services/"+url.PathEscape(gateway))
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
diff --git a/api/config_entry.go b/api/config_entry.go
index 91c407bb53..f1c4091d10 100644
--- a/api/config_entry.go
+++ b/api/config_entry.go
@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"net/url"
 	"strconv"
 	"strings"
 	"time"
@@ -378,7 +379,7 @@ func (conf *ConfigEntries) Get(kind string, name string, q *QueryOptions) (Confi
 		return nil, nil, err
 	}
 
-	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s/%s", kind, name))
+	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s/%s", url.PathEscape(kind), url.PathEscape(name)))
 	r.setQueryOptions(q)
 	rtt, resp, err := conf.c.doRequest(r)
 	if err != nil {
@@ -405,7 +406,7 @@ func (conf *ConfigEntries) List(kind string, q *QueryOptions) ([]ConfigEntry, *Q
 		return nil, nil, fmt.Errorf("The kind parameter must not be empty")
 	}
 
-	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s", kind))
+	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s", url.PathEscape(kind)))
 	r.setQueryOptions(q)
 	rtt, resp, err := conf.c.doRequest(r)
 	if err != nil {
@@ -485,7 +486,7 @@ func (conf *ConfigEntries) delete(kind, name string, params map[string]string, w
 		return false, nil, fmt.Errorf("Both kind and name parameters must not be empty")
 	}
 
-	r := conf.c.newRequest("DELETE", fmt.Sprintf("/v1/config/%s/%s", kind, name))
+	r := conf.c.newRequest("DELETE", fmt.Sprintf("/v1/config/%s/%s", url.PathEscape(kind), url.PathEscape(name)))
 	r.setWriteOptions(w)
 	for param, value := range params {
 		r.params.Set(param, value)
diff --git a/api/coordinate.go b/api/coordinate.go
index 7ef6ce2744..bd607e32fd 100644
--- a/api/coordinate.go
+++ b/api/coordinate.go
@@ -2,6 +2,7 @@ package api
 
 import (
 	"github.com/hashicorp/serf/coordinate"
+	"net/url"
 )
 
 // CoordinateEntry represents a node and its associated network coordinate.
@@ -96,7 +97,7 @@ func (c *Coordinate) Update(coord *CoordinateEntry, q *WriteOptions) (*WriteMeta
 
 // Node is used to return the coordinates of a single node in the LAN pool.
 func (c *Coordinate) Node(node string, q *QueryOptions) ([]*CoordinateEntry, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/coordinate/node/"+node)
+	r := c.c.newRequest("GET", "/v1/coordinate/node/"+url.PathEscape(node))
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
diff --git a/api/discovery_chain.go b/api/discovery_chain.go
index 29bda85912..10150f5de8 100644
--- a/api/discovery_chain.go
+++ b/api/discovery_chain.go
@@ -3,6 +3,7 @@ package api
 import (
 	"encoding/json"
 	"fmt"
+	"net/url"
 	"time"
 )
 
@@ -26,7 +27,7 @@ func (d *DiscoveryChain) Get(name string, opts *DiscoveryChainOptions, q *QueryO
 		method = "POST"
 	}
 
-	r := d.c.newRequest(method, fmt.Sprintf("/v1/discovery-chain/%s", name))
+	r := d.c.newRequest(method, fmt.Sprintf("/v1/discovery-chain/%s", url.PathEscape(name)))
 	r.setQueryOptions(q)
 
 	if opts != nil {

From 8abf4088c12b3041bdb07ee4e3ba56a4f30257c1 Mon Sep 17 00:00:00 2001
From: Krastin Krastev <krastin@hashicorp.com>
Date: Mon, 24 Jan 2022 16:35:18 +0100
Subject: [PATCH 27/98] fixing K8s notes placement in
 /docs/connect/observability/ui-visualization

---
 .../docs/connect/observability/ui-visualization.mdx | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/website/content/docs/connect/observability/ui-visualization.mdx b/website/content/docs/connect/observability/ui-visualization.mdx
index 63768ff6b8..4c222e010d 100644
--- a/website/content/docs/connect/observability/ui-visualization.mdx
+++ b/website/content/docs/connect/observability/ui-visualization.mdx
@@ -152,14 +152,6 @@ ui_config {
 <CodeBlockConfig>
 
 ```yaml
-################################### Notes: ####################################
-# On Kubernetes, Consul Server configuration is set in your Helm config via   #
-# the server.extraConfig key as JSON.                                         #
-#                                                                             #
-# The `{{` characters in the URL must be escaped using `{{ "{{" }}` so that   #
-# Helm doesn't try to template them.                                          #
-###############################################################################
-
 # The UI is enabled by default so this stanza is not required.
 ui:
   enabled: true
@@ -178,6 +170,11 @@ server:
 
 </CodeTabs>
 
+~> **Note**: On Kubernetes, Consul Server configuration is set in your Helm
+config via the [`server.extraConfig`](/docs/k8s/helm#v-server-extraconfig) key as JSON.
+The `{{` characters in the URL must be escaped using `{{ "{{" }}` so that Helm
+doesn't try to template them.
+
 ![Consul UI Service Dashboard Link](/img/ui-dashboard-url-template.png)
 
 ### Metrics Proxy

From 0e37b283236c2b544a0c2f242826d84e81725710 Mon Sep 17 00:00:00 2001
From: Michele Degges <mdeggies@gmail.com>
Date: Mon, 24 Jan 2022 07:43:20 -0800
Subject: [PATCH 28/98] Add missing consul.env file for linux packaging
 (#12159)

---
 .release/linux/package/etc/consul.d/consul.env | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 .release/linux/package/etc/consul.d/consul.env

diff --git a/.release/linux/package/etc/consul.d/consul.env b/.release/linux/package/etc/consul.d/consul.env
new file mode 100644
index 0000000000..e69de29bb2

From 6689425bec1839e69222dcfc9efb85512eb185f5 Mon Sep 17 00:00:00 2001
From: David Yu <dyu@hashicorp.com>
Date: Mon, 24 Jan 2022 09:04:02 -0800
Subject: [PATCH 29/98] docs: Admin Partitions K8s requirement update (#12173)

* docs: Admin Partitions K8s requirement update

* Update admin-partitions.mdx

* Update website/content/docs/enterprise/admin-partitions.mdx

Co-authored-by: mrspanishviking <kcardenas@hashicorp.com>

* extra space

Co-authored-by: mrspanishviking <kcardenas@hashicorp.com>
---
 website/content/docs/enterprise/admin-partitions.mdx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/enterprise/admin-partitions.mdx b/website/content/docs/enterprise/admin-partitions.mdx
index f55742e40f..d8f53bbb6b 100644
--- a/website/content/docs/enterprise/admin-partitions.mdx
+++ b/website/content/docs/enterprise/admin-partitions.mdx
@@ -82,7 +82,8 @@ Your Consul configuration must meet the following requirements to use admin part
 
 One of the primary use cases for admin partitions is for enabling a service mesh across multiple Kubernetes clusters. The following requirements must be met to create admin partitions on Kubernetes:
 
-* Two or more Kubernetes clusters. Consul servers must be deployed to a single cluster. The other clusters should run Consul clients.
+* If you are deploying Consul servers on Kubernetes, then ensure that the Consul servers are deployed within the same Kubernetes cluster. Consul servers may be deployed external to Kubernetes and configured using the `externalServers` stanza. 
+* Consul clients deployed on the same Kubernetes cluster as the Consul Servers must use the `default` partition. If the clients are required to run on a non-default partition, then the clients must be deployed in a separate Kubernetes cluster. 
 * A Consul Enterprise license must be installed on each Kubernetes cluster.
 * The helm chart for consul-k8s v0.39.0 or greater.
 * Consul 1.11.1-ent or greater.

From 282b662641ec74bd40e667ff63938c3e82c07618 Mon Sep 17 00:00:00 2001
From: Michele Degges <mdeggies@gmail.com>
Date: Mon, 24 Jan 2022 12:13:14 -0800
Subject: [PATCH 30/98] Don't kill service  if envfile isn't present

---
 .release/linux/package/usr/lib/systemd/system/consul.service | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.release/linux/package/usr/lib/systemd/system/consul.service b/.release/linux/package/usr/lib/systemd/system/consul.service
index bde1210aae..1bbf51a7a1 100644
--- a/.release/linux/package/usr/lib/systemd/system/consul.service
+++ b/.release/linux/package/usr/lib/systemd/system/consul.service
@@ -6,7 +6,7 @@ After=network-online.target
 ConditionFileNotEmpty=/etc/consul.d/consul.hcl
 
 [Service]
-EnvironmentFile=/etc/consul.d/consul.env
+EnvironmentFile=-/etc/consul.d/consul.env
 User=consul
 Group=consul
 ExecStart=/usr/bin/consul agent -config-dir=/etc/consul.d/

From 81a79a3595ec0569afe0704223c7585241aee08a Mon Sep 17 00:00:00 2001
From: Michele Degges <mdeggies@gmail.com>
Date: Mon, 24 Jan 2022 12:32:22 -0800
Subject: [PATCH 31/98] Adding changelog entry

---
 .changelog/12176.txt | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 .changelog/12176.txt

diff --git a/.changelog/12176.txt b/.changelog/12176.txt
new file mode 100644
index 0000000000..81e7f669d3
--- /dev/null
+++ b/.changelog/12176.txt
@@ -0,0 +1,3 @@
+```release-note:enhancement
+systemd: Support starting/stopping the systemd service for linux packages when the optional EnvironmentFile does not exist.
+```
\ No newline at end of file

From 6eea2f2d48ec8f759ad6605c50531c6e092a2852 Mon Sep 17 00:00:00 2001
From: Morgan Drake <12264057+modrake@users.noreply.github.com>
Date: Mon, 24 Jan 2022 14:34:57 -0800
Subject: [PATCH 32/98] add netcgo tag for darwin builds

---
 .github/workflows/build.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index e4261c1d1a..277a116100 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -218,7 +218,7 @@ jobs:
           GOLDFLAGS: "${{ needs.get-product-version.outputs.shared-ldflags }}"
         run: |
           mkdir dist out
-          go build -ldflags="$GOLDFLAGS" -o dist/ .
+          go build -ldflags="$GOLDFLAGS" -tags netcgo -o dist/ .
           zip -r -j out/${{ env.PKG_NAME }}_${{ needs.get-product-version.outputs.product-version }}_${{ matrix.goos }}_${{ matrix.goarch }}.zip dist/
 
       - uses: actions/upload-artifact@v2

From f5d816dacef1ffa015a378645253b072b39c8cd8 Mon Sep 17 00:00:00 2001
From: "Chris S. Kim" <ckim@hashicorp.com>
Date: Tue, 25 Jan 2022 12:15:06 -0500
Subject: [PATCH 33/98] Remove incorrect usage of url.PathEscape (#12184)

When r.toHTTP is called, http.Request is built with the path
already escaped. This removes all calls to url.PathEscape that
would have led to double-escaped URLs.
---
 api/acl.go             | 34 +++++++++++++++++-----------------
 api/agent.go           | 29 ++++++++++++++---------------
 api/catalog.go         | 11 +++++------
 api/config_entry.go    |  7 +++----
 api/coordinate.go      |  3 +--
 api/discovery_chain.go |  3 +--
 6 files changed, 41 insertions(+), 46 deletions(-)

diff --git a/api/acl.go b/api/acl.go
index c3038e3898..0f44494dda 100644
--- a/api/acl.go
+++ b/api/acl.go
@@ -552,7 +552,7 @@ func (a *ACL) Update(acl *ACLEntry, q *WriteOptions) (*WriteMeta, error) {
 //
 // Deprecated: Use TokenDelete instead.
 func (a *ACL) Destroy(id string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("PUT", "/v1/acl/destroy/"+url.PathEscape(id))
+	r := a.c.newRequest("PUT", "/v1/acl/destroy/"+id)
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -571,7 +571,7 @@ func (a *ACL) Destroy(id string, q *WriteOptions) (*WriteMeta, error) {
 //
 // Deprecated: Use TokenClone instead.
 func (a *ACL) Clone(id string, q *WriteOptions) (string, *WriteMeta, error) {
-	r := a.c.newRequest("PUT", "/v1/acl/clone/"+url.PathEscape(id))
+	r := a.c.newRequest("PUT", "/v1/acl/clone/"+id)
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -594,7 +594,7 @@ func (a *ACL) Clone(id string, q *WriteOptions) (string, *WriteMeta, error) {
 //
 // Deprecated: Use TokenRead instead.
 func (a *ACL) Info(id string, q *QueryOptions) (*ACLEntry, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/info/"+url.PathEscape(id))
+	r := a.c.newRequest("GET", "/v1/acl/info/"+id)
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -696,7 +696,7 @@ func (a *ACL) TokenUpdate(token *ACLToken, q *WriteOptions) (*ACLToken, *WriteMe
 	if token.AccessorID == "" {
 		return nil, nil, fmt.Errorf("Must specify an AccessorID for Token Updating")
 	}
-	r := a.c.newRequest("PUT", "/v1/acl/token/"+url.PathEscape(token.AccessorID))
+	r := a.c.newRequest("PUT", "/v1/acl/token/"+token.AccessorID)
 	r.setWriteOptions(q)
 	r.obj = token
 	rtt, resp, err := a.c.doRequest(r)
@@ -725,7 +725,7 @@ func (a *ACL) TokenClone(tokenID string, description string, q *WriteOptions) (*
 		return nil, nil, fmt.Errorf("Must specify a tokenID for Token Cloning")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/token/"+url.PathEscape(tokenID)+"/clone")
+	r := a.c.newRequest("PUT", "/v1/acl/token/"+tokenID+"/clone")
 	r.setWriteOptions(q)
 	r.obj = struct{ Description string }{description}
 	rtt, resp, err := a.c.doRequest(r)
@@ -748,7 +748,7 @@ func (a *ACL) TokenClone(tokenID string, description string, q *WriteOptions) (*
 // TokenDelete removes a single ACL token. The tokenID parameter must be a valid
 // Accessor ID of an existing token.
 func (a *ACL) TokenDelete(tokenID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/token/"+url.PathEscape(tokenID))
+	r := a.c.newRequest("DELETE", "/v1/acl/token/"+tokenID)
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -766,7 +766,7 @@ func (a *ACL) TokenDelete(tokenID string, q *WriteOptions) (*WriteMeta, error) {
 // TokenRead retrieves the full token details. The tokenID parameter must be a valid
 // Accessor ID of an existing token.
 func (a *ACL) TokenRead(tokenID string, q *QueryOptions) (*ACLToken, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/token/"+url.PathEscape(tokenID))
+	r := a.c.newRequest("GET", "/v1/acl/token/"+tokenID)
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -871,7 +871,7 @@ func (a *ACL) PolicyUpdate(policy *ACLPolicy, q *WriteOptions) (*ACLPolicy, *Wri
 		return nil, nil, fmt.Errorf("Must specify an ID in Policy Update")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/policy/"+url.PathEscape(policy.ID))
+	r := a.c.newRequest("PUT", "/v1/acl/policy/"+policy.ID)
 	r.setWriteOptions(q)
 	r.obj = policy
 	rtt, resp, err := a.c.doRequest(r)
@@ -893,7 +893,7 @@ func (a *ACL) PolicyUpdate(policy *ACLPolicy, q *WriteOptions) (*ACLPolicy, *Wri
 
 // PolicyDelete deletes a policy given its ID.
 func (a *ACL) PolicyDelete(policyID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/policy/"+url.PathEscape(policyID))
+	r := a.c.newRequest("DELETE", "/v1/acl/policy/"+policyID)
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -910,7 +910,7 @@ func (a *ACL) PolicyDelete(policyID string, q *WriteOptions) (*WriteMeta, error)
 
 // PolicyRead retrieves the policy details including the rule set.
 func (a *ACL) PolicyRead(policyID string, q *QueryOptions) (*ACLPolicy, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/policy/"+url.PathEscape(policyID))
+	r := a.c.newRequest("GET", "/v1/acl/policy/"+policyID)
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1021,7 +1021,7 @@ func (a *ACL) RulesTranslate(rules io.Reader) (string, error) {
 // Deprecated: Support for the legacy syntax translation will be removed
 // when legacy ACL support is removed.
 func (a *ACL) RulesTranslateToken(tokenID string) (string, error) {
-	r := a.c.newRequest("GET", "/v1/acl/rules/translate/"+url.PathEscape(tokenID))
+	r := a.c.newRequest("GET", "/v1/acl/rules/translate/"+tokenID)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
 		return "", err
@@ -1076,7 +1076,7 @@ func (a *ACL) RoleUpdate(role *ACLRole, q *WriteOptions) (*ACLRole, *WriteMeta,
 		return nil, nil, fmt.Errorf("Must specify an ID in Role Update")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/role/"+url.PathEscape(role.ID))
+	r := a.c.newRequest("PUT", "/v1/acl/role/"+role.ID)
 	r.setWriteOptions(q)
 	r.obj = role
 	rtt, resp, err := a.c.doRequest(r)
@@ -1098,7 +1098,7 @@ func (a *ACL) RoleUpdate(role *ACLRole, q *WriteOptions) (*ACLRole, *WriteMeta,
 
 // RoleDelete deletes a role given its ID.
 func (a *ACL) RoleDelete(roleID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/role/"+url.PathEscape(roleID))
+	r := a.c.newRequest("DELETE", "/v1/acl/role/"+roleID)
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1115,7 +1115,7 @@ func (a *ACL) RoleDelete(roleID string, q *WriteOptions) (*WriteMeta, error) {
 
 // RoleRead retrieves the role details (by ID). Returns nil if not found.
 func (a *ACL) RoleRead(roleID string, q *QueryOptions) (*ACLRole, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/role/"+url.PathEscape(roleID))
+	r := a.c.newRequest("GET", "/v1/acl/role/"+roleID)
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1365,7 +1365,7 @@ func (a *ACL) BindingRuleUpdate(rule *ACLBindingRule, q *WriteOptions) (*ACLBind
 		return nil, nil, fmt.Errorf("Must specify an ID in Binding Rule Update")
 	}
 
-	r := a.c.newRequest("PUT", "/v1/acl/binding-rule/"+url.PathEscape(rule.ID))
+	r := a.c.newRequest("PUT", "/v1/acl/binding-rule/"+rule.ID)
 	r.setWriteOptions(q)
 	r.obj = rule
 	rtt, resp, err := a.c.doRequest(r)
@@ -1387,7 +1387,7 @@ func (a *ACL) BindingRuleUpdate(rule *ACLBindingRule, q *WriteOptions) (*ACLBind
 
 // BindingRuleDelete deletes a binding rule given its ID.
 func (a *ACL) BindingRuleDelete(bindingRuleID string, q *WriteOptions) (*WriteMeta, error) {
-	r := a.c.newRequest("DELETE", "/v1/acl/binding-rule/"+url.PathEscape(bindingRuleID))
+	r := a.c.newRequest("DELETE", "/v1/acl/binding-rule/"+bindingRuleID)
 	r.setWriteOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1404,7 +1404,7 @@ func (a *ACL) BindingRuleDelete(bindingRuleID string, q *WriteOptions) (*WriteMe
 
 // BindingRuleRead retrieves the binding rule details. Returns nil if not found.
 func (a *ACL) BindingRuleRead(bindingRuleID string, q *QueryOptions) (*ACLBindingRule, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/acl/binding-rule/"+url.PathEscape(bindingRuleID))
+	r := a.c.newRequest("GET", "/v1/acl/binding-rule/"+bindingRuleID)
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
diff --git a/api/agent.go b/api/agent.go
index 04dd059d99..7bbe39ea79 100644
--- a/api/agent.go
+++ b/api/agent.go
@@ -7,7 +7,6 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"net/url"
 )
 
 // ServiceKind is the kind of service being registered.
@@ -628,7 +627,7 @@ func (a *Agent) AgentHealthServiceByID(serviceID string) (string, *AgentServiceC
 }
 
 func (a *Agent) AgentHealthServiceByIDOpts(serviceID string, q *QueryOptions) (string, *AgentServiceChecksInfo, error) {
-	path := fmt.Sprintf("/v1/agent/health/service/id/%v", url.PathEscape(serviceID))
+	path := fmt.Sprintf("/v1/agent/health/service/id/%v", serviceID)
 	r := a.c.newRequest("GET", path)
 	r.setQueryOptions(q)
 	r.params.Add("format", "json")
@@ -669,7 +668,7 @@ func (a *Agent) AgentHealthServiceByName(service string) (string, []AgentService
 }
 
 func (a *Agent) AgentHealthServiceByNameOpts(service string, q *QueryOptions) (string, []AgentServiceChecksInfo, error) {
-	path := fmt.Sprintf("/v1/agent/health/service/name/%v", url.PathEscape(service))
+	path := fmt.Sprintf("/v1/agent/health/service/name/%v", service)
 	r := a.c.newRequest("GET", path)
 	r.setQueryOptions(q)
 	r.params.Add("format", "json")
@@ -707,7 +706,7 @@ func (a *Agent) AgentHealthServiceByNameOpts(service string, q *QueryOptions) (s
 // agent-local state. That means there is no persistent raft index so we block
 // based on object hash instead.
 func (a *Agent) Service(serviceID string, q *QueryOptions) (*AgentService, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/agent/service/"+url.PathEscape(serviceID))
+	r := a.c.newRequest("GET", "/v1/agent/service/"+serviceID)
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -812,7 +811,7 @@ func (a *Agent) serviceRegister(service *AgentServiceRegistration, opts ServiceR
 // ServiceDeregister is used to deregister a service with
 // the local agent
 func (a *Agent) ServiceDeregister(serviceID string) error {
-	r := a.c.newRequest("PUT", "/v1/agent/service/deregister/"+url.PathEscape(serviceID))
+	r := a.c.newRequest("PUT", "/v1/agent/service/deregister/"+serviceID)
 	_, resp, err := a.c.doRequest(r)
 	if err != nil {
 		return err
@@ -827,7 +826,7 @@ func (a *Agent) ServiceDeregister(serviceID string) error {
 // ServiceDeregisterOpts is used to deregister a service with
 // the local agent with QueryOptions.
 func (a *Agent) ServiceDeregisterOpts(serviceID string, q *QueryOptions) error {
-	r := a.c.newRequest("PUT", "/v1/agent/service/deregister/"+url.PathEscape(serviceID))
+	r := a.c.newRequest("PUT", "/v1/agent/service/deregister/"+serviceID)
 	r.setQueryOptions(q)
 	_, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -884,7 +883,7 @@ func (a *Agent) updateTTL(checkID, note, status string) error {
 	default:
 		return fmt.Errorf("Invalid status: %s", status)
 	}
-	endpoint := fmt.Sprintf("/v1/agent/check/%s/%s", url.PathEscape(status), url.PathEscape(checkID))
+	endpoint := fmt.Sprintf("/v1/agent/check/%s/%s", status, checkID)
 	r := a.c.newRequest("PUT", endpoint)
 	r.params.Set("note", note)
 	_, resp, err := a.c.doRequest(r)
@@ -932,7 +931,7 @@ func (a *Agent) UpdateTTLOpts(checkID, output, status string, q *QueryOptions) e
 		return fmt.Errorf("Invalid status: %s", status)
 	}
 
-	endpoint := fmt.Sprintf("/v1/agent/check/update/%s", url.PathEscape(checkID))
+	endpoint := fmt.Sprintf("/v1/agent/check/update/%s", checkID)
 	r := a.c.newRequest("PUT", endpoint)
 	r.setQueryOptions(q)
 	r.obj = &checkUpdate{
@@ -976,7 +975,7 @@ func (a *Agent) CheckDeregister(checkID string) error {
 // CheckDeregisterOpts is used to deregister a check with
 // the local agent using query options
 func (a *Agent) CheckDeregisterOpts(checkID string, q *QueryOptions) error {
-	r := a.c.newRequest("PUT", "/v1/agent/check/deregister/"+url.PathEscape(checkID))
+	r := a.c.newRequest("PUT", "/v1/agent/check/deregister/"+checkID)
 	r.setQueryOptions(q)
 	_, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -992,7 +991,7 @@ func (a *Agent) CheckDeregisterOpts(checkID string, q *QueryOptions) error {
 // Join is used to instruct the agent to attempt a join to
 // another cluster member
 func (a *Agent) Join(addr string, wan bool) error {
-	r := a.c.newRequest("PUT", "/v1/agent/join/"+url.PathEscape(addr))
+	r := a.c.newRequest("PUT", "/v1/agent/join/"+addr)
 	if wan {
 		r.params.Set("wan", "1")
 	}
@@ -1044,7 +1043,7 @@ func (a *Agent) ForceLeavePrune(node string) error {
 // ForceLeaveOpts is used to have the agent eject a failed node or remove it
 // completely from the list of members.
 func (a *Agent) ForceLeaveOpts(node string, opts ForceLeaveOpts) error {
-	r := a.c.newRequest("PUT", "/v1/agent/force-leave/"+url.PathEscape(node))
+	r := a.c.newRequest("PUT", "/v1/agent/force-leave/"+node)
 	if opts.Prune {
 		r.params.Set("prune", "1")
 	}
@@ -1108,7 +1107,7 @@ func (a *Agent) ConnectCARoots(q *QueryOptions) (*CARootList, *QueryMeta, error)
 
 // ConnectCALeaf gets the leaf certificate for the given service ID.
 func (a *Agent) ConnectCALeaf(serviceID string, q *QueryOptions) (*LeafCert, *QueryMeta, error) {
-	r := a.c.newRequest("GET", "/v1/agent/connect/ca/leaf/"+url.PathEscape(serviceID))
+	r := a.c.newRequest("GET", "/v1/agent/connect/ca/leaf/"+serviceID)
 	r.setQueryOptions(q)
 	rtt, resp, err := a.c.doRequest(r)
 	if err != nil {
@@ -1136,7 +1135,7 @@ func (a *Agent) EnableServiceMaintenance(serviceID, reason string) error {
 }
 
 func (a *Agent) EnableServiceMaintenanceOpts(serviceID, reason string, q *QueryOptions) error {
-	r := a.c.newRequest("PUT", "/v1/agent/service/maintenance/"+url.PathEscape(serviceID))
+	r := a.c.newRequest("PUT", "/v1/agent/service/maintenance/"+serviceID)
 	r.setQueryOptions(q)
 	r.params.Set("enable", "true")
 	r.params.Set("reason", reason)
@@ -1158,7 +1157,7 @@ func (a *Agent) DisableServiceMaintenance(serviceID string) error {
 }
 
 func (a *Agent) DisableServiceMaintenanceOpts(serviceID string, q *QueryOptions) error {
-	r := a.c.newRequest("PUT", "/v1/agent/service/maintenance/"+url.PathEscape(serviceID))
+	r := a.c.newRequest("PUT", "/v1/agent/service/maintenance/"+serviceID)
 	r.setQueryOptions(q)
 	r.params.Set("enable", "false")
 	_, resp, err := a.c.doRequest(r)
@@ -1355,7 +1354,7 @@ func (a *Agent) updateTokenFallback(token string, q *WriteOptions, targets ...st
 }
 
 func (a *Agent) updateTokenOnce(target, token string, q *WriteOptions) (*WriteMeta, int, error) {
-	r := a.c.newRequest("PUT", fmt.Sprintf("/v1/agent/token/%s", url.PathEscape(target)))
+	r := a.c.newRequest("PUT", fmt.Sprintf("/v1/agent/token/%s", target))
 	r.setWriteOptions(q)
 	r.obj = &AgentToken{Token: token}
 
diff --git a/api/catalog.go b/api/catalog.go
index 54fcce85f4..80ae325eac 100644
--- a/api/catalog.go
+++ b/api/catalog.go
@@ -2,7 +2,6 @@ package api
 
 import (
 	"net"
-	"net/url"
 	"strconv"
 )
 
@@ -255,9 +254,9 @@ func (c *Catalog) ConnectMultipleTags(service string, tags []string, q *QueryOpt
 }
 
 func (c *Catalog) service(service string, tags []string, q *QueryOptions, connect bool) ([]*CatalogService, *QueryMeta, error) {
-	path := "/v1/catalog/service/" + url.PathEscape(service)
+	path := "/v1/catalog/service/" + service
 	if connect {
-		path = "/v1/catalog/connect/" + url.PathEscape(service)
+		path = "/v1/catalog/connect/" + service
 	}
 	r := c.c.newRequest("GET", path)
 	r.setQueryOptions(q)
@@ -288,7 +287,7 @@ func (c *Catalog) service(service string, tags []string, q *QueryOptions, connec
 
 // Node is used to query for service information about a single node
 func (c *Catalog) Node(node string, q *QueryOptions) (*CatalogNode, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/catalog/node/"+url.PathEscape(node))
+	r := c.c.newRequest("GET", "/v1/catalog/node/"+node)
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
@@ -315,7 +314,7 @@ func (c *Catalog) Node(node string, q *QueryOptions) (*CatalogNode, *QueryMeta,
 // a map of service ids to services. This different structure allows for using the wildcard specifier
 // '*' for the Namespace in the QueryOptions.
 func (c *Catalog) NodeServiceList(node string, q *QueryOptions) (*CatalogNodeServiceList, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/catalog/node-services/"+url.PathEscape(node))
+	r := c.c.newRequest("GET", "/v1/catalog/node-services/"+node)
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
@@ -339,7 +338,7 @@ func (c *Catalog) NodeServiceList(node string, q *QueryOptions) (*CatalogNodeSer
 
 // GatewayServices is used to query the services associated with an ingress gateway or terminating gateway.
 func (c *Catalog) GatewayServices(gateway string, q *QueryOptions) ([]*GatewayService, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/catalog/gateway-services/"+url.PathEscape(gateway))
+	r := c.c.newRequest("GET", "/v1/catalog/gateway-services/"+gateway)
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
diff --git a/api/config_entry.go b/api/config_entry.go
index f1c4091d10..91c407bb53 100644
--- a/api/config_entry.go
+++ b/api/config_entry.go
@@ -5,7 +5,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
-	"net/url"
 	"strconv"
 	"strings"
 	"time"
@@ -379,7 +378,7 @@ func (conf *ConfigEntries) Get(kind string, name string, q *QueryOptions) (Confi
 		return nil, nil, err
 	}
 
-	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s/%s", url.PathEscape(kind), url.PathEscape(name)))
+	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s/%s", kind, name))
 	r.setQueryOptions(q)
 	rtt, resp, err := conf.c.doRequest(r)
 	if err != nil {
@@ -406,7 +405,7 @@ func (conf *ConfigEntries) List(kind string, q *QueryOptions) ([]ConfigEntry, *Q
 		return nil, nil, fmt.Errorf("The kind parameter must not be empty")
 	}
 
-	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s", url.PathEscape(kind)))
+	r := conf.c.newRequest("GET", fmt.Sprintf("/v1/config/%s", kind))
 	r.setQueryOptions(q)
 	rtt, resp, err := conf.c.doRequest(r)
 	if err != nil {
@@ -486,7 +485,7 @@ func (conf *ConfigEntries) delete(kind, name string, params map[string]string, w
 		return false, nil, fmt.Errorf("Both kind and name parameters must not be empty")
 	}
 
-	r := conf.c.newRequest("DELETE", fmt.Sprintf("/v1/config/%s/%s", url.PathEscape(kind), url.PathEscape(name)))
+	r := conf.c.newRequest("DELETE", fmt.Sprintf("/v1/config/%s/%s", kind, name))
 	r.setWriteOptions(w)
 	for param, value := range params {
 		r.params.Set(param, value)
diff --git a/api/coordinate.go b/api/coordinate.go
index bd607e32fd..7ef6ce2744 100644
--- a/api/coordinate.go
+++ b/api/coordinate.go
@@ -2,7 +2,6 @@ package api
 
 import (
 	"github.com/hashicorp/serf/coordinate"
-	"net/url"
 )
 
 // CoordinateEntry represents a node and its associated network coordinate.
@@ -97,7 +96,7 @@ func (c *Coordinate) Update(coord *CoordinateEntry, q *WriteOptions) (*WriteMeta
 
 // Node is used to return the coordinates of a single node in the LAN pool.
 func (c *Coordinate) Node(node string, q *QueryOptions) ([]*CoordinateEntry, *QueryMeta, error) {
-	r := c.c.newRequest("GET", "/v1/coordinate/node/"+url.PathEscape(node))
+	r := c.c.newRequest("GET", "/v1/coordinate/node/"+node)
 	r.setQueryOptions(q)
 	rtt, resp, err := c.c.doRequest(r)
 	if err != nil {
diff --git a/api/discovery_chain.go b/api/discovery_chain.go
index 10150f5de8..29bda85912 100644
--- a/api/discovery_chain.go
+++ b/api/discovery_chain.go
@@ -3,7 +3,6 @@ package api
 import (
 	"encoding/json"
 	"fmt"
-	"net/url"
 	"time"
 )
 
@@ -27,7 +26,7 @@ func (d *DiscoveryChain) Get(name string, opts *DiscoveryChainOptions, q *QueryO
 		method = "POST"
 	}
 
-	r := d.c.newRequest(method, fmt.Sprintf("/v1/discovery-chain/%s", url.PathEscape(name)))
+	r := d.c.newRequest(method, fmt.Sprintf("/v1/discovery-chain/%s", name))
 	r.setQueryOptions(q)
 
 	if opts != nil {

From d2c0945f524ff0dc6cd9c13de363e1e1b7867d52 Mon Sep 17 00:00:00 2001
From: "R.B. Boyer" <4903+rboyer@users.noreply.github.com>
Date: Tue, 25 Jan 2022 11:24:27 -0600
Subject: [PATCH 34/98] xds: fix for delta xDS reconnect bug in LDS/CDS
 (#12174)

When a wildcard xDS type (LDS/CDS/SRDS) reconnects from a delta xDS stream,
prior to envoy `1.19.0` it would populate the `ResourceNamesSubscribe` field
with the full list of currently subscribed items, instead of simply omitting it
to infer that it wanted everything (which is what wildcard mode means).

This upstream issue was filed in envoyproxy/envoy#16063 and fixed in
envoyproxy/envoy#16153 which went out in Envoy `1.19.0` and is fixed in later
versions (later refactored in envoyproxy/envoy#16855).

This PR conditionally forces LDS/CDS to be wildcard-only even when the
connected Envoy requests a non-wildcard subscription, but only does so on
versions prior to `1.19.0`, as we should not need to do this on later versions.

This fixes the failure case as described here: #11833 (comment)

Co-authored-by: Huan Wang <fredwanghuan@gmail.com>
---
 .changelog/12174.txt               |  3 ++
 agent/xds/delta.go                 | 24 +++++++----
 agent/xds/delta_test.go            | 66 ++++++++++++++++++++++++++++++
 agent/xds/envoy_versioning.go      | 33 ++++++++-------
 agent/xds/envoy_versioning_test.go |  6 +++
 agent/xds/testing.go               | 11 ++++-
 6 files changed, 117 insertions(+), 26 deletions(-)
 create mode 100644 .changelog/12174.txt

diff --git a/.changelog/12174.txt b/.changelog/12174.txt
new file mode 100644
index 0000000000..b839df4eca
--- /dev/null
+++ b/.changelog/12174.txt
@@ -0,0 +1,3 @@
+```release-note:bug
+xds: fix for delta xDS reconnect bug in LDS/CDS
+```
diff --git a/agent/xds/delta.go b/agent/xds/delta.go
index 71c97af933..b0a4ccafcb 100644
--- a/agent/xds/delta.go
+++ b/agent/xds/delta.go
@@ -165,12 +165,6 @@ func (s *Server) processDelta(stream ADSDeltaStream, reqCh <-chan *envoy_discove
 				return status.Errorf(codes.InvalidArgument, "type URL is required for ADS")
 			}
 
-			if handler, ok := handlers[req.TypeUrl]; ok {
-				if handler.Recv(req) {
-					generator.Logger.Trace("subscribing to type", "typeUrl", req.TypeUrl)
-				}
-			}
-
 			if node == nil && req.Node != nil {
 				node = req.Node
 				var err error
@@ -180,6 +174,12 @@ func (s *Server) processDelta(stream ADSDeltaStream, reqCh <-chan *envoy_discove
 				}
 			}
 
+			if handler, ok := handlers[req.TypeUrl]; ok {
+				if handler.Recv(req, generator.ProxyFeatures) {
+					generator.Logger.Trace("subscribing to type", "typeUrl", req.TypeUrl)
+				}
+			}
+
 		case cfgSnap = <-stateCh:
 			newRes, err := generator.allResourcesFromSnapshot(cfgSnap)
 			if err != nil {
@@ -434,7 +434,7 @@ func newDeltaType(
 // Recv handles new discovery requests from envoy.
 //
 // Returns true the first time a type receives a request.
-func (t *xDSDeltaType) Recv(req *envoy_discovery_v3.DeltaDiscoveryRequest) bool {
+func (t *xDSDeltaType) Recv(req *envoy_discovery_v3.DeltaDiscoveryRequest, sf supportedProxyFeatures) bool {
 	if t == nil {
 		return false // not something we care about
 	}
@@ -447,6 +447,16 @@ func (t *xDSDeltaType) Recv(req *envoy_discovery_v3.DeltaDiscoveryRequest) bool
 		t.wildcard = len(req.ResourceNamesSubscribe) == 0
 		t.registered = true
 		registeredThisTime = true
+
+		if sf.ForceLDSandCDSToAlwaysUseWildcardsOnReconnect {
+			switch t.typeURL {
+			case ListenerType, ClusterType:
+				if !t.wildcard {
+					t.wildcard = true
+					logger.Trace("fixing Envoy bug fixed in 1.19.0 by inferring wildcard mode for type")
+				}
+			}
+		}
 	}
 
 	/*
diff --git a/agent/xds/delta_test.go b/agent/xds/delta_test.go
index d5b1a575ba..eca97e36ee 100644
--- a/agent/xds/delta_test.go
+++ b/agent/xds/delta_test.go
@@ -554,6 +554,72 @@ func TestServer_DeltaAggregatedResources_v3_SlowEndpointPopulation(t *testing.T)
 	}
 }
 
+func TestServer_DeltaAggregatedResources_v3_GetAllClusterAfterConsulRestarted(t *testing.T) {
+	// This illustrates a scenario related to https://github.com/hashicorp/consul/issues/11833
+
+	aclResolve := func(id string) (acl.Authorizer, error) {
+		// Allow all
+		return acl.RootAuthorizer("manage"), nil
+	}
+	scenario := newTestServerDeltaScenario(t, aclResolve, "web-sidecar-proxy", "", 0)
+	_, mgr, errCh, envoy := scenario.server, scenario.mgr, scenario.errCh, scenario.envoy
+	envoy.EnvoyVersion = "1.18.0"
+
+	sid := structs.NewServiceID("web-sidecar-proxy", nil)
+
+	// Register the proxy to create state needed to Watch() on
+	mgr.RegisterProxy(t, sid)
+
+	var snap *proxycfg.ConfigSnapshot
+	runStep(t, "get into state after consul restarted", func(t *testing.T) {
+		snap = newTestSnapshot(t, nil, "")
+
+		// Send initial cluster discover.
+		// This is to simulate the discovery request call from envoy after disconnected from consul ads stream.
+		//
+		// We need to force it to be an older version of envoy so that the logic shifts.
+		envoy.SendDeltaReq(t, ClusterType, &envoy_discovery_v3.DeltaDiscoveryRequest{
+			ResourceNamesSubscribe: []string{
+				"local_app",
+				"db.default.dc1.internal.11111111-2222-3333-4444-555555555555.consul",
+			},
+			InitialResourceVersions: map[string]string{
+				"local_app": "a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447",
+				"db.default.dc1.internal.11111111-2222-3333-4444-555555555555.consul": "5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
+			},
+		})
+
+		// Check no response sent yet
+		assertDeltaChanBlocked(t, envoy.deltaStream.sendCh)
+
+		requireProtocolVersionGauge(t, scenario, "v3", 1)
+
+		// Deliver a new snapshot
+		// the config contains 3 clusters: local_app, db, geo-cache.
+		// this is to simulate the fact that there is one additional (upstream) cluster gets added to the sidecar service
+		// during the time xds disconnected (consul restarted).
+		mgr.DeliverConfig(t, sid, snap)
+
+		assertDeltaResponseSent(t, envoy.deltaStream.sendCh, &envoy_discovery_v3.DeltaDiscoveryResponse{
+			TypeUrl: ClusterType,
+			Nonce:   hexString(1),
+			Resources: makeTestResources(t,
+				makeTestCluster(t, snap, "tcp:local_app"),
+				makeTestCluster(t, snap, "tcp:db"),
+				makeTestCluster(t, snap, "tcp:geo-cache"),
+			),
+		})
+	})
+
+	envoy.Close()
+	select {
+	case err := <-errCh:
+		require.NoError(t, err)
+	case <-time.After(50 * time.Millisecond):
+		t.Fatalf("timed out waiting for handler to finish")
+	}
+}
+
 func TestServer_DeltaAggregatedResources_v3_BasicProtocol_TCP_clusterChangesImpactEndpoints(t *testing.T) {
 	aclResolve := func(id string) (acl.Authorizer, error) {
 		// Allow all
diff --git a/agent/xds/envoy_versioning.go b/agent/xds/envoy_versioning.go
index 27df44f170..be0a770fe8 100644
--- a/agent/xds/envoy_versioning.go
+++ b/agent/xds/envoy_versioning.go
@@ -13,8 +13,7 @@ var (
 	// the zero'th point release of the last element of proxysupport.EnvoyVersions.
 	minSupportedVersion = version.Must(version.NewVersion("1.17.0"))
 
-	// add min version constraints for associated feature flags when necessary, for example:
-	// minVersionAllowingEmptyGatewayClustersWithIncrementalXDS = version.Must(version.NewVersion("1.16.0"))
+	minVersionToForceLDSandCDSToAlwaysUseWildcardsOnReconnect = version.Must(version.NewVersion("1.19.0"))
 
 	specificUnsupportedVersions = []unsupportedVersion{}
 )
@@ -26,16 +25,19 @@ type unsupportedVersion struct {
 }
 
 type supportedProxyFeatures struct {
-	// add version dependent feature flags here
+	// Older versions of Envoy incorrectly exploded a wildcard subscription for
+	// LDS and CDS into specific line items on incremental xDS reconnect. They
+	// would populate both InitialResourceVersions and ResourceNamesSubscribe
+	// when they SHOULD have left ResourceNamesSubscribe empty (or used an
+	// explicit "*" in later Envoy versions) to imply wildcard mode. On
+	// reconnect, Consul interpreted the lack of the wildcard attribute as
+	// implying that the Envoy instance should not receive updates for any
+	// newly created listeners and clusters for the remaining life of that
+	// Envoy sidecar process.
 	//
-	// For example, we previously had flags for Envoy < 1.16 called:
-	//
-	// GatewaysNeedStubClusterWhenEmptyWithIncrementalXDS
-	// IncrementalXDSUpdatesMustBeSerial
-	//
-	// Which then manifested in the code for checks with this struct populated.
-	// By dropping support for 1.15, we no longer have any special flags here
-	// but leaving this flagging functionality for future one-offs.
+	// see: https://github.com/envoyproxy/envoy/issues/16063
+	// see: https://github.com/envoyproxy/envoy/pull/16153
+	ForceLDSandCDSToAlwaysUseWildcardsOnReconnect bool
 }
 
 func determineSupportedProxyFeatures(node *envoy_core_v3.Node) (supportedProxyFeatures, error) {
@@ -73,12 +75,9 @@ func determineSupportedProxyFeaturesFromVersion(version *version.Version) (suppo
 
 	sf := supportedProxyFeatures{}
 
-	// add version constraints to populate feature flags here when necessary, for example:
-	/*
-		if version.LessThan(minVersionAllowingEmptyGatewayClustersWithIncrementalXDS) {
-			sf.GatewaysNeedStubClusterWhenEmptyWithIncrementalXDS = true
-		}
-	*/
+	if version.LessThan(minVersionToForceLDSandCDSToAlwaysUseWildcardsOnReconnect) {
+		sf.ForceLDSandCDSToAlwaysUseWildcardsOnReconnect = true
+	}
 
 	return sf, nil
 }
diff --git a/agent/xds/envoy_versioning_test.go b/agent/xds/envoy_versioning_test.go
index 75211ecc5b..47622ab737 100644
--- a/agent/xds/envoy_versioning_test.go
+++ b/agent/xds/envoy_versioning_test.go
@@ -125,6 +125,12 @@ func TestDetermineSupportedProxyFeaturesFromString(t *testing.T) {
 	for _, v := range []string{
 		"1.17.0", "1.17.1", "1.17.2", "1.17.3", "1.17.4",
 		"1.18.0", "1.18.1", "1.18.2", "1.18.3", "1.18.4",
+	} {
+		cases[v] = testcase{expect: supportedProxyFeatures{
+			ForceLDSandCDSToAlwaysUseWildcardsOnReconnect: true,
+		}}
+	}
+	for _, v := range []string{
 		"1.19.0", "1.19.1",
 		"1.20.0", "1.20.1",
 	} {
diff --git a/agent/xds/testing.go b/agent/xds/testing.go
index fc2e97baf3..90ea093c73 100644
--- a/agent/xds/testing.go
+++ b/agent/xds/testing.go
@@ -83,6 +83,8 @@ type TestEnvoy struct {
 	proxyID string
 	token   string
 
+	EnvoyVersion string
+
 	deltaStream *TestADSDeltaStream // Incremental v3
 }
 
@@ -182,9 +184,14 @@ func (e *TestEnvoy) sendDeltaReq(
 	e.mu.Lock()
 	defer e.mu.Unlock()
 
-	ev, valid := stringToEnvoyVersion(proxysupport.EnvoyVersions[0])
+	stringVersion := e.EnvoyVersion
+	if stringVersion == "" {
+		stringVersion = proxysupport.EnvoyVersions[0]
+	}
+
+	ev, valid := stringToEnvoyVersion(stringVersion)
 	if !valid {
-		t.Fatal("envoy version is not valid: %s", proxysupport.EnvoyVersions[0])
+		t.Fatal("envoy version is not valid: %s", stringVersion)
 	}
 
 	if req == nil {

From b199b60ded9b22d0be3cdd9b0947dcaa98194baa Mon Sep 17 00:00:00 2001
From: David Yu <dyu@hashicorp.com>
Date: Tue, 25 Jan 2022 15:02:19 -0800
Subject: [PATCH 35/98] docs: Service Sync clarify requirements when using
 Service Mesh (#12177)

* docs: Service Sync clarify requirements when using Service Mesh

* replace with relative link
---
 website/content/docs/k8s/service-sync.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/website/content/docs/k8s/service-sync.mdx b/website/content/docs/k8s/service-sync.mdx
index 686b50e06a..5fbabe6b27 100644
--- a/website/content/docs/k8s/service-sync.mdx
+++ b/website/content/docs/k8s/service-sync.mdx
@@ -32,6 +32,8 @@ service discovery, including hosted services like databases.
 
 ## Installation and Configuration
 
+~> Enabling both Service Mesh and Service Sync on the same Kubernetes services is not supported, as Service Mesh also registers Kubernetes service instances to Consul. Please ensure that Service Sync is only enabled for namespaces and services that are not injected with the Consul sidecar for Service Mesh as described in [Sync Enable/Disable](/docs/k8s/service-sync#sync-enable-disable).
+
 The service sync is done using an external long-running process in the
 [consul-k8s project](https://github.com/hashicorp/consul-k8s). This process
 can run either in or out of a Kubernetes cluster. However, running this within

From a3ad4be429ab004600f99ad53afee28e3843e1a8 Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Wed, 26 Jan 2022 08:12:12 -0800
Subject: [PATCH 36/98] docs: Add ingress TLS cipher and version documentation
 (#12163)

Document the new TLS cipher and version parameters that were added to
ingress gateways in #11576.

Co-authored-by: Mike Morris <mikemorris@users.noreply.github.com>
---
 .../config-entries/ingress-gateway.mdx        | 63 ++++++++++++++++++-
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx
index e539001d1f..cc3f1014e5 100644
--- a/website/content/docs/connect/config-entries/ingress-gateway.mdx
+++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx
@@ -979,6 +979,36 @@ You can specify the following parameters to configure ingress gateway configurat
               "Set this configuration to `true` to enable built-in TLS for every listener on the gateway.<br><br>If TLS is enabled, then each host defined in each service's `hosts` fields will be added as a DNSSAN to the gateway's x509 certificate.",
           },
         },
+        {
+          name: 'TLSMinVersion',
+          type: 'string: ""',
+          description: "Set the default minimum TLS version supported for the gateway's listeners. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy v1.22.0 and newer [will default to TLS 1.2 as a min version](https://github.com/envoyproxy/envoy/pull/19330), while older releases of Envoy default to TLS 1.0.",
+        },
+        {
+          name: 'TLSMaxVersion',
+          type: 'string: ""',
+          description: {
+            hcl:
+              "Set the default maximum TLS version supported for the gateway's listeners. Must be greater than or equal to `TLSMinVersion`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
+            yaml:
+              "Set the default maximum TLS version supported for the gateway's listeners. Must be greater than or equal to `tls_min_version`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
+          },
+        },
+        {
+          name: 'CipherSuites',
+          type: 'array<string>: <optional>',
+          description: `Set the default list of TLS cipher suites for the gateway's
+                        listeners to support when negotiating connections using
+                        TLS 1.2 or earlier. If unspecified, Envoy will use a
+                        [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites).
+                        The list of supported cipher suites can seen in
+                        [\`consul/types/tls.go\`](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169)
+                        and is dependent on underlying support in Envoy. Future
+                        releases of Envoy may remove currently-supported but
+                        insecure cipher suites, and future releases of Consul
+                        may add new supported cipher suites if any are added to
+                        Envoy.`
+        },
         {
           name: 'SDS',
           yaml: false,
@@ -1133,11 +1163,40 @@ You can specify the following parameters to configure ingress gateway configurat
               type: 'bool: false',
               description: {
                 hcl:
-                  "Set this configuration to `true` to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in each service's `Hosts` field will be added as a DNSSAN to the gateway's x509 certificate. Note that even hosts from other listeners with TLS disabled will be added.",
+                  "Set this configuration to `true` to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in each service's `Hosts` field will be added as a DNSSAN to the gateway's x509 certificate. Note that even hosts from other listeners with TLS disabled will be added. TLS can not be disabled for individual listeners if it is enabled on the gateway.",
                 yaml:
-                  "Set this configuration to `true` to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in the `hosts` field will be added as a DNSSAN to the gateway's x509 certificate. Note that even hosts from other listeners with TLS disabled will be added.",
+                  "Set this configuration to `true` to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in the `hosts` field will be added as a DNSSAN to the gateway's x509 certificate. Note that even hosts from other listeners with TLS disabled will be added. TLS can not be disabled for individual listeners if it is enabled on the gateway.",
               },
             },
+            {
+              name: 'TLSMinVersion',
+              type: 'string: ""',
+              description: "Set the minimum TLS version supported for this listener. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy v1.22.0 and newer [will default to TLS 1.2 as a min version](https://github.com/envoyproxy/envoy/pull/19330), while older releases of Envoy default to TLS 1.0.",
+            },
+            {
+              name: 'TLSMaxVersion',
+              type: 'string: ""',
+              description: {
+                hcl:
+                  "Set the maximum TLS version supported for this listener. Must be greater than or equal to `TLSMinVersion`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
+                yaml:
+                  "Set the maximum TLS version supported for this listener. Must be greater than or equal to `tls_min_version`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
+              },
+            },
+            {
+              name: 'CipherSuites',
+              type: 'array<string>: <optional>',
+              description: `Set the list of TLS cipher suites to support when negotiating
+                            connections using TLS 1.2 or earlier. If unspecified,
+                            Envoy will use a
+                            [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites).
+                            The list of supported cipher suites can seen in
+                            [\`consul/types/tls.go\`](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169)
+                            and is dependent on underlying support in Envoy. Future
+                            releases of Envoy may remove currently-supported but
+                            insecure cipher suites, and future releases of Consul
+                            may add new supported cipher suites if any are added to Envoy.`
+            },
             {
               name: 'SDS',
               type: 'SDSConfig: <optional>',

From 19a67d87687d7ec8f91bc75c4b2f7f1aecc2b60d Mon Sep 17 00:00:00 2001
From: Matt Keeler <mkeeler@users.noreply.github.com>
Date: Wed, 26 Jan 2022 11:51:19 -0500
Subject: [PATCH 37/98] Update telemetry page with advice for monitoring boltdb
 performance (#12141)

Co-authored-by: R.B. Boyer <4903+rboyer@users.noreply.github.com>
---
 website/content/docs/agent/telemetry.mdx | 56 +++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/agent/telemetry.mdx b/website/content/docs/agent/telemetry.mdx
index 0c8ea8d01d..9bb2ef5399 100644
--- a/website/content/docs/agent/telemetry.mdx
+++ b/website/content/docs/agent/telemetry.mdx
@@ -269,6 +269,60 @@ resources will still work.
 This metric should be monitored to ensure that the license doesn't expire to prevent degradation of functionality.
 
 
+### Bolt DB Performance
+
+| Metric Name                       | Description                                                      | Unit  | Type  |
+| :-------------------------------- | :--------------------------------------------------------------- | :---- | :---- |
+| `consul.raft.boltdb.freelistBytes`                  | Represents the number of bytes necessary to encode the freelist metadata. When [`raft_boltdb.NoFreelistSync`](/docs/agent/options#NoFreelistSync) is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge   |
+| `consul.raft.boltdb.logsPerBatch`                   | Measures the number of logs being written per batch to the db. | logs | sample |
+| `consul.raft.boltdb.storeLogs`                      | Measures the amount of time spent writing logs to the db. | ms | timer |
+
+
+** Requirements: **
+* Consul 1.11.0+
+
+**Why they're important:**
+
+The `consul.raft.boltdb.storeLogs` metric is a direct indicator of disk write performance of a Consul server. If there are issues with the disk or
+performance degradations related to Bolt DB, these metrics will show the issue and potentially the cause as well.
+
+**What to look for:**
+
+The primary thing to look for are increases in the `consul.raft.boltdb.storeLogs` times. Its value will directly govern an 
+upper limit to the throughput of write operations within Consul.
+
+In Consul each write operation will turn into a single Raft log to be committed. Raft will process these
+logs and store them within Bolt DB in batches. Each call to store logs within Bolt DB is measured to record how long
+it took as well as how many logs were contained in the batch. Writing logs is this fashion is serialized so that
+a subsequent log storage operation can only be started after the previous one completed. Therefore the maximum number
+of log storage operations that can be performed each second can be calculated with the following equation: 
+`(1000 ms) / (consul.raft.boltdb.storeLogs ms/op)`. From there we can extrapolate the maximum number of Consul writes
+per second by multiplying that value by the `consul.raft.boltdb.logsPerBatch` metric's value. When log storage 
+operations are becoming slower you may not see an immediate decrease in write throughput to Consul due to increased 
+batch sizes of the each operation. However, the max batch size allowed is 64 logs. Therefore if the `logsPerBatch`
+metric is near 64 and the `storeLogs` metric is seeing increased time to write each batch to disk, then it is likely 
+that increased write latencies and other errors may occur.
+
+There can be a number of potential issues that can cause this. Often times it could be performance of the underlying
+disks that is the issue. Other times it may be caused by Bolt DB behavior. Bolt DB keeps track of free space within
+the `raft.db` file. When needing to allocate data it will use existing free space first before further expanding the
+file. By default, Bolt DB will write a data structure containing metadata about free pages within the DB to disk for
+every log storage operation. Therefore if the free space within the database grows excessively large, such as after
+a large spike in writes beyond the normal steady state and a subsequent slow down in the write rate, then Bolt DB
+could end up writing a large amount of extra data to disk for each log storage operation. This has the potential
+to drastically increase disk write throughput, potentially beyond what the underlying disks can keep up with. To
+detect this situation you can look at the `consul.raft.boltdb.freelistBytes` metric. This metric is a count of
+the extra bytes that are being written for each log storage operation beyond the log data itself. While not a clear
+indicator of an actual issue, this metric can be used to diagnose why the `consul.raft.boltdb.storeLogs` metric
+is high. 
+
+If Bolt DB log storage performance becomes an issue and is caused by free list management then setting
+[`raft_boltdb.NoFreelistSync`](/docs/agent/options#NoFreelistSync) to `true` in the server's configuration
+may help to reduce disk IO and log storage operation times. Disabling free list syncing will however increase
+the startup time for a server as it must scan the raft.db file for free space instead of loading the already
+populated free list structure.
+
+
 ## Metrics Reference
 
 This is a full list of metrics emitted by Consul.
@@ -344,7 +398,7 @@ These metrics are used to monitor the health of the Consul servers.
 | `consul.raft.applied_index`                         | Represents the raft applied index.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | index                             | gauge   |
 | `consul.raft.apply`                                 | Counts the number of Raft transactions occurring over the interval, which is a general indicator of the write load on the Consul servers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | raft transactions / interval      | counter |
 | `consul.raft.barrier`                               | Counts the number of times the agent has started the barrier i.e the number of times it has issued a blocking call, to ensure that the agent has all the pending operations that were queued, to be applied to the agent's FSM.                                                                                                                                                                                                                                                                                                                                                                                                                               | blocks / interval                 | counter |
-| `consul.raft.boltdb.freelistBytes`                  | Represents the number of bytes necessary to encode the freelist metadata. When `raft_boltdb.NoFreelistSync` is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge   |
+| `consul.raft.boltdb.freelistBytes`                  | Represents the number of bytes necessary to encode the freelist metadata. When [`raft_boltdb.NoFreelistSync`](/docs/agent/options#NoFreelistSync) is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge   |
 | `consul.raft.boltdb.freePageBytes`                  | Represents the number of bytes of free space within the raft.db file. | bytes | gauge |
 | `consul.raft.boltdb.getLog`                         | Measures the amount of time spent reading logs from the db. | ms | timer |
 | `consul.raft.boltdb.logBatchSize`                   | Measures the total size in bytes of logs being written to the db in a single batch. | bytes | sample |

From 79f4d53079a63d29a29464850da1635864270163 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 8 Jul 2021 14:52:22 -0400
Subject: [PATCH 38/98] contrib: add first draft of Connect CA developer docs

Co-authored-by: Dhia Ayachi <dhia@hashicorp.com>
---
 docs/service-mesh/README.md                |  2 +-
 docs/service-mesh/ca/README.md             | 40 ++++++++++++++++++++++
 docs/service-mesh/ca/cert-relationship.mmd | 31 +++++++++++++++++
 docs/service-mesh/ca/cert-relationship.svg |  1 +
 4 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 docs/service-mesh/ca/README.md
 create mode 100644 docs/service-mesh/ca/cert-relationship.mmd
 create mode 100644 docs/service-mesh/ca/cert-relationship.svg

diff --git a/docs/service-mesh/README.md b/docs/service-mesh/README.md
index 7bc16f7f77..470fd28f29 100644
--- a/docs/service-mesh/README.md
+++ b/docs/service-mesh/README.md
@@ -3,7 +3,7 @@
 - call out: envoy/proxy is the data plane, Consul is the control plane
 - [xDS Server] - a gRPC service that implements [xDS] and handles requests from an [envoy proxy].
 - [agent/proxycfg]
-- CA Manager - certificate authority
+- [Certificate Authority](./ca) for issuing TLS certs for services and client agents
 - command/connect/envoy - bootstrapping and running envoy
 - command/connect/proxy - built-in proxy that is dev-only and not supported 
   for production.
diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
new file mode 100644
index 0000000000..7a12921772
--- /dev/null
+++ b/docs/service-mesh/ca/README.md
@@ -0,0 +1,40 @@
+# Certificate Authority (Connect CA)
+
+The Certificate Authority subsystem manages a CA trust chain for issuing certificates to
+services and client agents (via auto-encrypt and auto-config).
+
+## Architecture
+
+### High level overview
+
+- we can start with the mind map
+- high level explaination of what are the features that are involved in CA (mesh/connect, auto encrypt)
+- add all the func that are involved in the CA operations
+- relationship between the different certs
+
+
+### CA and Certificate relationship
+
+This diagram shows the relationship between the CA certificates in Consul primary and
+secondary.
+
+![CA relationship](./cert-relationship.svg)
+
+<sup>[source](./cert-relationship.mmd)</sup>
+
+TODO: describe the relationship
+
+* what does it mean for the external root CA to be optional
+  * it always exists , unless the Consul CA provider is used AND it has generated the CA
+    root.
+* relationship between Primary Root CA and Signing CA in the primary
+  * sometimes its the same thing (Consul, and AWS providers)
+  * sometimes it is different (Vault provider)
+* client agent cert is used by auto-encrypt for Agent HTTP TLS (and client side of RPC
+  TLS)
+* leaf cert service is the cert used by a service in the mesh
+
+### detailed call flow
+- sequence diagram for leader election
+- sequence diagram for leaf signing
+- sequence diagram for CA cert rotation
diff --git a/docs/service-mesh/ca/cert-relationship.mmd b/docs/service-mesh/ca/cert-relationship.mmd
new file mode 100644
index 0000000000..85ae848dcb
--- /dev/null
+++ b/docs/service-mesh/ca/cert-relationship.mmd
@@ -0,0 +1,31 @@
+graph TD
+ 
+    ExternalRootCA["External RootCA (optional)"]
+
+    subgraph "Consul Primary"
+        PrimaryRootCA["Primary Root CA"]
+        PrimarySigningCA["Primary Signing CA (conditional)"]
+    end
+
+    subgraph "Consul Secondary"
+        SeconarySigningCA["Seconary Signing CA"]
+    end
+
+    LeafCertAgentPrimary[Leaf Cert Client Agent]
+    LeafCertServicePrimary[Leaf Cert Service]
+
+    LeafCertAgentSecondary[Leaf Cert Client Agent]
+    LeafCertServiceSecondary[Leaf Cert Service]
+
+
+    ExternalRootCA -.-> PrimaryRootCA
+    PrimaryRootCA -.-> PrimarySigningCA
+
+    PrimaryRootCA --> SeconarySigningCA
+
+    PrimarySigningCA --> LeafCertAgentPrimary
+    PrimarySigningCA --> LeafCertServicePrimary
+
+    SeconarySigningCA --> LeafCertAgentSecondary
+    SeconarySigningCA --> LeafCertServiceSecondary
+
diff --git a/docs/service-mesh/ca/cert-relationship.svg b/docs/service-mesh/ca/cert-relationship.svg
new file mode 100644
index 0000000000..a32f838d19
--- /dev/null
+++ b/docs/service-mesh/ca/cert-relationship.svg
@@ -0,0 +1 @@
+<svg id="graph-div" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" height="417" style="max-width: 827.58984375px;" viewBox="0 0 827.58984375 417"><style>#graph-div{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#graph-div .error-icon{fill:#552222;}#graph-div .error-text{fill:#552222;stroke:#552222;}#graph-div .edge-thickness-normal{stroke-width:2px;}#graph-div .edge-thickness-thick{stroke-width:3.5px;}#graph-div .edge-pattern-solid{stroke-dasharray:0;}#graph-div .edge-pattern-dashed{stroke-dasharray:3;}#graph-div .edge-pattern-dotted{stroke-dasharray:2;}#graph-div .marker{fill:#333333;stroke:#333333;}#graph-div .marker.cross{stroke:#333333;}#graph-div svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#graph-div .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#graph-div .cluster-label text{fill:#333;}#graph-div .cluster-label span{color:#333;}#graph-div .label text,#graph-div span{fill:#333;color:#333;}#graph-div .node rect,#graph-div .node circle,#graph-div .node ellipse,#graph-div .node polygon,#graph-div .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#graph-div .node .label{text-align:center;}#graph-div .node.clickable{cursor:pointer;}#graph-div .arrowheadPath{fill:#333333;}#graph-div .edgePath .path{stroke:#333333;stroke-width:1.5px;}#graph-div .flowchart-link{stroke:#333333;fill:none;}#graph-div .edgeLabel{background-color:#e8e8e8;text-align:center;}#graph-div .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#graph-div .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#graph-div .cluster text{fill:#333;}#graph-div .cluster span{color:#333;}#graph-div div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80,100%,96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#graph-div .node rect,#graph-div .er.entityBox{fill:rgb(220,71,125);stroke-width:1;stroke:black;}#graph-div .node .label{color:white;}#graph-div .cluster rect{fill:#f0f0f0;stroke-width:1px;stroke:#333;}#graph-div .edgeLabel{background-color:#f0f0f0;}#graph-div .er.entityBox + .er.entityLabel{fill:white;}#graph-div .er.attributeBoxEven,#graph-div .er.attributeBoxOdd{fill:#fff;stroke:#777;}#graph-div:root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g><g class="output"><g class="clusters"><g class="cluster" id="flowchart-subGraph1-7796" transform="translate(636.9765625,268)" style="opacity: 1;"><rect width="358.484375" height="94" x="-179.2421875" y="-47"></rect><g class="label" transform="translate(0, -33)" id="graph-divText"><g transform="translate(-62.3828125,-12)"><foreignObject width="124.765625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul Secondary</div></foreignObject></g></g></g><g class="cluster" id="flowchart-subGraph0-7797" transform="translate(209.046875,208.5)" style="opacity: 1;"><rect width="402.09375" height="213" x="-201.046875" y="-106.5"></rect><g class="label" transform="translate(0, -92.5)" id="graph-divText"><g transform="translate(-53.203125,-12)"><foreignObject width="106.40625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul Primary</div></foreignObject></g></g></g></g><g class="edgePaths"><g class="edgePath LS-ExternalRootCA LE-PrimaryRootCA" id="L-ExternalRootCA-PrimaryRootCA" style="opacity: 1;"><path class="path" d="M224.046875,52L224.046875,56.166666666666664C224.046875,60.333333333333336,224.046875,68.66666666666667,224.046875,77C224.046875,85.33333333333333,224.046875,93.66666666666667,224.046875,102C224.046875,110.33333333333333,224.046875,118.66666666666667,224.046875,122.83333333333333L224.046875,127" marker-end="url(#arrowhead5097)" style="fill:none;stroke-width:2px;stroke-dasharray:3;"></path><defs><marker id="arrowhead5097" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimaryRootCA LE-PrimarySigningCA" id="L-PrimaryRootCA-PrimarySigningCA" style="opacity: 1;"><path class="path" d="M219.36602393617022,171L218.47949911347519,175.16666666666666C217.59297429078015,179.33333333333334,215.81992464539007,187.66666666666666,214.93339982269504,196C214.046875,204.33333333333334,214.046875,212.66666666666666,214.046875,221C214.046875,229.33333333333334,214.046875,237.66666666666666,214.046875,241.83333333333334L214.046875,246" marker-end="url(#arrowhead5098)" style="fill:none;stroke-width:2px;stroke-dasharray:3;"></path><defs><marker id="arrowhead5098" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimaryRootCA LE-SeconarySigningCA" id="L-PrimaryRootCA-SeconarySigningCA" style="opacity: 1;"><path class="path" d="M273.6364694148936,171L283.028438054078,175.16666666666666C292.4204066932624,179.33333333333334,311.2043439716312,187.66666666666666,320.5963126108156,196C329.98828125,204.33333333333334,329.98828125,212.66666666666666,368.3860677083333,222.61783253410795C406.7838541666667,232.56899840154918,483.5794270833333,244.1379968030984,521.9772135416666,249.922496003873L560.375,255.7069952046476" marker-end="url(#arrowhead5099)" style="fill:none"></path><defs><marker id="arrowhead5099" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimarySigningCA LE-LeafCertAgentPrimary" id="L-PrimarySigningCA-LeafCertAgentPrimary" style="opacity: 1;"><path class="path" d="M164.4572805851064,290L155.065311945922,294.1666666666667C145.6733433067376,298.3333333333333,126.8894060283688,306.6666666666667,117.49743738918441,315C108.10546875,323.3333333333333,108.10546875,331.6666666666667,108.10546875,340C108.10546875,348.3333333333333,108.10546875,356.6666666666667,108.10546875,360.8333333333333L108.10546875,365" marker-end="url(#arrowhead5100)" style="fill:none"></path><defs><marker id="arrowhead5100" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimarySigningCA LE-LeafCertServicePrimary" id="L-PrimarySigningCA-LeafCertServicePrimary" style="opacity: 1;"><path class="path" d="M263.6364694148936,290L273.028438054078,294.1666666666667C282.4204066932624,298.3333333333333,301.2043439716312,306.6666666666667,310.5963126108156,315C319.98828125,323.3333333333333,319.98828125,331.6666666666667,319.98828125,340C319.98828125,348.3333333333333,319.98828125,356.6666666666667,319.98828125,360.8333333333333L319.98828125,365" marker-end="url(#arrowhead5101)" style="fill:none"></path><defs><marker id="arrowhead5101" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-SeconarySigningCA LE-LeafCertAgentSecondary" id="L-SeconarySigningCA-LeafCertAgentSecondary" style="opacity: 1;"><path class="path" d="M592.3869680851063,290L582.994999445922,294.1666666666667C573.6030308067376,298.3333333333333,554.8190935283687,306.6666666666667,545.4271248891844,315C536.03515625,323.3333333333333,536.03515625,331.6666666666667,536.03515625,340C536.03515625,348.3333333333333,536.03515625,356.6666666666667,536.03515625,360.8333333333333L536.03515625,365" marker-end="url(#arrowhead5102)" style="fill:none"></path><defs><marker id="arrowhead5102" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-SeconarySigningCA LE-LeafCertServiceSecondary" id="L-SeconarySigningCA-LeafCertServiceSecondary" style="opacity: 1;"><path class="path" d="M691.5661569148937,290L700.958125554078,294.1666666666667C710.3500941932625,298.3333333333333,729.1340314716313,306.6666666666667,738.5260001108157,315C747.91796875,323.3333333333333,747.91796875,331.6666666666667,747.91796875,340C747.91796875,348.3333333333333,747.91796875,356.6666666666667,747.91796875,360.8333333333333L747.91796875,365" marker-end="url(#arrowhead5103)" style="fill:none"></path><defs><marker id="arrowhead5103" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g></g><g class="edgeLabels"><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-ExternalRootCA-PrimaryRootCA" class="edgeLabel L-LS-ExternalRootCA' L-LE-PrimaryRootCA"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimaryRootCA-PrimarySigningCA" class="edgeLabel L-LS-PrimaryRootCA' L-LE-PrimarySigningCA"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimaryRootCA-SeconarySigningCA" class="edgeLabel L-LS-PrimaryRootCA' L-LE-SeconarySigningCA"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimarySigningCA-LeafCertAgentPrimary" class="edgeLabel L-LS-PrimarySigningCA' L-LE-LeafCertAgentPrimary"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimarySigningCA-LeafCertServicePrimary" class="edgeLabel L-LS-PrimarySigningCA' L-LE-LeafCertServicePrimary"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-SeconarySigningCA-LeafCertAgentSecondary" class="edgeLabel L-LS-SeconarySigningCA' L-LE-LeafCertAgentSecondary"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-SeconarySigningCA-LeafCertServiceSecondary" class="edgeLabel L-LS-SeconarySigningCA' L-LE-LeafCertServiceSecondary"></span></div></foreignObject></g></g></g><g class="nodes"><g class="node default" id="flowchart-SeconarySigningCA-7777" transform="translate(641.9765625,268)" style="opacity: 1;"><rect rx="0" ry="0" x="-81.6015625" y="-22" width="163.203125" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-71.6015625,-12)"><foreignObject width="143.203125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Seconary Signing CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-PrimaryRootCA-7775" transform="translate(224.046875,149)" style="opacity: 1;"><rect rx="0" ry="0" x="-67.7890625" y="-22" width="135.578125" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-57.7890625,-12)"><foreignObject width="115.578125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Primary Root CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-PrimarySigningCA-7776" transform="translate(214.046875,268)" style="opacity: 1;"><rect rx="0" ry="0" x="-125.2109375" y="-22" width="250.421875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-115.2109375,-12)"><foreignObject width="230.421875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Primary Signing CA (conditional)</div></foreignObject></g></g></g><g class="node default" id="flowchart-ExternalRootCA-7774" transform="translate(224.046875,30)" style="opacity: 1;"><rect rx="0" ry="0" x="-105.59375" y="-22" width="211.1875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-95.59375,-12)"><foreignObject width="191.1875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">External RootCA (optional)</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertAgentPrimary-7778" transform="translate(108.10546875,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-90.2109375" y="-22" width="180.421875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-80.2109375,-12)"><foreignObject width="160.421875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Client Agent</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertServicePrimary-7779" transform="translate(319.98828125,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-71.671875" y="-22" width="143.34375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-61.671875,-12)"><foreignObject width="123.34375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Service</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertAgentSecondary-7780" transform="translate(536.03515625,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-90.2109375" y="-22" width="180.421875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-80.2109375,-12)"><foreignObject width="160.421875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Client Agent</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertServiceSecondary-7781" transform="translate(747.91796875,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-71.671875" y="-22" width="143.34375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-61.671875,-12)"><foreignObject width="123.34375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Service</div></foreignObject></g></g></g></g></g></g></svg>
\ No newline at end of file

From 440db2985ad57e135becf8c005c05e6951b8c4ab Mon Sep 17 00:00:00 2001
From: Dhia Ayachi <dhia@hashicorp.com>
Date: Thu, 8 Jul 2021 16:07:23 -0400
Subject: [PATCH 39/98] add HL diagram on the ca generation sequence

---
 docs/service-mesh/ca/README.md          | 10 ++++--
 docs/service-mesh/ca/hl-ca-overview.mmd | 43 +++++++++++++++++++++++++
 docs/service-mesh/ca/hl-ca-overview.svg |  1 +
 3 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 docs/service-mesh/ca/hl-ca-overview.mmd
 create mode 100644 docs/service-mesh/ca/hl-ca-overview.svg

diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
index 7a12921772..a9c7aaa4db 100644
--- a/docs/service-mesh/ca/README.md
+++ b/docs/service-mesh/ca/README.md
@@ -7,8 +7,14 @@ services and client agents (via auto-encrypt and auto-config).
 
 ### High level overview
 
-- we can start with the mind map
-- high level explaination of what are the features that are involved in CA (mesh/connect, auto encrypt)
+In Consul the leader is responsible for handling of the CA management. 
+When a leader election happen, and the elected leader do not have any root CA available it will start a process of creating a set of CA certificate.
+Those certificates will use to authenticate/encrypt communication between services (service mesh) or between `Consul client agent` (auto-encrypt/auto-config). This process is described in the following diagram:
+![CA creation](./hl-ca-overview.svg)
+
+<sup>[source](./hl-ca-overview.mmd)</sup>
+
+- high level explanation of what are the features that are involved in CA (mesh/connect, auto encrypt)
 - add all the func that are involved in the CA operations
 - relationship between the different certs
 
diff --git a/docs/service-mesh/ca/hl-ca-overview.mmd b/docs/service-mesh/ca/hl-ca-overview.mmd
new file mode 100644
index 0000000000..952f64b98f
--- /dev/null
+++ b/docs/service-mesh/ca/hl-ca-overview.mmd
@@ -0,0 +1,43 @@
+graph TD
+    subgraph "Primary DC"
+        leaderP["Leader"]
+        rootCAI["Root CA "]
+        rootCA["Root CA "]
+        Provider["Consul/AWS providers"]
+        IntermediateProvider["Vault provider"]
+        intermediateCAP["Intermediate CA "]
+        leafP["Leaf certificates"]
+    end
+
+    subgraph "Secondary DC"
+        leaderS["Leader"]
+        intermediateCAS["Intermediate CA"]
+        leafS["Leaf certificates"]
+        ProviderS["Consul/AWS/Vault providers"]
+    end
+
+    consulCAS["Consul client Agents"]
+    servicesS["Mesh services"]
+
+    consulCAP["Consul client Agents"]
+    servicesP["Mesh services"]
+    
+    leaderP -->|use|Provider
+    leaderP-->|use|IntermediateProvider
+    Provider--> |fetch/self sign|rootCA
+    IntermediateProvider --> |fetch/self sign|rootCAI 
+    rootCAI -->|sign| intermediateCAP
+    intermediateCAP -->|sign| leafP
+    rootCA -->|sign| leafP
+
+    leaderS -->|use| ProviderS
+    ProviderS --> |generate csr| intermediateCAS
+    rootCA -->|sign| intermediateCAS
+    rootCAI -->|sign| intermediateCAS
+    intermediateCAS --> |sign| leafS
+
+    leafS -->|auth/encrypt| servicesS
+    leafS -->|auth/encrypt| consulCAS
+    leafP -->|auth/encrypt| servicesP
+    leafP -->|auth/encrypt| consulCAP
+
diff --git a/docs/service-mesh/ca/hl-ca-overview.svg b/docs/service-mesh/ca/hl-ca-overview.svg
new file mode 100644
index 0000000000..76a6166245
--- /dev/null
+++ b/docs/service-mesh/ca/hl-ca-overview.svg
@@ -0,0 +1 @@
+<svg id="graph-div" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" height="725" style="max-width: 795.1953125px;" viewBox="0 0 795.1953125 725"><style>#graph-div{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#graph-div .error-icon{fill:#552222;}#graph-div .error-text{fill:#552222;stroke:#552222;}#graph-div .edge-thickness-normal{stroke-width:2px;}#graph-div .edge-thickness-thick{stroke-width:3.5px;}#graph-div .edge-pattern-solid{stroke-dasharray:0;}#graph-div .edge-pattern-dashed{stroke-dasharray:3;}#graph-div .edge-pattern-dotted{stroke-dasharray:2;}#graph-div .marker{fill:#333333;stroke:#333333;}#graph-div .marker.cross{stroke:#333333;}#graph-div svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#graph-div .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#graph-div .cluster-label text{fill:#333;}#graph-div .cluster-label span{color:#333;}#graph-div .label text,#graph-div span{fill:#333;color:#333;}#graph-div .node rect,#graph-div .node circle,#graph-div .node ellipse,#graph-div .node polygon,#graph-div .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#graph-div .node .label{text-align:center;}#graph-div .node.clickable{cursor:pointer;}#graph-div .arrowheadPath{fill:#333333;}#graph-div .edgePath .path{stroke:#333333;stroke-width:1.5px;}#graph-div .flowchart-link{stroke:#333333;fill:none;}#graph-div .edgeLabel{background-color:#e8e8e8;text-align:center;}#graph-div .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#graph-div .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#graph-div .cluster text{fill:#333;}#graph-div .cluster span{color:#333;}#graph-div div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80,100%,96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#graph-div .node rect,#graph-div .er.entityBox{fill:rgb(220,71,125);stroke-width:1;stroke:black;}#graph-div .node .label{color:white;}#graph-div .cluster rect{fill:#f0f0f0;stroke-width:1px;stroke:#333;}#graph-div .edgeLabel{background-color:#f0f0f0;}#graph-div .er.entityBox + .er.entityLabel{fill:white;}#graph-div .er.attributeBoxEven,#graph-div .er.attributeBoxOdd{fill:#fff;stroke:#777;}#graph-div:root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g><g class="output"><g class="clusters"><g class="cluster" id="flowchart-subGraph1-73217" transform="translate(181.203125,375)" style="opacity: 1;"><rect width="325.203125" height="448" x="-162.6015625" y="-224"></rect><g class="label" transform="translate(0, -210)" id="graph-divText"><g transform="translate(-48.65625,-12)"><foreignObject width="97.3125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Secondary DC</div></foreignObject></g></g></g><g class="cluster" id="flowchart-subGraph0-73218" transform="translate(575.5,303.5)" style="opacity: 1;"><rect width="423.390625" height="591" x="-211.6953125" y="-295.5"></rect><g class="label" transform="translate(0, -281.5)" id="graph-divText"><g transform="translate(-39.8515625,-12)"><foreignObject width="79.703125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Primary DC</div></foreignObject></g></g></g></g><g class="edgePaths"><g class="edgePath LS-leaderP LE-Provider" id="L-leaderP-Provider" style="opacity: 1;"><path class="path" d="M614.2552966101695,77L622.4731638418078,83.16666666666667C630.6910310734463,89.33333333333333,647.1267655367232,101.66666666666667,655.3446327683615,114C663.5625,126.33333333333333,663.5625,138.66666666666666,663.5625,149C663.5625,159.33333333333334,663.5625,167.66666666666666,663.5625,171.83333333333334L663.5625,176" marker-end="url(#arrowhead67890)" style="fill:none"></path><defs><marker id="arrowhead67890" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-leaderP LE-IntermediateProvider" id="L-leaderP-IntermediateProvider" style="opacity: 1;"><path class="path" d="M550.390625,71.81585562359007L535.9466145833334,78.84654635299172C521.5026041666666,85.87723708239338,492.6145833333333,99.9386185411967,478.1705729166667,113.13597593726502C463.7265625,126.33333333333333,463.7265625,138.66666666666666,463.7265625,149C463.7265625,159.33333333333334,463.7265625,167.66666666666666,463.7265625,171.83333333333334L463.7265625,176" marker-end="url(#arrowhead67891)" style="fill:none"></path><defs><marker id="arrowhead67891" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-Provider LE-rootCA" id="L-Provider-rootCA" style="opacity: 1;"><path class="path" d="M663.5625,220L663.5625,226.16666666666666C663.5625,232.33333333333334,663.5625,244.66666666666666,663.5625,257C663.5625,269.3333333333333,663.5625,281.6666666666667,663.5625,287.8333333333333L663.5625,294" marker-end="url(#arrowhead67892)" style="fill:none"></path><defs><marker id="arrowhead67892" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-IntermediateProvider LE-rootCAI" id="L-IntermediateProvider-rootCAI" style="opacity: 1;"><path class="path" d="M463.7265625,220L463.7265625,226.16666666666666C463.7265625,232.33333333333334,463.7265625,244.66666666666666,463.7265625,257C463.7265625,269.3333333333333,463.7265625,281.6666666666667,463.7265625,287.8333333333333L463.7265625,294" marker-end="url(#arrowhead67893)" style="fill:none"></path><defs><marker id="arrowhead67893" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-rootCAI LE-intermediateCAP" id="L-rootCAI-intermediateCAP" style="opacity: 1;"><path class="path" d="M484.6661811440678,338L490.53561970338984,344.1666666666667C496.4050582627119,350.3333333333333,508.14393538135596,362.6666666666667,514.013373940678,375C519.8828125,387.3333333333333,519.8828125,399.6666666666667,519.8828125,405.8333333333333L519.8828125,412" marker-end="url(#arrowhead67894)" style="fill:none"></path><defs><marker id="arrowhead67894" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-intermediateCAP LE-leafP" id="L-intermediateCAP-leafP" style="opacity: 1;"><path class="path" d="M519.8828125,456L519.8828125,462.1666666666667C519.8828125,468.3333333333333,519.8828125,480.6666666666667,532.5517522951977,493C545.2206920903955,505.3333333333333,570.558571680791,517.6666666666666,583.2275114759888,523.8333333333334L595.8964512711865,530" marker-end="url(#arrowhead67895)" style="fill:none"></path><defs><marker id="arrowhead67895" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-rootCA LE-leafP" id="L-rootCA-leafP" style="opacity: 1;"><path class="path" d="M680.2911811440678,338L684.9802811617232,344.1666666666667C689.6693811793784,350.3333333333333,699.0475812146892,362.6666666666667,703.7366812323447,378.6666666666667C708.42578125,394.6666666666667,708.42578125,414.3333333333333,708.42578125,434C708.42578125,453.6666666666667,708.42578125,473.3333333333333,701.3882525600283,489.3333333333333C694.3507238700564,505.3333333333333,680.2756664901129,517.6666666666666,673.2381378001412,523.8333333333334L666.2006091101695,530" marker-end="url(#arrowhead67896)" style="fill:none"></path><defs><marker id="arrowhead67896" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-leaderS LE-ProviderS" id="L-leaderS-ProviderS" style="opacity: 1;"><path class="path" d="M186.203125,220L186.203125,226.16666666666666C186.203125,232.33333333333334,186.203125,244.66666666666666,186.203125,257C186.203125,269.3333333333333,186.203125,281.6666666666667,186.203125,287.8333333333333L186.203125,294" marker-end="url(#arrowhead67897)" style="fill:none"></path><defs><marker id="arrowhead67897" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-ProviderS LE-intermediateCAS" id="L-ProviderS-intermediateCAS" style="opacity: 1;"><path class="path" d="M186.203125,338L186.203125,344.1666666666667C186.203125,350.3333333333333,186.203125,362.6666666666667,186.203125,375C186.203125,387.3333333333333,186.203125,399.6666666666667,186.203125,405.8333333333333L186.203125,412" marker-end="url(#arrowhead67898)" style="fill:none"></path><defs><marker id="arrowhead67898" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-rootCA LE-intermediateCAS" id="L-rootCA-intermediateCAS" style="opacity: 1;"><path class="path" d="M635.2191472457628,338L627.2744195798023,344.1666666666667C619.3296919138419,350.3333333333333,603.4402365819209,362.6666666666667,540.0443370409604,376.9849173520204C476.6484375,391.30316803737406,365.74609375,407.6063360747482,310.294921875,415.7579200934352L254.84375,423.90950411212225" marker-end="url(#arrowhead67899)" style="fill:none"></path><defs><marker id="arrowhead67899" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-rootCAI LE-intermediateCAS" id="L-rootCAI-intermediateCAS" style="opacity: 1;"><path class="path" d="M450.7252383474576,338L447.080927789548,344.1666666666667C443.4366172316384,350.3333333333333,436.14799611581924,362.6666666666667,403.5010813912429,375.88509336767544C370.8541666666667,389.10352006868425,312.8489583333333,403.2070401373685,283.8463541666667,410.2588001717107L254.84375,417.3105602060528" marker-end="url(#arrowhead67900)" style="fill:none"></path><defs><marker id="arrowhead67900" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-intermediateCAS LE-leafS" id="L-intermediateCAS-leafS" style="opacity: 1;"><path class="path" d="M186.203125,456L186.203125,462.1666666666667C186.203125,468.3333333333333,186.203125,480.6666666666667,186.203125,493C186.203125,505.3333333333333,186.203125,517.6666666666666,186.203125,523.8333333333334L186.203125,530" marker-end="url(#arrowhead67901)" style="fill:none"></path><defs><marker id="arrowhead67901" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-leafS LE-servicesS" id="L-leafS-servicesS" style="opacity: 1;"><path class="path" d="M230.94182180851064,574L239.41505984042553,578.1666666666666C247.88829787234044,582.3333333333334,264.8347739361702,590.6666666666666,273.3080119680851,601C281.78125,611.3333333333334,281.78125,623.6666666666666,281.78125,636C281.78125,648.3333333333334,281.78125,660.6666666666666,281.78125,666.8333333333334L281.78125,673" marker-end="url(#arrowhead67902)" style="fill:none"></path><defs><marker id="arrowhead67902" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-leafS LE-consulCAS" id="L-leafS-consulCAS" style="opacity: 1;"><path class="path" d="M141.46442819148936,574L132.99119015957447,578.1666666666666C124.51795212765957,582.3333333333334,107.57147606382978,590.6666666666666,99.09823803191489,601C90.625,611.3333333333334,90.625,623.6666666666666,90.625,636C90.625,648.3333333333334,90.625,660.6666666666666,90.625,666.8333333333334L90.625,673" marker-end="url(#arrowhead67903)" style="fill:none"></path><defs><marker id="arrowhead67903" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-leafP LE-servicesP" id="L-leafP-servicesP" style="opacity: 1;"><path class="path" d="M675.8655252659574,574L682.4510887632979,578.1666666666666C689.0366522606382,582.3333333333334,702.2077792553191,590.6666666666666,708.7933427526596,601C715.37890625,611.3333333333334,715.37890625,623.6666666666666,715.37890625,636C715.37890625,648.3333333333334,715.37890625,660.6666666666666,715.37890625,666.8333333333334L715.37890625,673" marker-end="url(#arrowhead67904)" style="fill:none"></path><defs><marker id="arrowhead67904" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-leafP LE-consulCAP" id="L-leafP-consulCAP" style="opacity: 1;"><path class="path" d="M575.8068484042553,574L563.4419049202128,578.1666666666666C551.0769614361702,582.3333333333334,526.3470744680851,590.6666666666666,513.9821309840426,601C501.6171875,611.3333333333334,501.6171875,623.6666666666666,501.6171875,636C501.6171875,648.3333333333334,501.6171875,660.6666666666666,501.6171875,666.8333333333334L501.6171875,673" marker-end="url(#arrowhead67905)" style="fill:none"></path><defs><marker id="arrowhead67905" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g></g><g class="edgeLabels"><g class="edgeLabel" transform="translate(663.5625,114)" style="opacity: 1;"><g transform="translate(-11.9765625,-12)" class="label"><rect rx="0" ry="0" width="23.953125" height="24"></rect><foreignObject width="23.953125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-leaderP-Provider" class="edgeLabel L-LS-leaderP' L-LE-Provider">use</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(463.7265625,114)" style="opacity: 1;"><g transform="translate(-11.9765625,-12)" class="label"><rect rx="0" ry="0" width="23.953125" height="24"></rect><foreignObject width="23.953125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-leaderP-IntermediateProvider" class="edgeLabel L-LS-leaderP' L-LE-IntermediateProvider">use</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(663.5625,257)" style="opacity: 1;"><g transform="translate(-52.2578125,-12)" class="label"><rect rx="0" ry="0" width="104.515625" height="24"></rect><foreignObject width="104.515625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-Provider-rootCA" class="edgeLabel L-LS-Provider' L-LE-rootCA">fetch/self sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(463.7265625,257)" style="opacity: 1;"><g transform="translate(-52.2578125,-12)" class="label"><rect rx="0" ry="0" width="104.515625" height="24"></rect><foreignObject width="104.515625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-IntermediateProvider-rootCAI" class="edgeLabel L-LS-IntermediateProvider' L-LE-rootCAI">fetch/self sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(519.8828125,375)" style="opacity: 1;"><g transform="translate(-13.90625,-12)" class="label"><rect rx="0" ry="0" width="27.8125" height="24"></rect><foreignObject width="27.8125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-rootCAI-intermediateCAP" class="edgeLabel L-LS-rootCAI' L-LE-intermediateCAP">sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(519.8828125,493)" style="opacity: 1;"><g transform="translate(-13.90625,-12)" class="label"><rect rx="0" ry="0" width="27.8125" height="24"></rect><foreignObject width="27.8125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-intermediateCAP-leafP" class="edgeLabel L-LS-intermediateCAP' L-LE-leafP">sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(708.42578125,434)" style="opacity: 1;"><g transform="translate(-13.90625,-12)" class="label"><rect rx="0" ry="0" width="27.8125" height="24"></rect><foreignObject width="27.8125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-rootCA-leafP" class="edgeLabel L-LS-rootCA' L-LE-leafP">sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(186.203125,257)" style="opacity: 1;"><g transform="translate(-11.9765625,-12)" class="label"><rect rx="0" ry="0" width="23.953125" height="24"></rect><foreignObject width="23.953125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-leaderS-ProviderS" class="edgeLabel L-LS-leaderS' L-LE-ProviderS">use</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(186.203125,375)" style="opacity: 1;"><g transform="translate(-44.6796875,-12)" class="label"><rect rx="0" ry="0" width="89.359375" height="24"></rect><foreignObject width="89.359375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-ProviderS-intermediateCAS" class="edgeLabel L-LS-ProviderS' L-LE-intermediateCAS">generate csr</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(587.55078125,375)" style="opacity: 1;"><g transform="translate(-13.90625,-12)" class="label"><rect rx="0" ry="0" width="27.8125" height="24"></rect><foreignObject width="27.8125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-rootCA-intermediateCAS" class="edgeLabel L-LS-rootCA' L-LE-intermediateCAS">sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(428.859375,375)" style="opacity: 1;"><g transform="translate(-13.90625,-12)" class="label"><rect rx="0" ry="0" width="27.8125" height="24"></rect><foreignObject width="27.8125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-rootCAI-intermediateCAS" class="edgeLabel L-LS-rootCAI' L-LE-intermediateCAS">sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(186.203125,493)" style="opacity: 1;"><g transform="translate(-13.90625,-12)" class="label"><rect rx="0" ry="0" width="27.8125" height="24"></rect><foreignObject width="27.8125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-intermediateCAS-leafS" class="edgeLabel L-LS-intermediateCAS' L-LE-leafS">sign</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(281.78125,636)" style="opacity: 1;"><g transform="translate(-47.6953125,-12)" class="label"><rect rx="0" ry="0" width="95.390625" height="24"></rect><foreignObject width="95.390625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-leafS-servicesS" class="edgeLabel L-LS-leafS' L-LE-servicesS">auth/encrypt</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(90.625,636)" style="opacity: 1;"><g transform="translate(-47.6953125,-12)" class="label"><rect rx="0" ry="0" width="95.390625" height="24"></rect><foreignObject width="95.390625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-leafS-consulCAS" class="edgeLabel L-LS-leafS' L-LE-consulCAS">auth/encrypt</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(715.37890625,636)" style="opacity: 1;"><g transform="translate(-47.6953125,-12)" class="label"><rect rx="0" ry="0" width="95.390625" height="24"></rect><foreignObject width="95.390625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-leafP-servicesP" class="edgeLabel L-LS-leafP' L-LE-servicesP">auth/encrypt</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(501.6171875,636)" style="opacity: 1;"><g transform="translate(-47.6953125,-12)" class="label"><rect rx="0" ry="0" width="95.390625" height="24"></rect><foreignObject width="95.390625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-leafP-consulCAP" class="edgeLabel L-LS-leafP' L-LE-consulCAP">auth/encrypt</span></div></foreignObject></g></g></g><g class="nodes"><g class="node default" id="flowchart-leaderS-73177" transform="translate(186.203125,198)" style="opacity: 1;"><rect rx="0" ry="0" x="-34.546875" y="-22" width="69.09375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-24.546875,-12)"><foreignObject width="49.09375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leader</div></foreignObject></g></g></g><g class="node default" id="flowchart-intermediateCAS-73178" transform="translate(186.203125,434)" style="opacity: 1;"><rect rx="0" ry="0" x="-68.640625" y="-22" width="137.28125" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-58.640625,-12)"><foreignObject width="117.28125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Intermediate CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-leafS-73179" transform="translate(186.203125,552)" style="opacity: 1;"><rect rx="0" ry="0" x="-69.046875" y="-22" width="138.09375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-59.046875,-12)"><foreignObject width="118.09375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf certificates</div></foreignObject></g></g></g><g class="node default" id="flowchart-ProviderS-73180" transform="translate(186.203125,316)" style="opacity: 1;"><rect rx="0" ry="0" x="-111.6328125" y="-22" width="223.265625" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-101.6328125,-12)"><foreignObject width="203.265625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul/AWS/Vault providers</div></foreignObject></g></g></g><g class="node default" id="flowchart-leaderP-73170" transform="translate(584.9375,55)" style="opacity: 1;"><rect rx="0" ry="0" x="-34.546875" y="-22" width="69.09375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-24.546875,-12)"><foreignObject width="49.09375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leader</div></foreignObject></g></g></g><g class="node default" id="flowchart-rootCAI-73171" transform="translate(463.7265625,316)" style="opacity: 1;"><rect rx="0" ry="0" x="-38.328125" y="-22" width="76.65625" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-28.328125,-12)"><foreignObject width="56.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Root CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-rootCA-73172" transform="translate(663.5625,316)" style="opacity: 1;"><rect rx="0" ry="0" x="-38.328125" y="-22" width="76.65625" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-28.328125,-12)"><foreignObject width="56.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Root CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-Provider-73173" transform="translate(663.5625,198)" style="opacity: 1;"><rect rx="0" ry="0" x="-88.6328125" y="-22" width="177.265625" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-78.6328125,-12)"><foreignObject width="157.265625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul/AWS providers</div></foreignObject></g></g></g><g class="node default" id="flowchart-IntermediateProvider-73174" transform="translate(463.7265625,198)" style="opacity: 1;"><rect rx="0" ry="0" x="-61.203125" y="-22" width="122.40625" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-51.203125,-12)"><foreignObject width="102.40625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Vault provider</div></foreignObject></g></g></g><g class="node default" id="flowchart-intermediateCAP-73175" transform="translate(519.8828125,434)" style="opacity: 1;"><rect rx="0" ry="0" x="-68.640625" y="-22" width="137.28125" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-58.640625,-12)"><foreignObject width="117.28125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Intermediate CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-leafP-73176" transform="translate(641.09375,552)" style="opacity: 1;"><rect rx="0" ry="0" x="-69.046875" y="-22" width="138.09375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-59.046875,-12)"><foreignObject width="118.09375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf certificates</div></foreignObject></g></g></g><g class="node default" id="flowchart-consulCAS-73181" transform="translate(90.625,695)" style="opacity: 1;"><rect rx="0" ry="0" x="-82.625" y="-22" width="165.25" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-72.625,-12)"><foreignObject width="145.25" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul client Agents</div></foreignObject></g></g></g><g class="node default" id="flowchart-servicesS-73182" transform="translate(281.78125,695)" style="opacity: 1;"><rect rx="0" ry="0" x="-58.53125" y="-22" width="117.0625" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-48.53125,-12)"><foreignObject width="97.0625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Mesh services</div></foreignObject></g></g></g><g class="node default" id="flowchart-consulCAP-73183" transform="translate(501.6171875,695)" style="opacity: 1;"><rect rx="0" ry="0" x="-82.625" y="-22" width="165.25" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-72.625,-12)"><foreignObject width="145.25" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul client Agents</div></foreignObject></g></g></g><g class="node default" id="flowchart-servicesP-73184" transform="translate(715.37890625,695)" style="opacity: 1;"><rect rx="0" ry="0" x="-58.53125" y="-22" width="117.0625" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-48.53125,-12)"><foreignObject width="97.0625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Mesh services</div></foreignObject></g></g></g></g></g></g></svg>
\ No newline at end of file

From c5c5d7777cdede8409c4b3aa8aca98964d9604e2 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 8 Jul 2021 17:07:15 -0400
Subject: [PATCH 40/98] contrib: add description of cert relationship diagram

And links to code
---
 docs/service-mesh/ca/README.md | 42 +++++++++++++++++++++++++---------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
index a9c7aaa4db..39f7f6ecf4 100644
--- a/docs/service-mesh/ca/README.md
+++ b/docs/service-mesh/ca/README.md
@@ -3,6 +3,17 @@
 The Certificate Authority subsystem manages a CA trust chain for issuing certificates to
 services and client agents (via auto-encrypt and auto-config).
 
+The code for the Certificate Authority is in the following packages:
+1. most of the core logic is in [agent/consul/leader_connect_ca.go]
+2. the providers are in [agent/connect/ca]
+3. the RPC interface is in [agent/consul/connect_ca_endpoint.go]
+
+
+[agent/consul/leader_connect_ca.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/leader_connect_ca.go
+[agent/connect/ca]: https://github.com/hashicorp/consul/blob/main/agent/connect/ca/
+[agent/consul/connect_ca_endpoint.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/connect_ca_endpoint.go
+
+
 ## Architecture
 
 ### High level overview
@@ -10,6 +21,7 @@ services and client agents (via auto-encrypt and auto-config).
 In Consul the leader is responsible for handling of the CA management. 
 When a leader election happen, and the elected leader do not have any root CA available it will start a process of creating a set of CA certificate.
 Those certificates will use to authenticate/encrypt communication between services (service mesh) or between `Consul client agent` (auto-encrypt/auto-config). This process is described in the following diagram:
+
 ![CA creation](./hl-ca-overview.svg)
 
 <sup>[source](./hl-ca-overview.mmd)</sup>
@@ -28,17 +40,25 @@ secondary.
 
 <sup>[source](./cert-relationship.mmd)</sup>
 
-TODO: describe the relationship
-
-* what does it mean for the external root CA to be optional
-  * it always exists , unless the Consul CA provider is used AND it has generated the CA
-    root.
-* relationship between Primary Root CA and Signing CA in the primary
-  * sometimes its the same thing (Consul, and AWS providers)
-  * sometimes it is different (Vault provider)
-* client agent cert is used by auto-encrypt for Agent HTTP TLS (and client side of RPC
-  TLS)
-* leaf cert service is the cert used by a service in the mesh
+
+In most cases there is an external root CA that provides an intermediate CA that Consul
+uses as the Primary Root CA. The only except to this is when the Consul CA Provider is
+used without specifying a `RootCert`. In this one case Consul will generate the the Root CA
+from the provided primary key, and it will be used in the primary as the top of the chain
+of trust.
+
+In the primary datacenter, the Consul and AWS providers use the Primary Root CA to sign
+leaf certificates. The Vault provider uses an intermediate CA to sign leaf certificates.
+
+Leaf certificates are created for two purposes:
+1. the Leaf Cert Service is used by envoy proxies in the mesh to perform mTLS with other
+   services.
+2. the Leaf Cert Client Agent is created by auto-encrypt and auto-config. It is used by
+   client agents for HTTP API TLS, and for mTLS for RPC requests to servers.
+
+Any secondary datacenters receive an intermediate certificate, signed by the Primary Root
+CA, which is used as the CA certificate to sign leaf certificates in the secondary
+datacenter.
 
 ### detailed call flow
 - sequence diagram for leader election

From 9a7a06f9f865fecefd87e4b93ecb6087f8ae3e31 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 8 Jul 2021 17:13:31 -0400
Subject: [PATCH 41/98] contrib: add CA operations

---
 docs/service-mesh/ca/README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
index 39f7f6ecf4..719d2881f6 100644
--- a/docs/service-mesh/ca/README.md
+++ b/docs/service-mesh/ca/README.md
@@ -60,6 +60,40 @@ Any secondary datacenters receive an intermediate certificate, signed by the Pri
 CA, which is used as the CA certificate to sign leaf certificates in the secondary
 datacenter.
 
+## Operations
+
+When trying to learn the CA subsystem it can be helpful to understand the operations that
+it can perform. The sections below are the complete set of read, write, and periodic
+operations that provide the full behaviour of the CA subsystem.
+
+### Periodic Operations
+
+Periodic (or background) opeartions are started automatically by the Consul leader. They run at some interval (often 1 hour).
+
+- `CAManager.InitializeCA` - attempts to initialize the CA when a leader is ellected. If the synchronous InitializeCA fails, `CAManager.backgroundCAInitialization` runs `InitializeCA` periodically in a goroutine until it succeeds.
+- `CAManager.RenewIntermediate` - (called by `CAManager.intermediateCertRenewalWatch`) runs in the primary if the provider uses a separate signing cert (the Vault provider). The operation always runs in the secondary. Renews the signing cert once half its lifetime has passed.
+- `CAManager.secondaryCARootWatch` - runs in secondary only. Performs a blocking query to the primary to retrieve any updates to the CA roots and stores them locally.
+- `Server.runCARootPruning` - removes non-active and expired roots from state.CARoots
+
+### Read Operations
+
+- `RPC.ConnectCA.ConfigurationGet` - returns the CA provider configuration. Only called by user, not by any internal subsystems.
+- `RPC.ConnectCA.Roots` - returns all the roots, the trust domain ID, and the ID of the active root. Each "root" also includes the signing key/cert, and any intermediate certs in the chain. It is used (via the cache) by all the connect proxy types.
+
+### Write Operations
+
+- `CAManager.UpdateConfiguration` - (via `RPC.ConnectCA.ConfigurationSet`) called by a user when they want to change the provider or provider configuration (ex: rotate root CA).
+- `CAManager.Provider.SignIntermediate` - (via `RPC.ConnectCA.SignIntermediate`) called from the secondary DC:
+    1. by `CAManager.RenewIntermediate` to sign the new intermediate when the old intermediate is about to expire
+    2. by `CAMananger.initializeSecondary` when setting up a new secondary, when the provider is changed in the secondary
+   by a user action, or when the primary roots changed and the secondary needs to generate a new intermediate for the new
+   primary roots.
+- `CAMananger.SignCertificate` - is used by:
+    1. (via `RPC.ConnectCA.Sign`) - called by client agents to sign a leaf cert for a connect proxy (via `agent/cache-types/connect_ca_leaf.go`)
+    2. (via in-process call to `RPC.ConnectCA.Sign`) - called by auto-encrypt to sign a leaf cert for a client agent
+    3. called by Auto-Config to sign a leaf cert for a client agent
+
+
 ### detailed call flow
 - sequence diagram for leader election
 - sequence diagram for leaf signing

From fa833ac0f814cf6dd55a054aaf648a5d8aa727d5 Mon Sep 17 00:00:00 2001
From: Dhia Ayachi <dhia@hashicorp.com>
Date: Fri, 9 Jul 2021 10:28:03 -0400
Subject: [PATCH 42/98] fix types and add reference to mesh and auto_config
 docs

---
 docs/service-mesh/ca/README.md | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
index 719d2881f6..40861a851f 100644
--- a/docs/service-mesh/ca/README.md
+++ b/docs/service-mesh/ca/README.md
@@ -18,17 +18,17 @@ The code for the Certificate Authority is in the following packages:
 
 ### High level overview
 
-In Consul the leader is responsible for handling of the CA management. 
+In Consul the leader is responsible for handling the CA management. 
 When a leader election happen, and the elected leader do not have any root CA available it will start a process of creating a set of CA certificate.
-Those certificates will use to authenticate/encrypt communication between services (service mesh) or between `Consul client agent` (auto-encrypt/auto-config). This process is described in the following diagram:
+Those certificates will be used to authenticate/encrypt communication between services (service mesh) or between `Consul client agent` (auto-encrypt/auto-config). This process is described in the following diagram:
 
 ![CA creation](./hl-ca-overview.svg)
 
 <sup>[source](./hl-ca-overview.mmd)</sup>
 
-- high level explanation of what are the features that are involved in CA (mesh/connect, auto encrypt)
-- add all the func that are involved in the CA operations
-- relationship between the different certs
+The features that benefit from Consul CA management are:
+- [service Mesh/Connect](https://www.consul.io/docs/connect)
+- [auto encrypt](https://www.consul.io/docs/agent/options#auto_encrypt)
 
 
 ### CA and Certificate relationship
@@ -43,7 +43,7 @@ secondary.
 
 In most cases there is an external root CA that provides an intermediate CA that Consul
 uses as the Primary Root CA. The only except to this is when the Consul CA Provider is
-used without specifying a `RootCert`. In this one case Consul will generate the the Root CA
+used without specifying a `RootCert`. In this one case Consul will generate the Root CA
 from the provided primary key, and it will be used in the primary as the top of the chain
 of trust.
 
@@ -93,7 +93,6 @@ Periodic (or background) opeartions are started automatically by the Consul lead
     2. (via in-process call to `RPC.ConnectCA.Sign`) - called by auto-encrypt to sign a leaf cert for a client agent
     3. called by Auto-Config to sign a leaf cert for a client agent
 
-
 ### detailed call flow
 - sequence diagram for leader election
 - sequence diagram for leaf signing

From b843a98890264790f5d1b22947c944f58cc9fe58 Mon Sep 17 00:00:00 2001
From: Dhia Ayachi <dhia@hashicorp.com>
Date: Fri, 9 Jul 2021 10:28:30 -0400
Subject: [PATCH 43/98] Add sequence diagram for leader boot sequence

---
 docs/service-mesh/ca/README.md              |  5 ++++-
 docs/service-mesh/ca/ca-leader-sequence.mmd | 19 +++++++++++++++++++
 docs/service-mesh/ca/ca-leader-sequence.svg |  1 +
 3 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 docs/service-mesh/ca/ca-leader-sequence.mmd
 create mode 100644 docs/service-mesh/ca/ca-leader-sequence.svg

diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
index 40861a851f..809dae8253 100644
--- a/docs/service-mesh/ca/README.md
+++ b/docs/service-mesh/ca/README.md
@@ -94,6 +94,9 @@ Periodic (or background) opeartions are started automatically by the Consul lead
     3. called by Auto-Config to sign a leaf cert for a client agent
 
 ### detailed call flow
-- sequence diagram for leader election
+![CA Leader Sequence](./ca-leader-sequence.svg)
+
+<sup>[source](./ca-leader-sequence.mmd)</sup>
+
 - sequence diagram for leaf signing
 - sequence diagram for CA cert rotation
diff --git a/docs/service-mesh/ca/ca-leader-sequence.mmd b/docs/service-mesh/ca/ca-leader-sequence.mmd
new file mode 100644
index 0000000000..f81e66b7ab
--- /dev/null
+++ b/docs/service-mesh/ca/ca-leader-sequence.mmd
@@ -0,0 +1,19 @@
+sequenceDiagram
+Participant Provider
+Participant PL As Primary Leader
+Participant SL As Secondary Leader
+Alt Primary don't have a valid CA
+PL->>Provider:initializeRootCA (fetch root and sign intermediate)
+Provider->>PL:root + intermediate
+PL->>PL:RPC ConnectCA.Roots (fetch primary root and store it)
+end
+SL->>PL: RPC ConnectCA.Roots (fetch primary root and store it)
+PL->>SL: Root + intermediate
+Alt Secondary needs a new intermediate (check if current intermediate is signed by primary root)
+SL->>Provider: Generate CSR
+Provider->>SL: CSR
+SL->>PL: ConnectCA.SignIntermediate (CSR)
+PL->>SL: Intermediate CA (secondary)
+SL->>Provider: Set Intermediate (secondary CA) + root (primary CA)
+SL->>SL: Store certs in RAFT (primary root + secondary intermediate)
+end
\ No newline at end of file
diff --git a/docs/service-mesh/ca/ca-leader-sequence.svg b/docs/service-mesh/ca/ca-leader-sequence.svg
new file mode 100644
index 0000000000..d19b957e44
--- /dev/null
+++ b/docs/service-mesh/ca/ca-leader-sequence.svg
@@ -0,0 +1 @@
+<svg id="graph-div" width="100%" xmlns="http://www.w3.org/2000/svg" height="919" style="max-width: 1298px;" viewBox="-50 -10 1298 919"><style>#graph-div{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#graph-div .error-icon{fill:#552222;}#graph-div .error-text{fill:#552222;stroke:#552222;}#graph-div .edge-thickness-normal{stroke-width:2px;}#graph-div .edge-thickness-thick{stroke-width:3.5px;}#graph-div .edge-pattern-solid{stroke-dasharray:0;}#graph-div .edge-pattern-dashed{stroke-dasharray:3;}#graph-div .edge-pattern-dotted{stroke-dasharray:2;}#graph-div .marker{fill:#333333;stroke:#333333;}#graph-div .marker.cross{stroke:#333333;}#graph-div svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#graph-div .actor{stroke:hsl(259.6261682243,59.7765363128%,87.9019607843%);fill:#ECECFF;}#graph-div text.actor &gt; tspan{fill:black;stroke:none;}#graph-div .actor-line{stroke:grey;}#graph-div .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#graph-div .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#graph-div #arrowhead path{fill:#333;stroke:#333;}#graph-div .sequenceNumber{fill:white;}#graph-div #sequencenumber{fill:#333;}#graph-div #crosshead path{fill:#333;stroke:#333;}#graph-div .messageText{fill:#333;stroke:#333;}#graph-div .labelBox{stroke:hsl(259.6261682243,59.7765363128%,87.9019607843%);fill:#ECECFF;}#graph-div .labelText,#graph-div .labelText &gt; tspan{fill:black;stroke:none;}#graph-div .loopText,#graph-div .loopText &gt; tspan{fill:black;stroke:none;}#graph-div .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243,59.7765363128%,87.9019607843%);fill:hsl(259.6261682243,59.7765363128%,87.9019607843%);}#graph-div .note{stroke:#aaaa33;fill:#fff5ad;}#graph-div .noteText,#graph-div .noteText &gt; tspan{fill:black;stroke:none;}#graph-div .activation0{fill:#f4f4f4;stroke:#666;}#graph-div .activation1{fill:#f4f4f4;stroke:#666;}#graph-div .activation2{fill:#f4f4f4;stroke:#666;}#graph-div .actor,#graph-div .er.entityBox{fill:rgb(220,71,125);stroke-width:1;stroke:black;}#graph-div .note{fill:#f0f0f0;stroke-width:1px;stroke:#333;}#graph-div .edgeLabel{background-color:#f0f0f0;}#graph-div .er.entityBox + .er.entityLabel{fill:white;}#graph-div .er.attributeBoxEven,#graph-div .er.attributeBoxOdd{fill:#fff;stroke:#777;}#graph-div:root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g></g><g><line id="actor654" x1="75" y1="5" x2="75" y2="908" class="actor-line" stroke-width="0.5px" stroke="#999"></line><rect x="0" y="0" fill="#eaeaea" stroke="#666" width="150" height="65" rx="3" ry="3" class="actor"></rect><text x="75" y="32.5" dominant-baseline="central" alignment-baseline="central" class="actor" style="text-anchor: middle; font-size: 14px; font-weight: 400; font-family: Open-Sans, sans-serif;"><tspan x="75" dy="0">Provider</tspan></text></g><g><line id="actor655" x1="510" y1="5" x2="510" y2="908" class="actor-line" stroke-width="0.5px" stroke="#999"></line><rect x="435" y="0" fill="#eaeaea" stroke="#666" width="150" height="65" rx="3" ry="3" class="actor"></rect><text x="510" y="32.5" dominant-baseline="central" alignment-baseline="central" class="actor" style="text-anchor: middle; font-size: 14px; font-weight: 400; font-family: Open-Sans, sans-serif;"><tspan x="510" dy="0">Primary Leader</tspan></text></g><g><line id="actor656" x1="972" y1="5" x2="972" y2="908" class="actor-line" stroke-width="0.5px" stroke="#999"></line><rect x="897" y="0" fill="#eaeaea" stroke="#666" width="150" height="65" rx="3" ry="3" class="actor"></rect><text x="972" y="32.5" dominant-baseline="central" alignment-baseline="central" class="actor" style="text-anchor: middle; font-size: 14px; font-weight: 400; font-family: Open-Sans, sans-serif;"><tspan x="972" dy="0">Secondary Leader</tspan></text></g><defs><marker id="arrowhead" refX="9" refY="5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z"></path></marker></defs><defs><marker id="crosshead" markerWidth="15" markerHeight="8" orient="auto" refX="16" refY="4"><path fill="black" stroke="#000000" stroke-width="1px" d="M 9,2 V 6 L16,4 Z" style="stroke-dasharray: 0, 0;"></path><path fill="none" stroke="#000000" stroke-width="1px" d="M 0,1 L 6,7 M 6,1 L 0,7" style="stroke-dasharray: 0, 0;"></path></marker></defs><defs><marker id="filled-head" refX="18" refY="7" markerWidth="20" markerHeight="28" orient="auto"><path d="M 18,7 L9,13 L14,7 L9,1 Z"></path></marker></defs><defs><marker id="sequencenumber" refX="15" refY="15" markerWidth="60" markerHeight="40" orient="auto"><circle cx="15" cy="15" r="6"></circle></marker></defs><text x="293" y="125" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">initializeRootCA (fetch root and sign intermediate)</text><line x1="510" y1="158" x2="75" y2="158" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="293" y="173" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">root + intermediate</text><line x1="75" y1="206" x2="510" y2="206" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="510" y="221" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">RPC ConnectCA.Roots (fetch primary root and store it)</text><path d="M 510,254 C 570,244 570,284 510,274" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></path><g><line x1="65" y1="75" x2="716" y2="75" class="loopLine"></line><line x1="716" y1="75" x2="716" y2="324" class="loopLine"></line><line x1="65" y1="324" x2="716" y2="324" class="loopLine"></line><line x1="65" y1="75" x2="65" y2="324" class="loopLine"></line><polygon points="65,75 115,75 115,88 106.6,95 65,95" class="labelBox"></polygon><text x="90" y="88" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="labelText" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">alt</text><text x="415.5" y="93" text-anchor="middle" class="loopText" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;"><tspan x="415.5">[Primary don't have a valid CA]</tspan></text></g><text x="741" y="339" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">RPC ConnectCA.Roots (fetch primary root and store it)</text><line x1="972" y1="372" x2="510" y2="372" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="741" y="387" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">Root + intermediate</text><line x1="510" y1="420" x2="972" y2="420" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="524" y="480" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">Generate CSR</text><line x1="972" y1="513" x2="75" y2="513" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="524" y="528" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">CSR</text><line x1="75" y1="561" x2="972" y2="561" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="741" y="576" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">ConnectCA.SignIntermediate (CSR)</text><line x1="972" y1="609" x2="510" y2="609" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="741" y="624" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">Intermediate CA (secondary)</text><line x1="510" y1="657" x2="972" y2="657" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="524" y="672" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">Set Intermediate (secondary CA) + root (primary CA)</text><line x1="972" y1="705" x2="75" y2="705" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></line><text x="972" y="720" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">Store certs in RAFT (primary root + secondary intermediate)</text><path d="M 972,753 C 1032,743 1032,783 972,773" class="messageLine0" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="fill: none;"></path><g><line x1="65" y1="430" x2="1198" y2="430" class="loopLine"></line><line x1="1198" y1="430" x2="1198" y2="823" class="loopLine"></line><line x1="65" y1="823" x2="1198" y2="823" class="loopLine"></line><line x1="65" y1="430" x2="65" y2="823" class="loopLine"></line><polygon points="65,430 115,430 115,443 106.6,450 65,450" class="labelBox"></polygon><text x="90" y="443" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="labelText" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;">alt</text><text x="656.5" y="448" text-anchor="middle" class="loopText" style="font-family: &quot;trebuchet ms&quot;, verdana, arial, sans-serif; font-size: 16px; font-weight: 400;"><tspan x="656.5">[Secondary needs a new intermediate (check if current intermediate is signed by primary root)]</tspan></text></g><g><rect x="0" y="843" fill="#eaeaea" stroke="#666" width="150" height="65" rx="3" ry="3" class="actor"></rect><text x="75" y="875.5" dominant-baseline="central" alignment-baseline="central" class="actor" style="text-anchor: middle; font-size: 14px; font-weight: 400; font-family: Open-Sans, sans-serif;"><tspan x="75" dy="0">Provider</tspan></text></g><g><rect x="435" y="843" fill="#eaeaea" stroke="#666" width="150" height="65" rx="3" ry="3" class="actor"></rect><text x="510" y="875.5" dominant-baseline="central" alignment-baseline="central" class="actor" style="text-anchor: middle; font-size: 14px; font-weight: 400; font-family: Open-Sans, sans-serif;"><tspan x="510" dy="0">Primary Leader</tspan></text></g><g><rect x="897" y="843" fill="#eaeaea" stroke="#666" width="150" height="65" rx="3" ry="3" class="actor"></rect><text x="972" y="875.5" dominant-baseline="central" alignment-baseline="central" class="actor" style="text-anchor: middle; font-size: 14px; font-weight: 400; font-family: Open-Sans, sans-serif;"><tspan x="972" dy="0">Secondary Leader</tspan></text></g></svg>
\ No newline at end of file

From 28d4b2316a5a5914c2b4ecfbce62e03a60a6e7e7 Mon Sep 17 00:00:00 2001
From: Dhia Ayachi <dhia@hashicorp.com>
Date: Fri, 9 Jul 2021 15:24:16 -0400
Subject: [PATCH 44/98] fix typo and add a TODO section for the remaining stuff

---
 docs/service-mesh/ca/README.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
index 809dae8253..2a3d14d637 100644
--- a/docs/service-mesh/ca/README.md
+++ b/docs/service-mesh/ca/README.md
@@ -1,6 +1,6 @@
 # Certificate Authority (Connect CA)
 
-The Certificate Authority subsystem manages a CA trust chain for issuing certificates to
+The Certificate Authority Subsystem manages a CA trust chain for issuing certificates to
 services and client agents (via auto-encrypt and auto-config).
 
 The code for the Certificate Authority is in the following packages:
@@ -93,10 +93,11 @@ Periodic (or background) opeartions are started automatically by the Consul lead
     2. (via in-process call to `RPC.ConnectCA.Sign`) - called by auto-encrypt to sign a leaf cert for a client agent
     3. called by Auto-Config to sign a leaf cert for a client agent
 
-### detailed call flow
+## detailed call flow
 ![CA Leader Sequence](./ca-leader-sequence.svg)
 
 <sup>[source](./ca-leader-sequence.mmd)</sup>
 
-- sequence diagram for leaf signing
+####TODO:
+- sequence diagram for leaf signing 
 - sequence diagram for CA cert rotation

From 2e2156a8bb325fcb1a3aea6a3faaa1139278a8a2 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Fri, 16 Jul 2021 16:48:46 -0400
Subject: [PATCH 45/98] contrib: add CA manager states diagram

---
 docs/service-mesh/ca/README.md         | 11 +++++++++++
 docs/service-mesh/ca/state-machine.mmd | 23 +++++++++++++++++++++++
 docs/service-mesh/ca/state-machine.svg |  1 +
 3 files changed, 35 insertions(+)
 create mode 100644 docs/service-mesh/ca/state-machine.mmd
 create mode 100644 docs/service-mesh/ca/state-machine.svg

diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
index 2a3d14d637..cd63244ee2 100644
--- a/docs/service-mesh/ca/README.md
+++ b/docs/service-mesh/ca/README.md
@@ -101,3 +101,14 @@ Periodic (or background) opeartions are started automatically by the Consul lead
 ####TODO:
 - sequence diagram for leaf signing 
 - sequence diagram for CA cert rotation
+
+## CAManager states
+
+This section is a work in progress
+
+TODO: style the diagram to match the others, and add some narative text to describe the
+diagram.
+
+![CA Mananger states](./state-machine.svg)
+
+
diff --git a/docs/service-mesh/ca/state-machine.mmd b/docs/service-mesh/ca/state-machine.mmd
new file mode 100644
index 0000000000..214e311679
--- /dev/null
+++ b/docs/service-mesh/ca/state-machine.mmd
@@ -0,0 +1,23 @@
+stateDiagram-v2
+
+    [*] --> Uninitialized
+    Uninitialized --> Initializing : InitializeCA
+    Uninitialized --> Reconfig : UpdateConfiguration
+    Reconfig --> Uninitialized : return
+
+    # Initialized can transition to any state
+    Initialized --> Renew : RenewIntermediate
+    Initialized --> Uninitialized : Stop
+    Initialized --> Reconfig  : UpdateConfiguration
+    Initialized --> Initializing : INVALID
+
+    # Initialized is set using validate=false
+    Uninitialized --> Initialized : INVALID
+    Reconfig --> Initialized : return
+    Initializing --> Initialized : InitializeCA complete
+    Renew --> Initialized : return
+
+    # Uninitialized is set using validate=false
+    Renew --> Uninitialized : Stop
+    Reconfig --> Uninitialized : Stop
+    Initializing --> Uninitialized : Stop
diff --git a/docs/service-mesh/ca/state-machine.svg b/docs/service-mesh/ca/state-machine.svg
new file mode 100644
index 0000000000..f63e880e08
--- /dev/null
+++ b/docs/service-mesh/ca/state-machine.svg
@@ -0,0 +1 @@
+<svg id="graph-div" width="884px" xmlns="http://www.w3.org/2000/svg" class="statediagram" height="458px" style="max-width: 1617.232421875px;" viewBox="0 0 924.1328125 458"><style>#graph-div{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#graph-div .error-icon{fill:#552222;}#graph-div .error-text{fill:#552222;stroke:#552222;}#graph-div .edge-thickness-normal{stroke-width:2px;}#graph-div .edge-thickness-thick{stroke-width:3.5px;}#graph-div .edge-pattern-solid{stroke-dasharray:0;}#graph-div .edge-pattern-dashed{stroke-dasharray:3;}#graph-div .edge-pattern-dotted{stroke-dasharray:2;}#graph-div .marker{fill:#333333;stroke:#333333;}#graph-div .marker.cross{stroke:#333333;}#graph-div svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#graph-div defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#graph-div g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#graph-div g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#graph-div g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#graph-div g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#graph-div g.stateGroup line{stroke:#333333;stroke-width:1;}#graph-div .transition{stroke:#333333;stroke-width:1;fill:none;}#graph-div .stateGroup .composit{fill:white;border-bottom:1px;}#graph-div .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#graph-div .state-note{stroke:#aaaa33;fill:#fff5ad;}#graph-div .state-note text{fill:black;stroke:none;font-size:10px;}#graph-div .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#graph-div .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#graph-div .edgeLabel .label text{fill:#333;}#graph-div .label div .edgeLabel{color:#333;}#graph-div .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#graph-div .node circle.state-start{fill:#333333;stroke:#333333;}#graph-div .node .fork-join{fill:#333333;stroke:#333333;}#graph-div .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#graph-div .end-state-inner{fill:white;stroke-width:1.5;}#graph-div .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#graph-div .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#graph-div #statediagram-barbEnd{fill:#333333;}#graph-div .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#graph-div .cluster-label,#graph-div .nodeLabel{color:#131300;}#graph-div .statediagram-cluster rect.outer{rx:5px;ry:5px;}#graph-div .statediagram-state .divider{stroke:#9370DB;}#graph-div .statediagram-state .title-state{rx:5px;ry:5px;}#graph-div .statediagram-cluster.statediagram-cluster .inner{fill:white;}#graph-div .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#graph-div .statediagram-cluster .inner{rx:0;ry:0;}#graph-div .statediagram-state rect.basic{rx:5px;ry:5px;}#graph-div .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#graph-div .note-edge{stroke-dasharray:5;}#graph-div .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#graph-div .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#graph-div .statediagram-note text{fill:black;}#graph-div .statediagram-note .nodeLabel{color:black;}#graph-div .statediagram .edgeLabel{color:red;}#graph-div .statediagram .edgeLabel #dependencyStart,#graph-div .statediagram .edgeLabel #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#graph-div .statediagram .edgeLabel .node rect,#graph-div .statediagram .edgeLabel .er.entityBox{fill:rgb(220,71,125);stroke-width:1;stroke:black;}#graph-div .statediagram .edgeLabel .node .label{color:white;}#graph-div .statediagram .edgeLabel .cluster rect{fill:#f0f0f0;stroke-width:1px;stroke:#333;}#graph-div .statediagram .edgeLabel .edgeLabel{background-color:#f0f0f0;}#graph-div .statediagram .edgeLabel .er.entityBox + .er.entityLabel{fill:white;}#graph-div .statediagram .edgeLabel .er.attributeBoxEven,#graph-div .statediagram .edgeLabel .er.attributeBoxOdd{fill:#fff;stroke:#777;}#graph-div .statediagram .edgeLabel:root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g><defs><marker id="statediagram-barbEnd" refX="19" refY="7" markerWidth="20" markerHeight="14" markerUnits="strokeWidth" orient="auto"><path d="M 19,7 L9,13 L14,7 L9,1 Z"></path></marker></defs><g class="root"><g class="clusters"></g><g class="edgePaths"><path d="M475.73828125,22L475.73828125,26.166666666666668C475.73828125,30.333333333333332,475.73828125,38.666666666666664,475.73828125,47C475.73828125,55.333333333333336,475.73828125,63.666666666666664,475.73828125,67.83333333333333L475.73828125,72" id="edge6884" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M491.6817961836283,111L496.72376244469024,117.16666666666667C501.7657287057522,123.33333333333333,511.8496612278761,135.66666666666666,512.7036320058997,148C513.5576027839232,160.33333333333334,505.18161181784654,172.66666666666666,500.9936163348082,178.83333333333334L496.8056208517699,185" id="edge6885" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M528.64453125,99.66608863609686L580.8352864583334,107.72174053008071C633.0260416666666,115.77739242406456,737.4075520833334,131.88869621203227,789.5983072916666,149.3610147726828C841.7890625,166.83333333333334,841.7890625,185.66666666666666,841.7890625,204.5C841.7890625,223.33333333333334,841.7890625,242.16666666666666,841.7890625,261C841.7890625,279.8333333333333,841.7890625,298.6666666666667,841.7890625,317.5C841.7890625,336.3333333333333,841.7890625,355.1666666666667,816.6875,372.0996673843436C791.5859375,389.0326681020206,741.3828125,404.0653362040411,716.28125,411.5816702550514L691.1796875,419.0980043060616" id="edge6886" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M653.1015625,411L653.1015625,404.8333333333333C653.1015625,398.6666666666667,653.1015625,386.3333333333333,653.1015625,370.75C653.1015625,355.1666666666667,653.1015625,336.3333333333333,653.1015625,317.5C653.1015625,298.6666666666667,653.1015625,279.8333333333333,653.1015625,261C653.1015625,242.16666666666666,653.1015625,223.33333333333334,653.1015625,204.5C653.1015625,185.66666666666666,653.1015625,166.83333333333334,632.3587239583334,150.8089270638329C611.6158854166666,134.78452079433248,570.1302083333334,121.56904158866497,549.3873697916666,114.96130198583121L528.64453125,108.35356238299747" id="edge6887" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M391.8984375,327.044105096318L356.3958333333333,334.87008758026496C320.8932291666667,342.69607006421194,249.88802083333334,358.348035032106,200.76432291666666,373.00818915473764C151.640625,387.66834327736916,124.3984375,401.33668655473844,110.77734375,408.17085819342304L97.15625,415.00502983210765" id="edge6888" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M415.8004701327434,298L409.66705844395284,291.8333333333333C403.53364675516224,285.6666666666667,391.26682337758115,273.3333333333333,385.1334116887906,257.75C379,242.16666666666666,379,223.33333333333334,379,204.5C379,185.66666666666666,379,166.83333333333334,389.5584554756637,151.25C400.1169109513274,135.66666666666666,421.2338219026549,123.33333333333333,431.7922773783186,117.16666666666667L442.3507328539823,111" id="edge6889" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M478.4921875,325.3343424739792L523.3177083333334,333.44528539498265C568.1432291666666,341.5562283159861,657.7942708333334,357.77811415799306,692.3226862094394,372.0557237456632C726.8511015855457,386.3333333333333,706.2568906710916,398.6666666666667,695.9597852138644,404.8333333333333L685.6626797566372,411" id="edge6890" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M399.53878595132744,298L388.26279037610624,291.8333333333333C376.986794800885,285.6666666666667,354.4348036504425,273.3333333333333,360.91531849188794,260.5524465619366C367.3958333333333,247.77155979053995,402.9088541666667,234.54311958107994,420.6653645833333,227.9288994763499L438.421875,221.3146793716199" id="edge6891" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M520.69047289823,111L534.906123248525,117.16666666666667C549.12177359882,123.33333333333333,577.55307429941,135.66666666666666,591.768724649705,151.25C605.984375,166.83333333333334,605.984375,185.66666666666666,605.984375,204.5C605.984375,223.33333333333334,605.984375,242.16666666666666,584.7356770833334,258.6127731271824C563.4869791666666,275.0588795876981,520.9895833333334,289.1177591753961,499.7408854166667,296.1471989692451L478.4921875,303.1766387630941" id="edge6892" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M615.0234375,420.62688226014626L585.0520833333334,412.85573521678856C555.0807291666666,405.0845881734308,495.1380208333333,389.5422940867154,465.1666666666667,375.604480376691C435.1953125,361.6666666666667,435.1953125,349.3333333333333,435.1953125,343.1666666666667L435.1953125,337" id="edge6893" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M483.5625,224L483.5625,230.16666666666666C483.5625,236.33333333333334,483.5625,248.66666666666666,478.2834854351033,261C473.0044708702065,273.3333333333333,462.44644174041304,285.6666666666667,457.16742717551625,291.8333333333333L451.88841261061947,298" id="edge6894" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M66.2734375,411L66.2734375,404.8333333333333C66.2734375,398.6666666666667,66.2734375,386.3333333333333,120.54427083333333,371.85514520068335C174.81510416666666,357.3769570680333,283.3567708333333,340.7539141360665,337.6276041666667,332.44239267008317L391.8984375,324.1308712040998" id="edge6895" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M51.60529590707965,411L46.96665283923304,404.8333333333333C42.328009771386434,398.6666666666667,33.05072363569322,386.3333333333333,28.412080567846612,370.75C23.7734375,355.1666666666667,23.7734375,336.3333333333333,23.7734375,317.5C23.7734375,298.6666666666667,23.7734375,279.8333333333333,23.7734375,261C23.7734375,242.16666666666666,23.7734375,223.33333333333334,23.7734375,204.5C23.7734375,185.66666666666666,23.7734375,166.83333333333334,90.283203125,149.10229927774847C156.79296875,131.37126522216366,289.8125,114.7425304443273,356.322265625,106.42816305540912L422.83203125,98.11379566649093" id="edge6896" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M615.0234375,424.89895456209575L557.3515625,416.41579546841314C499.6796875,407.93263637473046,384.3359375,390.96631818736523,326.6640625,373.06649242701593C268.9921875,355.1666666666667,268.9921875,336.3333333333333,268.9921875,317.5C268.9921875,298.6666666666667,268.9921875,279.8333333333333,268.9921875,261C268.9921875,242.16666666666666,268.9921875,223.33333333333334,268.9921875,204.5C268.9921875,185.66666666666666,268.9921875,166.83333333333334,294.6321614583333,150.40972156618236C320.2721354166667,133.98610979903137,371.5520833333333,119.97221959806274,397.1920572916667,112.96527449757842L422.83203125,105.9583293970941" id="edge6897" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path><path d="M470.36252074115043,185L466.1881683259587,178.83333333333334C462.01381591076694,172.66666666666666,453.6651110803835,160.33333333333334,452.8111403023599,148C451.9571695243363,135.66666666666666,458.5979327986726,123.33333333333333,461.9183144358407,117.16666666666667L465.23869607300884,111" id="edge6898" class=" edge-thickness-normal transition" style="fill:none" marker-end="url(#statediagram-barbEnd)"></path></g><g class="edgeLabels"><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel"></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(521.93359375, 148)"><g class="label" transform="translate(-40.84375, -12)"><rect rx="0" ry="0" width="81.6875" height="24"></rect><foreignObject width="81.6875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">InitializeCA</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(841.7890625, 261)"><g class="label" transform="translate(-74.34375, -12)"><rect rx="0" ry="0" width="148.6875" height="24"></rect><foreignObject width="148.6875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">UpdateConfiguration</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(653.1015625, 261)"><g class="label" transform="translate(-22.5, -12)"><rect rx="0" ry="0" width="45" height="24"></rect><foreignObject width="45" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">return</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(178.8828125, 374)"><g class="label" transform="translate(-70.109375, -12)"><rect rx="0" ry="0" width="140.21875" height="24"></rect><foreignObject width="140.21875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">RenewIntermediate</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(379, 204.5)"><g class="label" transform="translate(-15.7734375, -12)"><rect rx="0" ry="0" width="31.546875" height="24"></rect><foreignObject width="31.546875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">Stop</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(747.4453125, 374)"><g class="label" transform="translate(-74.34375, -12)"><rect rx="0" ry="0" width="148.6875" height="24"></rect><foreignObject width="148.6875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">UpdateConfiguration</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(331.8828125, 261)"><g class="label" transform="translate(-27.1171875, -12)"><rect rx="0" ry="0" width="54.234375" height="24"></rect><foreignObject width="54.234375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">INVALID</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(605.984375, 204.5)"><g class="label" transform="translate(-27.1171875, -12)"><rect rx="0" ry="0" width="54.234375" height="24"></rect><foreignObject width="54.234375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">INVALID</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(435.1953125, 374)"><g class="label" transform="translate(-22.5, -12)"><rect rx="0" ry="0" width="45" height="24"></rect><foreignObject width="45" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">return</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(483.5625, 261)"><g class="label" transform="translate(-76.859375, -12)"><rect rx="0" ry="0" width="153.71875" height="24"></rect><foreignObject width="153.71875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">InitializeCA complete</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(66.2734375, 374)"><g class="label" transform="translate(-22.5, -12)"><rect rx="0" ry="0" width="45" height="24"></rect><foreignObject width="45" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">return</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(23.7734375, 261)"><g class="label" transform="translate(-15.7734375, -12)"><rect rx="0" ry="0" width="31.546875" height="24"></rect><foreignObject width="31.546875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">Stop</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(268.9921875, 261)"><g class="label" transform="translate(-15.7734375, -12)"><rect rx="0" ry="0" width="31.546875" height="24"></rect><foreignObject width="31.546875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">Stop</span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(445.31640625, 148)"><g class="label" transform="translate(-15.7734375, -12)"><rect rx="0" ry="0" width="31.546875" height="24"></rect><foreignObject width="31.546875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="edgeLabel">Stop</span></div></foreignObject></g></g></g><g class="nodes"><g class="node default" id="state-root_start-6884" transform="translate(475.73828125, 15)"><circle class="state-start" r="7" width="14" height="14"></circle></g><g class="node statediagram-state" id="state-Uninitialized-6898" transform="translate(475.73828125, 91.5)"><rect class="basic label-container" style="" x="-52.90625" y="-19.5" width="105.8125" height="39"></rect><g class="label" style="" transform="translate(-45.40625, -12)"><foreignObject width="90.8125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="nodeLabel">Uninitialized</span></div></foreignObject></g></g><g class="node statediagram-state" id="state-Initializing-6898" transform="translate(483.5625, 204.5)"><rect class="basic label-container" style="" x="-45.140625" y="-19.5" width="90.28125" height="39"></rect><g class="label" style="" transform="translate(-37.640625, -12)"><foreignObject width="75.28125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="nodeLabel">Initializing</span></div></foreignObject></g></g><g class="node statediagram-state" id="state-Reconfig-6897" transform="translate(653.1015625, 430.5)"><rect class="basic label-container" style="" x="-38.078125" y="-19.5" width="76.15625" height="39"></rect><g class="label" style="" transform="translate(-30.578125, -12)"><foreignObject width="61.15625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="nodeLabel">Reconfig</span></div></foreignObject></g></g><g class="node statediagram-state" id="state-Initialized-6895" transform="translate(435.1953125, 317.5)"><rect class="basic label-container" style="" x="-43.296875" y="-19.5" width="86.59375" height="39"></rect><g class="label" style="" transform="translate(-35.796875, -12)"><foreignObject width="71.59375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="nodeLabel">Initialized</span></div></foreignObject></g></g><g class="node statediagram-state" id="state-Renew-6896" transform="translate(66.2734375, 430.5)"><rect class="basic label-container" style="" x="-30.8828125" y="-19.5" width="61.765625" height="39"></rect><g class="label" style="" transform="translate(-23.3828125, -12)"><foreignObject width="46.765625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span class="nodeLabel">Renew</span></div></foreignObject></g></g></g></g></g></svg>
\ No newline at end of file

From 4c4a9f3e65aac77ba9cf515d6dac39b64e2b9e7a Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 26 Jan 2022 09:23:10 -0800
Subject: [PATCH 46/98] added GWclass and GWClassConfig

---
 website/content/docs/api-gateway.mdx | 111 ++++++++++++++++++++++++---
 1 file changed, 100 insertions(+), 11 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index d2d44d4656..e1ec5cc673 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -3,16 +3,17 @@ layout: docs
 page_title: API Gateway
 description: Using Consul API gateway functionality
 ---
+
 # Consul API Gateway
 
-The Consul API Gateway add-on module helps users control access to services running within a Consul service mesh. Using the API Gateway, applications and services running in a Consul datacenter can be accessed by network clients residing outside of the datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol. 
+This topic describes how to use the Consul API Gateway add-on module, which helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol.
 
 ## Introduction
 
-Consul API Gateway is an implementation of the Kubernetes Gateway [API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. The Consul API gateway solves for two primary use cases:
+Consul API Gateway is an implementation of the Kubernetes Gateway [API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases:
 
-* **Controlling access at the point entry** - The Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g. VeriSign, Let’sEncrypt). 
-* **Simplifying traffic management** - The Consul API Gateway can be used to load balance requests across services and route traffic to the appropriate service based on matching one or more criteria such as hostname, path, header presence or value, and HTTP Method type (e.g. Get, Post, Patch).
+- **Controlling access at the point entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., VeriSign, Let’sEncrypt).
+- **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service based on matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH).
 
 ## Requirements
 
@@ -47,7 +48,11 @@ controller:
 $ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
 ```
 
-The following components will be installed: - Gateway controller - CRDs required by the Kubernetes Gateway API specification - `kustomize` manifests for completing the installation
+The following components will be installed:
+
+- Gateway controller
+- CRDs required by the Kubernetes Gateway API specification
+- `kustomize` manifests for completing the installation
 
 1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster.
 
@@ -67,6 +72,8 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=
 $ kubectl apply --values gateway-configuration.yaml
 ```
 
+<!--- Commented out per https://github.com/hashicorp/consul/pull/11951/files#r791204596
+
 ### Using the Consul API Gateway Binary
 
 You can download the Consul API Gateway binary and use it to manually start the control plane server.
@@ -112,22 +119,27 @@ You can also issue the `version` command to print the Consul API Gateway version
 $ ./consul-api-gateway version
 consul-api-gateway 0.1.0
 ```
+--->
 
 ## Configuration
 
-Create the following artifacts to configure the API Gateway:
+Configure the following artifacts to facilitate ingress into your Consul service mesh:
 
-- [Gateway](#gateway): Defines the gateway properties, including listeners.
+- [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`.
+- [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways.
+- [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gatway-related configuration parameters for the `GatewayClass` resource.
 - [Listeners](#listeners): Defines listener properties, such as protocol, port, and namespace.
 - [Routes](#routes): Specifies the path from the client to the listener.
 
 ### Gateway
 
-The gateway object contains gateway listeners.
+The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`.
+
 Add the `kind: Gateway` option to the configuration file to declare a gateway.
-The following example creates a gateway called `example-gateway` that includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration).
+The following example creates a gateway called `example-gateway`.
+The gateway is based on the `test-gateway-class` and includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration).
 
-<CodeBlockConfig lineNumbers highlight="2,4,9,13">
+<CodeBlockConfig filename="gateway.yaml" lineNumbers highlight="2,4,8,9,13">
 
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1alpha2
@@ -137,7 +149,7 @@ metadata:
   annotations:
     'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
 spec:
-  gatewayClassName: default-consul-gateway-class
+  gatewayClassName: test-gateway-class
   listeners:
     - protocol: HTTPS
       hostname: DNS_HOSTNAME
@@ -156,6 +168,83 @@ spec:
 Refer to the Kubernetes Gateway API documentation for details about configuring gateways:
 <https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway>
 
+### GatewayClass
+
+The `GatewayClass` resource is used as a template for creating `Gateway` resources.
+The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resource within the cluster (`parametersRef`).
+
+When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation.
+If you want to propagate changes made to the `GatewayClass` after gateways have been created, then the implementation must document this behavior.
+The `gateway-exists-finalizer.gateway.networking.k8s.io` finalizer must also be added to a `GatewayClass` to ensure that a `GatewayClass` associated with a `Gateway` is not deleted while in use.
+
+Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class.
+The following example creates a gateway class called `test-gateway-class`.
+
+<CodeBlockConfig filename="gateway.yaml">
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: GatewayClass
+metadata:
+  name: test-gateway-class
+spec:
+  controllerName: 'hashicorp.com/consul-api-gateway-controller'
+  parametersRef:
+    group: api-gateway.consul.hashicorp.com
+    kind: GatewayClassConfig
+    name: test-gateway-class-config
+```
+
+</CodeBlockConfig>
+
+Refer to the Kubernetes Gateway API documentation for details about configuring gateway classes:
+<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass>
+
+### GatewayClassConfig
+
+The `GatewayClassConfig` object describes additional Consul API Gateway-related configuration parameters for the `GatewayClass`.
+
+Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class.
+The following example creates a gateway class called `test-gateway-class-config`.
+
+<CodeBlockConfig filename="gateway.yaml">
+
+```yaml
+apiVersion: api-gateway.consul.hashicorp.com/v1alpha1
+kind: GatewayClassConfig
+metadata:
+  name: test-gateway-class-config
+spec:
+  useHostPorts: true
+  logLevel: trace
+  consul:
+    scheme: https
+    caSecret: consul-ca-cert
+    ports:
+      http: 8501
+      grpc: 8502
+```
+
+</CodeBlockConfig>
+
+The following table describes the required parameters for the `spec` array:
+
+| Parameter      | Description                                                                                                                                          | Type    | Default |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- |
+| `useHostPorts` | Enables the gateway to use the host ports                                                                                                            | Boolean | `true`  |
+| `logLevel`     | Specifies the error reporting level for logs. You can specify the following values: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`, `OFF` | String  | `trace` |
+| `consul`       | Specifies ingress properties for Consul. See [Consul Configuration](#consul-configuration)                                                           | Array   | N/A     |
+
+#### Consul Configuration
+
+The following table describes the parameters available for the `consul` element of the `GatewayClassConfiguration`:
+
+| Parameter  | Description                                                   | Type   | Default                         |
+| ---------- | ------------------------------------------------------------- | ------ | ------------------------------- |
+| `scheme`   | Specifies the message protocol.                               | String | `http`                          |
+| `caSecret` | Specifies the name of the CA secret.                          | String | none                            |
+| `ports`    | Specifies which ports to use for API and application traffic. | Array  | `http: 8501` <br/> `grpc: 8502` |
+
 ### Listeners
 
 Listeners are the logical endpoints bound to the gateway's addresses.

From 737c0097e00b1036cf993ed6e17c37005c9cc14d Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Fri, 30 Jul 2021 19:20:02 -0400
Subject: [PATCH 47/98] acl: extract a backend type for the ACLResolverBackend

This is a small step to isolate the functionality that is used for the
ACLResolver from the large Client and Server structs.
---
 agent/consul/acl.go         | 40 +++++++++++++++++++------------------
 agent/consul/acl_client.go  | 17 ++++++++++------
 agent/consul/acl_server.go  | 16 ++++++++++-----
 agent/consul/acl_test.go    |  2 +-
 agent/consul/client.go      |  2 +-
 agent/consul/replication.go |  2 +-
 agent/consul/server.go      |  2 +-
 7 files changed, 47 insertions(+), 34 deletions(-)

diff --git a/agent/consul/acl.go b/agent/consul/acl.go
index b475bf1596..4e8c885380 100644
--- a/agent/consul/acl.go
+++ b/agent/consul/acl.go
@@ -133,11 +133,12 @@ func tokenSecretCacheID(token string) string {
 	return "token-secret:" + token
 }
 
-type ACLResolverDelegate interface {
+type ACLResolverBackend interface {
 	ACLDatacenter() string
 	ResolveIdentityFromToken(token string) (bool, structs.ACLIdentity, error)
 	ResolvePolicyFromID(policyID string) (bool, *structs.ACLPolicy, error)
 	ResolveRoleFromID(roleID string) (bool, *structs.ACLRole, error)
+	// TODO: separate methods for each RPC call (there are 4)
 	RPC(method string, args interface{}, reply interface{}) error
 	EnterpriseACLResolverDelegate
 }
@@ -160,8 +161,9 @@ type ACLResolverConfig struct {
 	// CacheConfig is a pass through configuration for ACL cache limits
 	CacheConfig *structs.ACLCachesConfig
 
-	// Delegate that implements some helper functionality that is server/client specific
-	Delegate ACLResolverDelegate
+	// Backend is used to retrieve data from the state store, or perform RPCs
+	// to fetch data from other Datacenters.
+	Backend ACLResolverBackend
 
 	// DisableDuration is the length of time to leave ACLs disabled when an RPC
 	// request to a server indicates that the ACL system is disabled. If set to
@@ -219,9 +221,9 @@ type ACLResolverSettings struct {
 // ACLResolver is the type to handle all your token and policy resolution needs.
 //
 // Supports:
-//   - Resolving tokens locally via the ACLResolverDelegate
-//   - Resolving policies locally via the ACLResolverDelegate
-//   - Resolving roles locally via the ACLResolverDelegate
+//   - Resolving tokens locally via the ACLResolverBackend
+//   - Resolving policies locally via the ACLResolverBackend
+//   - Resolving roles locally via the ACLResolverBackend
 //   - Resolving legacy tokens remotely via an ACL.GetPolicy RPC
 //   - Resolving tokens remotely via an ACL.TokenRead RPC
 //   - Resolving policies remotely via an ACL.PolicyResolve RPC
@@ -245,8 +247,8 @@ type ACLResolver struct {
 	config ACLResolverSettings
 	logger hclog.Logger
 
-	delegate ACLResolverDelegate
-	aclConf  *acl.Config
+	backend ACLResolverBackend
+	aclConf *acl.Config
 
 	tokens *token.Store
 
@@ -298,7 +300,7 @@ func NewACLResolver(config *ACLResolverConfig) (*ACLResolver, error) {
 	if config == nil {
 		return nil, fmt.Errorf("ACL Resolver must be initialized with a config")
 	}
-	if config.Delegate == nil {
+	if config.Backend == nil {
 		return nil, fmt.Errorf("ACL Resolver must be initialized with a valid delegate")
 	}
 
@@ -331,7 +333,7 @@ func NewACLResolver(config *ACLResolverConfig) (*ACLResolver, error) {
 	return &ACLResolver{
 		config:             config.Config,
 		logger:             config.Logger.Named(logging.ACL),
-		delegate:           config.Delegate,
+		backend:            config.Backend,
 		aclConf:            config.ACLConfig,
 		cache:              cache,
 		disableDuration:    config.DisableDuration,
@@ -349,7 +351,7 @@ func (r *ACLResolver) fetchAndCacheIdentityFromToken(token string, cached *struc
 	cacheID := tokenSecretCacheID(token)
 
 	req := structs.ACLTokenGetRequest{
-		Datacenter:  r.delegate.ACLDatacenter(),
+		Datacenter:  r.backend.ACLDatacenter(),
 		TokenID:     token,
 		TokenIDType: structs.ACLTokenSecret,
 		QueryOptions: structs.QueryOptions{
@@ -359,7 +361,7 @@ func (r *ACLResolver) fetchAndCacheIdentityFromToken(token string, cached *struc
 	}
 
 	var resp structs.ACLTokenResponse
-	err := r.delegate.RPC("ACL.TokenRead", &req, &resp)
+	err := r.backend.RPC("ACL.TokenRead", &req, &resp)
 	if err == nil {
 		if resp.Token == nil {
 			r.cache.PutIdentity(cacheID, nil)
@@ -396,7 +398,7 @@ func (r *ACLResolver) fetchAndCacheIdentityFromToken(token string, cached *struc
 // we initiate an RPC for the value.
 func (r *ACLResolver) resolveIdentityFromToken(token string) (structs.ACLIdentity, error) {
 	// Attempt to resolve locally first (local results are not cached)
-	if done, identity, err := r.delegate.ResolveIdentityFromToken(token); done {
+	if done, identity, err := r.backend.ResolveIdentityFromToken(token); done {
 		return identity, err
 	}
 
@@ -437,7 +439,7 @@ func (r *ACLResolver) resolveIdentityFromToken(token string) (structs.ACLIdentit
 
 func (r *ACLResolver) fetchAndCachePoliciesForIdentity(identity structs.ACLIdentity, policyIDs []string, cached map[string]*structs.PolicyCacheEntry) (map[string]*structs.ACLPolicy, error) {
 	req := structs.ACLPolicyBatchGetRequest{
-		Datacenter: r.delegate.ACLDatacenter(),
+		Datacenter: r.backend.ACLDatacenter(),
 		PolicyIDs:  policyIDs,
 		QueryOptions: structs.QueryOptions{
 			Token:      identity.SecretToken(),
@@ -446,7 +448,7 @@ func (r *ACLResolver) fetchAndCachePoliciesForIdentity(identity structs.ACLIdent
 	}
 
 	var resp structs.ACLPolicyBatchResponse
-	err := r.delegate.RPC("ACL.PolicyResolve", &req, &resp)
+	err := r.backend.RPC("ACL.PolicyResolve", &req, &resp)
 	if err == nil {
 		out := make(map[string]*structs.ACLPolicy)
 		for _, policy := range resp.Policies {
@@ -492,7 +494,7 @@ func (r *ACLResolver) fetchAndCachePoliciesForIdentity(identity structs.ACLIdent
 
 func (r *ACLResolver) fetchAndCacheRolesForIdentity(identity structs.ACLIdentity, roleIDs []string, cached map[string]*structs.RoleCacheEntry) (map[string]*structs.ACLRole, error) {
 	req := structs.ACLRoleBatchGetRequest{
-		Datacenter: r.delegate.ACLDatacenter(),
+		Datacenter: r.backend.ACLDatacenter(),
 		RoleIDs:    roleIDs,
 		QueryOptions: structs.QueryOptions{
 			Token:      identity.SecretToken(),
@@ -501,7 +503,7 @@ func (r *ACLResolver) fetchAndCacheRolesForIdentity(identity structs.ACLIdentity
 	}
 
 	var resp structs.ACLRoleBatchResponse
-	err := r.delegate.RPC("ACL.RoleResolve", &req, &resp)
+	err := r.backend.RPC("ACL.RoleResolve", &req, &resp)
 	if err == nil {
 		out := make(map[string]*structs.ACLRole)
 		for _, role := range resp.Roles {
@@ -774,7 +776,7 @@ func (r *ACLResolver) collectPoliciesForIdentity(identity structs.ACLIdentity, p
 	}
 
 	for _, policyID := range policyIDs {
-		if done, policy, err := r.delegate.ResolvePolicyFromID(policyID); done {
+		if done, policy, err := r.backend.ResolvePolicyFromID(policyID); done {
 			if err != nil && !acl.IsErrNotFound(err) {
 				return nil, err
 			}
@@ -871,7 +873,7 @@ func (r *ACLResolver) collectRolesForIdentity(identity structs.ACLIdentity, role
 	expCacheMap := make(map[string]*structs.RoleCacheEntry)
 
 	for _, roleID := range roleIDs {
-		if done, role, err := r.delegate.ResolveRoleFromID(roleID); done {
+		if done, role, err := r.backend.ResolveRoleFromID(roleID); done {
 			if err != nil && !acl.IsErrNotFound(err) {
 				return nil, err
 			}
diff --git a/agent/consul/acl_client.go b/agent/consul/acl_client.go
index 36f3f19a79..2378776c83 100644
--- a/agent/consul/acl_client.go
+++ b/agent/consul/acl_client.go
@@ -5,7 +5,7 @@ import (
 	"github.com/hashicorp/consul/agent/structs"
 )
 
-var clientACLCacheConfig *structs.ACLCachesConfig = &structs.ACLCachesConfig{
+var clientACLCacheConfig = &structs.ACLCachesConfig{
 	// The ACL cache configuration on client agents is more conservative than
 	// on the servers. It is assumed that individual client agents will have
 	// fewer distinct identities accessing the client than a server would
@@ -23,23 +23,28 @@ var clientACLCacheConfig *structs.ACLCachesConfig = &structs.ACLCachesConfig{
 	Roles: 128,
 }
 
-func (c *Client) ACLDatacenter() string {
-	// For resolution running on clients, servers within the current datacenter
+type clientACLResolverBackend struct {
+	// TODO: un-embed
+	*Client
+}
+
+func (c *clientACLResolverBackend) ACLDatacenter() string {
+	// For resolution running on clients servers within the current datacenter
 	// must be queried first to pick up local tokens.
 	return c.config.Datacenter
 }
 
-func (c *Client) ResolveIdentityFromToken(token string) (bool, structs.ACLIdentity, error) {
+func (c *clientACLResolverBackend) ResolveIdentityFromToken(token string) (bool, structs.ACLIdentity, error) {
 	// clients do no local identity resolution at the moment
 	return false, nil, nil
 }
 
-func (c *Client) ResolvePolicyFromID(policyID string) (bool, *structs.ACLPolicy, error) {
+func (c *clientACLResolverBackend) ResolvePolicyFromID(policyID string) (bool, *structs.ACLPolicy, error) {
 	// clients do no local policy resolution at the moment
 	return false, nil, nil
 }
 
-func (c *Client) ResolveRoleFromID(roleID string) (bool, *structs.ACLRole, error) {
+func (c *clientACLResolverBackend) ResolveRoleFromID(roleID string) (bool, *structs.ACLRole, error) {
 	// clients do no local role resolution at the moment
 	return false, nil, nil
 }
diff --git a/agent/consul/acl_server.go b/agent/consul/acl_server.go
index f16b1cc864..497b347d73 100644
--- a/agent/consul/acl_server.go
+++ b/agent/consul/acl_server.go
@@ -100,9 +100,14 @@ func (s *Server) LocalTokensEnabled() bool {
 	return true
 }
 
-func (s *Server) ACLDatacenter() string {
-	// For resolution running on servers the only option
-	// is to contact the configured ACL Datacenter
+type serverACLResolverBackend struct {
+	// TODO: un-embed
+	*Server
+}
+
+func (s *serverACLResolverBackend) ACLDatacenter() string {
+	// For resolution running on servers the only option is to contact the
+	// configured ACL Datacenter
 	if s.config.PrimaryDatacenter != "" {
 		return s.config.PrimaryDatacenter
 	}
@@ -114,6 +119,7 @@ func (s *Server) ACLDatacenter() string {
 }
 
 // ResolveIdentityFromToken retrieves a token's full identity given its secretID.
+// TODO: why does some code call this directly instead of using ACLResolver.ResolveTokenToIdentity ?
 func (s *Server) ResolveIdentityFromToken(token string) (bool, structs.ACLIdentity, error) {
 	// only allow remote RPC resolution when token replication is off and
 	// when not in the ACL datacenter
@@ -131,7 +137,7 @@ func (s *Server) ResolveIdentityFromToken(token string) (bool, structs.ACLIdenti
 	return s.InPrimaryDatacenter() || index > 0, nil, acl.ErrNotFound
 }
 
-func (s *Server) ResolvePolicyFromID(policyID string) (bool, *structs.ACLPolicy, error) {
+func (s *serverACLResolverBackend) ResolvePolicyFromID(policyID string) (bool, *structs.ACLPolicy, error) {
 	index, policy, err := s.fsm.State().ACLPolicyGetByID(nil, policyID, nil)
 	if err != nil {
 		return true, nil, err
@@ -145,7 +151,7 @@ func (s *Server) ResolvePolicyFromID(policyID string) (bool, *structs.ACLPolicy,
 	return s.InPrimaryDatacenter() || index > 0, policy, acl.ErrNotFound
 }
 
-func (s *Server) ResolveRoleFromID(roleID string) (bool, *structs.ACLRole, error) {
+func (s *serverACLResolverBackend) ResolveRoleFromID(roleID string) (bool, *structs.ACLRole, error) {
 	index, role, err := s.fsm.State().ACLRoleGetByID(nil, roleID, nil)
 	if err != nil {
 		return true, nil, err
diff --git a/agent/consul/acl_test.go b/agent/consul/acl_test.go
index d45b1e1973..ee328039bf 100644
--- a/agent/consul/acl_test.go
+++ b/agent/consul/acl_test.go
@@ -715,7 +715,7 @@ func newTestACLResolver(t *testing.T, delegate *ACLResolverTestDelegate, cb func
 			Roles:          4,
 		},
 		DisableDuration: aclClientDisabledTTL,
-		Delegate:        delegate,
+		Backend:         delegate,
 	}
 
 	if cb != nil {
diff --git a/agent/consul/client.go b/agent/consul/client.go
index 999f986634..369595bc0d 100644
--- a/agent/consul/client.go
+++ b/agent/consul/client.go
@@ -119,7 +119,7 @@ func NewClient(config *Config, deps Deps) (*Client, error) {
 
 	aclConfig := ACLResolverConfig{
 		Config:          config.ACLResolverSettings,
-		Delegate:        c,
+		Backend:         &clientACLResolverBackend{Client: c},
 		Logger:          c.logger,
 		DisableDuration: aclClientDisabledTTL,
 		CacheConfig:     clientACLCacheConfig,
diff --git a/agent/consul/replication.go b/agent/consul/replication.go
index 4b6f74c5cd..d4d449aa1f 100644
--- a/agent/consul/replication.go
+++ b/agent/consul/replication.go
@@ -110,7 +110,7 @@ func NewReplicator(config *ReplicatorConfig) (*Replicator, error) {
 		return nil, fmt.Errorf("Cannot create the Replicator without a config")
 	}
 	if config.Delegate == nil {
-		return nil, fmt.Errorf("Cannot create the Replicator without a Delegate set in the config")
+		return nil, fmt.Errorf("Cannot create the Replicator without a Backend set in the config")
 	}
 	if config.Logger == nil {
 		logger := hclog.New(&hclog.LoggerOptions{})
diff --git a/agent/consul/server.go b/agent/consul/server.go
index e076af7214..a3a9b75ca5 100644
--- a/agent/consul/server.go
+++ b/agent/consul/server.go
@@ -450,7 +450,7 @@ func NewServer(config *Config, flat Deps) (*Server, error) {
 	s.aclConfig = newACLConfig(partitionInfo, logger)
 	aclConfig := ACLResolverConfig{
 		Config:      config.ACLResolverSettings,
-		Delegate:    s,
+		Backend:     &serverACLResolverBackend{Server: s},
 		CacheConfig: serverACLCacheConfig,
 		Logger:      logger,
 		ACLConfig:   s.aclConfig,

From f9aef8018bd25722b1b1cb579c806ee776e93513 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Wed, 1 Dec 2021 13:40:41 -0500
Subject: [PATCH 48/98] Apply suggestions from code review

Co-authored-by: Chris S. Kim <ckim@hashicorp.com>
---
 agent/consul/acl.go         | 2 +-
 agent/consul/replication.go | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/agent/consul/acl.go b/agent/consul/acl.go
index 4e8c885380..ee0a1704ef 100644
--- a/agent/consul/acl.go
+++ b/agent/consul/acl.go
@@ -301,7 +301,7 @@ func NewACLResolver(config *ACLResolverConfig) (*ACLResolver, error) {
 		return nil, fmt.Errorf("ACL Resolver must be initialized with a config")
 	}
 	if config.Backend == nil {
-		return nil, fmt.Errorf("ACL Resolver must be initialized with a valid delegate")
+		return nil, fmt.Errorf("ACL Resolver must be initialized with a valid backend")
 	}
 
 	if config.Logger == nil {
diff --git a/agent/consul/replication.go b/agent/consul/replication.go
index d4d449aa1f..4b6f74c5cd 100644
--- a/agent/consul/replication.go
+++ b/agent/consul/replication.go
@@ -110,7 +110,7 @@ func NewReplicator(config *ReplicatorConfig) (*Replicator, error) {
 		return nil, fmt.Errorf("Cannot create the Replicator without a config")
 	}
 	if config.Delegate == nil {
-		return nil, fmt.Errorf("Cannot create the Replicator without a Backend set in the config")
+		return nil, fmt.Errorf("Cannot create the Replicator without a Delegate set in the config")
 	}
 	if config.Logger == nil {
 		logger := hclog.New(&hclog.LoggerOptions{})

From 52ac7657c7f61683216ab18b00359bd7c7a02272 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 26 Jan 2022 09:32:47 -0800
Subject: [PATCH 49/98] fixed formattting issues

---
 website/content/docs/api-gateway.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index e1ec5cc673..9a8168a2db 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -50,9 +50,9 @@ $ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
 
 The following components will be installed:
 
-- Gateway controller
-- CRDs required by the Kubernetes Gateway API specification
-- `kustomize` manifests for completing the installation
+    - Gateway controller
+    - CRDs required by the Kubernetes Gateway API specification
+    - `kustomize` manifests for completing the installation
 
 1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster.
 

From 41709dcc291e07dcb1d7c10d22f04de35496e29a Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 26 Jan 2022 09:44:32 -0800
Subject: [PATCH 50/98] trying to fix persistent formatting problems

---
 website/content/docs/api-gateway.mdx | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 9a8168a2db..38d48c725b 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -28,27 +28,27 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
   <CodeBlockConfig hideClipboard filename="values.yaml">
 
-```yaml
-global:
-  name: consul
-  image: 'hashicorp/consul:1.11.2'
-  tls:
+  ```yaml
+  global:
+    name: consul
+    image: 'hashicorp/consul:1.11.2'
+    tls:
+      enabled: true
+  connectInject:
     enabled: true
-connectInject:
-  enabled: true
-controller:
-  enabled: true
-```
+  controller:
+    enabled: true
+  ```
 
   </CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
-```shell-session
-$ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
-```
+  ```shell-session
+  $ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
+  ```
 
-The following components will be installed:
+  The following components will be installed:
 
     - Gateway controller
     - CRDs required by the Kubernetes Gateway API specification

From 759dd935444dc9236272d8e21af5fc77928336f0 Mon Sep 17 00:00:00 2001
From: Dao Thanh Tung <ttdao.2015@accountancy.smu.edu.sg>
Date: Thu, 27 Jan 2022 02:12:42 +0800
Subject: [PATCH 51/98] URL-encode/decode resource names for HTTP API part 3
 (#12103)

---
 agent/event_endpoint.go            |  7 +++++--
 agent/federation_state_endpoint.go |  6 ++++--
 agent/health_endpoint.go           |  6 +++++-
 agent/intentions_endpoint.go       |  5 ++++-
 agent/kvs_endpoint.go              |  7 +++++--
 agent/prepared_query_endpoint.go   |  5 ++++-
 agent/session_endpoint.go          | 25 ++++++++++++++++++++-----
 7 files changed, 47 insertions(+), 14 deletions(-)

diff --git a/agent/event_endpoint.go b/agent/event_endpoint.go
index eb6561a1b7..10421d6202 100644
--- a/agent/event_endpoint.go
+++ b/agent/event_endpoint.go
@@ -6,7 +6,6 @@ import (
 	"io"
 	"net/http"
 	"strconv"
-	"strings"
 	"time"
 
 	"github.com/hashicorp/consul/acl"
@@ -21,7 +20,11 @@ func (s *HTTPHandlers) EventFire(resp http.ResponseWriter, req *http.Request) (i
 	s.parseDC(req, &dc)
 
 	event := &UserEvent{}
-	event.Name = strings.TrimPrefix(req.URL.Path, "/v1/event/fire/")
+	var err error
+	event.Name, err = getPathSuffixUnescaped(req.URL.Path, "/v1/event/fire/")
+	if err != nil {
+		return nil, err
+	}
 	if event.Name == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing name")
diff --git a/agent/federation_state_endpoint.go b/agent/federation_state_endpoint.go
index ef807adfaf..94b7a7cdd1 100644
--- a/agent/federation_state_endpoint.go
+++ b/agent/federation_state_endpoint.go
@@ -2,14 +2,16 @@ package agent
 
 import (
 	"net/http"
-	"strings"
 
 	"github.com/hashicorp/consul/agent/structs"
 )
 
 // GET /v1/internal/federation-state/<datacenter>
 func (s *HTTPHandlers) FederationStateGet(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
-	datacenterName := strings.TrimPrefix(req.URL.Path, "/v1/internal/federation-state/")
+	datacenterName, err := getPathSuffixUnescaped(req.URL.Path, "/v1/internal/federation-state/")
+	if err != nil {
+		return nil, err
+	}
 	if datacenterName == "" {
 		return nil, BadRequestError{Reason: "Missing datacenter name"}
 	}
diff --git a/agent/health_endpoint.go b/agent/health_endpoint.go
index d47252626f..f6e803a3cb 100644
--- a/agent/health_endpoint.go
+++ b/agent/health_endpoint.go
@@ -30,7 +30,11 @@ func (s *HTTPHandlers) HealthChecksInState(resp http.ResponseWriter, req *http.R
 	}
 
 	// Pull out the service name
-	args.State = strings.TrimPrefix(req.URL.Path, "/v1/health/state/")
+	var err error
+	args.State, err = getPathSuffixUnescaped(req.URL.Path, "/v1/health/state/")
+	if err != nil {
+		return nil, err
+	}
 	if args.State == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing check state")
diff --git a/agent/intentions_endpoint.go b/agent/intentions_endpoint.go
index 8a8456721d..2bb55b7f4b 100644
--- a/agent/intentions_endpoint.go
+++ b/agent/intentions_endpoint.go
@@ -486,7 +486,10 @@ func parseIntentionStringComponent(input string, entMeta *structs.EnterpriseMeta
 // IntentionSpecific handles the endpoint for /v1/connect/intentions/:id.
 // Deprecated: use IntentionExact.
 func (s *HTTPHandlers) IntentionSpecific(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
-	id := strings.TrimPrefix(req.URL.Path, "/v1/connect/intentions/")
+	id, err := getPathSuffixUnescaped(req.URL.Path, "/v1/connect/intentions/")
+	if err != nil {
+		return nil, err
+	}
 
 	switch req.Method {
 	case "GET":
diff --git a/agent/kvs_endpoint.go b/agent/kvs_endpoint.go
index 6534718d20..b6bed301be 100644
--- a/agent/kvs_endpoint.go
+++ b/agent/kvs_endpoint.go
@@ -6,7 +6,6 @@ import (
 	"io"
 	"net/http"
 	"strconv"
-	"strings"
 
 	"github.com/hashicorp/consul/agent/structs"
 	"github.com/hashicorp/consul/api"
@@ -20,7 +19,11 @@ func (s *HTTPHandlers) KVSEndpoint(resp http.ResponseWriter, req *http.Request)
 	}
 
 	// Pull out the key name, validation left to each sub-handler
-	args.Key = strings.TrimPrefix(req.URL.Path, "/v1/kv/")
+	var err error
+	args.Key, err = getPathSuffixUnescaped(req.URL.Path, "/v1/kv/")
+	if err != nil {
+		return nil, err
+	}
 
 	// Check for a key list
 	keyList := false
diff --git a/agent/prepared_query_endpoint.go b/agent/prepared_query_endpoint.go
index 023119e4ce..31e900288e 100644
--- a/agent/prepared_query_endpoint.go
+++ b/agent/prepared_query_endpoint.go
@@ -319,7 +319,10 @@ func (s *HTTPHandlers) PreparedQuerySpecific(resp http.ResponseWriter, req *http
 	}
 
 	path := req.URL.Path
-	id := strings.TrimPrefix(path, "/v1/query/")
+	id, err := getPathSuffixUnescaped(path, "/v1/query/")
+	if err != nil {
+		return nil, err
+	}
 
 	switch {
 	case strings.HasSuffix(path, "/execute"):
diff --git a/agent/session_endpoint.go b/agent/session_endpoint.go
index 97ff995b71..9371bf7418 100644
--- a/agent/session_endpoint.go
+++ b/agent/session_endpoint.go
@@ -3,7 +3,6 @@ package agent
 import (
 	"fmt"
 	"net/http"
-	"strings"
 	"time"
 
 	"github.com/hashicorp/consul/agent/structs"
@@ -72,7 +71,11 @@ func (s *HTTPHandlers) SessionDestroy(resp http.ResponseWriter, req *http.Reques
 	}
 
 	// Pull out the session id
-	args.Session.ID = strings.TrimPrefix(req.URL.Path, "/v1/session/destroy/")
+	var err error
+	args.Session.ID, err = getPathSuffixUnescaped(req.URL.Path, "/v1/session/destroy/")
+	if err != nil {
+		return nil, err
+	}
 	if args.Session.ID == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing session")
@@ -97,7 +100,11 @@ func (s *HTTPHandlers) SessionRenew(resp http.ResponseWriter, req *http.Request)
 	}
 
 	// Pull out the session id
-	args.SessionID = strings.TrimPrefix(req.URL.Path, "/v1/session/renew/")
+	var err error
+	args.SessionID, err = getPathSuffixUnescaped(req.URL.Path, "/v1/session/renew/")
+	if err != nil {
+		return nil, err
+	}
 	args.Session = args.SessionID
 	if args.SessionID == "" {
 		resp.WriteHeader(http.StatusBadRequest)
@@ -128,7 +135,11 @@ func (s *HTTPHandlers) SessionGet(resp http.ResponseWriter, req *http.Request) (
 	}
 
 	// Pull out the session id
-	args.SessionID = strings.TrimPrefix(req.URL.Path, "/v1/session/info/")
+	var err error
+	args.SessionID, err = getPathSuffixUnescaped(req.URL.Path, "/v1/session/info/")
+	if err != nil {
+		return nil, err
+	}
 	args.Session = args.SessionID
 	if args.SessionID == "" {
 		resp.WriteHeader(http.StatusBadRequest)
@@ -183,7 +194,11 @@ func (s *HTTPHandlers) SessionsForNode(resp http.ResponseWriter, req *http.Reque
 	}
 
 	// Pull out the node name
-	args.Node = strings.TrimPrefix(req.URL.Path, "/v1/session/node/")
+	var err error
+	args.Node, err = getPathSuffixUnescaped(req.URL.Path, "/v1/session/node/")
+	if err != nil {
+		return nil, err
+	}
 	if args.Node == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing node name")

From f4df4c25f26e8e1f0da400d578b9b935194b3c94 Mon Sep 17 00:00:00 2001
From: David Yu <dyu@hashicorp.com>
Date: Wed, 26 Jan 2022 10:18:31 -0800
Subject: [PATCH 52/98] docs: iptables for TProxy requirement (#12180)

* docs: iptables

Add iptables requirement

* Update website/content/docs/connect/transparent-proxy.mdx

Co-authored-by: Kyle Schochenmaier <kschoche@gmail.com>

Co-authored-by: Kyle Schochenmaier <kschoche@gmail.com>
---
 website/content/docs/connect/transparent-proxy.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx
index ee8aa12115..54c672a9b1 100644
--- a/website/content/docs/connect/transparent-proxy.mdx
+++ b/website/content/docs/connect/transparent-proxy.mdx
@@ -33,6 +33,7 @@ the traffic redirection command is automatically set up via an init container.
 * To use transparent proxy on Kubernetes, Consul-helm >= `0.32.0` and Consul-k8s >= `0.26.0` are required in addition to Consul >= `1.10.0`.
 * If the default policy for ACLs is "deny", then Service Intentions should be set up to allow intended services to connect to each other.
 Otherwise, all Connect services can talk to all other services.
+* If using Transparent Proxy, all worker nodes within a Kubernetes cluster must have the `ip_tables` kernel module running, e.g. `modprobe ip_tables`. 
 
 The Kubernetes integration takes care of registering Kubernetes services with Consul, injecting a sidecar proxy, and
 enabling traffic redirection.

From 4df488b1d3dc348006596465727f907c7b756a3e Mon Sep 17 00:00:00 2001
From: Luke Kysow <1034429+lkysow@users.noreply.github.com>
Date: Wed, 26 Jan 2022 10:39:33 -0800
Subject: [PATCH 53/98] Update distributed-tracing.mdx with caveat on 128 bit
 IDs (#12196)

* Update distributed-tracing.mdx
---
 .../docs/connect/distributed-tracing.mdx      | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/website/content/docs/connect/distributed-tracing.mdx b/website/content/docs/connect/distributed-tracing.mdx
index cabdf92b35..2098fb5ed9 100644
--- a/website/content/docs/connect/distributed-tracing.mdx
+++ b/website/content/docs/connect/distributed-tracing.mdx
@@ -238,3 +238,25 @@ config to take effect.
    Envoy not yet having support.
 
 1. Tracing is only supported with Envoy proxies, not the built-in proxy.
+
+1. When configuring the Zipkin tracer in `envoy_tracing_json`, set [`trace_id_128bit`](https://www.envoyproxy.io/docs/envoy/v1.21.0/api-v3/config/trace/v3/zipkin.proto#envoy-v3-api-field-config-trace-v3-zipkinconfig-trace-id-128bit) to  `true` if your application is configured to generate 128-bit trace IDs. For example:
+
+   <CodeBlockConfig highlight="10">
+
+   ```json
+   {
+     "http": {
+       "name": "envoy.tracers.zipkin",
+       "typedConfig": {
+         "@type": "type.googleapis.com/envoy.config.trace.v3.ZipkinConfig",
+         "collector_cluster": "zipkin",
+         "collector_endpoint_version": "HTTP_JSON",
+         "collector_endpoint": "/api/v2/spans",
+         "shared_span_context": false,
+         "trace_id_128bit": true
+       }
+     }
+   }
+   ```
+
+   </CodeBlockConfig>

From 2f291df412c82f7177926dc93d84d99a24c9ebff Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Wed, 26 Jan 2022 13:01:57 -0800
Subject: [PATCH 54/98] docs: Clarify docs for providing multiple join
 addresses

Rephrase the comment about specifying multiple join addresses to
clarify that it pertains to joining a single cluster by attempting to
contact one or more nodes.
---
 website/content/commands/join.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/website/content/commands/join.mdx b/website/content/commands/join.mdx
index 2184191352..2186e67e82 100644
--- a/website/content/commands/join.mdx
+++ b/website/content/commands/join.mdx
@@ -34,9 +34,9 @@ are not supported from commands, but may be from the corresponding HTTP endpoint
 
 Usage: `consul join [options] address ...`
 
-You may call join with multiple addresses if you want to try to join
-multiple clusters. Consul will attempt to join all addresses, and the join
-command will fail only if Consul was unable to join with any.
+You may call `join` with multiple addresses if you want attempt to join the cluster
+through multiple nodes. Consul will attempt to join all addresses. The join
+command will fail only if Consul was unable to join any of the specified addresses.
 
 #### API Options
 

From c198c7408bf93f332486a3e05b1ec18d7d5ea455 Mon Sep 17 00:00:00 2001
From: Luke Kysow <1034429+lkysow@users.noreply.github.com>
Date: Wed, 26 Jan 2022 14:22:12 -0800
Subject: [PATCH 55/98] Update docs for new client daemonset name (#12200)

---
 website/content/docs/k8s/upgrade/index.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/docs/k8s/upgrade/index.mdx b/website/content/docs/k8s/upgrade/index.mdx
index 2a2eeb67e5..05eaf5bba7 100644
--- a/website/content/docs/k8s/upgrade/index.mdx
+++ b/website/content/docs/k8s/upgrade/index.mdx
@@ -183,7 +183,7 @@ $ helm diff upgrade consul hashicorp/consul --version 0.24.1 --values /path/to/y
   grep "has changed"
 ```
 
-1. Take specific note if `consul, DaemonSet` or `consul-server, StatefulSet` are listed.
+1. Take specific note if `consul-client, DaemonSet` or `consul-server, StatefulSet` are listed.
    This means that your Consul client daemonset or Consul server statefulset (or both) will be redeployed.
 
 If either is being redeployed, we will follow the same pattern for upgrades as

From f28f0375a5368db837b1a78e365d9efa5256b98c Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 26 Jan 2022 15:11:40 -0800
Subject: [PATCH 56/98] added more complete spec info and applied feedback

---
 website/content/docs/api-gateway.mdx | 153 ++++++++++++++-------------
 1 file changed, 81 insertions(+), 72 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 38d48c725b..11cdf3355e 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -28,27 +28,27 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
   <CodeBlockConfig hideClipboard filename="values.yaml">
 
-  ```yaml
-  global:
-    name: consul
-    image: 'hashicorp/consul:1.11.2'
-    tls:
-      enabled: true
-  connectInject:
-    enabled: true
-  controller:
+```yaml
+global:
+  name: consul
+  image: 'hashicorp/consul:1.11.2'
+  tls:
     enabled: true
-  ```
+connectInject:
+  enabled: true
+controller:
+  enabled: true
+```
 
   </CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
-  ```shell-session
-  $ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
-  ```
+```shell-session
+$ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
+```
 
-  The following components will be installed:
+The following components will be installed:
 
     - Gateway controller
     - CRDs required by the Kubernetes Gateway API specification
@@ -125,53 +125,16 @@ consul-api-gateway 0.1.0
 
 Configure the following artifacts to facilitate ingress into your Consul service mesh:
 
-- [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`.
-- [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways.
 - [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gatway-related configuration parameters for the `GatewayClass` resource.
-- [Listeners](#listeners): Defines listener properties, such as protocol, port, and namespace.
+- [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways.
+- [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses.
 - [Routes](#routes): Specifies the path from the client to the listener.
 
-### Gateway
-
-The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`.
-
-Add the `kind: Gateway` option to the configuration file to declare a gateway.
-The following example creates a gateway called `example-gateway`.
-The gateway is based on the `test-gateway-class` and includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration).
-
-<CodeBlockConfig filename="gateway.yaml" lineNumbers highlight="2,4,8,9,13">
-
-```yaml
-apiVersion: gateway.networking.k8s.io/v1alpha2
-kind: Gateway
-metadata:
-  name: example-gateway
-  annotations:
-    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
-spec:
-  gatewayClassName: test-gateway-class
-  listeners:
-    - protocol: HTTPS
-      hostname: DNS_HOSTNAME
-      port: 443
-      name: https
-      allowedRoutes:
-        namespaces:
-          from: Same
-      tls:
-        certificateRefs:
-          - name: gateway-production-certificate
-```
-
-</CodeBlockConfig>
-
-Refer to the Kubernetes Gateway API documentation for details about configuring gateways:
-<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway>
-
 ### GatewayClass
 
 The `GatewayClass` resource is used as a template for creating `Gateway` resources.
 The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resource within the cluster (`parametersRef`).
+The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`.
 
 When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation.
 If you want to propagate changes made to the `GatewayClass` after gateways have been created, then the implementation must document this behavior.
@@ -216,10 +179,10 @@ metadata:
   name: test-gateway-class-config
 spec:
   useHostPorts: true
-  logLevel: trace
+  logLevel: 'trace'
   consul:
-    scheme: https
-    caSecret: consul-ca-cert
+    scheme: 'https'
+    caSecret: 'consul-ca-cert'
     ports:
       http: 8501
       grpc: 8502
@@ -229,23 +192,65 @@ spec:
 
 The following table describes the required parameters for the `spec` array:
 
-| Parameter      | Description                                                                                                                                          | Type    | Default |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- |
-| `useHostPorts` | Enables the gateway to use the host ports                                                                                                            | Boolean | `true`  |
-| `logLevel`     | Specifies the error reporting level for logs. You can specify the following values: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`, `OFF` | String  | `trace` |
-| `consul`       | Specifies ingress properties for Consul. See [Consul Configuration](#consul-configuration)                                                           | Array   | N/A     |
+| Parameter                         | Description                                                                                                                                                                                                                                                                                                               | Type    | Default                                          |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
+| `consul.address`                  | Specifies the address of the Consul server to communicate with in the gateway pod. If unspecified, the pod will attempt to use a local agent on the host on which the pod is running.                                                                                                                                     | String  | N/A                                              |
+| `consul.authentication.account`   | Specifies the Kubernetes service account to use for authentication.                                                                                                                                                                                                                                                       | String  | N/A                                              |
+| `consul.authentication.managed`   | Set to `true` to enable deployments to run with managed service accounts created by the gateway controller. The `consul.authentication.account` field is ignored when this option is enabled.                                                                                                                             | Boolean | `false`                                          |
+| `consul.authentication.method`    | Specifies the Consul auth method used for initial authentication by Consul API Gateway.                                                                                                                                                                                                                                   | String  | N/A                                              |
+| `consul.authentication.namespace` | Specifies the Consul namespace to use for authentication.                                                                                                                                                                                                                                                                 | String  | N/A                                              |
+| `consul.ports.grpc`               | Specifies the gRPC port for Consul's xDS server.                                                                                                                                                                                                                                                                          | Integer | `8502`                                           |
+| `consul.ports.http`               | Specifies the port for Consul's HTTP server.                                                                                                                                                                                                                                                                              | Integer | `8500`                                           |
+| `consul.scheme`                   | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`.                                                                                                                                                                                                                    | String  | `"http"`                                         |
+| `copyAnnotations.service`         | List of annotations to copy to the gateway service.                                                                                                                                                                                                                                                                       | Array   | `["external-dns.alpha.kubernetes.io/hostname"]`  |
+| `image.consulAPIGateway`          | The image to use for consul-api-gateway.                                                                                                                                                                                                                                                                                  | String  | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` |
+| `image.envoy`                     | Specifies the container image to use for Envoy.                                                                                                                                                                                                                                                                           | String  | `"envoyproxy/envoy:v1.19-latest"`                |
+| `logLevel`                        | Specifies the error reporting level for logs. You can specify the following values: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`, `OFF`                                                                                                                                                                      | String  | `"info"`                                         |
+| `nodeSelector`                    | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ | Object  | N/A                                              |
+| `serviceType`                     | Sepcifies the ingress methods for a service. The following values are supported: <br/>`ClusterIP` <br/>`NodePort` <br/>`LoadBalancer`                                                                                                                                                                                     | String  | N/A                                              |
+| `useHostPorts`                    | If set to `true`, then the Envoy container ports are mapped to host ports.                                                                                                                                                                                                                                                | Boolean | `false`                                          |
+
+Refer to the Consul API Gateway repository for the complete specification:
+<https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml>
 
-#### Consul Configuration
+### Gateway
 
-The following table describes the parameters available for the `consul` element of the `GatewayClassConfiguration`:
+The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`.
 
-| Parameter  | Description                                                   | Type   | Default                         |
-| ---------- | ------------------------------------------------------------- | ------ | ------------------------------- |
-| `scheme`   | Specifies the message protocol.                               | String | `http`                          |
-| `caSecret` | Specifies the name of the CA secret.                          | String | none                            |
-| `ports`    | Specifies which ports to use for API and application traffic. | Array  | `http: 8501` <br/> `grpc: 8502` |
+Add the `kind: Gateway` option to the configuration file to declare a gateway.
+The following example creates a gateway called `example-gateway`.
+The gateway is based on the `test-gateway-class` and includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration).
 
-### Listeners
+<CodeBlockConfig filename="gateway.yaml">
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: Gateway
+metadata:
+  name: example-gateway
+  annotations:
+    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
+spec:
+  gatewayClassName: test-gateway-class
+  listeners:
+    - protocol: HTTPS
+      hostname: DNS_HOSTNAME
+      port: 443
+      name: https
+      allowedRoutes:
+        namespaces:
+          from: Same
+      tls:
+        certificateRefs:
+          - name: gateway-production-certificate
+```
+
+</CodeBlockConfig>
+
+Refer to the Kubernetes Gateway API documentation for details about configuring gateways:
+<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway>
+
+#### Listeners
 
 Listeners are the logical endpoints bound to the gateway's addresses.
 Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener:
@@ -257,14 +262,16 @@ Add the `listener` object to the `gateway` configuration and specify the followi
 Refer to the Kubernetes Gateway API documentation for details about configuring listeners:
 <https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener>
 
-In the example included the [Gateway](#gateway) description, a listener named `https` that listens over `HTTPS` is configured to listen on port `443`
-
 ### Route
 
 Routes are independent configuration objects that are associated with specific listeners.
+
 Use the `kind: HTTPRoute` option to declare a route and use the `spec` option to specify the route details.
+
 The following example creates a route named `example-route` associated with a listener defined in `example-gateway`.
 
+<CodeBlockConfig filename="routes.yaml">
+
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1alpha2
 kind: HTTPRoute
@@ -279,3 +286,5 @@ spec:
           name: echo
           port: 8080
 ```
+
+</CodeBlockConfig>

From f2f0c5156b3de7955e0e586def83edbae9b4e253 Mon Sep 17 00:00:00 2001
From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Date: Wed, 26 Jan 2022 15:16:22 -0800
Subject: [PATCH 57/98] Apply suggestions from code review

Adding content and feedback from @mikemorris

Co-authored-by: Mike Morris <mikemorris@users.noreply.github.com>
---
 website/content/docs/api-gateway.mdx | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 11cdf3355e..79c5ba32d4 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -10,9 +10,9 @@ This topic describes how to use the Consul API Gateway add-on module, which help
 
 ## Introduction
 
-Consul API Gateway is an implementation of the Kubernetes Gateway [API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases:
+Consul API Gateway is an implementation of the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases:
 
-- **Controlling access at the point entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., VeriSign, Let’sEncrypt).
+- **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., VeriSign, Let’sEncrypt).
 - **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service based on matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH).
 
 ## Requirements
@@ -137,8 +137,6 @@ The specification includes the name of the controller (`controllerName`) and an
 The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`.
 
 When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation.
-If you want to propagate changes made to the `GatewayClass` after gateways have been created, then the implementation must document this behavior.
-The `gateway-exists-finalizer.gateway.networking.k8s.io` finalizer must also be added to a `GatewayClass` to ensure that a `GatewayClass` associated with a `Gateway` is not deleted while in use.
 
 Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class.
 The following example creates a gateway class called `test-gateway-class`.
@@ -258,6 +256,13 @@ Add the `listener` object to the `gateway` configuration and specify the followi
 - `hostname`: Hostname specifies the virtual hostname to match for protocol types.
 - `port`: Specifies the network port.
 - `protocol`: Specifies the network protocol expected by the listener.
+- `tls` [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig)
+  - `mode` [`TLSModeType`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType): Defaults to `Terminate` if unspecified, `Passthrough` is not yet supported.
+  - `certificateRefs` [`[]*SecretObjectReference`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference): Used for Envoy SDS (Secret Discovery Service) to support terminating TLS.
+  - `options`:  Key/value pairs to enable implementation-specific extended TLS configuration. Consul API Gateway supports the following options:
+    - `"api-gateway.consul.hashicorp.com/tls_min_version"`: Set the minimum TLS version supported for this listener. Allowed values are `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. If unspecified, Consul API Gateway will default to TLS 1.2.
+    - `"api-gateway.consul.hashicorp.com/tls_max_version"`: Set the maximum TLS version supported for this listener. Must be greater than or equal to `TLSMinVersion`. Allowed values are `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Consul API Gateway will use Envoy's current default of TLS 1.3.
+    - `"api-gateway.consul.hashicorp.com/tls_cipher_suites"`: Set the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier. If unspecified, Consul API Gateway will set a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites). The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. Future releases of Envoy may remove currently-supported but insecure cipher suites, and future releases of Consul API Gateway may add new supported cipher suites if any are added to Envoy.
 
 Refer to the Kubernetes Gateway API documentation for details about configuring listeners:
 <https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener>

From c7ac8b0eaea127f0883e639a03881ae2f2836c45 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Wed, 26 Jan 2022 16:04:24 -0800
Subject: [PATCH 58/98] integrated TLS info

---
 website/content/docs/api-gateway.mdx | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 79c5ba32d4..5cddea611c 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -253,16 +253,18 @@ Refer to the Kubernetes Gateway API documentation for details about configuring
 Listeners are the logical endpoints bound to the gateway's addresses.
 Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener:
 
-- `hostname`: Hostname specifies the virtual hostname to match for protocol types.
-- `port`: Specifies the network port.
-- `protocol`: Specifies the network protocol expected by the listener.
-- `tls` [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig)
-  - `mode` [`TLSModeType`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType): Defaults to `Terminate` if unspecified, `Passthrough` is not yet supported.
-  - `certificateRefs` [`[]*SecretObjectReference`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference): Used for Envoy SDS (Secret Discovery Service) to support terminating TLS.
-  - `options`:  Key/value pairs to enable implementation-specific extended TLS configuration. Consul API Gateway supports the following options:
-    - `"api-gateway.consul.hashicorp.com/tls_min_version"`: Set the minimum TLS version supported for this listener. Allowed values are `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. If unspecified, Consul API Gateway will default to TLS 1.2.
-    - `"api-gateway.consul.hashicorp.com/tls_max_version"`: Set the maximum TLS version supported for this listener. Must be greater than or equal to `TLSMinVersion`. Allowed values are `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Consul API Gateway will use Envoy's current default of TLS 1.3.
-    - `"api-gateway.consul.hashicorp.com/tls_cipher_suites"`: Set the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier. If unspecified, Consul API Gateway will set a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites). The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. Future releases of Envoy may remove currently-supported but insecure cipher suites, and future releases of Consul API Gateway may add new supported cipher suites if any are added to Envoy.
+| Parameter                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Type    | Default         |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- |
+| `hostname`                      | Specifies the virtual hostname to match for protocol types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | String  | none            |
+| `port`                          | Specifies the network port number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Integer | none            |
+| `protocol`                      | Specifies the network protocol expected by the listener.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | String  | `http`          |
+| `tls`                           | Collection of parameters that specify TLS options for the listener. Refer to the [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig) documentation for additional information about configuring TLS.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Object  | N/A             |
+| `tls.mode`                      | Specifies a mode for operating Consul API Gateway listeners over TLS. <br/>You can only specify the `Terminate` mode, which configures the TLS session between the downstream client and the gateway to terminate at the gateway. <br/>Refer to the [`TLSModeType` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType) for additional information.                                                                                                                                                                                                                                                                                                                      | String  | `Terminate`     |
+| `tls.certificateRefs`           | Specifies the name of secret object used for Envoy SDS (Secret Discovery Service) to support terminating TLS. Refer to the [`[]*SecretObjectReference` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference) for additional information.                                                                                                                                                                                                                                                                                                                                                                                                                        | String  | N/A             |
+| `tls.options`                   | Specifies key/value pairs to enable extended TLS configuration specific to an implementation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Object  | N/A             |
+| `tls.options.tls_min_version`   | Specifies the minimum TLS version supported for the listener. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | String  | `TLS 1.2`       |
+| `tls.options.tls_max_version"`  | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | String  | `TLS 1.3`       |
+| `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier. <br/>If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites) will be used. <br/>The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String  | See description |
 
 Refer to the Kubernetes Gateway API documentation for details about configuring listeners:
 <https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener>

From eac0f5b860951cf3b51fd11d4d65b8f64e9bfb24 Mon Sep 17 00:00:00 2001
From: John Cowen <johncowen@users.noreply.github.com>
Date: Thu, 27 Jan 2022 11:21:12 +0000
Subject: [PATCH 59/98] ui: class-map helper (#12202)

{{class-map}} is used to easily add a list of classes, conditionally, and
have them all formatted nicely ready to be printed in a DOM class attribute.

For ease, as well as using entries, you can also just provide a simple string
without the boolean and that class will always be added.
---
 .../consul-ui/app/helpers/class-map.js        | 17 +++++++
 .../consul-ui/app/helpers/class-map.mdx       | 45 +++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 ui/packages/consul-ui/app/helpers/class-map.js
 create mode 100644 ui/packages/consul-ui/app/helpers/class-map.mdx

diff --git a/ui/packages/consul-ui/app/helpers/class-map.js b/ui/packages/consul-ui/app/helpers/class-map.js
new file mode 100644
index 0000000000..c698dd7a63
--- /dev/null
+++ b/ui/packages/consul-ui/app/helpers/class-map.js
@@ -0,0 +1,17 @@
+import { helper } from '@ember/component/helper';
+
+/**
+ * Conditionally maps classInfos (classes) to a string ready for typical DOM
+ * usage (i.e. space delimited)
+ *
+ * @typedef {([string, boolean] | [string])} classInfo
+ * @param {(classInfo | string)[]} entries - An array of 'entry-like' arrays of `classInfo`s to map
+ */
+const classMap = entries => {
+  const str = entries
+    .filter(entry => (typeof entry === 'string' ? true : entry[entry.length - 1]))
+    .map(entry => (typeof entry === 'string' ? entry : entry[0]))
+    .join(' ');
+  return str.length > 0 ? str : undefined;
+};
+export default helper(classMap);
diff --git a/ui/packages/consul-ui/app/helpers/class-map.mdx b/ui/packages/consul-ui/app/helpers/class-map.mdx
new file mode 100644
index 0000000000..21db053f8f
--- /dev/null
+++ b/ui/packages/consul-ui/app/helpers/class-map.mdx
@@ -0,0 +1,45 @@
+# class-map
+
+`{{class-map}}` is used to easily add a list of classes, conditionally, and
+have them all formatted nicely ready to be printed in a DOM `class` attribute.
+
+For ease, as well as using entries, you can also just provide a simple string
+without the boolean and that class will always be added.
+
+```hbs preview-template
+<figure>
+  <figcaption>
+    The correct classes added/omitted
+  </figcaption>
+  <div
+    class={{class-map
+      'component-name'
+      (array 'add-this-class' true)
+      (array 'dont-add-this-class' false)
+      'simple-string-class'
+    }}
+    ...attributes
+  >
+    <code>
+      class="{{class-map
+        (array 'add-this-class' true)
+        (array 'dont-add-this-class' false)
+        'simple-string-class'
+      }}"
+    </code>
+  </div>
+</figure>
+```
+
+## Positional Arguments
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `entries` | `(classInfo \| string)[]` |  | An array of 'entry-like' arrays of `classInfo`s to map |
+
+## Types
+
+| Type | Default | Description |
+| --- | --- | --- |
+| `classInfo` | `([string, boolean] \| [string])` |  |
+

From de13e207e5d788ed0e57096464841f918f3f5cc6 Mon Sep 17 00:00:00 2001
From: John Cowen <johncowen@users.noreply.github.com>
Date: Thu, 27 Jan 2022 11:27:38 +0000
Subject: [PATCH 60/98] ui: css-prop modifier (#12205)

Get the value for a single specific CSS Property from the modified element.
returns can be specified either as a second parameter or an option.
---
 .../consul-ui/app/modifiers/css-prop.js       | 12 +++++++++
 .../consul-ui/app/modifiers/css-prop.mdx      | 25 +++++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 ui/packages/consul-ui/app/modifiers/css-prop.js
 create mode 100644 ui/packages/consul-ui/app/modifiers/css-prop.mdx

diff --git a/ui/packages/consul-ui/app/modifiers/css-prop.js b/ui/packages/consul-ui/app/modifiers/css-prop.js
new file mode 100644
index 0000000000..2b836acd11
--- /dev/null
+++ b/ui/packages/consul-ui/app/modifiers/css-prop.js
@@ -0,0 +1,12 @@
+import Modifier from 'ember-modifier';
+import { inject as service } from '@ember/service';
+
+export default class CSSPropModifier extends Modifier {
+  @service('-document') doc;
+  didReceiveArguments() {
+    const params = this.args.positional;
+    const options = this.args.named;
+    const returns = params[1] || options.returns;
+    returns(this.doc.defaultView.getComputedStyle(this.element).getPropertyValue(params[0]));
+  }
+}
diff --git a/ui/packages/consul-ui/app/modifiers/css-prop.mdx b/ui/packages/consul-ui/app/modifiers/css-prop.mdx
new file mode 100644
index 0000000000..2ddf1bead5
--- /dev/null
+++ b/ui/packages/consul-ui/app/modifiers/css-prop.mdx
@@ -0,0 +1,25 @@
+# css-prop
+
+Get the value for a single specific CSS Property from the modified element.
+`returns` can be specified either as a second parameter or an option.
+
+```hbs preview-template
+<div
+  {{css-prop '--red-500' returns=(set this 'red')}}
+>
+  <code>--red-500: {{this.red}}</code>
+</div>
+```
+
+## Positional Arguments
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `property` | `string` |  | The name of the CSS property to fetch from the element |
+| `returns` | `function` |  | Usually `set` or `mut` or similar |
+
+## Named Arguments
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `returns` | `function` |  | See the `returns` positional argument |

From c1d438ed03d8cf7690baea06449f54aa2eed8d4a Mon Sep 17 00:00:00 2001
From: "Chris S. Kim" <ckim@hashicorp.com>
Date: Thu, 27 Jan 2022 10:59:05 -0500
Subject: [PATCH 61/98] ci: Update CI to stash changes before checkout (#12210)

---
 .circleci/config.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index aa5c02dd3b..cb1b1a5885 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -690,10 +690,15 @@ jobs:
               git config --local user.email "github-team-consul-core@hashicorp.com"
               git config --local user.name "hc-github-team-consul-core"
               
+              # stash newly built bindata_assetfs.go
+              git stash push
+              
               # checkout the CI branch and merge latest from main
               git checkout ci/main-assetfs-build
               git merge --no-edit main
             
+              git stash pop
+            
               short_sha=$(git rev-parse --short HEAD)
               git add agent/uiserver/bindata_assetfs.go
               git commit -m "auto-updated agent/uiserver/bindata_assetfs.go from commit ${short_sha}"

From 4d97b6852619fca713ed54c2181272ce0350a72c Mon Sep 17 00:00:00 2001
From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Date: Thu, 27 Jan 2022 08:06:54 -0800
Subject: [PATCH 62/98] Apply suggestions from code review

Thanks for catching my typos!

Co-authored-by: Nathan Coleman <nathandanielcoleman@gmail.com>
---
 website/content/docs/api-gateway.mdx | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 5cddea611c..eceefb8bd4 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -12,8 +12,8 @@ This topic describes how to use the Consul API Gateway add-on module, which help
 
 Consul API Gateway is an implementation of the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases:
 
-- **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., VeriSign, Let’sEncrypt).
-- **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service based on matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH).
+- **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., Verisign, Let’s Encrypt).
+- **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH).
 
 ## Requirements
 
@@ -54,7 +54,7 @@ The following components will be installed:
     - CRDs required by the Kubernetes Gateway API specification
     - `kustomize` manifests for completing the installation
 
-1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster.
+1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster:
 
 ```shell-session
 $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
@@ -65,7 +65,7 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=
 
 1. Verify that the [requirements](#requirements) have been met.
 1. Verify that the Consul API Gateway software has been installed and applied (see [Installation](#installation)).
-1. Configure the gateway, listener(s), and route(s) as described in [Configuration](#configuration)
+1. Configure the gateway, listener(s), and route(s) as described in [Configuration](#configuration).
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
 ```shell-session
@@ -125,7 +125,7 @@ consul-api-gateway 0.1.0
 
 Configure the following artifacts to facilitate ingress into your Consul service mesh:
 
-- [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gatway-related configuration parameters for the `GatewayClass` resource.
+- [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gateway-related configuration parameters for the `GatewayClass` resource.
 - [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways.
 - [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses.
 - [Routes](#routes): Specifies the path from the client to the listener.
@@ -133,13 +133,13 @@ Configure the following artifacts to facilitate ingress into your Consul service
 ### GatewayClass
 
 The `GatewayClass` resource is used as a template for creating `Gateway` resources.
-The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resource within the cluster (`parametersRef`).
+The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resources within the cluster (`parametersRef`).
 The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`.
 
 When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation.
 
 Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class.
-The following example creates a gateway class called `test-gateway-class`.
+The following example creates a gateway class called `test-gateway-class`:
 
 <CodeBlockConfig filename="gateway.yaml">
 
@@ -166,7 +166,7 @@ Refer to the Kubernetes Gateway API documentation for details about configuring
 The `GatewayClassConfig` object describes additional Consul API Gateway-related configuration parameters for the `GatewayClass`.
 
 Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class.
-The following example creates a gateway class called `test-gateway-class-config`.
+The following example creates a gateway class called `test-gateway-class-config`:
 
 <CodeBlockConfig filename="gateway.yaml">
 
@@ -203,9 +203,9 @@ The following table describes the required parameters for the `spec` array:
 | `copyAnnotations.service`         | List of annotations to copy to the gateway service.                                                                                                                                                                                                                                                                       | Array   | `["external-dns.alpha.kubernetes.io/hostname"]`  |
 | `image.consulAPIGateway`          | The image to use for consul-api-gateway.                                                                                                                                                                                                                                                                                  | String  | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` |
 | `image.envoy`                     | Specifies the container image to use for Envoy.                                                                                                                                                                                                                                                                           | String  | `"envoyproxy/envoy:v1.19-latest"`                |
-| `logLevel`                        | Specifies the error reporting level for logs. You can specify the following values: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`, `OFF`                                                                                                                                                                      | String  | `"info"`                                         |
+| `logLevel`                        | Specifies the error reporting level for logs. You can specify the following values: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`, `OFF`.                                                                                                                                                                      | String  | `"info"`                                         |
 | `nodeSelector`                    | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ | Object  | N/A                                              |
-| `serviceType`                     | Sepcifies the ingress methods for a service. The following values are supported: <br/>`ClusterIP` <br/>`NodePort` <br/>`LoadBalancer`                                                                                                                                                                                     | String  | N/A                                              |
+| `serviceType`                     | Specifies the ingress methods for a service. The following values are supported: <br/>`ClusterIP` <br/>`NodePort` <br/>`LoadBalancer`.                                                                                                                                                                                     | String  | N/A                                              |
 | `useHostPorts`                    | If set to `true`, then the Envoy container ports are mapped to host ports.                                                                                                                                                                                                                                                | Boolean | `false`                                          |
 
 Refer to the Consul API Gateway repository for the complete specification:

From 3324bea8294ca18e8bb9c4a15075e3af58747f6c Mon Sep 17 00:00:00 2001
From: Mike Morris <mikemorris@users.noreply.github.com>
Date: Thu, 27 Jan 2022 11:12:23 -0500
Subject: [PATCH 63/98] website: fix indentation to resolve CodeBlockConfig
 syntax error

---
 website/content/docs/api-gateway.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index eceefb8bd4..d7446ec3a8 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -26,7 +26,7 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
 1. Create a values file for your Consul server agents that contains the following parameters:
 
-  <CodeBlockConfig hideClipboard filename="values.yaml">
+<CodeBlockConfig hideClipboard filename="values.yaml">
 
 ```yaml
 global:
@@ -40,7 +40,7 @@ controller:
   enabled: true
 ```
 
-  </CodeBlockConfig>
+</CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 

From 1c7a9c688546106f63f34fc7c2950027fad051e9 Mon Sep 17 00:00:00 2001
From: Mike Morris <mikemorris@users.noreply.github.com>
Date: Thu, 27 Jan 2022 11:34:11 -0500
Subject: [PATCH 64/98] website: fix ordering of list with nested code blocks

---
 website/content/docs/api-gateway.mdx | 54 ++++++++++++++--------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index d7446ec3a8..0f3817a79c 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -26,40 +26,40 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
 1. Create a values file for your Consul server agents that contains the following parameters:
 
-<CodeBlockConfig hideClipboard filename="values.yaml">
-
-```yaml
-global:
-  name: consul
-  image: 'hashicorp/consul:1.11.2'
-  tls:
+  <CodeBlockConfig hideClipboard filename="values.yaml">
+
+  ```yaml
+  global:
+    name: consul
+    image: 'hashicorp/consul:1.11.2'
+    tls:
+      enabled: true
+  connectInject:
     enabled: true
-connectInject:
-  enabled: true
-controller:
-  enabled: true
-```
+  controller:
+    enabled: true
+  ```
 
-</CodeBlockConfig>
+  </CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
-```shell-session
-$ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
-```
+  ```shell-session
+  $ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
+  ```
 
-The following components will be installed:
+  The following components will be installed:
 
-    - Gateway controller
-    - CRDs required by the Kubernetes Gateway API specification
-    - `kustomize` manifests for completing the installation
+     - Gateway controller
+     - CRDs required by the Kubernetes Gateway API specification
+     - `kustomize` manifests for completing the installation
 
 1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster:
 
-```shell-session
-$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
-$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
-```
+  ```shell-session
+  $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
+  $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
+  ```
 
 ## Usage
 
@@ -68,9 +68,9 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=
 1. Configure the gateway, listener(s), and route(s) as described in [Configuration](#configuration).
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
-```shell-session
-$ kubectl apply --values gateway-configuration.yaml
-```
+  ```shell-session
+  $ kubectl apply --values gateway-configuration.yaml
+  ```
 
 <!--- Commented out per https://github.com/hashicorp/consul/pull/11951/files#r791204596
 

From 474e03f0d2a41864ee0b2de5a5c51eed457b6da2 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Mon, 13 Dec 2021 17:02:35 -0600
Subject: [PATCH 65/98] docs: Merge ECS Architecture into overview

---
 website/content/docs/ecs/architecture.mdx     | 96 -------------------
 .../content/docs/ecs/get-started/install.mdx  |  2 +-
 .../get-started/production-installation.mdx   |  2 +-
 website/content/docs/ecs/index.mdx            | 91 ++++++++++++++++++
 website/data/docs-nav-data.json               |  4 -
 5 files changed, 93 insertions(+), 102 deletions(-)
 delete mode 100644 website/content/docs/ecs/architecture.mdx

diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx
deleted file mode 100644
index b6e262832e..0000000000
--- a/website/content/docs/ecs/architecture.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-layout: docs
-page_title: Architecture - AWS ECS
-description: >-
-  Architecture of Consul Service Mesh on AWS ECS (Elastic Container Service).
----
-
-# Architecture
-
-The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster:
-
-![Consul on ECS Architecture](/img/consul-ecs-arch.png)
-
-1. **Consul servers:** Production-ready Consul server cluster
-1. **Application tasks:** Runs user application containers along with two helper containers:
-   1. **Consul client:** The Consul client container runs Consul. The Consul client communicates
-      with the Consul server and configures the Envoy proxy sidecar. This communication
-      is called _control plane_ communication.
-   1. **Sidecar proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests
-      to and from the application container(s) run through the sidecar proxy. This communication
-      is called _data plane_ communication.
-1. **ACL Controller:** Automatically provisions Consul ACL tokens for Consul clients and service mesh services
-   in an ECS Cluster.
-
-For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture).
-
-In addition to the long-running Consul client and sidecar proxy containers, the `mesh-init` container runs
-at startup and sets up initial configuration for Consul and Envoy.
-
-### Task Startup
-
-This diagram shows the timeline of a task starting up and all its containers:
-
-<img alt="Task Startup Timeline" src="/img/ecs-task-startup.svg" style={{display: "block", maxWidth: "400px"}} />
-
-- **T0:** ECS starts the task. The `consul-client` and `mesh-init` containers start:
-  - `consul-client` uses the `retry-join` option to join the Consul cluster
-  - `mesh-init` registers the service for the current task and its sidecar proxy with
-    Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s
-    bootstrap JSON file and write it to a shared volume. `mesh-init` exits after completing these operations.
-
-- **T1:** The following containers start:
-  - The `sidecar-proxy` container starts and runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
-  - If applicable, the `health-sync` container syncs health checks from ECS to Consul (see [ECS Health Check Syncing](#ecs-health-check-syncing)).
-- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, your application containers are started since all Consul machinery is ready to service requests. The only running containers are `consul-client`, `sidecar-proxy`, and your application container(s).
-
-### Task Shutdown
-
-This diagram shows an example timeline of a task shutting down:
-
-<img alt="Task Shutdown Timeline" src="/img/ecs-task-shutdown.svg" style={{display: "block", maxWidth: "400px"}} />
-
-- **T0**: ECS sends a TERM signal to all containers. Each container reacts to the TERM signal:
-  - `consul-client` begins to gracefully leave the Consul cluster.
-  - `health-sync` stops syncing health status from ECS into Consul checks.
-  - `sidecar-proxy` ignores the TERM signal and continues running until the `user-app` container exits. This allows the application container to continue making outgoing requests through the proxy to the mesh.
-  - `user-app` exits if it is not configured to ignore the TERM signal. The `user-app` container will continue running if it is configured to ignore the TERM signal.
-- **T1**:
-  - `health-sync` updates its Consul checks to critical status and exits. This ensures this service instance is marked unhealthy.
-  - `sidecar-proxy` notices the `user-app` container has stopped and exits.
-- **T2**: `consul-client` finishes gracefully leaving the Consul datacenter and exits.
-- **T3**:
-  - ECS notices all containers have exited, and will soon change the Task status to `STOPPED`
-  - Updates about this task have reached the rest of the Consul cluster, so downstream proxies have been updated to stopped sending traffic to this task.
-- **T4**: At this point task shutdown should be complete. Otherwise, ECS will send a KILL signal to any containers still running. The KILL signal cannot be ignored and will forcefully stop containers. This will interrupt in-progress operations and possibly cause errors.
-
-### Automatic ACL Token Provisioning
-
-Consul ACL tokens secure communication between agents and services.
-The following containers in a task require an ACL token:
-
-- `consul-client`: The Consul client uses a token to authorize itself with Consul servers.
-  All `consul-client` containers share the same token.
-- `mesh-init`: The `mesh-init` container uses a token to register the service with Consul.
-  This token is unique for the Consul service, and is shared by instances of the service.
-
-The ACL controller automatically creates ACL tokens for mesh-enabled tasks in an ECS cluster.
-The `acl-controller` Terraform module creates the ACL controller task. The controller creates the
-ACL token used by `consul-client` containers at startup and then watches for tasks in the cluster. It checks tags
-to determine if the task is mesh-enabled. If so, it creates the service ACL token for the task, if the
-token does not yet exist.
-
-The ACL controller stores all ACL tokens in AWS Secrets Manager, and tasks are configured to pull these
-tokens from AWS Secrets Manager when they start.
-
-### ECS Health Check Syncing
-
-If the following conditions apply, ECS health checks automatically sync with Consul health checks for all application containers:
-
-* marked as `essential` 
-* have ECS `healthChecks` 
-* are not configured with native Consul health checks 
-
-The `mesh-init` container creates a TTL health check for
-every container that fits these criteria and the `health-sync` container ensures
-that the ECS and Consul health checks remain in sync.
diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx
index b6d5230636..9bca982489 100644
--- a/website/content/docs/ecs/get-started/install.mdx
+++ b/website/content/docs/ecs/get-started/install.mdx
@@ -182,5 +182,5 @@ python manage.py runserver "127.0.0.1:8080"
 - Configure a secure [Production Installation](/docs/ecs/get-started/production-installation).
 - Now that your applications are running in the service mesh, read about
   other [Service Mesh features](/docs/connect).
-- View the [Architecture](/docs/ecs/architecture) documentation to understand
+- View the [Architecture](/docs/ecs#architecture) documentation to understand
   what's going on under the hood.
diff --git a/website/content/docs/ecs/get-started/production-installation.mdx b/website/content/docs/ecs/get-started/production-installation.mdx
index 8e0c8199a4..2f9bb0551e 100644
--- a/website/content/docs/ecs/get-started/production-installation.mdx
+++ b/website/content/docs/ecs/get-started/production-installation.mdx
@@ -19,7 +19,7 @@ A secure Consul cluster should include the following:
 ## Deploy ACL Controller
 
 Before deploying your service, you will need to deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller) so that it can provision the necessary tokens
-for tasks on the service mesh. To learn more about the ACL Controller, please see [Automatic ACL Token Provisioning](/docs/ecs/architecture#automatic-acl-token-provisioning).
+for tasks on the service mesh. To learn more about the ACL Controller, please see [Automatic ACL Token Provisioning](/docs/ecs#automatic-acl-token-provisioning).
 
 To deploy the controller, you will first need store an ACL token with `acl:write` privileges
 and a CA certificate for the Consul server in AWS Secrets Manager.
diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx
index 68fa655bbe..27a44bef59 100644
--- a/website/content/docs/ecs/index.mdx
+++ b/website/content/docs/ecs/index.mdx
@@ -28,3 +28,94 @@ There are several ways to get started with Consul with ECS.
 * The [Consul with Dev Server on EC2](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2) example installation deploys a sample application in ECS using the EC2 launch type.
 
 See the [Requirements](/docs/ecs/get-started/requirements) and the full [Install Guide](/docs/ecs/get-started/install) when you're ready to install Consul on an existing ECS cluster and add existing tasks to the service mesh.
+
+
+## Architecture
+
+The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster:
+
+![Consul on ECS Architecture](/img/consul-ecs-arch.png)
+
+1. **Consul servers:** Production-ready Consul server cluster
+1. **Application tasks:** Runs user application containers along with two helper containers:
+   1. **Consul client:** The Consul client container runs Consul. The Consul client communicates
+      with the Consul server and configures the Envoy proxy sidecar. This communication
+      is called _control plane_ communication.
+   1. **Sidecar proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests
+      to and from the application container(s) run through the sidecar proxy. This communication
+      is called _data plane_ communication.
+1. **ACL Controller:** Automatically provisions Consul ACL tokens for Consul clients and service mesh services
+   in an ECS Cluster.
+
+For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture).
+
+In addition to the long-running Consul client and sidecar proxy containers, the `mesh-init` container runs
+at startup and sets up initial configuration for Consul and Envoy.
+
+### Task Startup
+
+This diagram shows the timeline of a task starting up and all its containers:
+
+<img alt="Task Startup Timeline" src="/img/ecs-task-startup.svg" style={{display: "block", maxWidth: "400px"}} />
+
+- **T0:** ECS starts the task. The `consul-client` and `mesh-init` containers start:
+  - `consul-client` uses the `retry-join` option to join the Consul cluster
+  - `mesh-init` registers the service for the current task and its sidecar proxy with
+    Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s
+    bootstrap JSON file and write it to a shared volume. `mesh-init` exits after completing these operations.
+
+- **T1:** The following containers start:
+  - The `sidecar-proxy` container starts and runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
+  - If applicable, the `health-sync` container syncs health checks from ECS to Consul (see [ECS Health Check Syncing](#ecs-health-check-syncing)).
+- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, your application containers are started since all Consul machinery is ready to service requests. The only running containers are `consul-client`, `sidecar-proxy`, and your application container(s).
+
+### Task Shutdown
+
+This diagram shows an example timeline of a task shutting down:
+
+<img alt="Task Shutdown Timeline" src="/img/ecs-task-shutdown.svg" style={{display: "block", maxWidth: "400px"}} />
+
+- **T0**: ECS sends a TERM signal to all containers. Each container reacts to the TERM signal:
+  - `consul-client` begins to gracefully leave the Consul cluster.
+  - `health-sync` stops syncing health status from ECS into Consul checks.
+  - `sidecar-proxy` ignores the TERM signal and continues running until the `user-app` container exits. This allows the application container to continue making outgoing requests through the proxy to the mesh.
+  - `user-app` exits if it is not configured to ignore the TERM signal. The `user-app` container will continue running if it is configured to ignore the TERM signal.
+- **T1**:
+  - `health-sync` updates its Consul checks to critical status and exits. This ensures this service instance is marked unhealthy.
+  - `sidecar-proxy` notices the `user-app` container has stopped and exits.
+- **T2**: `consul-client` finishes gracefully leaving the Consul datacenter and exits.
+- **T3**:
+  - ECS notices all containers have exited, and will soon change the Task status to `STOPPED`
+  - Updates about this task have reached the rest of the Consul cluster, so downstream proxies have been updated to stopped sending traffic to this task.
+- **T4**: At this point task shutdown should be complete. Otherwise, ECS will send a KILL signal to any containers still running. The KILL signal cannot be ignored and will forcefully stop containers. This will interrupt in-progress operations and possibly cause errors.
+
+### Automatic ACL Token Provisioning
+
+Consul ACL tokens secure communication between agents and services.
+The following containers in a task require an ACL token:
+
+- `consul-client`: The Consul client uses a token to authorize itself with Consul servers.
+  All `consul-client` containers share the same token.
+- `mesh-init`: The `mesh-init` container uses a token to register the service with Consul.
+  This token is unique for the Consul service, and is shared by instances of the service.
+
+The ACL controller automatically creates ACL tokens for mesh-enabled tasks in an ECS cluster.
+The `acl-controller` Terraform module creates the ACL controller task. The controller creates the
+ACL token used by `consul-client` containers at startup and then watches for tasks in the cluster. It checks tags
+to determine if the task is mesh-enabled. If so, it creates the service ACL token for the task, if the
+token does not yet exist.
+
+The ACL controller stores all ACL tokens in AWS Secrets Manager, and tasks are configured to pull these
+tokens from AWS Secrets Manager when they start.
+
+### ECS Health Check Syncing
+
+If the following conditions apply, ECS health checks automatically sync with Consul health checks for all application containers:
+
+* marked as `essential`
+* have ECS `healthChecks`
+* are not configured with native Consul health checks
+
+The `mesh-init` container creates a TTL health check for
+every container that fits these criteria and the `health-sync` container ensures
+that the ECS and Consul health checks remain in sync.
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index c58c649180..58acc8c971 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -628,10 +628,6 @@
           }
         ]
       },
-      {
-        "title": "Architecture",
-        "path": "ecs/architecture"
-      },
       {
         "title": "Consul Enterprise",
         "path": "ecs/enterprise"

From 5fd955dfab9722e072f13f6858b76f756aeaf7b3 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Mon, 13 Dec 2021 17:25:28 -0600
Subject: [PATCH 66/98] docs: Flatten ECS "Getting Started" navigation

---
 website/content/docs/ecs/enterprise.mdx       |  4 +--
 website/content/docs/ecs/index.mdx            |  2 +-
 .../docs/ecs/{get-started => }/install.mdx    |  2 +-
 .../migrate-existing-tasks.mdx                |  2 +-
 .../production-installation.mdx               |  4 +--
 .../ecs/{get-started => }/requirements.mdx    |  0
 website/data/docs-nav-data.json               | 33 ++++++++-----------
 7 files changed, 21 insertions(+), 26 deletions(-)
 rename website/content/docs/ecs/{get-started => }/install.mdx (98%)
 rename website/content/docs/ecs/{get-started => }/migrate-existing-tasks.mdx (96%)
 rename website/content/docs/ecs/{get-started => }/production-installation.mdx (95%)
 rename website/content/docs/ecs/{get-started => }/requirements.mdx (100%)

diff --git a/website/content/docs/ecs/enterprise.mdx b/website/content/docs/ecs/enterprise.mdx
index e2e15a029a..b181b5e130 100644
--- a/website/content/docs/ecs/enterprise.mdx
+++ b/website/content/docs/ecs/enterprise.mdx
@@ -27,10 +27,10 @@ module "my_task" {
 
 ## Licensing
 
-~> **Warning:** Consul Enterprise is currently only fully supported when [ACLs are enabled](/docs/ecs/get-started/production-installation#deploy-acl-controller).
+~> **Warning:** Consul Enterprise is currently only fully supported when [ACLs are enabled](/docs/ecs/production-installation#deploy-acl-controller).
 
 Consul Enterprise [requires a license](/docs/enterprise/license/overview). If running
-Consul on ECS with [ACLs enabled](/docs/ecs/get-started/production-installation#deploy-acl-controller), the license
+Consul on ECS with [ACLs enabled](/docs/ecs/production-installation#deploy-acl-controller), the license
 will be automatically pulled down from Consul servers.
 
 Currently there is no capability for specifying the license when ACLs are disabled so if you wish to
diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx
index 27a44bef59..27019c3fbb 100644
--- a/website/content/docs/ecs/index.mdx
+++ b/website/content/docs/ecs/index.mdx
@@ -27,7 +27,7 @@ There are several ways to get started with Consul with ECS.
 * The [Consul with Dev Server on Fargate](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate) example installation deploys a sample application in ECS using the Fargate launch type.
 * The [Consul with Dev Server on EC2](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2) example installation deploys a sample application in ECS using the EC2 launch type.
 
-See the [Requirements](/docs/ecs/get-started/requirements) and the full [Install Guide](/docs/ecs/get-started/install) when you're ready to install Consul on an existing ECS cluster and add existing tasks to the service mesh.
+See the [Requirements](/docs/ecs/requirements) and the full [Install Guide](/docs/ecs/install) when you're ready to install Consul on an existing ECS cluster and add existing tasks to the service mesh.
 
 
 ## Architecture
diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/install.mdx
similarity index 98%
rename from website/content/docs/ecs/get-started/install.mdx
rename to website/content/docs/ecs/install.mdx
index 9bca982489..bbd8a48d35 100644
--- a/website/content/docs/ecs/get-started/install.mdx
+++ b/website/content/docs/ecs/install.mdx
@@ -179,7 +179,7 @@ python manage.py runserver "127.0.0.1:8080"
 
 ## Next Steps
 
-- Configure a secure [Production Installation](/docs/ecs/get-started/production-installation).
+- Configure a secure [Production Installation](/docs/ecs/production-installation).
 - Now that your applications are running in the service mesh, read about
   other [Service Mesh features](/docs/connect).
 - View the [Architecture](/docs/ecs#architecture) documentation to understand
diff --git a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx b/website/content/docs/ecs/migrate-existing-tasks.mdx
similarity index 96%
rename from website/content/docs/ecs/get-started/migrate-existing-tasks.mdx
rename to website/content/docs/ecs/migrate-existing-tasks.mdx
index aedca03911..0d6a069233 100644
--- a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx
+++ b/website/content/docs/ecs/migrate-existing-tasks.mdx
@@ -111,5 +111,5 @@ resource.
 
 Now that your task(s) are migrated to the `mesh-task` module,
 
-- Start at the [ECS Service section](/docs/ecs/get-started/install#ecs-service) of the Installation Guide to continue installing Consul on ECS.
+- Start at the [ECS Service section](/docs/ecs/install#ecs-service) of the Installation Guide to continue installing Consul on ECS.
 - Refer to the [`mesh-task` reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for all available inputs to your mesh tasks.
diff --git a/website/content/docs/ecs/get-started/production-installation.mdx b/website/content/docs/ecs/production-installation.mdx
similarity index 95%
rename from website/content/docs/ecs/get-started/production-installation.mdx
rename to website/content/docs/ecs/production-installation.mdx
index 2f9bb0551e..19375ed9f6 100644
--- a/website/content/docs/ecs/get-started/production-installation.mdx
+++ b/website/content/docs/ecs/production-installation.mdx
@@ -68,7 +68,7 @@ deploying this controller.
 ## Deploy Services
 
 Once the ACL controller is up and running, you will be able to deploy services on the mesh using the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
-Start with the basic configuration for the [Task Module](/docs/ecs/get-started/install#task-module) and specify additional settings to make the configuration production-ready.
+Start with the basic configuration for the [Task Module](/docs/ecs/install#task-module) and specify additional settings to make the configuration production-ready.
 
 First, you will need to create an AWS Secrets Manager secret for the gossip encryption key that the Consul clients
 should use.
@@ -104,5 +104,5 @@ module "my_task" {
 }
 ```
 
-Now you can deploy your services! Follow the rest of the steps in the [Installation instructions](/docs/ecs/get-started/install#task-module)
+Now you can deploy your services! Follow the rest of the steps in the [Installation instructions](/docs/ecs/install#task-module)
 to deploy and connect your services.
diff --git a/website/content/docs/ecs/get-started/requirements.mdx b/website/content/docs/ecs/requirements.mdx
similarity index 100%
rename from website/content/docs/ecs/get-started/requirements.mdx
rename to website/content/docs/ecs/requirements.mdx
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 58acc8c971..84a6a960b9 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -608,25 +608,20 @@
         "path": "ecs"
       },
       {
-        "title": "Get Started",
-        "routes": [
-          {
-            "title": "Requirements",
-            "path": "ecs/get-started/requirements"
-          },
-          {
-            "title": "Installation",
-            "path": "ecs/get-started/install"
-          },
-          {
-            "title": "Production Installation",
-            "path": "ecs/get-started/production-installation"
-          },
-          {
-            "title": "Migrate Existing Tasks",
-            "path": "ecs/get-started/migrate-existing-tasks"
-          }
-        ]
+        "title": "Requirements",
+        "path": "ecs/requirements"
+      },
+      {
+        "title": "Installation",
+        "path": "ecs/install"
+      },
+      {
+        "title": "Production Installation",
+        "path": "ecs/production-installation"
+      },
+      {
+        "title": "Migrate Existing Tasks",
+        "path": "ecs/migrate-existing-tasks"
       },
       {
         "title": "Consul Enterprise",

From e4c90cc2b8998a1c0c4db3bab2a4cfc13152ad21 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Tue, 18 Jan 2022 16:17:49 -0600
Subject: [PATCH 67/98] docs: Unmerge ECS architecture from overview

---
 website/content/docs/ecs/architecture.mdx     |  97 ++++++++++++++++
 website/content/docs/ecs/index.mdx            | 107 +++---------------
 website/content/docs/ecs/install.mdx          |   2 +-
 .../docs/ecs/production-installation.mdx      |   2 +-
 website/data/docs-nav-data.json               |   4 +
 5 files changed, 116 insertions(+), 96 deletions(-)
 create mode 100644 website/content/docs/ecs/architecture.mdx

diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx
new file mode 100644
index 0000000000..766402fcc0
--- /dev/null
+++ b/website/content/docs/ecs/architecture.mdx
@@ -0,0 +1,97 @@
+---
+layout: docs
+page_title: Architecture - AWS ECS
+description: >-
+  Architecture of Consul Service Mesh on AWS ECS (Elastic Container Service).
+---
+
+# Architecture
+
+The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster:
+
+![Consul on ECS Architecture](/img/consul-ecs-arch.png)
+
+1. **Consul servers:** Production-ready Consul server cluster
+1. **Application tasks:** Runs user application containers along with two helper containers:
+   1. **Consul client:** The Consul client container runs Consul. The Consul client communicates
+      with the Consul server and configures the Envoy proxy sidecar. This communication
+      is called _control plane_ communication.
+   1. **Sidecar proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests
+      to and from the application container(s) run through the sidecar proxy. This communication
+      is called _data plane_ communication.
+1. **Mesh Init:** Each task runs a short-lived container, called `mesh-init`, which sets up initial configuration
+   for Consul and Envoy.
+1. **Health Syncing:** Optionally, an additional `health-sync` container can be included in a task to sync health statuses
+   from ECS into Consul.
+1. **ACL Controller:** Automatically provisions Consul ACL tokens for Consul clients and service mesh services
+   in an ECS Cluster.
+
+For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture).
+
+## Task Startup
+
+This diagram shows the timeline of a task starting up and all its containers:
+
+<img alt="Task Startup Timeline" src="/img/ecs-task-startup.svg" style={{display: "block", maxWidth: "400px"}} />
+
+- **T0:** ECS starts the task. The `consul-client` and `mesh-init` containers start:
+  - `consul-client` uses the `retry-join` option to join the Consul cluster
+  - `mesh-init` registers the service for the current task and its sidecar proxy with
+    Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s
+    bootstrap JSON file and write it to a shared volume. `mesh-init` exits after completing these operations.
+
+- **T1:** The following containers start:
+  - The `sidecar-proxy` container starts and runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
+  - If applicable, the `health-sync` container syncs health checks from ECS to Consul (see [ECS Health Check Syncing](#ecs-health-check-syncing)).
+- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, your application containers are started since all Consul machinery is ready to service requests. The only running containers are `consul-client`, `sidecar-proxy`, and your application container(s).
+
+## Task Shutdown
+
+This diagram shows an example timeline of a task shutting down:
+
+<img alt="Task Shutdown Timeline" src="/img/ecs-task-shutdown.svg" style={{display: "block", maxWidth: "400px"}} />
+
+- **T0**: ECS sends a TERM signal to all containers. Each container reacts to the TERM signal:
+  - `consul-client` begins to gracefully leave the Consul cluster.
+  - `health-sync` stops syncing health status from ECS into Consul checks.
+  - `sidecar-proxy` ignores the TERM signal and continues running until the `user-app` container exits. This allows the application container to continue making outgoing requests through the proxy to the mesh.
+  - `user-app` exits if it is not configured to ignore the TERM signal. The `user-app` container will continue running if it is configured to ignore the TERM signal.
+- **T1**:
+  - `health-sync` updates its Consul checks to critical status and exits. This ensures this service instance is marked unhealthy.
+  - `sidecar-proxy` notices the `user-app` container has stopped and exits.
+- **T2**: `consul-client` finishes gracefully leaving the Consul datacenter and exits.
+- **T3**:
+  - ECS notices all containers have exited, and will soon change the Task status to `STOPPED`
+  - Updates about this task have reached the rest of the Consul cluster, so downstream proxies have been updated to stopped sending traffic to this task.
+- **T4**: At this point task shutdown should be complete. Otherwise, ECS will send a KILL signal to any containers still running. The KILL signal cannot be ignored and will forcefully stop containers. This will interrupt in-progress operations and possibly cause errors.
+
+## Automatic ACL Token Provisioning
+
+Consul ACL tokens secure communication between agents and services.
+The following containers in a task require an ACL token:
+
+- `consul-client`: The Consul client uses a token to authorize itself with Consul servers.
+  All `consul-client` containers share the same token.
+- `mesh-init`: The `mesh-init` container uses a token to register the service with Consul.
+  This token is unique for the Consul service, and is shared by instances of the service.
+
+The ACL controller automatically creates ACL tokens for mesh-enabled tasks in an ECS cluster.
+The `acl-controller` Terraform module creates the ACL controller task. The controller creates the
+ACL token used by `consul-client` containers at startup and then watches for tasks in the cluster. It checks tags
+to determine if the task is mesh-enabled. If so, it creates the service ACL token for the task, if the
+token does not yet exist.
+
+The ACL controller stores all ACL tokens in AWS Secrets Manager, and tasks are configured to pull these
+tokens from AWS Secrets Manager when they start.
+
+## ECS Health Check Syncing
+
+If the following conditions apply, ECS health checks automatically sync with Consul health checks for all application containers:
+
+* marked as `essential`
+* have ECS `healthChecks`
+* are not configured with native Consul health checks
+
+The `mesh-init` container creates a TTL health check for
+every container that fits these criteria and the `health-sync` container ensures
+that the ECS and Consul health checks remain in sync.
diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx
index 27019c3fbb..1078d65c76 100644
--- a/website/content/docs/ecs/index.mdx
+++ b/website/content/docs/ecs/index.mdx
@@ -8,9 +8,8 @@ description: >-
 
 # AWS ECS
 
-Consul can be deployed on [AWS ECS](https://aws.amazon.com/ecs/) (Elastic Container Service) using our official Terraform modules.
-
-![Consul on ECS Architecture](/img/consul-ecs-arch.png)
+Consul service mesh applications can be deployed on [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS)
+using our official Terraform modules.
 
 ## Service Mesh
 
@@ -18,6 +17,17 @@ Using Consul on AWS ECS enables you to add your ECS tasks to the service mesh an
 take advantage of features such as zero-trust-security, intentions, observability,
 traffic policy, and more.
 
+## Architecture
+
+![Consul on ECS Architecture](/img/consul-ecs-arch.png)
+
+Consul on ECS follows an [architecture](/docs/internals/architecture) similar to other platforms, but each ECS task is a
+Consul node. An ECS task runs the user application container(s), as well as a Consul client container for control plane
+communication and an [Envoy](https://envoyproxy.io/) sidecar proxy container to faciliate data plane communication for
+[Consul Connect](/docs/connect).
+
+For a detailed architecture overview, see the [Architecture](/docs/ecs/architecture) page.
+
 ## Getting Started
 
 There are several ways to get started with Consul with ECS.
@@ -28,94 +38,3 @@ There are several ways to get started with Consul with ECS.
 * The [Consul with Dev Server on EC2](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2) example installation deploys a sample application in ECS using the EC2 launch type.
 
 See the [Requirements](/docs/ecs/requirements) and the full [Install Guide](/docs/ecs/install) when you're ready to install Consul on an existing ECS cluster and add existing tasks to the service mesh.
-
-
-## Architecture
-
-The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster:
-
-![Consul on ECS Architecture](/img/consul-ecs-arch.png)
-
-1. **Consul servers:** Production-ready Consul server cluster
-1. **Application tasks:** Runs user application containers along with two helper containers:
-   1. **Consul client:** The Consul client container runs Consul. The Consul client communicates
-      with the Consul server and configures the Envoy proxy sidecar. This communication
-      is called _control plane_ communication.
-   1. **Sidecar proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests
-      to and from the application container(s) run through the sidecar proxy. This communication
-      is called _data plane_ communication.
-1. **ACL Controller:** Automatically provisions Consul ACL tokens for Consul clients and service mesh services
-   in an ECS Cluster.
-
-For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture).
-
-In addition to the long-running Consul client and sidecar proxy containers, the `mesh-init` container runs
-at startup and sets up initial configuration for Consul and Envoy.
-
-### Task Startup
-
-This diagram shows the timeline of a task starting up and all its containers:
-
-<img alt="Task Startup Timeline" src="/img/ecs-task-startup.svg" style={{display: "block", maxWidth: "400px"}} />
-
-- **T0:** ECS starts the task. The `consul-client` and `mesh-init` containers start:
-  - `consul-client` uses the `retry-join` option to join the Consul cluster
-  - `mesh-init` registers the service for the current task and its sidecar proxy with
-    Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s
-    bootstrap JSON file and write it to a shared volume. `mesh-init` exits after completing these operations.
-
-- **T1:** The following containers start:
-  - The `sidecar-proxy` container starts and runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
-  - If applicable, the `health-sync` container syncs health checks from ECS to Consul (see [ECS Health Check Syncing](#ecs-health-check-syncing)).
-- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, your application containers are started since all Consul machinery is ready to service requests. The only running containers are `consul-client`, `sidecar-proxy`, and your application container(s).
-
-### Task Shutdown
-
-This diagram shows an example timeline of a task shutting down:
-
-<img alt="Task Shutdown Timeline" src="/img/ecs-task-shutdown.svg" style={{display: "block", maxWidth: "400px"}} />
-
-- **T0**: ECS sends a TERM signal to all containers. Each container reacts to the TERM signal:
-  - `consul-client` begins to gracefully leave the Consul cluster.
-  - `health-sync` stops syncing health status from ECS into Consul checks.
-  - `sidecar-proxy` ignores the TERM signal and continues running until the `user-app` container exits. This allows the application container to continue making outgoing requests through the proxy to the mesh.
-  - `user-app` exits if it is not configured to ignore the TERM signal. The `user-app` container will continue running if it is configured to ignore the TERM signal.
-- **T1**:
-  - `health-sync` updates its Consul checks to critical status and exits. This ensures this service instance is marked unhealthy.
-  - `sidecar-proxy` notices the `user-app` container has stopped and exits.
-- **T2**: `consul-client` finishes gracefully leaving the Consul datacenter and exits.
-- **T3**:
-  - ECS notices all containers have exited, and will soon change the Task status to `STOPPED`
-  - Updates about this task have reached the rest of the Consul cluster, so downstream proxies have been updated to stopped sending traffic to this task.
-- **T4**: At this point task shutdown should be complete. Otherwise, ECS will send a KILL signal to any containers still running. The KILL signal cannot be ignored and will forcefully stop containers. This will interrupt in-progress operations and possibly cause errors.
-
-### Automatic ACL Token Provisioning
-
-Consul ACL tokens secure communication between agents and services.
-The following containers in a task require an ACL token:
-
-- `consul-client`: The Consul client uses a token to authorize itself with Consul servers.
-  All `consul-client` containers share the same token.
-- `mesh-init`: The `mesh-init` container uses a token to register the service with Consul.
-  This token is unique for the Consul service, and is shared by instances of the service.
-
-The ACL controller automatically creates ACL tokens for mesh-enabled tasks in an ECS cluster.
-The `acl-controller` Terraform module creates the ACL controller task. The controller creates the
-ACL token used by `consul-client` containers at startup and then watches for tasks in the cluster. It checks tags
-to determine if the task is mesh-enabled. If so, it creates the service ACL token for the task, if the
-token does not yet exist.
-
-The ACL controller stores all ACL tokens in AWS Secrets Manager, and tasks are configured to pull these
-tokens from AWS Secrets Manager when they start.
-
-### ECS Health Check Syncing
-
-If the following conditions apply, ECS health checks automatically sync with Consul health checks for all application containers:
-
-* marked as `essential`
-* have ECS `healthChecks`
-* are not configured with native Consul health checks
-
-The `mesh-init` container creates a TTL health check for
-every container that fits these criteria and the `health-sync` container ensures
-that the ECS and Consul health checks remain in sync.
diff --git a/website/content/docs/ecs/install.mdx b/website/content/docs/ecs/install.mdx
index bbd8a48d35..d98fb15bdf 100644
--- a/website/content/docs/ecs/install.mdx
+++ b/website/content/docs/ecs/install.mdx
@@ -182,5 +182,5 @@ python manage.py runserver "127.0.0.1:8080"
 - Configure a secure [Production Installation](/docs/ecs/production-installation).
 - Now that your applications are running in the service mesh, read about
   other [Service Mesh features](/docs/connect).
-- View the [Architecture](/docs/ecs#architecture) documentation to understand
+- View the [Architecture](/docs/ecs/architecture) documentation to understand
   what's going on under the hood.
diff --git a/website/content/docs/ecs/production-installation.mdx b/website/content/docs/ecs/production-installation.mdx
index 19375ed9f6..9c8c6c6e6c 100644
--- a/website/content/docs/ecs/production-installation.mdx
+++ b/website/content/docs/ecs/production-installation.mdx
@@ -19,7 +19,7 @@ A secure Consul cluster should include the following:
 ## Deploy ACL Controller
 
 Before deploying your service, you will need to deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller) so that it can provision the necessary tokens
-for tasks on the service mesh. To learn more about the ACL Controller, please see [Automatic ACL Token Provisioning](/docs/ecs#automatic-acl-token-provisioning).
+for tasks on the service mesh. To learn more about the ACL Controller, please see [Automatic ACL Token Provisioning](/docs/ecs/architecture#automatic-acl-token-provisioning).
 
 To deploy the controller, you will first need store an ACL token with `acl:write` privileges
 and a CA certificate for the Consul server in AWS Secrets Manager.
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 84a6a960b9..028a950e01 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -623,6 +623,10 @@
         "title": "Migrate Existing Tasks",
         "path": "ecs/migrate-existing-tasks"
       },
+      {
+        "title": "Architecture",
+        "path": "ecs/architecture"
+      },
       {
         "title": "Consul Enterprise",
         "path": "ecs/enterprise"

From 4414cb395c06cb17b48c4b6823c10956aa6ebdc3 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Tue, 18 Jan 2022 14:52:40 -0600
Subject: [PATCH 68/98] docs: Manual installation of Consul on ECS

---
 .../content/docs/ecs/install-no-terraform.mdx | 492 ++++++++++++++++++
 website/content/docs/ecs/install.mdx          |  97 ++--
 website/content/docs/ecs/requirements.mdx     |  12 +-
 website/data/docs-nav-data.json               |   6 +-
 4 files changed, 565 insertions(+), 42 deletions(-)
 create mode 100644 website/content/docs/ecs/install-no-terraform.mdx

diff --git a/website/content/docs/ecs/install-no-terraform.mdx b/website/content/docs/ecs/install-no-terraform.mdx
new file mode 100644
index 0000000000..5f6378eafb
--- /dev/null
+++ b/website/content/docs/ecs/install-no-terraform.mdx
@@ -0,0 +1,492 @@
+---
+layout: docs
+page_title: Manual Installation - AWS ECS
+description: >-
+  Manually Install Consul Service Mesh on AWS ECS (Elastic Container Service).
+---
+
+# Manual Installation
+
+While the [Consul ECS Terraform module](/docs/ecs/install) is the easiest way to use Consul on ECS,
+this page will describe how to directly create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs)
+for use without Terraform.
+
+## Pre-requisites
+
+* This page assumes you are familiar with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for more details.
+* This page does not show how to create all necessary AWS resources, such as a VPC or the ECS Cluster.
+  For complete runnable examples, see the links in the [Getting Started](/docs/ecs#getting-started) section.
+
+# Task Definition
+
+You must define a Task Definition which includes the following containers:
+
+* Your application container
+* An Envoy sidecar-proxy container
+* A Consul Agent container
+* The `consul-ecs-mesh-init` container for service mesh setup
+* Optionally, a `consul-ecs-health-sync` container to sync ECS health checks into Consul
+
+## Top-level fields
+
+In your task definition, you'll need to define these important top-level fields:
+
+```json
+{
+  "family": "my-example-client-app",
+  "networkMode": "awsvpc",
+  "volumes": [
+    {
+      "name": "consul_data",
+    },
+    {
+      "name": "consul_binary",
+    }
+  ],
+  "containerDefinitions": [...]
+}
+```
+
+| Field name             | Type   | Description                                                                                         |
+| -------------          | ------ | --------------------------------------------------------------------------------------------------- |
+| `family`               | string | The task family name. This is used as the Consul service name, by default.                          |
+| `networkMode`          | string | Must be `awsvpc`, which is the only network mode supported by Consul on ECS.                        |
+| `volumes`              | list   | These are volumes used to share information between containers, which is important for setup steps. |
+| `containerDefinitions` | list   | The list of containers to run in this task (see below).                                             |
+
+## Application container
+
+First, include your application container in the `containerDefinitions` list
+in the task definition:
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "example-client-app",
+      "image": "docker.io/org/my_task:v0.0.1",
+      "essential": true,
+      "dependsOn": [
+        {
+          "containerName": "consul-ecs-mesh-init",
+          "condition": "SUCCESS"
+        },
+        {
+          "containerName": "sidecar-proxy",
+          "condition": "HEALTHY"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Field name  | Type    | Description                                                                                                                     |
+| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------        |
+| `name`      | string  | The name of your application container.                                                                                         |
+| `image`     | string  | The container image used to run your application.                                                                               |
+| `essential` | boolean | Set this to `true` ensures your application container ties into the health of the task. All tasks must have at least one essential container. |
+| `dependsOn` | list    | Container dependendencies are used to ensure the service mesh is ready before your application starts.                          |
+
+See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) documentation for a complete reference.
+
+## `sidecar-proxy` container
+
+The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect.
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "example-client-app",
+      "image": "docker.io/org/my_task:v0.0.1",
+      ...
+    },
+    {
+      "name": "sidecar-proxy",
+      "image": "envoyproxy/envoy-alpine:<VERSION>",
+      "essential": false,
+      "dependsOn": [
+        {
+          "containerName": "consul-ecs-mesh-init",
+          "condition": "SUCCESS"
+        }
+      ],
+      "healthCheck": {
+        "retries": 3,
+        "command": ["nc", "-z", "127.0.0.1", "20000"],
+        "timeout": 5,
+        "interval": 30
+      },
+      "mountPoints": [
+        {
+          "readOnly": true,
+          "containerPath": "/consul",
+          "sourceVolume": "consul_data"
+        }
+      ],
+      "ulimits": [
+        {
+          "name": "nofile",
+          "softLimit": 1048576,
+          "hardLimit": 1048576
+        }
+      ],
+      "command": ["envoy", "--config-path", "/consul/envoy-bootstrap.json"],
+      "entryPoint": ["/consul/consul-ecs", "envoy-entrypoint"],
+    }
+  ]
+}
+```
+
+| Field name    | Type    | Description                                                                                                        |
+| -----------   | ------- | ------------------------------------------------------------------------------------------------------------------ |
+| `name`        | string  | The name of the container, which should always be `sidecar-proxy`.                                                 |
+| `image`       | string  | The container image for Envoy. We recommend using `envoyproxy/envoy-alpine`.                                       |
+| `dependsOn`   | list    | Envoy must start after `consul-ecs-mesh-init`, which creates the bootstrap configuration file for Envoy.           |
+| `healthCheck` | list    | A health check should be definied for Envoy's primary listener port.                                               |
+| `mountPoints` | list    | The mounts the `/consul` data volume which contains the Envoy configuration file.                                  |
+| `ulimits`     | list    | Set the file descriptor limit, `nofile`, to a sufficiently high value so that Envoy does not fail to open sockets. |
+| `entrypoint`  | list    | A custom entrypoint binary is used to help facilitate graceful shutdown.                                           |
+| `command`     | list    | The startup command. This passes the bootstrap configuration to Envoy.                                             |
+
+-> **NOTE**: Envoy and Consul must be compatible versions. See the [supported versions of Envoy](https://www.consul.io/docs/connect/proxies/envoy#supported-versions) for each Consul release.
+
+
+## `consul-client` container
+
+Each task must include a Consul agent container in order for the task to join your Consul cluster.
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "example-client-app",
+      "image": "docker.io/org/my_task:v0.0.1",
+      ...
+    },
+    {
+      "name": "sidecar-proxy",
+      "image": "envoyproxy/envoy-alpine:<ENVOY_VERSION>",
+      ...
+    }
+    {
+      "name": "consul-client"
+      "image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
+      "mountPoints": [
+        {
+          "readOnly": false,
+          "containerPath": "/consul",
+          "sourceVolume": "consul_data"
+        },
+        {
+          "containerPath": "/bin/consul-inject",
+          "sourceVolume": "consul_binary"
+        }
+      ],
+      "entryPoint": ["/bin/sh", "-ec"],
+      "command": [
+        "cp /bin/consul /bin/consul-inject/consul\n\nECS_IPV4=$(curl -s $ECS_CONTAINER_METADATA_URI_V4 | jq -r '.Networks[0].IPv4Addresses[0]')\n\n\ncat << EOF > /consul/agent-defaults.hcl\naddresses = {\n  dns = \"127.0.0.1\"\n  grpc = \"127.0.0.1\"\n  http = \"127.0.0.1\"\n}\nadvertise_addr = \"$ECS_IPV4\"\nadvertise_reconnect_timeout = \"15m\"\nclient_addr = \"0.0.0.0\"\ndatacenter = \"dc1\"\nenable_central_service_config = true\nleave_on_terminate = true\nports {\n  grpc = 8502\n}\nretry_join = [\n  \"<Consul server location>",\n]\ntelemetry {\n  disable_compat_1.9 = true\n}\n\nEOF\n\ncat << EOF > /consul/agent-extra.hcl\naddresses = {\n  dns = \"0.0.0.0\"\n}\nlog_level = \"debug\"\n\nEOF\n\nexec consul agent \\\n    -data-dir /consul/data \\\n    -config-file /consul/agent-defaults.hcl \\\n    -config-file /consul/agent-extra.hcl\n"
+      ]
+    }
+  ]
+}
+```
+
+| Field name    | Type    | Description                                                                                                              |
+| -----------   | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | string  | The name of the Consul agent container, which should always be `consul-client`.                                          |
+| `image`       | string  | The container image for Consul. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits.    |
+| `mountPoints` | list    | The mounts the `/consul` data volume which contains the Envoy configuration file.                                        |
+| `ulimits`     | list    | Set the file descriptor limit, `nofile`, to a sufficiently high value so that Envoy does not fail to open sockets.       |
+| `entrypoint`  | list    | A custom entrypoint binary is used to run Envoy, in order to facilitate graceful shutdown.                               |
+| `command`     | list    | The startup command. See below for details.
+
+The following is the recommended `command` script for the Consul agent.
+This is the same as the above `command` field, but is unescaped and has comments added.
+
+```shell
+# Copy the consul binary to a shared volume for mesh-init to use to generate Envoy configuration.
+cp /bin/consul /bin/consul-inject/consul
+
+# At runtime, determine the IP address assigned to this ECS Task.
+ECS_IPV4=$(curl -s $ECS_CONTAINER_METADATA_URI_V4 | jq -r '.Networks[0].IPv4Addresses[0]')
+
+# Define the Consul agent configuration file.
+cat << EOF > /consul/agent-defaults.hcl
+addresses = {
+  dns = "127.0.0.1"
+  grpc = "127.0.0.1"
+  http = "127.0.0.1"
+}
+advertise_addr = "$ECS_IPV4"
+advertise_reconnect_timeout = "15m"
+client_addr = "0.0.0.0"
+datacenter = "dc1"
+enable_central_service_config = true
+leave_on_terminate = true
+ports {
+  grpc = 8502
+}
+retry_join = ["<consul server location>"]
+telemetry {
+  disable_compat_1.9 = true
+}
+
+EOF
+
+# Start the consul agent.
+exec consul agent \
+    -data-dir /consul/data \
+    -config-file /consul/agent-defaults.hcl
+```
+
+You can tailor the configuration above for your use case, but it's important to set the following fields as show:
+
+| Field name           | Type    | Description                                                                                                  |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
+| `addresses.*`        | strings | Set the DNS, GRPC, and HTTP addresses to `127.0.0.1` to ensure these are not accessible outside of the task. |
+| `advertise_addr`     | string  | This must be set to the task IP address so that other Consul agents know how to reach this agent.            |
+| `client_addr`        | string  | This must bind to an interface reacable by other Consul agents.                                              |
+| `leave_on_terminate` | boolean | This ensures this Consul agent will leave the cluster gracefully before exiting.                             |
+| `retry_join`         | string  | This must be set to your Consul server location(s) so this agent can join the Consul cluster.                |
+
+-> **NOTE**: It is important to use `exec` to start the Consul agent, so that the Consul agent runs as PID 1. This ensures
+the Consul agent directly receives signals from ECS, which is important for graceful shutdown of the Consul agent.
+
+## `mesh-init` container
+
+The mesh-init container runs at task startup to setup this instance for Consul service mesh.
+It will register this service and proxy with Consul and write Envoy bootstrap configuration
+to a shared volume.
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "example-client-app",
+      "image": "docker.io/org/my_task:v0.0.1",
+      ...
+    },
+    {
+      "name": "sidecar-proxy",
+      "image": "envoyproxy/envoy-alpine:<ENVOY_VERSION>",
+      ...
+    },
+    {
+      "name": "consul-client"
+      "image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
+      ...
+    },
+    {
+      "name": "consul-ecs-mesh-init",
+      "image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
+      "command": ["mesh-init"],
+      "essential": false,
+      "environment": [
+        {
+          "name": "CONSUL_ECS_CONFIG_JSON",
+          "value": "{\"bootstrapDir\":\"/consul\",\"healthSyncContainers\":[],\"proxy\":{\"upstreams\":[{\"destinationName\":\"example-server-app\",\"localBindPort\":1234}]},\"service\":{\"checks\":[],\"meta\":{},\"name\":\"example-client-app\",\"port\":9090,\"tags\":[]}}"
+        }
+      ],
+      "mountPoints": [
+        {
+          "readOnly": false,
+          "containerPath": "/consul",
+          "sourceVolume": "consul_data"
+        },
+        {
+          "readOnly": true,
+          "containerPath": "/bin/consul-inject",
+          "sourceVolume": "consul_binary"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Field name    | Type    | Description                                                                                                                  |
+| -----------   | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string  | The container name should be `consul-ecs-mesh-init`.                                                                         |
+| `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.            |
+| `mountPoints` | list    | The mounts two volumes so that mesh-init can invoke the `consul` binary to write bootstrap Envoy configuration.              |
+| `command`     | list    | Set the `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command.                                       |
+| `environment` | list    | This must include the `CONSUL_ECS_CONFIG_JSON` variable. See below for details.                                              |
+
+Additional configuration is passed to the `consul-ecs mesh-init` command in JSON format using the `CONSUL_ECS_CONFIG_JSON` environment variable.
+Here is the sample config from above, expanded to be readable:
+
+```json
+{
+  "bootstrapDir": "/consul",
+  "healthSyncContainers": [],
+  "proxy": {
+    "upstreams": [
+      {
+        "destinationName": "example-server-app",
+        "localBindPort": 1234
+      }
+    ]
+  },
+  "service": {
+    "checks": [],
+    "meta": {},
+    "name": "example-client-app",
+    "port": 9090,
+    "tags": []
+  }
+}
+```
+
+| Field name        | Type   | Description                                                                                                                    |
+| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `bootstrapDir`    | string | This is the path of a  shared volume the is mounted to other containers, where `mesh-init` will write out Envoy configuration. |
+| `proxy.upstreams` | list   | The upstream services that your application calls over the service mesh, if any.                                               |
+| `service.name`    | string | The name used to register this service into the Consul service catalog.                                                        |
+| `service.port`    | number | The port your application listens on. Set to `0` if your application does not listen on any port.                              |
+| `service.checks`  | list   | Consul [checks](/docs/discovery/checks) to include, to have Consul run health checks against your application. |
+
+See the [`consul-ecs JSON Schema`](https://github.com/hashicorp/consul-ecs/blob/main/config/schema.json) for a complete reference of fields.
+
+## `consul-ecs-health-sync` container
+
+Optionally, Consul ECS can sync health checks for this task into Consul checks.
+This allows you to configure a health check for your application in one place, and
+see a consistent health status in both ECS and Consul.
+
+First, you'll need to add an ECS health check command to the container definition for your application.
+This configures a health check command that runs `curl localhost:9090/health` to check the application health:
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "example-client-app",
+      "image": "docker.io/org/my_task:v0.0.1",
+      "healthCheck": {
+        "retries": 3,
+        "command": ["CMD-SHELL", "curl localhost:9090/health"],
+        "timeout": 5,
+        "interval": 30
+      },
+      ...
+    },
+    ...
+  ]
+}
+```
+
+See the [ECS health check documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_healthcheck) for details on defining ECS health checks.
+
+Next, you must tell Consul ECS which containers will have their health status synced into Consul. To do this,
+set the `healthSyncContainers` field of the `CONSUL_ECS_CONFIG_JSON` variable to include your application container name.
+
+Here is the expanded configuration:
+
+```json
+{
+  "bootstrapDir": "/consul",
+  "healthSyncContainers": ["example-client-app"],
+  "proxy": {
+    "upstreams": [
+      {
+        "destinationName": "example-server-app",
+        "localBindPort": 1234
+      }
+    ]
+  },
+  "service": {
+    "checks": [],
+    "meta": {},
+    "name": "example-client-app",
+    "port": 9090,
+    "tags": []
+  }
+}
+```
+
+Then, update the task definition so that the `consul-ecs-mesh-init` container uses new configuration.
+You should compact and escape the JSON configuration above, and copy the result into the `CONSUL_ECS_CONFIG_JSON`
+environment variable:
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "consul-ecs-mesh-init",
+      "image": "public.ecr.aws/hashicorp/consul-ecs:<VERSION>",
+      "environment": [
+        {
+          "name": "CONSUL_ECS_CONFIG_JSON",
+          "value": "{\"bootstrapDir\":\"/consul\",\"healthSyncContainers\":[\"example-client-app\"],\"proxy\":{\"upstreams\":[{\"destinationName\":\"example-server-app\",\"localBindPort\":1234}]},\"service\":{\"checks\":[],\"meta\":{},\"name\":\"example-client-app\",\"port\":9090,\"tags\":[]}}"
+        }
+      ],
+      ...
+    },
+    ...
+  ]
+}
+```
+
+Finally, include the `consul-ecs-health-sync` container in the `containerDefinitions` list.
+Be sure to pass the same value as above for the `CONSUL_ECS_CONFIG_JSON` environment
+variable:
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "example-client-app",
+      "image": "docker.io/org/my_task:v0.0.1",
+      ...
+    },
+    {
+      "name": "sidecar-proxy",
+      "image": "envoyproxy/envoy-alpine:<ENVOY_VERSION>",
+      ...
+    },
+    {
+      "name": "consul-client"
+      "image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
+      ...
+    },
+    {
+      "name": "consul-ecs-mesh-init",
+      "image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
+      ...
+    },
+    {
+      "name": "consul-ecs-health-sync",
+      "image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
+      "command": ["health-sync"],
+      "essential": false,
+      "dependsOn": [
+        {
+          "containerName": "consul-ecs-mesh-init",
+          "condition": "SUCCESS"
+        }
+      ],
+      "environment": [
+        {
+          "name": "CONSUL_ECS_CONFIG_JSON",
+          "value": "{\"bootstrapDir\":\"/consul\",\"healthSyncContainers\":[\"example-client-app\"],\"proxy\":{\"upstreams\":[{\"destinationName\":\"example-server-app\",\"localBindPort\":1234}]},\"service\":{\"checks\":[],\"meta\":{},\"name\":\"example-client-app\",\"port\":9090,\"tags\":[]}}"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Field name    | Type   | Description                                                                                                       |
+| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
+| `name`        | string | The container name which should be `consul-ecs-health-sync`.                                                      |
+| `image`       | string | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits. |
+| `command`     | list   | Set to `["health-sync"]` to run the `consul-ecs health-sync` command.                                             |
+| `dependsOn`   | list   | The `health-sync` container should not start until `mesh-init` has finished service and proxy registration.       |
+| `environment` | list   | Set the `CONSUL_ECS_CONFIG_JSON` variable to pass configuration to the `consul-ecs health-sync command.           |
+
+# Next Steps
+
+* Create the task definition using the [AWS Console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskdefinition.html) or the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html), or another method of your choice.
+* Create an [ECS Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) to start tasks using the task definition.
diff --git a/website/content/docs/ecs/install.mdx b/website/content/docs/ecs/install.mdx
index d98fb15bdf..3554043cd9 100644
--- a/website/content/docs/ecs/install.mdx
+++ b/website/content/docs/ecs/install.mdx
@@ -1,28 +1,30 @@
 ---
 layout: docs
-page_title: Installation - AWS ECS
+page_title: Installation with Terraform - AWS ECS
 description: >-
-  Install Consul Service Mesh on AWS ECS (Elastic Container Service).
+  Install Consul Service Mesh on AWS ECS with Terraform (Elastic Container Service).
 ---
 
-# Installation
+# Installation with Terraform
 
-Installing Consul on ECS is a multi-part process:
+This will describe how to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh.
 
-1. [**Task Module:**](#task-module) Define the [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task)
-   to create a task definition with the necessary sidecar containers for your application to join the service mesh.
-1. [**Routing:**](#routing) With your tasks as part of the mesh, you must specify their upstream
-   services and change the URLs the tasks are using so that they're making requests through the service mesh.
-1. [**Bind Address:**](#bind-address) Now that all communication is flowing through the service mesh,
-   you should change the address your application is listening on to `127.0.0.1`
-   so that it only receives requests through the sidecar proxy.
+## Pre-requisites
 
--> **NOTE:** This page assumes you're familiar with ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for more details.
+* This pages assumes you are familiar with Terraform. If you are new to Terraform, see the [Terraform documentation](https://www.terraform.io/docs) to
+  learn about infrastructure as code and how to get started with Terraform.
+* This page assumes you are familiar with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for more details.
+* This page does not show how to create all necessary AWS resources, such as a VPC or the ECS Cluster.
+  For complete runnable examples, see the links in the [Getting Started](/docs/ecs#getting-started) section.
 
-## Task Module
+## Using the Mesh Task Module
 
-In order to add the necessary sidecar containers for your task to join the mesh,
-you must use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task):
+To run an application in ECS with Consul service mesh, you must create an ECS task definition which includes your application container(s)
+and additional sidecar containers, such as the Consul agent container and the Envoy sidecar proxy container.
+
+The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers.
+
+Here is an example Terraform configuration file which defines a task definition with an application container called `example-client-app`.
 
 ```hcl
 module "my_task" {
@@ -53,35 +55,52 @@ module "my_task" {
 }
 ```
 
-All possible inputs are documented on the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs),
+All possible inputs are documented in the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs),
 however there are some important inputs worth highlighting:
 
-- `family` is used as the [task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family)
-  but it's also used as the name of the service that gets registered in Consul.
-- `container_definitions` accepts an array of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions).
-  This is where you include application containers.
-- `port` is the port that your application listens on. This should be set to a
-  string, not an integer, i.e. `port = "9090"`, not `port = 9090`.
-- `retry_join` is passed to the [`-retry-join`](/docs/agent/options#_retry_join) option for the Consul agent. This tells
-  the agent the location of your Consul servers so that it can join the Consul cluster.
-
--> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true`
-in their [`network_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#network_configuration) block so that ECS can pull the Docker images.
+| Input Variable          | Type     | Description                                                                                                                                                                                                                                    |
+| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `source` and `version`  | string   | This specifies the source location and version of the `mesh-task` module.                                                                                                                                                                      |
+| `family`                | string   | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name, by default.                                          |
+| `container_definitions` | list     | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. |
+| `port`                  | number   | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`.                                                                                                                  |
+| `retry_join`            | list     | The is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers.                                                                                                  |
 
 ## ECS Service
 
+[ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common
+ways to start tasks using a task definition..
+
 To define an ECS Service, reference the mesh-task module's `task_definition_arn` output value
 in your `aws_ecs_service` resource:
 
 ```hcl
 resource "aws_ecs_service" "my_task" {
-  ...
+  name            = "my_task_service"
   task_definition = module.my_task.task_definition_arn
+  launch_type     = "FARGATE"
+  propagate_tags  = "TASK_DEFINITION"
+  ...
 }
 ```
 
-After running `terraform apply`, you should see your tasks registered in
-the Consul UI.
+This is a partial configuration to highlight some important fields.
+See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) documentation for a complete reference.
+
+| Input Variable    | Type    | Description                                                                                                         |
+| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `name`            | string  | The name of the ECS service. This is required by AWS but is not used by Consul service mesh.                        |
+| `task_definition` | string  | The task definition used to start tasks. Set this to the task definition ARN returned by the `mesh-task` module.    |
+| `launch_type`     | string  | The launch type. Consul on ECS supports the `FARGATE` and `EC2` launch types.                                       |
+| `propagate_tags`  | string  | This must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. |
+
+After defining the Terraform configuration for both the `mesh-task` and ECS service,
+run `terraform apply` to create the ECS task definition and service resources. The ECS
+service will soon start your application in a task. The task will automatically
+register itself into the Consul service catalog.
+
+-> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true`
+in their [`network_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#network_configuration) block so that ECS can pull the Docker images.
 
 ## Routing
 
@@ -94,25 +113,23 @@ needs to call. You then must modify your application to make requests to the sid
 proxy on that port.
 
 For example, if your application `web` makes calls to another application called `backend`, then you would first configure the `mesh-task` module's upstream(s):
-`backend`.
 
 ```hcl
 module "web" {
   family = "web"
   upstreams = [
     {
-      destination_name = "backend"
-      local_bind_port  = 8080
+      destinationName = "backend"
+      localBindPort = 8080
     }
   ]
 }
 ```
 
-- Set the `destination_name` to the name of the upstream service (in this case `backend`)
-- Set `local_bind_port` to an unused port. This is the port that the sidecar proxy
-  will listen on. Any requests to this port will be forwarded over to the `destination_name`.
-  This does not have to be the port that `backend` is listening on because the service mesh
-  will handle routing the request to the right port.
+| Input Variable    | Type    | Description                                                                                                                                                      |
+| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `destinationName` | string  | The name of the upstream service, as it is registered in the Consul service catalog.                                                                             |
+| `localBindPort`   | number  | Requests to this port will be forwarded by the proxy to the upstream service. This must be an unused port, but does not need to match the upstream service port. |
 
 If you have multiple upstream services they each need to be listed here.
 
@@ -127,8 +144,8 @@ module "web" {
   family = "web"
   upstreams = [
     {
-      destination_name = "backend"
-      local_bind_port  = 8080
+      destinationName = "backend"
+      localBindPort = 8080
     }
   ]
   container_definitions = [
diff --git a/website/content/docs/ecs/requirements.mdx b/website/content/docs/ecs/requirements.mdx
index 1c4d0488df..c7d0b7407d 100644
--- a/website/content/docs/ecs/requirements.mdx
+++ b/website/content/docs/ecs/requirements.mdx
@@ -9,8 +9,18 @@ description: >-
 
 The following requirements must be met in order to install Consul on ECS:
 
-1. **Terraform:** The tasks that you want to add to the service mesh must first be modeled in Terraform.
 1. **Launch Type:** Fargate and EC2 launch types are supported.
 1. **Subnets:** ECS Tasks can run in private or public subnets. Tasks must have [network access](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/) to Amazon ECR or other public container registries to pull images.
 1. **Consul Servers:** You can use your own Consul servers running on virtual machines or use [HashiCorp Cloud Platform Consul](https://www.hashicorp.com/cloud-platform) to host the servers for you. For development purposes or testing, you may use the `dev-server` [Terraform module](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main) that runs the Consul server as an ECS task. The `dev-server` does not support persistent storage.
 1. **ACL Controller:** If you are running a secure Consul installation with ACLs enabled, configure the ACL controller.
+1. **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a
+   Consul agent container and a sidecar proxy container. These additional sidecar containers must
+   be included in the ECS task definition. The Consul ECS Terraform modules will include these
+   sidecar containers for you. Or if you do not use Terraform, you can construct the task
+   definition yourself by following our documentation.
+1. **Routing:** With your application running in tasks as part of the mesh, you must specify the
+   upstream services that your application calls. You will also need to change the URLs your
+   application uses to ensure the application is making requests through the service mesh.
+1. **Bind Address:** Once all communication is flowing through the service mesh, you should change
+   the address your application is listening on to `127.0.0.1` so that it only receives requests
+   through the sidecar proxy.
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 028a950e01..fdbacd0e94 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -612,7 +612,7 @@
         "path": "ecs/requirements"
       },
       {
-        "title": "Installation",
+        "title": "Installation with Terraform",
         "path": "ecs/install"
       },
       {
@@ -630,6 +630,10 @@
       {
         "title": "Consul Enterprise",
         "path": "ecs/enterprise"
+      },
+      {
+        "title": "Manual Installation",
+        "path": "ecs/install-no-terraform"
       }
     ]
   },

From b8d4876d05d4553dec96d905251d4e85338679ed Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Wed, 19 Jan 2022 15:18:15 -0600
Subject: [PATCH 69/98] docs: Apply suggestions for manual ECS installation

Co-authored-by: Luke Kysow <1034429+lkysow@users.noreply.github.com>
---
 website/content/docs/ecs/install-no-terraform.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/ecs/install-no-terraform.mdx b/website/content/docs/ecs/install-no-terraform.mdx
index 5f6378eafb..4cdc9ba309 100644
--- a/website/content/docs/ecs/install-no-terraform.mdx
+++ b/website/content/docs/ecs/install-no-terraform.mdx
@@ -17,7 +17,7 @@ for use without Terraform.
 * This page does not show how to create all necessary AWS resources, such as a VPC or the ECS Cluster.
   For complete runnable examples, see the links in the [Getting Started](/docs/ecs#getting-started) section.
 
-# Task Definition
+## Task Definition
 
 You must define a Task Definition which includes the following containers:
 
@@ -57,7 +57,7 @@ In your task definition, you'll need to define these important top-level fields:
 ## Application container
 
 First, include your application container in the `containerDefinitions` list
-in the task definition:
+in the task definition. Ensure that the `dependsOn` field is set as shown below so that your application container starts in the correct order (see [task startup](/docs/ecs/architecture#task-startup) for more information):
 
 ```json
 {
@@ -155,7 +155,7 @@ The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for
 
 ## `consul-client` container
 
-Each task must include a Consul agent container in order for the task to join your Consul cluster.
+Each task must include a Consul client container in order for the task to join your Consul cluster.
 
 ```json
 {
@@ -197,7 +197,7 @@ Each task must include a Consul agent container in order for the task to join yo
 | -----------   | ------- | ------------------------------------------------------------------------------------------------------------------------ |
 | `name`        | string  | The name of the Consul agent container, which should always be `consul-client`.                                          |
 | `image`       | string  | The container image for Consul. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits.    |
-| `mountPoints` | list    | The mounts the `/consul` data volume which contains the Envoy configuration file.                                        |
+| `mountPoints` | list    | Mount the `/consul` data volume which contains the Envoy configuration file.                                        |
 | `ulimits`     | list    | Set the file descriptor limit, `nofile`, to a sufficiently high value so that Envoy does not fail to open sockets.       |
 | `entrypoint`  | list    | A custom entrypoint binary is used to run Envoy, in order to facilitate graceful shutdown.                               |
 | `command`     | list    | The startup command. See below for details.

From 485069db78768983439adf7f1e8d6aa7e3bd0082 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Wed, 19 Jan 2022 17:55:55 -0600
Subject: [PATCH 70/98] docs: Improving ECS manual installation page

---
 .../content/docs/ecs/install-no-terraform.mdx | 179 ++++++++++--------
 1 file changed, 97 insertions(+), 82 deletions(-)

diff --git a/website/content/docs/ecs/install-no-terraform.mdx b/website/content/docs/ecs/install-no-terraform.mdx
index 4cdc9ba309..4a4f80e439 100644
--- a/website/content/docs/ecs/install-no-terraform.mdx
+++ b/website/content/docs/ecs/install-no-terraform.mdx
@@ -23,7 +23,7 @@ You must define a Task Definition which includes the following containers:
 
 * Your application container
 * An Envoy sidecar-proxy container
-* A Consul Agent container
+* A Consul client container
 * The `consul-ecs-mesh-init` container for service mesh setup
 * Optionally, a `consul-ecs-health-sync` container to sync ECS health checks into Consul
 
@@ -47,17 +47,19 @@ In your task definition, you'll need to define these important top-level fields:
 }
 ```
 
-| Field name             | Type   | Description                                                                                         |
-| -------------          | ------ | --------------------------------------------------------------------------------------------------- |
-| `family`               | string | The task family name. This is used as the Consul service name, by default.                          |
-| `networkMode`          | string | Must be `awsvpc`, which is the only network mode supported by Consul on ECS.                        |
-| `volumes`              | list   | These are volumes used to share information between containers, which is important for setup steps. |
-| `containerDefinitions` | list   | The list of containers to run in this task (see below).                                             |
+| Field name             | Type   | Description                                                                                                        |
+| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| `family`               | string | The task family name. This is used as the Consul service name, by default.                                         |
+| `networkMode`          | string | Must be `awsvpc`, which is the only network mode supported by Consul on ECS.                                       |
+| `volumes`              | list   | Must be defined as shown above. Volumes ares used to share configuration between containers for intial task setup. |
+| `containerDefinitions` | list   | The list of containers to run in this task (see below).                                                            |
 
 ## Application container
 
 First, include your application container in the `containerDefinitions` list
-in the task definition. Ensure that the `dependsOn` field is set as shown below so that your application container starts in the correct order (see [task startup](/docs/ecs/architecture#task-startup) for more information):
+in the task definition. Ensure that the `dependsOn` field is set as shown below
+so that your application container starts in the correct order (see [task
+startup](/docs/ecs/architecture#task-startup) for more information):
 
 ```json
 {
@@ -75,18 +77,19 @@ in the task definition. Ensure that the `dependsOn` field is set as shown below
           "containerName": "sidecar-proxy",
           "condition": "HEALTHY"
         }
-      ]
+      ],
+      ...
     }
   ]
 }
 ```
 
-| Field name  | Type    | Description                                                                                                                     |
-| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------        |
-| `name`      | string  | The name of your application container.                                                                                         |
-| `image`     | string  | The container image used to run your application.                                                                               |
-| `essential` | boolean | Set this to `true` ensures your application container ties into the health of the task. All tasks must have at least one essential container. |
-| `dependsOn` | list    | Container dependendencies are used to ensure the service mesh is ready before your application starts.                          |
+| Field name  | Type    | Description                                                                                                                      |
+| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `name`      | string  | The name of your application container.                                                                                          |
+| `image`     | string  | The container image used to run your application.                                                                                |
+| `essential` | boolean | Must be `true` to ensure your application container ties into the health of the task.                                            |
+| `dependsOn` | list    | Must be set as show above. Container dependencies ensure your application container starts after service mesh setup is complete. |
 
 See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) documentation for a complete reference.
 
@@ -94,6 +97,8 @@ See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/devel
 
 The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect.
 
+<CodeBlockConfig highlight="8-40">
+
 ```json
 {
   "containerDefinitions": [
@@ -139,24 +144,29 @@ The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for
 }
 ```
 
-| Field name    | Type    | Description                                                                                                        |
-| -----------   | ------- | ------------------------------------------------------------------------------------------------------------------ |
-| `name`        | string  | The name of the container, which should always be `sidecar-proxy`.                                                 |
-| `image`       | string  | The container image for Envoy. We recommend using `envoyproxy/envoy-alpine`.                                       |
-| `dependsOn`   | list    | Envoy must start after `consul-ecs-mesh-init`, which creates the bootstrap configuration file for Envoy.           |
-| `healthCheck` | list    | A health check should be definied for Envoy's primary listener port.                                               |
-| `mountPoints` | list    | The mounts the `/consul` data volume which contains the Envoy configuration file.                                  |
-| `ulimits`     | list    | Set the file descriptor limit, `nofile`, to a sufficiently high value so that Envoy does not fail to open sockets. |
-| `entrypoint`  | list    | A custom entrypoint binary is used to help facilitate graceful shutdown.                                           |
-| `command`     | list    | The startup command. This passes the bootstrap configuration to Envoy.                                             |
+</CodeBlockConfig>
 
--> **NOTE**: Envoy and Consul must be compatible versions. See the [supported versions of Envoy](https://www.consul.io/docs/connect/proxies/envoy#supported-versions) for each Consul release.
+In most cases, the `sidecar-proxy` container can be configured exactly as shown above.
 
+| Field name    | Type    | Description                                                                                                                                                |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string  | The container name, which must be `sidecar-proxy`.                                                                                                         |
+| `image`       | string  | The Envoy image. This must be a [supported version of Envoy](/docs/connect/proxies/envoy#supported-versions).                                              |
+| `dependsOn`   | list    | Must be set as shown above to ensure Envoy starts after the `consul-ecs-mesh-init` has written the `envoy-bootstrap.json` config file for Envoy.           |
+| `healthCheck` | list    | Must be set as shown above to monitor the health of Envoy's primary listener port, which ties into container dependencies and startup ordering.            |
+| `mountPoints` | list    | Must be set as shown above to access the files shared in the `consul` directory, like the Envoy bootstrap configuration file and the `consul-ecs` binary.  |
+| `ulimits`     | list    | The `nofile` ulimit must be raised to a sufficiently high value so that Envoy does not fail to open sockets.                                               |
+| `entrypoint`  | list    | Must be set to the custom Envoy entrypoint to facilitate graceful shutdown.                                                                                |
+| `command`     | list    | The startup command. This passes the bootstrap configuration to Envoy.                                                                                     |
+
+-> **NOTE**: Envoy and Consul must be compatible versions. See the [supported versions of Envoy](/docs/connect/proxies/envoy#supported-versions) in the Consul documentation.
 
 ## `consul-client` container
 
 Each task must include a Consul client container in order for the task to join your Consul cluster.
 
+<CodeBlockConfig highlight="13-31">
+
 ```json
 {
   "containerDefinitions": [
@@ -193,14 +203,15 @@ Each task must include a Consul client container in order for the task to join y
 }
 ```
 
-| Field name    | Type    | Description                                                                                                              |
-| -----------   | ------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `name`        | string  | The name of the Consul agent container, which should always be `consul-client`.                                          |
-| `image`       | string  | The container image for Consul. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits.    |
-| `mountPoints` | list    | Mount the `/consul` data volume which contains the Envoy configuration file.                                        |
-| `ulimits`     | list    | Set the file descriptor limit, `nofile`, to a sufficiently high value so that Envoy does not fail to open sockets.       |
-| `entrypoint`  | list    | A custom entrypoint binary is used to run Envoy, in order to facilitate graceful shutdown.                               |
-| `command`     | list    | The startup command. See below for details.
+</CodeBlockConfig>
+
+| Field name    | Type    | Description                                                                                                         |
+| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string  | The container name, which should always be `consul-client`.                                                         |
+| `image`       | string  | The Consul image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits.             |
+| `mountPoints` | list    | Must be set as shown above. Volumes are mounted to share information with other containers for task setup.          |
+| `entrypoint`  | list    | Must be set to a plain shell so that the startup `command` works properly.                                          |
+| `command`     | list    | The startup command. See below for details.                                                                         |
 
 The following is the recommended `command` script for the Consul agent.
 This is the same as the above `command` field, but is unescaped and has comments added.
@@ -212,7 +223,7 @@ cp /bin/consul /bin/consul-inject/consul
 # At runtime, determine the IP address assigned to this ECS Task.
 ECS_IPV4=$(curl -s $ECS_CONTAINER_METADATA_URI_V4 | jq -r '.Networks[0].IPv4Addresses[0]')
 
-# Define the Consul agent configuration file.
+# Write the Consul agent configuration file.
 cat << EOF > /consul/agent-defaults.hcl
 addresses = {
   dns = "127.0.0.1"
@@ -241,24 +252,30 @@ exec consul agent \
     -config-file /consul/agent-defaults.hcl
 ```
 
-You can tailor the configuration above for your use case, but it's important to set the following fields as show:
+Set the following fields as shown above:
 
 | Field name           | Type    | Description                                                                                                  |
 | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
 | `addresses.*`        | strings | Set the DNS, GRPC, and HTTP addresses to `127.0.0.1` to ensure these are not accessible outside of the task. |
-| `advertise_addr`     | string  | This must be set to the task IP address so that other Consul agents know how to reach this agent.            |
-| `client_addr`        | string  | This must bind to an interface reacable by other Consul agents.                                              |
-| `leave_on_terminate` | boolean | This ensures this Consul agent will leave the cluster gracefully before exiting.                             |
-| `retry_join`         | string  | This must be set to your Consul server location(s) so this agent can join the Consul cluster.                |
+| `advertise_addr`     | string  | Must be set to the task IP address so that other Consul agents know how to reach this agent.                 |
+| `client_addr`        | string  | Must be set to an interface reacable by other Consul agents.                                                 |
+| `datacenter`         | string  | Must be set to the Consul datacenter this task will join.                                                    |
+| `leave_on_terminate` | boolean | Must be set to `true` so that the Consul agent leaves the cluster gracefully before exiting.                 |
+| `retry_join`         | string  | Must be set to your Consul server location(s) so this agent can join the Consul cluster.                     |
 
--> **NOTE**: It is important to use `exec` to start the Consul agent, so that the Consul agent runs as PID 1. This ensures
+-> **NOTE**: Use `exec` to start the Consul agent, so that the Consul agent runs as PID 1. This ensures
 the Consul agent directly receives signals from ECS, which is important for graceful shutdown of the Consul agent.
 
+Refer to the [Consul Agent documentation](/docs/agent/options#configuration_files) for a complete reference of Consul agent
+configuration options.
+
 ## `mesh-init` container
 
-The mesh-init container runs at task startup to setup this instance for Consul service mesh.
-It will register this service and proxy with Consul and write Envoy bootstrap configuration
-to a shared volume.
+The `mesh-init` container runs at task startup to setup this instance for Consul service mesh.
+It registers the service and proxy for this task with Consul and writes Envoy bootstrap
+configuration to a shared volume.
+
+<CodeBlockConfig highlight="18-41">
 
 ```json
 {
@@ -306,15 +323,17 @@ to a shared volume.
 }
 ```
 
-| Field name    | Type    | Description                                                                                                                  |
-| -----------   | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `name`        | string  | The container name should be `consul-ecs-mesh-init`.                                                                         |
-| `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.            |
-| `mountPoints` | list    | The mounts two volumes so that mesh-init can invoke the `consul` binary to write bootstrap Envoy configuration.              |
-| `command`     | list    | Set the `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command.                                       |
-| `environment` | list    | This must include the `CONSUL_ECS_CONFIG_JSON` variable. See below for details.                                              |
+</CodeBlockConfig>
+
+| Field name    | Type    | Description                                                                                                         |
+| -----------   | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string  | The container name should be `consul-ecs-mesh-init`.                                                                |
+| `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.   |
+| `mountPoints` | list    | Must be set as show above, so the `consul` and `consul-ecs` binaries can be shared among containers for task setup. |
+| `command`     | list    | Set the `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command.                              |
+| `environment` | list    | This must include the `CONSUL_ECS_CONFIG_JSON` variable. See below for details.                                     |
 
-Additional configuration is passed to the `consul-ecs mesh-init` command in JSON format using the `CONSUL_ECS_CONFIG_JSON` environment variable.
+Configuration is passed to the `consul-ecs mesh-init` command in JSON format using the `CONSUL_ECS_CONFIG_JSON` environment variable.
 Here is the sample config from above, expanded to be readable:
 
 ```json
@@ -355,8 +374,9 @@ Optionally, Consul ECS can sync health checks for this task into Consul checks.
 This allows you to configure a health check for your application in one place, and
 see a consistent health status in both ECS and Consul.
 
-First, you'll need to add an ECS health check command to the container definition for your application.
-This configures a health check command that runs `curl localhost:9090/health` to check the application health:
+For example, the following defines an ECS health check command that runs `curl localhost:9090/health`:
+
+<CodeBlockConfig highlight="6-11">
 
 ```json
 {
@@ -377,38 +397,27 @@ This configures a health check command that runs `curl localhost:9090/health` to
 }
 ```
 
-See the [ECS health check documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_healthcheck) for details on defining ECS health checks.
+</CodeBlockConfig>
 
-Next, you must tell Consul ECS which containers will have their health status synced into Consul. To do this,
-set the `healthSyncContainers` field of the `CONSUL_ECS_CONFIG_JSON` variable to include your application container name.
+First, tell Consul ECS which containers need their health status synced into Consul. To do this,
+add the container name(s) to the `healthSyncContainers` list of the `CONSUL_ECS_CONFIG_JSON` variable:
 
-Here is the expanded configuration:
+<CodeBlockConfig highlight="3-3">
 
 ```json
 {
   "bootstrapDir": "/consul",
   "healthSyncContainers": ["example-client-app"],
-  "proxy": {
-    "upstreams": [
-      {
-        "destinationName": "example-server-app",
-        "localBindPort": 1234
-      }
-    ]
-  },
-  "service": {
-    "checks": [],
-    "meta": {},
-    "name": "example-client-app",
-    "port": 9090,
-    "tags": []
-  }
+  ...
 }
 ```
 
-Then, update the task definition so that the `consul-ecs-mesh-init` container uses new configuration.
-You should compact and escape the JSON configuration above, and copy the result into the `CONSUL_ECS_CONFIG_JSON`
-environment variable:
+</CodeBlockConfig>
+
+Next, pass the new configuration to the `consul-ecs-mesh-init` container. You should compact and escape the JSON
+configuration above, and copy the result into the `CONSUL_ECS_CONFIG_JSON` environment variable:
+
+<CodeBlockConfig highlight="7-10">
 
 ```json
 {
@@ -429,9 +438,13 @@ environment variable:
 }
 ```
 
+</CodeBlockConfig>
+
 Finally, include the `consul-ecs-health-sync` container in the `containerDefinitions` list.
-Be sure to pass the same value as above for the `CONSUL_ECS_CONFIG_JSON` environment
-variable:
+The exact same configuration for the `CONSUL_ECS_CONFIG_JSON` environment variable is used
+for the health sync container.
+
+<CodeBlockConfig highlight="23-40">
 
 ```json
 {
@@ -478,13 +491,15 @@ variable:
 }
 ```
 
+</CodeBlockConfig>
+
 | Field name    | Type   | Description                                                                                                       |
 | ------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
-| `name`        | string | The container name which should be `consul-ecs-health-sync`.                                                      |
+| `name`        | string | The container name, which must be `consul-ecs-health-sync`.                                                       |
 | `image`       | string | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits. |
-| `command`     | list   | Set to `["health-sync"]` to run the `consul-ecs health-sync` command.                                             |
-| `dependsOn`   | list   | The `health-sync` container should not start until `mesh-init` has finished service and proxy registration.       |
-| `environment` | list   | Set the `CONSUL_ECS_CONFIG_JSON` variable to pass configuration to the `consul-ecs health-sync command.           |
+| `command`     | list   | Must be set to `["health-sync"]` to run the `consul-ecs health-sync` command.                                     |
+| `dependsOn`   | list   | Must be set as shown above to ensure the `health-sync` container starts after service registration has completed. |
+| `environment` | list   | Must include the `CONSUL_ECS_CONFIG_JSON` variable to pass configuration to the `consul-ecs health-sync` command. |
 
 # Next Steps
 

From 919b659c984c38459ce0ee47b759b91b0062d0ca Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Wed, 19 Jan 2022 18:07:44 -0600
Subject: [PATCH 71/98] docs: Correct ECS filename -> manual-installation.mdx

---
 .../{install-no-terraform.mdx => manual-installation.mdx}   | 0
 website/content/docs/ecs/requirements.mdx                   | 6 +++---
 website/data/docs-nav-data.json                             | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)
 rename website/content/docs/ecs/{install-no-terraform.mdx => manual-installation.mdx} (100%)

diff --git a/website/content/docs/ecs/install-no-terraform.mdx b/website/content/docs/ecs/manual-installation.mdx
similarity index 100%
rename from website/content/docs/ecs/install-no-terraform.mdx
rename to website/content/docs/ecs/manual-installation.mdx
diff --git a/website/content/docs/ecs/requirements.mdx b/website/content/docs/ecs/requirements.mdx
index c7d0b7407d..73570f16bd 100644
--- a/website/content/docs/ecs/requirements.mdx
+++ b/website/content/docs/ecs/requirements.mdx
@@ -15,9 +15,9 @@ The following requirements must be met in order to install Consul on ECS:
 1. **ACL Controller:** If you are running a secure Consul installation with ACLs enabled, configure the ACL controller.
 1. **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a
    Consul agent container and a sidecar proxy container. These additional sidecar containers must
-   be included in the ECS task definition. The Consul ECS Terraform modules will include these
-   sidecar containers for you. Or if you do not use Terraform, you can construct the task
-   definition yourself by following our documentation.
+   be included in the ECS task definition. The [Consul ECS Terraform module](/docs/ecs/install)
+   will include these sidecar containers for you. Or if you do not use Terraform, you can construct
+   the task definition yourself by following [our documentation](/docs/ecs/manual-installation).
 1. **Routing:** With your application running in tasks as part of the mesh, you must specify the
    upstream services that your application calls. You will also need to change the URLs your
    application uses to ensure the application is making requests through the service mesh.
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index fdbacd0e94..3e1566d563 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -633,7 +633,7 @@
       },
       {
         "title": "Manual Installation",
-        "path": "ecs/install-no-terraform"
+        "path": "ecs/manual-installation"
       }
     ]
   },

From bb4a03525465c018d2d41cb92dc5e85cb2121f79 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Fri, 21 Jan 2022 10:12:32 -0600
Subject: [PATCH 72/98] docs: Apply suggestions to ECS docs from code review

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---
 website/content/docs/ecs/install.mdx          | 12 ++++---
 .../content/docs/ecs/manual-installation.mdx  | 32 +++++++++----------
 website/content/docs/ecs/requirements.mdx     |  2 +-
 3 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/website/content/docs/ecs/install.mdx b/website/content/docs/ecs/install.mdx
index 3554043cd9..32d3dee3a4 100644
--- a/website/content/docs/ecs/install.mdx
+++ b/website/content/docs/ecs/install.mdx
@@ -1,15 +1,17 @@
 ---
 layout: docs
-page_title: Installation with Terraform - AWS ECS
+page_title: Installing Consul on AWS ECS using Terraform  
 description: >-
   Install Consul Service Mesh on AWS ECS with Terraform (Elastic Container Service).
 ---
 
 # Installation with Terraform
 
-This will describe how to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh.
+This topic describes how to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh.
 
-## Pre-requisites
+This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples.
+
+## Prerequisites
 
 * This pages assumes you are familiar with Terraform. If you are new to Terraform, see the [Terraform documentation](https://www.terraform.io/docs) to
   learn about infrastructure as code and how to get started with Terraform.
@@ -24,7 +26,7 @@ and additional sidecar containers, such as the Consul agent container and the En
 
 The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers.
 
-Here is an example Terraform configuration file which defines a task definition with an application container called `example-client-app`.
+The following example shows a Terraform configuration file that defines a task definition with an application container called `example-client-app`.
 
 ```hcl
 module "my_task" {
@@ -61,7 +63,7 @@ however there are some important inputs worth highlighting:
 | Input Variable          | Type     | Description                                                                                                                                                                                                                                    |
 | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `source` and `version`  | string   | This specifies the source location and version of the `mesh-task` module.                                                                                                                                                                      |
-| `family`                | string   | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name, by default.                                          |
+| `family`                | string   | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default.                                          |
 | `container_definitions` | list     | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. |
 | `port`                  | number   | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`.                                                                                                                  |
 | `retry_join`            | list     | The is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers.                                                                                                  |
diff --git a/website/content/docs/ecs/manual-installation.mdx b/website/content/docs/ecs/manual-installation.mdx
index 4a4f80e439..16b6dd5a17 100644
--- a/website/content/docs/ecs/manual-installation.mdx
+++ b/website/content/docs/ecs/manual-installation.mdx
@@ -7,19 +7,17 @@ description: >-
 
 # Manual Installation
 
-While the [Consul ECS Terraform module](/docs/ecs/install) is the easiest way to use Consul on ECS,
-this page will describe how to directly create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs)
-for use without Terraform.
+This topic describes how to manually create the ECS task definition for use without Terraform from the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs). Refer to the [Consul ECS Terraform module](/docs/ecs/install) documentation for an alternative method for installing Consul on ECS.
 
-## Pre-requisites
+This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples.
 
-* This page assumes you are familiar with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for more details.
-* This page does not show how to create all necessary AWS resources, such as a VPC or the ECS Cluster.
-  For complete runnable examples, see the links in the [Getting Started](/docs/ecs#getting-started) section.
+## Prerequisites
+
+You should have some familiarity with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details.
 
 ## Task Definition
 
-You must define a Task Definition which includes the following containers:
+You must define a task definition which includes the following containers:
 
 * Your application container
 * An Envoy sidecar-proxy container
@@ -29,7 +27,7 @@ You must define a Task Definition which includes the following containers:
 
 ## Top-level fields
 
-In your task definition, you'll need to define these important top-level fields:
+Your task definition must include the following top-level fields:
 
 ```json
 {
@@ -49,9 +47,9 @@ In your task definition, you'll need to define these important top-level fields:
 
 | Field name             | Type   | Description                                                                                                        |
 | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
-| `family`               | string | The task family name. This is used as the Consul service name, by default.                                         |
+| `family`               | string | The task family name. This is used as the Consul service name by default.                                         |
 | `networkMode`          | string | Must be `awsvpc`, which is the only network mode supported by Consul on ECS.                                       |
-| `volumes`              | list   | Must be defined as shown above. Volumes ares used to share configuration between containers for intial task setup. |
+| `volumes`              | list   | Must be defined as shown above. Volumes are used to share configuration between containers for intial task setup. |
 | `containerDefinitions` | list   | The list of containers to run in this task (see below).                                                            |
 
 ## Application container
@@ -95,7 +93,7 @@ See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/devel
 
 ## `sidecar-proxy` container
 
-The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect.
+The `sidecar-proxy` container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect. In most cases, the container should contain the following parameters and values.
 
 <CodeBlockConfig highlight="8-40">
 
@@ -146,7 +144,7 @@ The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for
 
 </CodeBlockConfig>
 
-In most cases, the `sidecar-proxy` container can be configured exactly as shown above.
+The following table describes the available configuration settings.
 
 | Field name    | Type    | Description                                                                                                                                                |
 | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -252,7 +250,7 @@ exec consul agent \
     -config-file /consul/agent-defaults.hcl
 ```
 
-Set the following fields as shown above:
+The following table describes the values that you should use to configure the `command` script:
 
 | Field name           | Type    | Description                                                                                                  |
 | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
@@ -263,7 +261,7 @@ Set the following fields as shown above:
 | `leave_on_terminate` | boolean | Must be set to `true` so that the Consul agent leaves the cluster gracefully before exiting.                 |
 | `retry_join`         | string  | Must be set to your Consul server location(s) so this agent can join the Consul cluster.                     |
 
--> **NOTE**: Use `exec` to start the Consul agent, so that the Consul agent runs as PID 1. This ensures
+-> **NOTE**: Use `exec` to start the Consul agent so that the Consul agent runs as PID 1. This ensures
 the Consul agent directly receives signals from ECS, which is important for graceful shutdown of the Consul agent.
 
 Refer to the [Consul Agent documentation](/docs/agent/options#configuration_files) for a complete reference of Consul agent
@@ -364,14 +362,14 @@ Here is the sample config from above, expanded to be readable:
 | `proxy.upstreams` | list   | The upstream services that your application calls over the service mesh, if any.                                               |
 | `service.name`    | string | The name used to register this service into the Consul service catalog.                                                        |
 | `service.port`    | number | The port your application listens on. Set to `0` if your application does not listen on any port.                              |
-| `service.checks`  | list   | Consul [checks](/docs/discovery/checks) to include, to have Consul run health checks against your application. |
+| `service.checks`  | list   | Specifies the Consul health [checks](/docs/discovery/checks) to run against your application. |
 
 See the [`consul-ecs JSON Schema`](https://github.com/hashicorp/consul-ecs/blob/main/config/schema.json) for a complete reference of fields.
 
 ## `consul-ecs-health-sync` container
 
 Optionally, Consul ECS can sync health checks for this task into Consul checks.
-This allows you to configure a health check for your application in one place, and
+This allows you to configure a health check for your application in one place and
 see a consistent health status in both ECS and Consul.
 
 For example, the following defines an ECS health check command that runs `curl localhost:9090/health`:
diff --git a/website/content/docs/ecs/requirements.mdx b/website/content/docs/ecs/requirements.mdx
index 73570f16bd..faedb2f2a3 100644
--- a/website/content/docs/ecs/requirements.mdx
+++ b/website/content/docs/ecs/requirements.mdx
@@ -16,7 +16,7 @@ The following requirements must be met in order to install Consul on ECS:
 1. **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a
    Consul agent container and a sidecar proxy container. These additional sidecar containers must
    be included in the ECS task definition. The [Consul ECS Terraform module](/docs/ecs/install)
-   will include these sidecar containers for you. Or if you do not use Terraform, you can construct
+   will include these sidecar containers for you. If you do not use Terraform, you can construct
    the task definition yourself by following [our documentation](/docs/ecs/manual-installation).
 1. **Routing:** With your application running in tasks as part of the mesh, you must specify the
    upstream services that your application calls. You will also need to change the URLs your

From 296fbaf5b1e48df298e305f46202aa4a87c835b1 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Fri, 21 Jan 2022 14:11:11 -0600
Subject: [PATCH 73/98] docs: Improving ECS installation docs

---
 website/content/docs/ecs/install.mdx          | 23 +++--
 .../content/docs/ecs/manual-installation.mdx  | 85 ++++++++++++-------
 2 files changed, 65 insertions(+), 43 deletions(-)

diff --git a/website/content/docs/ecs/install.mdx b/website/content/docs/ecs/install.mdx
index 32d3dee3a4..dc35b53efe 100644
--- a/website/content/docs/ecs/install.mdx
+++ b/website/content/docs/ecs/install.mdx
@@ -1,32 +1,29 @@
 ---
 layout: docs
-page_title: Installing Consul on AWS ECS using Terraform  
+page_title: Installing Consul on AWS ECS using Terraform
 description: >-
   Install Consul Service Mesh on AWS ECS with Terraform (Elastic Container Service).
 ---
 
 # Installation with Terraform
 
-This topic describes how to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh.
+This topic describes how to use the [`mesh-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh. If you do not use Terraform, see the [Manual Installation](/docs/ecs/manual-installation) page to install Consul on ECS without Terraform.
 
 This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples.
 
 ## Prerequisites
 
-* This pages assumes you are familiar with Terraform. If you are new to Terraform, see the [Terraform documentation](https://www.terraform.io/docs) to
-  learn about infrastructure as code and how to get started with Terraform.
-* This page assumes you are familiar with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for more details.
-* This page does not show how to create all necessary AWS resources, such as a VPC or the ECS Cluster.
-  For complete runnable examples, see the links in the [Getting Started](/docs/ecs#getting-started) section.
+* You should have some familiarity with using Terraform. Refer to the [Terraform documentation](https://www.terraform.io/docs) to learn about infrastructure as code and how to get started with Terraform.
+* You should also be familiar with AWS ECS before following these instructions. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details.
 
 ## Using the Mesh Task Module
 
-To run an application in ECS with Consul service mesh, you must create an ECS task definition which includes your application container(s)
+To run an application in ECS with Consul service mesh, you must create an ECS task definition, which includes your application container(s)
 and additional sidecar containers, such as the Consul agent container and the Envoy sidecar proxy container.
 
 The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers.
 
-The following example shows a Terraform configuration file that defines a task definition with an application container called `example-client-app`.
+The following example shows a Terraform configuration file that creates a task definition with an application container called `example-client-app`.
 
 ```hcl
 module "my_task" {
@@ -52,7 +49,7 @@ module "my_task" {
     }
   ]
 
-  port       = "9090"
+  port       = 9090
   retry_join = ["<address of the Consul server>"]
 }
 ```
@@ -63,9 +60,9 @@ however there are some important inputs worth highlighting:
 | Input Variable          | Type     | Description                                                                                                                                                                                                                                    |
 | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `source` and `version`  | string   | This specifies the source location and version of the `mesh-task` module.                                                                                                                                                                      |
-| `family`                | string   | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default.                                          |
+| `family`                | string   | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default.                                           |
 | `container_definitions` | list     | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. |
-| `port`                  | number   | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`.                                                                                                                  |
+| `port`                  | integer  | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`.                                                                                                                  |
 | `retry_join`            | list     | The is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers.                                                                                                  |
 
 ## ECS Service
@@ -131,7 +128,7 @@ module "web" {
 | Input Variable    | Type    | Description                                                                                                                                                      |
 | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `destinationName` | string  | The name of the upstream service, as it is registered in the Consul service catalog.                                                                             |
-| `localBindPort`   | number  | Requests to this port will be forwarded by the proxy to the upstream service. This must be an unused port, but does not need to match the upstream service port. |
+| `localBindPort`   | integer | Requests to this port will be forwarded by the proxy to the upstream service. This must be an unused port, but does not need to match the upstream service port. |
 
 If you have multiple upstream services they each need to be listed here.
 
diff --git a/website/content/docs/ecs/manual-installation.mdx b/website/content/docs/ecs/manual-installation.mdx
index 16b6dd5a17..56ca858271 100644
--- a/website/content/docs/ecs/manual-installation.mdx
+++ b/website/content/docs/ecs/manual-installation.mdx
@@ -7,7 +7,7 @@ description: >-
 
 # Manual Installation
 
-This topic describes how to manually create the ECS task definition for use without Terraform from the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs). Refer to the [Consul ECS Terraform module](/docs/ecs/install) documentation for an alternative method for installing Consul on ECS.
+The following instructions describe how to manually create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) without Terraform. Refer to the [Consul ECS Terraform module](/docs/ecs/install) documentation for an alternative method for installing Consul on ECS.
 
 This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples.
 
@@ -17,17 +17,22 @@ You should have some familiarity with AWS ECS. See [What is Amazon Elastic Conta
 
 ## Task Definition
 
-You must define a task definition which includes the following containers:
+You must create a task definition, which includes the following containers:
 
 * Your application container
 * An Envoy sidecar-proxy container
 * A Consul client container
-* The `consul-ecs-mesh-init` container for service mesh setup
+* A `consul-ecs-mesh-init` container for service mesh setup
 * Optionally, a `consul-ecs-health-sync` container to sync ECS health checks into Consul
 
 ## Top-level fields
 
-Your task definition must include the following top-level fields:
+Your task definition must include the following top-level fields.
+
+The `volumes` list contains two [bind mounts](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bind-mounts.html),
+named `consul_data` and `consul_binary`. Bind mounts are directories on the host which can be mounted into one or more containers
+in order to share files among containers. For Consul on ECS, certain binaries and configuration are shared among containers
+during task startup.
 
 ```json
 {
@@ -55,9 +60,14 @@ Your task definition must include the following top-level fields:
 ## Application container
 
 First, include your application container in the `containerDefinitions` list
-in the task definition. Ensure that the `dependsOn` field is set as shown below
-so that your application container starts in the correct order (see [task
-startup](/docs/ecs/architecture#task-startup) for more information):
+in the task definition.
+
+Ensure that the `containerName` and `condition` fields in the `dependsOn` list
+are specified as described in the following example. These are container dependencies,
+which must be used to enforce a specific [startup order](/docs/ecs/architecture#task-startup).
+By using the following settings, your application container will start after `consul-ecs-mesh-init`
+has completed task setup and after `sidecar-proxy` is ready to proxy traffic between
+this task and the service mesh.
 
 ```json
 {
@@ -87,7 +97,7 @@ startup](/docs/ecs/architecture#task-startup) for more information):
 | `name`      | string  | The name of your application container.                                                                                          |
 | `image`     | string  | The container image used to run your application.                                                                                |
 | `essential` | boolean | Must be `true` to ensure your application container ties into the health of the task.                                            |
-| `dependsOn` | list    | Must be set as show above. Container dependencies ensure your application container starts after service mesh setup is complete. |
+| `dependsOn` | list    | Must be set as shown above. Container dependencies ensure your application container starts after service mesh setup is complete. |
 
 See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) documentation for a complete reference.
 
@@ -95,6 +105,11 @@ See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/devel
 
 The `sidecar-proxy` container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect. In most cases, the container should contain the following parameters and values.
 
+The `mountPoints` list must be set as shown in the following example. This will mount the shared `consul_data` volume into the
+`sidecar-proxy` container at the path `/consul`. This volume is where the `consul-ecs-mesh-init` container copies the `envoy-bootstrap.json`
+file and the `consul-ecs` binary, which are required to start Envoy. The `dependsOn` list must also be defined as follows to ensure the
+`sidecar-proxy` container starts after `consul-ecs-mesh-init` has successfully written these files to the shared volume.
+
 <CodeBlockConfig highlight="8-40">
 
 ```json
@@ -144,7 +159,7 @@ The `sidecar-proxy` container runs [Envoy proxy](/docs/connect/proxies/envoy) fo
 
 </CodeBlockConfig>
 
-The following table describes the available configuration settings.
+The following table describes the necessary configuration settings.
 
 | Field name    | Type    | Description                                                                                                                                                |
 | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -152,9 +167,9 @@ The following table describes the available configuration settings.
 | `image`       | string  | The Envoy image. This must be a [supported version of Envoy](/docs/connect/proxies/envoy#supported-versions).                                              |
 | `dependsOn`   | list    | Must be set as shown above to ensure Envoy starts after the `consul-ecs-mesh-init` has written the `envoy-bootstrap.json` config file for Envoy.           |
 | `healthCheck` | list    | Must be set as shown above to monitor the health of Envoy's primary listener port, which ties into container dependencies and startup ordering.            |
-| `mountPoints` | list    | Must be set as shown above to access the files shared in the `consul` directory, like the Envoy bootstrap configuration file and the `consul-ecs` binary.  |
+| `mountPoints` | list    | Must be set as shown above to access the files shared in the `/consul` directory, like the Envoy bootstrap configuration file and the `consul-ecs` binary. |
 | `ulimits`     | list    | The `nofile` ulimit must be raised to a sufficiently high value so that Envoy does not fail to open sockets.                                               |
-| `entrypoint`  | list    | Must be set to the custom Envoy entrypoint to facilitate graceful shutdown.                                                                                |
+| `entrypoint`  | list    | Must be set to the custom Envoy entrypoint, `consul-ecs envoy-entrypoint`, to facilitate graceful shutdown.                                                |
 | `command`     | list    | The startup command. This passes the bootstrap configuration to Envoy.                                                                                     |
 
 -> **NOTE**: Envoy and Consul must be compatible versions. See the [supported versions of Envoy](/docs/connect/proxies/envoy#supported-versions) in the Consul documentation.
@@ -215,7 +230,7 @@ The following is the recommended `command` script for the Consul agent.
 This is the same as the above `command` field, but is unescaped and has comments added.
 
 ```shell
-# Copy the consul binary to a shared volume for mesh-init to use to generate Envoy configuration.
+# Copy the consul binary to a shared volume for `consul-ecs-mesh-init` to use to generate Envoy configuration.
 cp /bin/consul /bin/consul-inject/consul
 
 # At runtime, determine the IP address assigned to this ECS Task.
@@ -267,9 +282,9 @@ the Consul agent directly receives signals from ECS, which is important for grac
 Refer to the [Consul Agent documentation](/docs/agent/options#configuration_files) for a complete reference of Consul agent
 configuration options.
 
-## `mesh-init` container
+## `consul-ecs-mesh-init` container
 
-The `mesh-init` container runs at task startup to setup this instance for Consul service mesh.
+The `consul-ecs-mesh-init` container runs at task startup to setup this instance for Consul service mesh.
 It registers the service and proxy for this task with Consul and writes Envoy bootstrap
 configuration to a shared volume.
 
@@ -329,10 +344,16 @@ configuration to a shared volume.
 | `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.   |
 | `mountPoints` | list    | Must be set as show above, so the `consul` and `consul-ecs` binaries can be shared among containers for task setup. |
 | `command`     | list    | Set the `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command.                              |
-| `environment` | list    | This must include the `CONSUL_ECS_CONFIG_JSON` variable. See below for details.                                     |
+| `environment` | list    | This must include the [`CONSUL_ECS_CONFIG_JSON`](/docs/ecs/manual-installation#consul_ecs_config_json) variable. See below for details.    |
+
+### `CONSUL_ECS_CONFIG_JSON`
+
+Configuration is passed to the `consul-ecs` binary in JSON format using the `CONSUL_ECS_CONFIG_JSON` environment variable.
 
-Configuration is passed to the `consul-ecs mesh-init` command in JSON format using the `CONSUL_ECS_CONFIG_JSON` environment variable.
-Here is the sample config from above, expanded to be readable:
+The following is an example of the configuration that might be used for a service named `example-client-app` with one upstream
+service name `example-server-app`. The `proxy` and `service` blocks include information used by `consul-ecs-mesh-init` to perform
+[service registration](/docs/discovery/services) with Consul during task startup. The same configuration format is used for
+the `consul-ecs-health-sync` container.
 
 ```json
 {
@@ -356,13 +377,14 @@ Here is the sample config from above, expanded to be readable:
 }
 ```
 
-| Field name        | Type   | Description                                                                                                                    |
-| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| `bootstrapDir`    | string | This is the path of a  shared volume the is mounted to other containers, where `mesh-init` will write out Envoy configuration. |
-| `proxy.upstreams` | list   | The upstream services that your application calls over the service mesh, if any.                                               |
-| `service.name`    | string | The name used to register this service into the Consul service catalog.                                                        |
-| `service.port`    | number | The port your application listens on. Set to `0` if your application does not listen on any port.                              |
-| `service.checks`  | list   | Specifies the Consul health [checks](/docs/discovery/checks) to run against your application. |
+| Field name             | Type    | Description                                                                                                                                     |
+| ---------------------- | ------  | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bootstrapDir`         | string  | This is the path of a  shared volume the is mounted to other containers, where `consul-ecs-mesh-init` will write out Envoy configuration.       |
+| `healthSyncContainers` | list    | Used for [health status syncing](/docs/ecs/manual-installation#consul-ecs-health-sync-container) from ECS to Consul. See below for details.     |
+| `proxy.upstreams`      | list    | The upstream services that your application calls over the service mesh, if any. The `destinationName` and `localBindPort` fields are required. |
+| `service.name`         | string  | The name used to register this service into the Consul service catalog.                                                                         |
+| `service.port`         | integer | The port your application listens on. Set to `0` if your application does not listen on any port.                                               |
+| `service.checks`       | list    | Consul [checks](/docs/discovery/checks) to include so that Consul can run health checks against your application.                               |
 
 See the [`consul-ecs JSON Schema`](https://github.com/hashicorp/consul-ecs/blob/main/config/schema.json) for a complete reference of fields.
 
@@ -397,8 +419,10 @@ For example, the following defines an ECS health check command that runs `curl l
 
 </CodeBlockConfig>
 
-First, tell Consul ECS which containers need their health status synced into Consul. To do this,
-add the container name(s) to the `healthSyncContainers` list of the `CONSUL_ECS_CONFIG_JSON` variable:
+First, define which containers need their health status synced into Consul. To do this,
+add the container name(s) to the `healthSyncContainers` list of the `CONSUL_ECS_CONFIG_JSON` variable,
+as shown in the following example. This configuration must be passed to both the `consul-ecs-mesh-init`
+and `consul-ecs-health-sync` containers.
 
 <CodeBlockConfig highlight="3-3">
 
@@ -412,8 +436,9 @@ add the container name(s) to the `healthSyncContainers` list of the `CONSUL_ECS_
 
 </CodeBlockConfig>
 
-Next, pass the new configuration to the `consul-ecs-mesh-init` container. You should compact and escape the JSON
-configuration above, and copy the result into the `CONSUL_ECS_CONFIG_JSON` environment variable:
+Next, set the `CONSUL_ECS_CONFIG_JSON` variable for the `consul-ecs-mesh-init` container.
+The following example shows how the `CONSUL_ECS_CONFIG_JSON` variable should be formatted.
+The JSON configuration is compacted down to a single line and escaped.
 
 <CodeBlockConfig highlight="7-10">
 
@@ -439,8 +464,8 @@ configuration above, and copy the result into the `CONSUL_ECS_CONFIG_JSON` envir
 </CodeBlockConfig>
 
 Finally, include the `consul-ecs-health-sync` container in the `containerDefinitions` list.
-The exact same configuration for the `CONSUL_ECS_CONFIG_JSON` environment variable is used
-for the health sync container.
+Pass the same value for `CONSUL_ECS_CONFIG_JSON` for both the `consul-ecs-health-sync`
+and `consul-ecs-mesh-init` containers.
 
 <CodeBlockConfig highlight="23-40">
 

From 5ccc1fdcca835945886f5ee02ba5ece73294b1d1 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Tue, 25 Jan 2022 12:24:37 -0600
Subject: [PATCH 74/98] docs: Refine ECS installation docs

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---
 website/content/docs/ecs/install.mdx          | 95 ++++++++++++++++---
 .../content/docs/ecs/manual-installation.mdx  | 27 +++---
 2 files changed, 98 insertions(+), 24 deletions(-)

diff --git a/website/content/docs/ecs/install.mdx b/website/content/docs/ecs/install.mdx
index dc35b53efe..ce51332b59 100644
--- a/website/content/docs/ecs/install.mdx
+++ b/website/content/docs/ecs/install.mdx
@@ -11,6 +11,17 @@ This topic describes how to use the [`mesh-task`](https://registry.terraform.io/
 
 This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples.
 
+## Overview
+
+This topic describes the following procedure:
+
+1. Create Terraform configuration files for the necessary components:
+
+    * [ECS task definition](#using-the-mesh-task-module): Use the `mesh-task` module to create an ECS task definition for Consul on ECS
+    * [ECS service](#ecs-service): Use the `aws_ecs_service` resource to create an ECS service that schedules service mesh tasks to run on ECS
+
+2. [Run Terraform](#running-terraform) to deploy the resources in AWS
+
 ## Prerequisites
 
 * You should have some familiarity with using Terraform. Refer to the [Terraform documentation](https://www.terraform.io/docs) to learn about infrastructure as code and how to get started with Terraform.
@@ -23,7 +34,9 @@ and additional sidecar containers, such as the Consul agent container and the En
 
 The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers.
 
-The following example shows a Terraform configuration file that creates a task definition with an application container called `example-client-app`.
+The following example shows a Terraform configuration file that creates a task definition with an application container called `example-client-app` in a file called `mesh-task.tf`:
+
+<CodeBlockConfig filename="mesh-task.tf">
 
 ```hcl
 module "my_task" {
@@ -54,26 +67,84 @@ module "my_task" {
 }
 ```
 
-All possible inputs are documented in the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs),
-however there are some important inputs worth highlighting:
+</CodeBlockConfig>
+
+The following fields are required. Refer to the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for a complete reference.
 
 | Input Variable          | Type     | Description                                                                                                                                                                                                                                    |
 | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `source` and `version`  | string   | This specifies the source location and version of the `mesh-task` module.                                                                                                                                                                      |
+| `source`                | string   | Must be set to the source location of the `mesh-task` module, `hashicorp/consul-ecs/aws//modules/mesh-task`.                                                                                                                                   |
+| `version`               | string   | Must be set to the version of the `mesh-task` module.                                                                                                                                                                                          |
 | `family`                | string   | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default.                                           |
 | `container_definitions` | list     | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. |
 | `port`                  | integer  | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`.                                                                                                                  |
 | `retry_join`            | list     | The is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers.                                                                                                  |
 
+### Running Terraform
+
+You will need to run Terraform to create the task definition.
+
+Save the Terraform configuration for the task definition to a file, such as `mesh-task.tf`.
+You should place this file in a directory alongside other Terraform configuration files for your project.
+
+The `mesh-task` module requires the AWS Terraform provider. The following example shows how to include
+and configure the AWS provider in a file called `provider.tf`. Refer to the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
+documentation for complete configuration details.
+
+<CodeBlockConfig filename="provider.tf">
+
+```hcl
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "<latest version>"
+    }
+  }
+}
+
+provider "aws" {
+  region = "<AWS region>"
+  ...
+}
+```
+
+</CodeBlockConfig>
+
+Additional AWS resources for your project can be included in additional Terraform configuration files
+in the same directory. The following example shows a basic project directory:
+
+```shell-session
+$ ls
+mesh-task.tf
+provider.tf
+...
+```
+
+Terraform should be run in your project directory as follows.
+
+* Run `terraform init` first to download dependencies, such as Terraform providers
+* Run `terraform apply` to have Terraform create AWS resources, such as the task definition from the `mesh-task` module.
+
+Terraform automatically reads all files in the current directory that have a `.tf` file extension.
+Refer to the [Terraform documentation](https://www.terraform.io/docs) for more information and Terraform best practices.
+
 ## ECS Service
 
 [ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common
-ways to start tasks using a task definition..
+ways to start tasks using a task definition.
+
+To define an ECS service, reference the `mesh-task` module's `task_definition_arn` output value
+in your `aws_ecs_service` resource. The following example shows how to include the service in the `mesh-task.tf` file.
 
-To define an ECS Service, reference the mesh-task module's `task_definition_arn` output value
-in your `aws_ecs_service` resource:
+<CodeBlockConfig filename="mesh-task.tf" highlight="6-12">
 
 ```hcl
+module "my_task" {
+  source  = "hashicorp/consul-ecs/aws//modules/mesh-task"
+  ...
+}
+
 resource "aws_ecs_service" "my_task" {
   name            = "my_task_service"
   task_definition = module.my_task.task_definition_arn
@@ -83,6 +154,8 @@ resource "aws_ecs_service" "my_task" {
 }
 ```
 
+</CodeBlockConfig>
+
 This is a partial configuration to highlight some important fields.
 See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) documentation for a complete reference.
 
@@ -93,10 +166,10 @@ See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aw
 | `launch_type`     | string  | The launch type. Consul on ECS supports the `FARGATE` and `EC2` launch types.                                       |
 | `propagate_tags`  | string  | This must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. |
 
-After defining the Terraform configuration for both the `mesh-task` and ECS service,
-run `terraform apply` to create the ECS task definition and service resources. The ECS
-service will soon start your application in a task. The task will automatically
-register itself into the Consul service catalog.
+After including the ECS service in your Terraform configuration, run `terraform apply`
+from your project directory to create the ECS service resource. The ECS service will
+soon start your application in a task. The task will automatically register itself
+into the Consul service catalog during startup.
 
 -> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true`
 in their [`network_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#network_configuration) block so that ECS can pull the Docker images.
diff --git a/website/content/docs/ecs/manual-installation.mdx b/website/content/docs/ecs/manual-installation.mdx
index 56ca858271..31e57eac3f 100644
--- a/website/content/docs/ecs/manual-installation.mdx
+++ b/website/content/docs/ecs/manual-installation.mdx
@@ -52,10 +52,10 @@ during task startup.
 
 | Field name             | Type   | Description                                                                                                        |
 | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
-| `family`               | string | The task family name. This is used as the Consul service name by default.                                         |
+| `family`               | string | The task family name. This is used as the Consul service name by default.                                          |
 | `networkMode`          | string | Must be `awsvpc`, which is the only network mode supported by Consul on ECS.                                       |
-| `volumes`              | list   | Must be defined as shown above. Volumes are used to share configuration between containers for intial task setup. |
-| `containerDefinitions` | list   | The list of containers to run in this task (see below).                                                            |
+| `volumes`              | list   | Must be defined as shown above. Volumes are used to share configuration between containers for intial task setup.  |
+| `containerDefinitions` | list   | The list of containers to run in this task (see [Application container](#application-container)).                  |
 
 ## Application container
 
@@ -218,16 +218,17 @@ Each task must include a Consul client container in order for the task to join y
 
 </CodeBlockConfig>
 
-| Field name    | Type    | Description                                                                                                         |
-| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
-| `name`        | string  | The container name, which should always be `consul-client`.                                                         |
-| `image`       | string  | The Consul image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits.             |
-| `mountPoints` | list    | Must be set as shown above. Volumes are mounted to share information with other containers for task setup.          |
-| `entrypoint`  | list    | Must be set to a plain shell so that the startup `command` works properly.                                          |
-| `command`     | list    | The startup command. See below for details.                                                                         |
+| Field name    | Type    | Description                                                                                                                       |
+| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string  | The container name, which should always be `consul-client`.                                                                       |
+| `image`       | string  | The Consul image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits.                           |
+| `mountPoints` | list    | Must be set as shown above. Volumes are mounted to share information with other containers for task setup.                        |
+| `entrypoint`  | list    | Must be set to a plain shell so that the startup `command` works properly.                                                        |
+| `command`     | list    | Specifies the contents of the [startup script](#consul-client-startup-script). Copy the script and format it into a JSON string.  |
+
+### Consul client startup script
 
-The following is the recommended `command` script for the Consul agent.
-This is the same as the above `command` field, but is unescaped and has comments added.
+The following script is used to start the Consul client for Consul on ECS.
 
 ```shell
 # Copy the consul binary to a shared volume for `consul-ecs-mesh-init` to use to generate Envoy configuration.
@@ -271,7 +272,7 @@ The following table describes the values that you should use to configure the `c
 | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
 | `addresses.*`        | strings | Set the DNS, GRPC, and HTTP addresses to `127.0.0.1` to ensure these are not accessible outside of the task. |
 | `advertise_addr`     | string  | Must be set to the task IP address so that other Consul agents know how to reach this agent.                 |
-| `client_addr`        | string  | Must be set to an interface reacable by other Consul agents.                                                 |
+| `client_addr`        | string  | Must be set to an interface reachable by other Consul agents.                                                |
 | `datacenter`         | string  | Must be set to the Consul datacenter this task will join.                                                    |
 | `leave_on_terminate` | boolean | Must be set to `true` so that the Consul agent leaves the cluster gracefully before exiting.                 |
 | `retry_join`         | string  | Must be set to your Consul server location(s) so this agent can join the Consul cluster.                     |

From 08c046b3b0050be90e8f2555d47b1876971c4e4a Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Mon, 24 Jan 2022 17:43:20 -0600
Subject: [PATCH 75/98] docs: Manual secure configuration for ECS

---
 website/content/docs/ecs/index.mdx            |   6 +-
 .../docs/ecs/manual/acl-controller.mdx        | 213 +++++++++++++++++
 .../install.mdx}                              |  37 ++-
 .../docs/ecs/manual/secure-configuration.mdx  | 215 ++++++++++++++++++
 website/content/docs/ecs/requirements.mdx     |   4 +-
 .../docs/ecs/{ => terraform}/install.mdx      |   2 +-
 .../migrate-existing-tasks.mdx                |   4 +-
 .../secure-configuration.mdx}                 |  10 +-
 website/data/docs-nav-data.json               |  42 +++-
 9 files changed, 501 insertions(+), 32 deletions(-)
 create mode 100644 website/content/docs/ecs/manual/acl-controller.mdx
 rename website/content/docs/ecs/{manual-installation.mdx => manual/install.mdx} (92%)
 create mode 100644 website/content/docs/ecs/manual/secure-configuration.mdx
 rename website/content/docs/ecs/{ => terraform}/install.mdx (99%)
 rename website/content/docs/ecs/{ => terraform}/migrate-existing-tasks.mdx (96%)
 rename website/content/docs/ecs/{production-installation.mdx => terraform/secure-configuration.mdx} (92%)

diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx
index 1078d65c76..cf9e638160 100644
--- a/website/content/docs/ecs/index.mdx
+++ b/website/content/docs/ecs/index.mdx
@@ -9,7 +9,8 @@ description: >-
 # AWS ECS
 
 Consul service mesh applications can be deployed on [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS)
-using our official Terraform modules.
+using either our official [Terraform modules](/docs/ecs/terraform/install) or without Terraform by [manually configuring
+the task definition](/docs/ecs/manual/install).
 
 ## Service Mesh
 
@@ -37,4 +38,5 @@ There are several ways to get started with Consul with ECS.
 * The [Consul with Dev Server on Fargate](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate) example installation deploys a sample application in ECS using the Fargate launch type.
 * The [Consul with Dev Server on EC2](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2) example installation deploys a sample application in ECS using the EC2 launch type.
 
-See the [Requirements](/docs/ecs/requirements) and the full [Install Guide](/docs/ecs/install) when you're ready to install Consul on an existing ECS cluster and add existing tasks to the service mesh.
+See the [Requirements](/docs/ecs/requirements) and then choose whether to [install with Terraform](/docs/ecs/terraform/install) or [install without Terraform](/docs/ecs/manual/install)
+when you're ready to install Consul on an existing ECS cluster and add tasks to the service mesh.
diff --git a/website/content/docs/ecs/manual/acl-controller.mdx b/website/content/docs/ecs/manual/acl-controller.mdx
new file mode 100644
index 0000000000..7264ea4f2d
--- /dev/null
+++ b/website/content/docs/ecs/manual/acl-controller.mdx
@@ -0,0 +1,213 @@
+---
+layout: docs
+page_title: ACL Controller - AWS ECS
+description: >-
+  Manual Deployment of the ACL Controller for Consul Service Mesh on AWS ECS (Elastic Container Service).
+---
+
+# Install the ACL Controller
+
+This topic describes how to manually deploy the ACL controller to [automatically provision ACL tokens](/docs/ecs/architecture#automatic-acl-token-provisioning) for Consul on ECS.
+If you are using Terraform, refer to the [Terraform Secure Configuration](/docs/ecs/terraform/secure-configuration) page to deploy the ACL controller.
+
+## Prerequisites
+
+* Your application tasks must include certain tags to be compatible with the ACL controller.
+Refer to the [Task Tags](/docs/ecs/manual/install#task-tags) section of the installation page.
+* You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following [Learn Guides](https://learn.hashicorp.com/collections/consul/security) for an introduction and the [ACL system](/docs/security/acl) documentation for more information.
+
+## Setup AWS Secrets Manager
+
+The ACL controller supports managing secrets in AWS Secrets Manager.
+
+Before deploying the ACL controller for the first time, you must [create the following secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) from Consul in AWS Secrets Manager.
+
+| Secret                  | Initial Value  | Sample Secret Name             |
+| ---------------------   | -------------- | ------------------------------ |
+| Consul server CA cert   | Set            | `my-consul-ca-cert`            |
+| Bootstrap ACL Token     | Set            | `my-consul-bootstrap-token`    |
+| Consul Client ACL Token | Empty          | `<PREFIX>-consul-client-token` |
+
+The secret for the client token must be intially empty. The ACL controller creates the client token in Consul
+and stores the token in Secrets Manager. In the secret name, `<PREFIX>` should be replaced with the
+[secret name prefix](/docs/ecs/manual/acl-controller#secret-name-prefix) of your choice.
+
+### Secret Name Prefix
+
+The ACL controller requires that the secrets it reads and writes are named with a unique prefix. The name prefix is used
+in the [Task Role Policy](/docs/ecs/manual/acl-controller#task-role-policy) to limit the ACL controller's access within
+AWS Secrets Manager to only those secrets strictly needed by the ACL controller.
+
+The name prefix should be unique among secrets your AWS account. We recommend a short (8 character) random
+string for the prefix.
+
+-> **NOTE:** If you are using the ACL controller with multiple ECS clusters, each cluster requires
+its own instance of the ACL controller, and each instance of the ACL controller should have a unique
+name prefix.
+
+## Task Definition
+
+You must create a task definition to deploy the ACL controller in your ECS cluster.
+The ACL controller must run in the same ECS cluster hosting your service mesh application
+tasks.
+
+The following example shows how the task definition should be configured for the ACL controller.
+
+```json
+{
+  "family": "my-consul-acl-controller".
+  "networkMode": "awsvpc",
+  "containerDefinitions": [
+    {
+      "name": "acl-controller",
+      "image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
+      "essential": true,
+      "command": [
+        "acl-controller",
+        "-consul-client-secret-arn", "arn:aws:secretsmanager:us-west-2:000000000000:secret:<PREFIX>-consul-client-token",
+        "-secret-name-prefix", "<PREFIX>",
+      ],
+      "secrets": [
+        {
+          "name": "CONSUL_HTTP_TOKEN",
+          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token"
+        },
+        {
+          "name": "CONSUL_CACERT_PEM",
+          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
+        }
+      ],
+      "environment": [
+        {
+          "name": "CONSUL_HTTP_ADDR",
+          "value": "<Consul server HTTP API address>"
+        }
+      ]
+    }
+  ]
+}
+```
+
+You must include the following top-level fields.
+
+| Field name    | Type    | Description                                                                  |
+| -----------   | ------- | ---------------------------------------------------------------------------- |
+| `family`      | string  | The task family name of your choice.                                         |
+| `networkMode` | string  | Must be `awsvpc`, which is the only network mode supported by Consul on ECS. |
+
+In the `containerDefinitions` list, include one container with the following fields.
+
+| Field name    | Type    | Description                                                                                                                      |
+| -----------   | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string  | The container name, which should be `acl-controller`                                                                             |
+| `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.                |
+| `command`     | list    | Must be set as shown. The startup command for the ACL controller.                                                                |
+| `essential`   | boolean | Must be `true` to ensure the container health ties into the health of the task.                                                  |
+| `secrets`     | list    | Must have `CONSUL_HTTP_TOKEN` set to the ACL bootstrap token and `CONSUL_CACERT_PEM` set to the Consul server CA certificate.    |
+| `environment` | string  | Must set the `CONSUL_HTTP_ADDR` environment variable to the address of the HTTP API of your Consul servers.                      |
+
+The following CLI options are required in the `command` field of the container definition.
+
+| Flag                        | Type    | Description                                                                                                          |
+| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `-consul-client-secret-arn` | string  | The secret where the ACL controller will store the Consul client token.                                              |
+| `-secret-name-prefix`       | string  | The [secret name prefix](/docs/ecs/manual/acl-controller#secret-name-prefix) that you chose for this ACL controller. |
+
+## ECS Service
+
+Once the task definition is created, define an ECS service in order to start an ACL controller task.
+
+The following example contains the recommended settings for the ACL controller. Refer to
+the [ECS service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service_definition_parameters.html) documentation
+to complete the remaining details for your use case.
+
+```json
+{
+   "cluster": "<Your ECS cluster ARN>"
+   "desiredCount": 1,
+   "launchType": "FARGATE",
+   "serviceName": "my-acl-controller",
+   "taskDefinition": "<task definition ARN>",
+   ...
+}
+```
+
+| Field name       | Type    | Description                                                                                                      |
+| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| `cluster`        | string  | Set to your ECS cluster name or ARN. This must be the same ECS cluster where your service mesh applications run. |
+| `desiredCount`   | integer | Must be 1. Only one instance of the ACL controller should run per ECS cluster.                                   |
+| `launchType`     | string  | Consul on ECS supports both the `FARGATE` and `EC2` launch types.                                                |
+| `serviceName`    | string  | The service name of your choice.                                                                                 |
+| `taskDefinition` | string  | Must be set to the ACL controller [task definition](/docs/ecs/manual/acl-controller#task-definition).            |
+
+## AWS IAM Roles
+
+The ECS task and execution roles must be configured to allow the ACL controller access
+to the ECS API and Secrets Manager API.
+
+### Task Role Policy
+
+The following example shows the policy needed for the ECS task role for the ACL controller.
+This grants the ACL controller permission to list tasks, describe tasks, and read and update
+secrets.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ecs:ListTasks",
+        "ecs:DescribeTasks"
+      ],
+      "Resource": ["*"]
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "secretsmanager:GetSecretValue",
+        "secretsmanager:UpdateSecret"
+      ],
+      "Resource": [
+        "arn:aws:secretsmanager:us-west-2:000000000000:secret:<PREFIX>-*"
+      ]
+    }
+  ]
+}
+```
+
+The following are the required permissions. You will need to substitute `<PREFIX>` with your chosen [name prefix](/docs/ecs/manual/acl-controller#secret-name-prefix).
+
+| Action                          | Resource                                                          | Description                                                                        |
+| ------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `ecs:ListTasks`                 | `*`                                                               | Allow the ACL controller to watch for new tasks.                                   |
+| `ecs:DescribeTasks`             | `*`                                                               | Allow the ACL controller to retrieve details for new tasks.                        |
+| `secretsmanager:GetSecretValue` | `arn:aws:secretsmanager:us-west-2:000000000000:secret:<PREFIX>-*` | Allow the ACL controller to read secrets with a name prefix.                       |
+| `secretsmanager:UpdateSecret`   | `arn:aws:secretsmanager:us-west-2:000000000000:secret:<PREFIX>-*` | Allow the ACL controller to store Consul ACL tokens in secrets with a name prefix. |
+
+### Execution Role Policy
+
+The following IAM policy document allows ECS to retrieve secrets needed
+to start the ACL controller task from AWS Secrets Manager, including the ACL
+bootstrap token.
+
+The following example shows the policy needed for the execution role.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "secretsmanager:GetSecretValue"
+      ],
+      "Resource": [
+        "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token",
+        "arn:aws:secretsmanager:us-west-2:000000000000:secret:<PREFIX>-consul-client-token"
+      ]
+    }
+  ]
+}
+```
diff --git a/website/content/docs/ecs/manual-installation.mdx b/website/content/docs/ecs/manual/install.mdx
similarity index 92%
rename from website/content/docs/ecs/manual-installation.mdx
rename to website/content/docs/ecs/manual/install.mdx
index 31e57eac3f..87b98ed86f 100644
--- a/website/content/docs/ecs/manual-installation.mdx
+++ b/website/content/docs/ecs/manual/install.mdx
@@ -7,7 +7,7 @@ description: >-
 
 # Manual Installation
 
-The following instructions describe how to manually create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) without Terraform. Refer to the [Consul ECS Terraform module](/docs/ecs/install) documentation for an alternative method for installing Consul on ECS.
+The following instructions describe how to manually create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) without Terraform. Refer to the [Consul ECS Terraform module](/docs/ecs/terraform/install) documentation for an alternative method for installing Consul on ECS.
 
 This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples.
 
@@ -47,6 +47,16 @@ during task startup.
     }
   ],
   "containerDefinitions": [...]
+  "tags": [
+    {
+      "key": "consul.hashicorp.com/mesh",
+      "value": "true"
+    },
+    {
+      "key": "consul.hashicorp.com/service-name",
+      "value":  "example-client-app"
+    }
+  ]
 }
 ```
 
@@ -57,6 +67,16 @@ during task startup.
 | `volumes`              | list   | Must be defined as shown above. Volumes are used to share configuration between containers for intial task setup.  |
 | `containerDefinitions` | list   | The list of containers to run in this task (see [Application container](#application-container)).                  |
 
+### Task Tags
+
+The `tags` list must include the following if you are using the ACL controller in a [secure configuration](/docs/manual/secure-configuration).
+Without these tags, the ACL controller will be unable to provision a service token for the task.
+
+| Tag Key                             | Tag Value           | Description                                                                                                                |
+| ----------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `consul.hashicorp.com/mesh`         | `true` (string)     | The ACL controller ignores tasks without this tag set to `true`.                                                           |
+| `consul.hashicorp.com/service-name` | Consul service name | Specifies the Consul service associated with this task. Required if the service name is different than the task `family`.  |
+
 ## Application container
 
 First, include your application container in the `containerDefinitions` list
@@ -339,13 +359,13 @@ configuration to a shared volume.
 
 </CodeBlockConfig>
 
-| Field name    | Type    | Description                                                                                                         |
-| -----------   | ------- | ------------------------------------------------------------------------------------------------------------------- |
-| `name`        | string  | The container name should be `consul-ecs-mesh-init`.                                                                |
-| `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.   |
-| `mountPoints` | list    | Must be set as show above, so the `consul` and `consul-ecs` binaries can be shared among containers for task setup. |
-| `command`     | list    | Set the `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command.                              |
-| `environment` | list    | This must include the [`CONSUL_ECS_CONFIG_JSON`](/docs/ecs/manual-installation#consul_ecs_config_json) variable. See below for details.    |
+| Field name    | Type    | Description                                                                                                                             |
+| -----------   | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string  | The container name should be `consul-ecs-mesh-init`.                                                                                    |
+| `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.                       |
+| `mountPoints` | list    | Must be set as show above, so the `consul` and `consul-ecs` binaries can be shared among containers for task setup.                     |
+| `command`     | list    | Set to `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command.                                                   |
+| `environment` | list    | This must include the [`CONSUL_ECS_CONFIG_JSON`](/docs/ecs/manual-installation#consul_ecs_config_json) variable. See below for details. |
 
 ### `CONSUL_ECS_CONFIG_JSON`
 
@@ -529,3 +549,4 @@ and `consul-ecs-mesh-init` containers.
 
 * Create the task definition using the [AWS Console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskdefinition.html) or the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html), or another method of your choice.
 * Create an [ECS Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) to start tasks using the task definition.
+* Follow the [Secure Configration](/docs/ecs/manual/secure-configuration) to get production-ready.
diff --git a/website/content/docs/ecs/manual/secure-configuration.mdx b/website/content/docs/ecs/manual/secure-configuration.mdx
new file mode 100644
index 0000000000..57b12467c1
--- /dev/null
+++ b/website/content/docs/ecs/manual/secure-configuration.mdx
@@ -0,0 +1,215 @@
+---
+layout: docs
+page_title: Secure Configuration - AWS ECS
+description: >-
+  Manual Secure Confguration of the Consul Service Mesh on AWS ECS (Elastic Container Service).
+---
+
+# Secure Configuration
+
+For a production-ready installation of Consul on ECS, you will need to make sure that the cluster is secured.
+A secure Consul cluster should include the following:
+
+1. [TLS Encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers.
+1. [Gossip Encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic.
+1. [Access Control (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh.
+
+-> **NOTE:** This page assumes that you have already configured your Consul server with the above features.
+
+## Prerequisites
+
+* You should already have followed the [installation instructions](/docs/ecs/manual/install) to understand how to define
+the necessary components of the task definition for Consul on ECS.
+* You should be familiar with [specifying sensitive data](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) on ECS.
+* You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following [Learn Guides](https://learn.hashicorp.com/collections/consul/security) for an introduction and the [ACL system](/docs/security/acl) documentation for more information.
+
+## ACL Tokens
+
+You must create two types of ACL tokens for Consul on ECS:
+
+* **Client tokens:** used by the `consul-client` containers to join the Consul cluster
+* **Service tokens:** used by sidecar containers for service registration and health syncing
+
+The following sections describe the ACL polices which must be associated with these token types.
+
+-> **NOTE:** This section describes how operators would create ACL tokens by hand. To ease operator
+burden, the ACL Controller can automatically create ACL tokens for Consul on ECS. Refer to the
+[ACL Controller](/docs/manual/acl-controller) page for installation details.
+
+### Create Consul client token
+
+You must create a token for the Consul client. This is a shared token used by the `consul-client`
+containers to join the Consul cluster.
+
+The following is the ACL policy needed for the Consul client token:
+
+```hcl
+node_prefix "" {
+  policy = "write"
+}
+service_prefix "" {
+  policy = "read"
+}
+```
+
+This policy allows `node:write` for any node name, which is necessary because the Consul node
+names on ECS are not known until runtime.
+
+### Create service tokens
+
+Service tokens should be associated with a [service identity](https://www.consul.io/docs/security/acl/acl-system#acl-service-identities).
+The service identity includes `service:write` permissions for the service and sidecar proxy.
+
+The following example shows how to use the Consul CLI to create a service token for a service named `example-client-app`:
+
+```shell
+consul acl token create -service-identity=example-client-app ...
+```
+
+-> **NOTE**: You will need to create one service token for each registered Consul service in ECS,
+including when new services are added to the service mesh.
+
+## Secret storage
+
+You should securely store the following secrets in order to make them available to ECS tasks.
+
+1. Consul Server CA certificate
+2. Consul gossip encryption key
+3. Consul client ACL token
+4. Consul service ACL tokens (one per service)
+
+These secrets can be securely stored and passed to ECS tasks using either of the following AWS secret services:
+
+* [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-parameters.html)
+* [AWS Secrets Manager](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-secrets.html)
+
+Once the secrets are stored they can be referenced using their ARN. The following shows
+example secret ARNs when using AWS Secrets Manager:
+
+| Secret                 | Sample Secret ARN                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------------- |
+| Consul Server CA Cert  | `arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert`           |
+| Gossip encryption key  | `arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-gossip-key`        |
+| Client token           | `arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-client-token`      |
+| Service token          | `arn:aws:secretsmanager:us-west-2:000000000000:secret:my-example-client-app-token` |
+
+## Configure `consul-client`
+
+The following secrets must be passed to the `consul-client` container:
+
+* Consul server CA certificate
+* Gossip encryption key
+* Consul client ACL token
+
+The following example shows how to include these secrets in the task definition. The `secrets`
+list specifies environment variable `name`s that will be set to the secret values for this container.
+ECS automatically fetches the secret values specified in the `valueFrom` fields during task provisioning.
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "consul-client"
+      "image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
+      "secrets": [
+        {
+          "name": "CONSUL_CACERT",
+          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
+        },
+        {
+          "name": "CONSUL_GOSSIP_ENCRYPTION_KEY",
+          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-gossip-key"
+        },
+        {
+          "name": "AGENT_TOKEN",
+          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-client-token"
+        }
+      ]
+    },
+    ...
+  ]
+}
+```
+
+Next, update Consul configuration options to pass the secrets to the Consul client.
+
+The following is an example of the *additional* content to include in the `consul-client` startup script. Refer to the [install
+page](/docs/ecs/manual/install#consul-client-container) for the remainder of the startup script and how to pass this
+script to the container.
+
+<CodeBlockConfig highlight="3-4,10-29">
+
+```shell
+...
+
+# Write the CA Cert to a file
+echo "$CONSUL_CACERT" > /tmp/consul-ca-cert.pem
+
+# Write the Consul agent configuration file.
+cat << EOF > /consul/agent-defaults.hcl
+...
+
+# Configure gossip encryption key
+encrypt = "$CONSUL_GOSSIP_ENCRYPTION_KEY"
+
+# Configure TLS settings
+auto_encrypt = {
+  tls = true
+  ip_san = ["$ECS_IPV4"]
+}
+ca_file = "/tmp/consul-ca-cert.pem"
+verify_outgoing = true
+
+# Configure ACLs
+acl {
+  enabled = true
+  default_policy = "deny"
+  down_policy = "async-cache"
+  tokens {
+    agent = "$AGENT_TOKEN"
+  }
+}
+
+EOF
+```
+
+</CodeBlockConfig>
+
+The following are the additional fields that must be included in the Consul client configuration file.
+
+| Field name                                                 | Type    | Description                                                                          |
+| ---------------------------------------------------------  | ------- | ------------------------------------------------------------------------------------ |
+| [`encrypt`](/docs/agent/options#_encrypt)                  | string  | Specifies the gossip encryption key                                                  |
+| [`ca_file`](/docs/agent/options#ca_file)                   | string  | Specifies the Consul server CA cert for TLS verification.                            |
+| [`acl.enabled`](/docs/agent/options#acl_enabled)           | boolen  | Enable ACLs for this agent.                                                          |
+| [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) | string  | Specifies the Consul client token which authorizes this agent with Consul servers.   |
+
+## Configure `consul-ecs-mesh-init` and `consul-ecs-health-sync`
+
+Both `consul-ecs-mesh-init` and `consul-ecs-health-sync` containers need to be configured with
+the service ACL token. This allows these containers to make HTTP API requests to the local
+Consul client for service registration and health syncing.
+
+The following shows how to set the `CONSUL_HTTP_TOKEN` variable to the service token for the `example-client-app` service,
+if the token is stored in AWS Secrets Manager.
+
+<CodeBlockConfig highlight="5-8">
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "secrets": [
+        {
+          "name": "CONSUL_HTTP_TOKEN",
+          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-example-client-app-token"
+        }
+      ]
+    },
+    ...
+  ],
+  ...
+}
+```
+
+</CodeBlockConfig>
diff --git a/website/content/docs/ecs/requirements.mdx b/website/content/docs/ecs/requirements.mdx
index faedb2f2a3..972b545a56 100644
--- a/website/content/docs/ecs/requirements.mdx
+++ b/website/content/docs/ecs/requirements.mdx
@@ -15,9 +15,9 @@ The following requirements must be met in order to install Consul on ECS:
 1. **ACL Controller:** If you are running a secure Consul installation with ACLs enabled, configure the ACL controller.
 1. **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a
    Consul agent container and a sidecar proxy container. These additional sidecar containers must
-   be included in the ECS task definition. The [Consul ECS Terraform module](/docs/ecs/install)
+   be included in the ECS task definition. The [Consul ECS Terraform module](/docs/ecs/terraform/install)
    will include these sidecar containers for you. If you do not use Terraform, you can construct
-   the task definition yourself by following [our documentation](/docs/ecs/manual-installation).
+   the task definition yourself by following [our documentation](/docs/ecs/manual/install).
 1. **Routing:** With your application running in tasks as part of the mesh, you must specify the
    upstream services that your application calls. You will also need to change the URLs your
    application uses to ensure the application is making requests through the service mesh.
diff --git a/website/content/docs/ecs/install.mdx b/website/content/docs/ecs/terraform/install.mdx
similarity index 99%
rename from website/content/docs/ecs/install.mdx
rename to website/content/docs/ecs/terraform/install.mdx
index ce51332b59..6d98026667 100644
--- a/website/content/docs/ecs/install.mdx
+++ b/website/content/docs/ecs/terraform/install.mdx
@@ -268,7 +268,7 @@ python manage.py runserver "127.0.0.1:8080"
 
 ## Next Steps
 
-- Configure a secure [Production Installation](/docs/ecs/production-installation).
+- Follow the [Secure Configuration](/docs/ecs/secure-configuration) to get production-ready.
 - Now that your applications are running in the service mesh, read about
   other [Service Mesh features](/docs/connect).
 - View the [Architecture](/docs/ecs/architecture) documentation to understand
diff --git a/website/content/docs/ecs/migrate-existing-tasks.mdx b/website/content/docs/ecs/terraform/migrate-existing-tasks.mdx
similarity index 96%
rename from website/content/docs/ecs/migrate-existing-tasks.mdx
rename to website/content/docs/ecs/terraform/migrate-existing-tasks.mdx
index 0d6a069233..7281a7a11b 100644
--- a/website/content/docs/ecs/migrate-existing-tasks.mdx
+++ b/website/content/docs/ecs/terraform/migrate-existing-tasks.mdx
@@ -90,7 +90,7 @@ module "my_task" {
     }
   ]
 
-  port       = "9090"
+  port       = 9090
   retry_join = ["<address of the Consul server>"]
 }
 ```
@@ -111,5 +111,5 @@ resource.
 
 Now that your task(s) are migrated to the `mesh-task` module,
 
-- Start at the [ECS Service section](/docs/ecs/install#ecs-service) of the Installation Guide to continue installing Consul on ECS.
+- Start at the [ECS Service section](/docs/ecs/terraform/install#ecs-service) of the Installation Guide to continue installing Consul on ECS.
 - Refer to the [`mesh-task` reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for all available inputs to your mesh tasks.
diff --git a/website/content/docs/ecs/production-installation.mdx b/website/content/docs/ecs/terraform/secure-configuration.mdx
similarity index 92%
rename from website/content/docs/ecs/production-installation.mdx
rename to website/content/docs/ecs/terraform/secure-configuration.mdx
index 9c8c6c6e6c..0d6e9ef483 100644
--- a/website/content/docs/ecs/production-installation.mdx
+++ b/website/content/docs/ecs/terraform/secure-configuration.mdx
@@ -1,11 +1,11 @@
 ---
 layout: docs
-page_title: Production Installation - AWS ECS
+page_title: Secure Configuration - AWS ECS
 description: >-
-  Production Installation of the Consul Service Mesh on AWS ECS (Elastic Container Service).
+  Secure Configuration of the Consul Service Mesh on AWS ECS (Elastic Container Service) with Terraform.
 ---
 
-# Production Installation
+# Secure Configuration
 
 For a production-ready installation of Consul on ECS, you will need to make sure that the cluster is secured.
 A secure Consul cluster should include the following:
@@ -68,7 +68,7 @@ deploying this controller.
 ## Deploy Services
 
 Once the ACL controller is up and running, you will be able to deploy services on the mesh using the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
-Start with the basic configuration for the [Task Module](/docs/ecs/install#task-module) and specify additional settings to make the configuration production-ready.
+Start with the basic configuration for the [Task Module](/docs/ecs/terraform/install#task-module) and specify additional settings to make the configuration production-ready.
 
 First, you will need to create an AWS Secrets Manager secret for the gossip encryption key that the Consul clients
 should use.
@@ -104,5 +104,5 @@ module "my_task" {
 }
 ```
 
-Now you can deploy your services! Follow the rest of the steps in the [Installation instructions](/docs/ecs/install#task-module)
+Now you can deploy your services! Follow the rest of the steps in the [Installation instructions](/docs/ecs/terraform/install#task-module)
 to deploy and connect your services.
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 3e1566d563..e55bf32d1a 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -612,16 +612,38 @@
         "path": "ecs/requirements"
       },
       {
-        "title": "Installation with Terraform",
-        "path": "ecs/install"
-      },
-      {
-        "title": "Production Installation",
-        "path": "ecs/production-installation"
+        "title": "Install with Terraform",
+        "routes": [
+          {
+            "title": "Installation",
+            "path": "ecs/terraform/install"
+          },
+          {
+            "title": "Secure Configuration",
+            "path": "ecs/terraform/secure-configuration"
+          },
+          {
+            "title": "Migrate Existing Tasks",
+            "path": "ecs/terraform/migrate-existing-tasks"
+          }
+        ]
       },
       {
-        "title": "Migrate Existing Tasks",
-        "path": "ecs/migrate-existing-tasks"
+        "title": "Install Manually",
+        "routes": [
+          {
+            "title": "Installation",
+            "path": "ecs/manual/install"
+          },
+          {
+            "title": "Secure Configuration",
+            "path": "ecs/manual/secure-configuration"
+          },
+          {
+            "title": "ACL Controller",
+            "path": "ecs/manual/acl-controller"
+          }
+        ]
       },
       {
         "title": "Architecture",
@@ -630,10 +652,6 @@
       {
         "title": "Consul Enterprise",
         "path": "ecs/enterprise"
-      },
-      {
-        "title": "Manual Installation",
-        "path": "ecs/manual-installation"
       }
     ]
   },

From 8c8292a9d168618e4fca30e3fbc4e071ef2aaa20 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Wed, 26 Jan 2022 17:12:34 -0600
Subject: [PATCH 76/98] docs: Fixes to ECS manual secure configuration

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---
 website/content/docs/ecs/index.mdx                 |  5 +++--
 website/content/docs/ecs/manual/acl-controller.mdx | 10 +++++-----
 website/content/docs/ecs/manual/install.mdx        | 14 +++++++-------
 .../docs/ecs/manual/secure-configuration.mdx       |  4 ++--
 website/content/docs/ecs/terraform/install.mdx     |  1 +
 5 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx
index cf9e638160..b62f2175de 100644
--- a/website/content/docs/ecs/index.mdx
+++ b/website/content/docs/ecs/index.mdx
@@ -38,5 +38,6 @@ There are several ways to get started with Consul with ECS.
 * The [Consul with Dev Server on Fargate](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate) example installation deploys a sample application in ECS using the Fargate launch type.
 * The [Consul with Dev Server on EC2](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2) example installation deploys a sample application in ECS using the EC2 launch type.
 
-See the [Requirements](/docs/ecs/requirements) and then choose whether to [install with Terraform](/docs/ecs/terraform/install) or [install without Terraform](/docs/ecs/manual/install)
-when you're ready to install Consul on an existing ECS cluster and add tasks to the service mesh.
+Refer to the [Requirements](/docs/ecs/requirements) and use one of the following sets of instructions when you're ready to install Consul on an existing ECS cluster and add tasks to the service mesh: 
+* [Install with Terraform](/docs/ecs/terraform/install) 
+* [Install Manually](/docs/ecs/manual/install)
diff --git a/website/content/docs/ecs/manual/acl-controller.mdx b/website/content/docs/ecs/manual/acl-controller.mdx
index 7264ea4f2d..eeb52b20f0 100644
--- a/website/content/docs/ecs/manual/acl-controller.mdx
+++ b/website/content/docs/ecs/manual/acl-controller.mdx
@@ -16,7 +16,7 @@ If you are using Terraform, refer to the [Terraform Secure Configuration](/docs/
 Refer to the [Task Tags](/docs/ecs/manual/install#task-tags) section of the installation page.
 * You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following [Learn Guides](https://learn.hashicorp.com/collections/consul/security) for an introduction and the [ACL system](/docs/security/acl) documentation for more information.
 
-## Setup AWS Secrets Manager
+## Set Up Secrets
 
 The ACL controller supports managing secrets in AWS Secrets Manager.
 
@@ -38,7 +38,7 @@ The ACL controller requires that the secrets it reads and writes are named with
 in the [Task Role Policy](/docs/ecs/manual/acl-controller#task-role-policy) to limit the ACL controller's access within
 AWS Secrets Manager to only those secrets strictly needed by the ACL controller.
 
-The name prefix should be unique among secrets your AWS account. We recommend a short (8 character) random
+The name prefix should be unique among secrets in your AWS account. We recommend using a short (8 character) random
 string for the prefix.
 
 -> **NOTE:** If you are using the ACL controller with multiple ECS clusters, each cluster requires
@@ -55,7 +55,7 @@ The following example shows how the task definition should be configured for the
 
 ```json
 {
-  "family": "my-consul-acl-controller".
+  "family": "my-consul-acl-controller",
   "networkMode": "awsvpc",
   "containerDefinitions": [
     {
@@ -102,7 +102,7 @@ In the `containerDefinitions` list, include one container with the following fie
 | `name`        | string  | The container name, which should be `acl-controller`                                                                             |
 | `image`       | string  | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits.                |
 | `command`     | list    | Must be set as shown. The startup command for the ACL controller.                                                                |
-| `essential`   | boolean | Must be `true` to ensure the container health ties into the health of the task.                                                  |
+| `essential`   | boolean | Must be `true` to ensure the health of your application container affects the health status of the task.                         |
 | `secrets`     | list    | Must have `CONSUL_HTTP_TOKEN` set to the ACL bootstrap token and `CONSUL_CACERT_PEM` set to the Consul server CA certificate.    |
 | `environment` | string  | Must set the `CONSUL_HTTP_ADDR` environment variable to the address of the HTTP API of your Consul servers.                      |
 
@@ -135,7 +135,7 @@ to complete the remaining details for your use case.
 | Field name       | Type    | Description                                                                                                      |
 | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
 | `cluster`        | string  | Set to your ECS cluster name or ARN. This must be the same ECS cluster where your service mesh applications run. |
-| `desiredCount`   | integer | Must be 1. Only one instance of the ACL controller should run per ECS cluster.                                   |
+| `desiredCount`   | integer | Must be `1`. Only one instance of the ACL controller should run per ECS cluster.                                   |
 | `launchType`     | string  | Consul on ECS supports both the `FARGATE` and `EC2` launch types.                                                |
 | `serviceName`    | string  | The service name of your choice.                                                                                 |
 | `taskDefinition` | string  | Must be set to the ACL controller [task definition](/docs/ecs/manual/acl-controller#task-definition).            |
diff --git a/website/content/docs/ecs/manual/install.mdx b/website/content/docs/ecs/manual/install.mdx
index 87b98ed86f..d9804f8ed7 100644
--- a/website/content/docs/ecs/manual/install.mdx
+++ b/website/content/docs/ecs/manual/install.mdx
@@ -112,11 +112,11 @@ this task and the service mesh.
 }
 ```
 
-| Field name  | Type    | Description                                                                                                                      |
-| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `name`      | string  | The name of your application container.                                                                                          |
-| `image`     | string  | The container image used to run your application.                                                                                |
-| `essential` | boolean | Must be `true` to ensure your application container ties into the health of the task.                                            |
+| Field name  | Type    | Description                                                                                                                       |
+| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------  |
+| `name`      | string  | The name of your application container.                                                                                           |
+| `image`     | string  | The container image used to run your application.                                                                                 |
+| `essential` | boolean | Must be `true` to ensure the health of your application container affects the health status of the task.                          |
 | `dependsOn` | list    | Must be set as shown above. Container dependencies ensure your application container starts after service mesh setup is complete. |
 
 See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) documentation for a complete reference.
@@ -185,7 +185,7 @@ The following table describes the necessary configuration settings.
 | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`        | string  | The container name, which must be `sidecar-proxy`.                                                                                                         |
 | `image`       | string  | The Envoy image. This must be a [supported version of Envoy](/docs/connect/proxies/envoy#supported-versions).                                              |
-| `dependsOn`   | list    | Must be set as shown above to ensure Envoy starts after the `consul-ecs-mesh-init` has written the `envoy-bootstrap.json` config file for Envoy.           |
+| `dependsOn`   | list    | Must be set as shown above to ensure Envoy starts after the `consul-ecs-mesh-init` container has written the `envoy-bootstrap.json` config file for Envoy. |
 | `healthCheck` | list    | Must be set as shown above to monitor the health of Envoy's primary listener port, which ties into container dependencies and startup ordering.            |
 | `mountPoints` | list    | Must be set as shown above to access the files shared in the `/consul` directory, like the Envoy bootstrap configuration file and the `consul-ecs` binary. |
 | `ulimits`     | list    | The `nofile` ulimit must be raised to a sufficiently high value so that Envoy does not fail to open sockets.                                               |
@@ -400,7 +400,7 @@ the `consul-ecs-health-sync` container.
 
 | Field name             | Type    | Description                                                                                                                                     |
 | ---------------------- | ------  | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bootstrapDir`         | string  | This is the path of a  shared volume the is mounted to other containers, where `consul-ecs-mesh-init` will write out Envoy configuration.       |
+| `bootstrapDir`         | string  | This is the path of a  shared volume that is mounted to other containers, where `consul-ecs-mesh-init` will write out Envoy configuration.      |
 | `healthSyncContainers` | list    | Used for [health status syncing](/docs/ecs/manual-installation#consul-ecs-health-sync-container) from ECS to Consul. See below for details.     |
 | `proxy.upstreams`      | list    | The upstream services that your application calls over the service mesh, if any. The `destinationName` and `localBindPort` fields are required. |
 | `service.name`         | string  | The name used to register this service into the Consul service catalog.                                                                         |
diff --git a/website/content/docs/ecs/manual/secure-configuration.mdx b/website/content/docs/ecs/manual/secure-configuration.mdx
index 57b12467c1..3e2722a79c 100644
--- a/website/content/docs/ecs/manual/secure-configuration.mdx
+++ b/website/content/docs/ecs/manual/secure-configuration.mdx
@@ -14,7 +14,7 @@ A secure Consul cluster should include the following:
 1. [Gossip Encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic.
 1. [Access Control (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh.
 
--> **NOTE:** This page assumes that you have already configured your Consul server with the above features.
+-> **NOTE:** In this topic, we assume that you have already configured your Consul server with the security-related features.
 
 ## Prerequisites
 
@@ -175,7 +175,7 @@ EOF
 
 </CodeBlockConfig>
 
-The following are the additional fields that must be included in the Consul client configuration file.
+The following table describes the additional fields that must be included in the Consul client configuration file.
 
 | Field name                                                 | Type    | Description                                                                          |
 | ---------------------------------------------------------  | ------- | ------------------------------------------------------------------------------------ |
diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx
index 6d98026667..af1ad061f2 100644
--- a/website/content/docs/ecs/terraform/install.mdx
+++ b/website/content/docs/ecs/terraform/install.mdx
@@ -77,6 +77,7 @@ The following fields are required. Refer to the [module reference documentation]
 | `version`               | string   | Must be set to the version of the `mesh-task` module.                                                                                                                                                                                          |
 | `family`                | string   | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default.                                           |
 | `container_definitions` | list     | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. |
+| `essential`             | boolean  | Must be `true` to ensure the health of your application container affects the health status of the task.                                                                                                                                       |
 | `port`                  | integer  | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`.                                                                                                                  |
 | `retry_join`            | list     | The is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers.                                                                                                  |
 

From 3fe88783e02e1cea0691550fdd86befb87e25aa4 Mon Sep 17 00:00:00 2001
From: Paul Glass <pglass@hashicorp.com>
Date: Tue, 25 Jan 2022 14:30:27 -0600
Subject: [PATCH 77/98] docs: Add configuration reference for ECS

---
 .../docs/ecs/configuration-reference.mdx      | 147 ++++++++++++++++++
 website/content/docs/ecs/manual/install.mdx   |   2 +-
 website/data/docs-nav-data.json               |   4 +
 3 files changed, 152 insertions(+), 1 deletion(-)
 create mode 100644 website/content/docs/ecs/configuration-reference.mdx

diff --git a/website/content/docs/ecs/configuration-reference.mdx b/website/content/docs/ecs/configuration-reference.mdx
new file mode 100644
index 0000000000..8e39efb932
--- /dev/null
+++ b/website/content/docs/ecs/configuration-reference.mdx
@@ -0,0 +1,147 @@
+---
+layout: docs
+page_title: AWS ECS
+description: >-
+  Configuration Reference for Consul on AWS ECS (Elastic Container Service).
+  Do not modify by hand! This is automatically generated documentation.
+---
+
+# Configuration Reference
+
+This pages details the configuration options for the JSON config format used
+by the `consul-ecs` binary. This configuration is passed to the `consul-ecs`
+binary as a string using the `CONSUL_ECS_CONFIG_JSON` environment variable.
+
+This configuration format follows a [JSON schema](https://github.com/hashicorp/consul-ecs/blob/main/config/schema.json)
+that can be used for validation.
+
+## Terraform Mesh Task Module Configuration
+
+The `mesh-task` Terraform module provides input variables for commonly used fields.
+The following table shows which Terraform input variables correspond to each field
+of the Consul ECS configuration. Refer to the
+[Terraform registry documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs)
+for a complete reference of supported input variables for the `mesh-task` module.
+
+| Terraform Input Variable | Consul ECS Config Field               |
+| ------------------------ | ------------------------------------- |
+| `upstreams`              | [`proxy.upstreams`](#proxy-upstreams) |
+| `checks`                 | [`service.checks`](#service-checks)   |
+| `consul_service_name`    | [`service.name`](#service)            |
+| `consul_service_tags`    | [`service.tags`](#service)            |
+| `consul_service_meta`    | [`service.meta`](#service)            |
+| `consul_namespace`       | [`service.namespace`](#service)       |
+| `consul_partition`       | [`service.partition`](#service)       |
+
+Each of these Terraform input variables follow the Consul ECS config schema.
+The remaining fields of the Consul ECS configuration not listed in this table can be passed
+using the `consul_ecs_config` input variable.
+
+# Top-level fields
+
+These are the top-level fields for the Consul ECS configuration format.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `bootstrapDir` | `string` | required | The directory at which to mount the shared volume where Envoy bootstrap configuration is written by `consul-ecs mesh-init`.  |
+| `healthSyncContainers` | `array` | optional | The names of containers that will have health check status synced from ECS into Consul. Cannot be specified with `service.checks`.  |
+| [`proxy`](#proxy) | `object` | optional | Configuration for the sidecar proxy registration with Consul.  |
+| [`service`](#service) | `object` | required | Configuration for Consul service registration.  |
+
+# `service`
+
+Configuration for Consul service registration.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| [`checks`](#service-checks) | `array` | optional | The list of Consul checks for the service. Cannot be specified with `healthSyncContainers`.  |
+| `enableTagOverride` | `boolean` | optional | Determines if the anti-entropy feature for the service is enabled  |
+| `meta` | `object` | optional | Key-value pairs of metadata to include for the Consul service.  |
+| `name` | `string` | optional | The name the service will be registered as in Consul. Defaults to the Task family name if empty or null.  |
+| `namespace` | `string` | optional | The Consul namespace where the service will be registered [Consul Enterprise].  |
+| `partition` | `string` | optional | The Consul admin partition where the service will be registered [Consul Enterprise].  |
+| `port` | `integer` | required | Port the application listens on, if any.  |
+| `tags` | `array` | optional | List of string values that can be used to add service-level labels.  |
+| [`weights`](#service-weights) | `object` | optional | Configures the weight of the service in terms of its DNS service (SRV) response.  |
+
+# `service.checks`
+
+Defines the Consul checks for the service. Each check may contain these fields.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `aliasNode` | `string` | optional | Specifies the ID of the node for an alias check.  |
+| `aliasService` | `string` | optional | Specifies the ID of a service for an alias check.  |
+| `args` | `array` | optional | Command arguments to run to update the status of the check.  |
+| `body` | `string` | optional | Specifies a body that should be sent with `HTTP` checks.  |
+| `checkId` | `string` | optional | The unique ID for this check on the node. Defaults to the check `name`.  |
+| `failuresBeforeCritical` | `integer` | optional | Specifies the number of consecutive unsuccessful results required before check status transitions to critical.  |
+| `grpc` | `string` | optional | Specifies a `gRPC` check. Must be an endpoint that supports the [standard gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). The endpoint will be probed every `interval`.  |
+| `grpcUseTls` | `boolean` | optional | Specifies whether to use TLS for this gRPC health check.  |
+| `h2ping` | `string` | optional | Specifies this is an h2ping check. Must be an address, which will be pinged every `interval`.  |
+| `h2pingUseTls` | `boolean` | optional | Specifies whether TLS is used for an h2ping check.  |
+| `header` | `object` | optional | Specifies a set of headers that should be set for HTTP checks. Each header can have multiple values.  |
+| `http` | `string` | optional | Specifies this is an HTTP check. Must be a URL against which request is performed every `interval`.  |
+| `interval` | `string` | optional | Specifies the frequency at which to run this check. Required for HTTP and TCP checks.  |
+| `method` | `string` | optional | Specifies the HTTP method to be used for an HTTP check. When no value is specified, `GET` is used.  |
+| `name` | `string` | optional | The name of the check.  |
+| `notes` | `string` | optional | Specifies arbitrary information for humans. This is not used by Consul internally.  |
+| `status` | `string` | optional | Specifies the initial status the health check. Must be one of `passing`, `warning`, `critical`, `maintenance`, or`null`. |
+| `successBeforePassing` | `integer` | optional | Specifies the number of consecutive successful results required before check status transitions to passing.  |
+| `tcp` | `string` | optional | Specifies this is a TCP check. Must be an IP/hostname plus port to which a TCP connection is made every `interval`.  |
+| `timeout` | `string` | optional | Specifies a timeout for outgoing connections in the case of a Script, HTTP, TCP, or gRPC check. Must be a duration string, such as `10s` or `5m`.  |
+| `tlsServerName` | `string` | optional | Specifies an optional string used to set the SNI host when connecting via TLS.  |
+| `tlsSkipVerify` | `boolean` | optional | Specifies if the certificate for an HTTPS check should not be verified.  |
+| `ttl` | `string` | optional | Specifies this is a TTL check. Must be a duration string, such as `10s` or `5m`.  |
+
+# `service.weights`
+
+Configures the weight of the service in terms of its DNS service (SRV) response.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `passing` | `integer` | required | Weight for the service when its health checks are passing.  |
+| `warning` | `integer` | required | Weight for the service when it has health checks in `warning` status.  |
+
+# `proxy`
+
+Configuration for the sidecar proxy registration with Consul.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `config` | `object` | optional | Object value that specifies an opaque JSON configuration. The JSON is stored and returned along with the service instance when called from the API.  |
+| [`meshGateway`](#proxy-meshgateway) | `object` | optional | Specifies the mesh gateway configuration for the proxy.  |
+| [`upstreams`](#proxy-upstreams) | `array` | optional | The list of the upstream services that the proxy should create listeners for.  |
+
+# `proxy.upstreams`
+
+The list of the upstream services that the proxy should create listeners for. Each upstream may contain these fields.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `config` | `object` | optional | Specifies opaque configuration options that will be provided to the proxy instance for the upstream.  |
+| `datacenter` | `string` | optional | Specifies the datacenter to issue the discovery query to.  |
+| `destinationName` | `string` | required | Specifies the name of the upstream service or prepared query to route the service mesh to.  |
+| `destinationNamespace` | `string` | optional | Specifies the namespace containing the upstream service [Consul Enterprise].  |
+| `destinationPartition` | `string` | optional | Specifies the name of the admin partition containing the upstream service [Consul Enterprise].  |
+| `destinationType` | `string` | optional | Specifies the type of discovery query the proxy should use for finding service mesh instances. Must be one of `service`, `prepared_query`, or`null`. |
+| `localBindAddress` | `string` | optional | Specifies the address to bind a local listener to.  |
+| `localBindPort` | `integer` | required | Specifies the port to bind a local listener to. The application will make outbound connections to the upstream from the local port.  |
+| [`meshGateway`](#proxy-upstreams-meshgateway) | `object` | optional | Specifies the mesh gateway configuration for the proxy for this upstream.  |
+
+## `proxy.upstreams.meshGateway`
+
+Specifies the mesh gateway configuration for the proxy for this upstream.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `mode` | `string` | required | Specifies how the upstream with a remote destination datacenter gets resolved. Must be one of `none`, `local`, or`remote`. |
+
+# `proxy.meshGateway`
+
+Specifies the mesh gateway configuration for the proxy.
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `mode` | `string` | required | Specifies how upstreams with a remote destination datacenter get resolved. Must be one of `none`, `local`, or`remote`. |
+
diff --git a/website/content/docs/ecs/manual/install.mdx b/website/content/docs/ecs/manual/install.mdx
index d9804f8ed7..d3bac3206b 100644
--- a/website/content/docs/ecs/manual/install.mdx
+++ b/website/content/docs/ecs/manual/install.mdx
@@ -407,7 +407,7 @@ the `consul-ecs-health-sync` container.
 | `service.port`         | integer | The port your application listens on. Set to `0` if your application does not listen on any port.                                               |
 | `service.checks`       | list    | Consul [checks](/docs/discovery/checks) to include so that Consul can run health checks against your application.                               |
 
-See the [`consul-ecs JSON Schema`](https://github.com/hashicorp/consul-ecs/blob/main/config/schema.json) for a complete reference of fields.
+See the [Configuration Reference](/docs/ecs/configuration-reference) for a complete reference of fields.
 
 ## `consul-ecs-health-sync` container
 
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index e55bf32d1a..fe8413cef4 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -652,6 +652,10 @@
       {
         "title": "Consul Enterprise",
         "path": "ecs/enterprise"
+      },
+      {
+        "title": "Configuration Reference",
+        "path": "ecs/configuration-reference"
       }
     ]
   },

From f05bad4a1d6cfcb2cca0ff78eb6aa19ffc9df76c Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Wed, 1 Dec 2021 15:11:20 -0500
Subject: [PATCH 78/98] ca: update GenerateRoot godoc

---
 agent/connect/ca/provider.go        | 14 +++++++++++---
 agent/connect/ca/provider_consul.go |  3 +--
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/agent/connect/ca/provider.go b/agent/connect/ca/provider.go
index 4bab873aa9..6eab92f96e 100644
--- a/agent/connect/ca/provider.go
+++ b/agent/connect/ca/provider.go
@@ -118,9 +118,17 @@ type Provider interface {
 }
 
 type PrimaryProvider interface {
-	// GenerateRoot causes the creation of a new root certificate for this provider.
-	// This can also be a no-op if a root certificate already exists for the given
-	// config. If IsPrimary is false, calling this method is an error.
+	// GenerateRoot is called:
+	//   * to initialize the CA system when a server is elected as a raft leader
+	//   * when the CA configuration is updated in a way that might require
+	//     generating a new root certificate.
+	//
+	// In both cases GenerateRoot is always called on a newly created provider
+	// after calling Provider.Configure, and before any other calls to the
+	// provider.
+	//
+	// The provider should return an existing root certificate if one exists,
+	// otherwise it should generate a new root certificate and return it.
 	GenerateRoot() error
 
 	// ActiveRoot returns the currently active root CA for this
diff --git a/agent/connect/ca/provider_consul.go b/agent/connect/ca/provider_consul.go
index dea91e5d7d..d0e746803c 100644
--- a/agent/connect/ca/provider_consul.go
+++ b/agent/connect/ca/provider_consul.go
@@ -159,8 +159,7 @@ func (c *ConsulProvider) ActiveRoot() (string, error) {
 	return providerState.RootCert, nil
 }
 
-// GenerateRoot initializes a new root certificate and private key
-// if needed.
+// GenerateRoot initializes a new root certificate and private key if needed.
 func (c *ConsulProvider) GenerateRoot() error {
 	providerState, err := c.getState()
 	if err != nil {

From c2b9c81a5569f989a93f65e4b3b974192c9798fc Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Wed, 1 Dec 2021 15:40:27 -0500
Subject: [PATCH 79/98] ca: update MockProvider for new interface

---
 agent/connect/ca/mock_Provider.go | 46 +++++++++++--------------------
 1 file changed, 16 insertions(+), 30 deletions(-)

diff --git a/agent/connect/ca/mock_Provider.go b/agent/connect/ca/mock_Provider.go
index 59f5374fef..ec79ea5c70 100644
--- a/agent/connect/ca/mock_Provider.go
+++ b/agent/connect/ca/mock_Provider.go
@@ -34,34 +34,13 @@ func (_m *MockProvider) ActiveIntermediate() (string, error) {
 	return r0, r1
 }
 
-// ActiveRoot provides a mock function with given fields:
-func (_m *MockProvider) ActiveRoot() (string, error) {
-	ret := _m.Called()
-
-	var r0 string
-	if rf, ok := ret.Get(0).(func() string); ok {
-		r0 = rf()
-	} else {
-		r0 = ret.Get(0).(string)
-	}
-
-	var r1 error
-	if rf, ok := ret.Get(1).(func() error); ok {
-		r1 = rf()
-	} else {
-		r1 = ret.Error(1)
-	}
-
-	return r0, r1
-}
-
-// Cleanup provides a mock function with given fields: providerTypeChange, config
-func (_m *MockProvider) Cleanup(providerTypeChange bool, config map[string]interface{}) error {
-	ret := _m.Called(providerTypeChange, config)
+// Cleanup provides a mock function with given fields: providerTypeChange, otherConfig
+func (_m *MockProvider) Cleanup(providerTypeChange bool, otherConfig map[string]interface{}) error {
+	ret := _m.Called(providerTypeChange, otherConfig)
 
 	var r0 error
 	if rf, ok := ret.Get(0).(func(bool, map[string]interface{}) error); ok {
-		r0 = rf(providerTypeChange, config)
+		r0 = rf(providerTypeChange, otherConfig)
 	} else {
 		r0 = ret.Error(0)
 	}
@@ -147,17 +126,24 @@ func (_m *MockProvider) GenerateIntermediateCSR() (string, error) {
 }
 
 // GenerateRoot provides a mock function with given fields:
-func (_m *MockProvider) GenerateRoot() error {
+func (_m *MockProvider) GenerateRoot() (RootResult, error) {
 	ret := _m.Called()
 
-	var r0 error
-	if rf, ok := ret.Get(0).(func() error); ok {
+	var r0 RootResult
+	if rf, ok := ret.Get(0).(func() RootResult); ok {
 		r0 = rf()
 	} else {
-		r0 = ret.Error(0)
+		r0 = ret.Get(0).(RootResult)
 	}
 
-	return r0
+	var r1 error
+	if rf, ok := ret.Get(1).(func() error); ok {
+		r1 = rf()
+	} else {
+		r1 = ret.Error(1)
+	}
+
+	return r0, r1
 }
 
 // SetIntermediate provides a mock function with given fields: intermediatePEM, rootPEM

From 1aba658402e175d1bc414dca780fae02852bfdbf Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 10:01:29 -0800
Subject: [PATCH 80/98] applying additional feedback

---
 website/content/docs/api-gateway.mdx | 96 ++++++++++++++--------------
 1 file changed, 48 insertions(+), 48 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 0f3817a79c..a3a0826eca 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -28,27 +28,27 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
   <CodeBlockConfig hideClipboard filename="values.yaml">
 
-  ```yaml
-  global:
-    name: consul
-    image: 'hashicorp/consul:1.11.2'
-    tls:
-      enabled: true
-  connectInject:
-    enabled: true
-  controller:
+```yaml
+global:
+  name: consul
+  image: 'hashicorp/consul:1.11.2'
+  tls:
     enabled: true
-  ```
+connectInject:
+  enabled: true
+controller:
+  enabled: true
+```
 
   </CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
-  ```shell-session
-  $ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
-  ```
+```shell-session
+$ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
+```
 
-  The following components will be installed:
+The following components will be installed:
 
      - Gateway controller
      - CRDs required by the Kubernetes Gateway API specification
@@ -56,10 +56,10 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
 1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster:
 
-  ```shell-session
-  $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
-  $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
-  ```
+```shell-session
+$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
+$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
+```
 
 ## Usage
 
@@ -68,9 +68,9 @@ Your datacenter must meet the following requirements prior to configuring the Co
 1. Configure the gateway, listener(s), and route(s) as described in [Configuration](#configuration).
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
-  ```shell-session
-  $ kubectl apply --values gateway-configuration.yaml
-  ```
+```shell-session
+$ kubectl apply --values gateway-configuration.yaml
+```
 
 <!--- Commented out per https://github.com/hashicorp/consul/pull/11951/files#r791204596
 
@@ -158,8 +158,7 @@ spec:
 
 </CodeBlockConfig>
 
-Refer to the Kubernetes Gateway API documentation for details about configuring gateway classes:
-<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass>
+Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for details about configuring gateway classes.
 
 ### GatewayClassConfig
 
@@ -190,26 +189,25 @@ spec:
 
 The following table describes the required parameters for the `spec` array:
 
-| Parameter                         | Description                                                                                                                                                                                                                                                                                                               | Type    | Default                                          |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
-| `consul.address`                  | Specifies the address of the Consul server to communicate with in the gateway pod. If unspecified, the pod will attempt to use a local agent on the host on which the pod is running.                                                                                                                                     | String  | N/A                                              |
-| `consul.authentication.account`   | Specifies the Kubernetes service account to use for authentication.                                                                                                                                                                                                                                                       | String  | N/A                                              |
-| `consul.authentication.managed`   | Set to `true` to enable deployments to run with managed service accounts created by the gateway controller. The `consul.authentication.account` field is ignored when this option is enabled.                                                                                                                             | Boolean | `false`                                          |
-| `consul.authentication.method`    | Specifies the Consul auth method used for initial authentication by Consul API Gateway.                                                                                                                                                                                                                                   | String  | N/A                                              |
-| `consul.authentication.namespace` | Specifies the Consul namespace to use for authentication.                                                                                                                                                                                                                                                                 | String  | N/A                                              |
-| `consul.ports.grpc`               | Specifies the gRPC port for Consul's xDS server.                                                                                                                                                                                                                                                                          | Integer | `8502`                                           |
-| `consul.ports.http`               | Specifies the port for Consul's HTTP server.                                                                                                                                                                                                                                                                              | Integer | `8500`                                           |
-| `consul.scheme`                   | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`.                                                                                                                                                                                                                    | String  | `"http"`                                         |
-| `copyAnnotations.service`         | List of annotations to copy to the gateway service.                                                                                                                                                                                                                                                                       | Array   | `["external-dns.alpha.kubernetes.io/hostname"]`  |
-| `image.consulAPIGateway`          | The image to use for consul-api-gateway.                                                                                                                                                                                                                                                                                  | String  | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` |
-| `image.envoy`                     | Specifies the container image to use for Envoy.                                                                                                                                                                                                                                                                           | String  | `"envoyproxy/envoy:v1.19-latest"`                |
-| `logLevel`                        | Specifies the error reporting level for logs. You can specify the following values: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`, `OFF`.                                                                                                                                                                      | String  | `"info"`                                         |
-| `nodeSelector`                    | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ | Object  | N/A                                              |
-| `serviceType`                     | Specifies the ingress methods for a service. The following values are supported: <br/>`ClusterIP` <br/>`NodePort` <br/>`LoadBalancer`.                                                                                                                                                                                     | String  | N/A                                              |
-| `useHostPorts`                    | If set to `true`, then the Envoy container ports are mapped to host ports.                                                                                                                                                                                                                                                | Boolean | `false`                                          |
-
-Refer to the Consul API Gateway repository for the complete specification:
-<https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml>
+| Parameter                         | Description                                                                                                                                                                                                                                                                                                                                                                         | Type    | Default                                          |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
+| `consul.address`                  | Specifies the address of the Consul server to communicate with in the gateway pod. If unspecified, the pod will attempt to use a local agent on the host on which the pod is running.                                                                                                                                                                                               | String  | N/A                                              |
+| `consul.authentication.account`   | Specifies the Kubernetes service account to use for authentication.                                                                                                                                                                                                                                                                                                                 | String  | N/A                                              |
+| `consul.authentication.managed`   | Set to `true` to enable deployments to run with managed service accounts created by the gateway controller. The `consul.authentication.account` field is ignored when this option is enabled.                                                                                                                                                                                       | Boolean | `false`                                          |
+| `consul.authentication.method`    | Specifies the Consul auth method used for initial authentication by Consul API Gateway.                                                                                                                                                                                                                                                                                             | String  | N/A                                              |
+| `consul.authentication.namespace` | Specifies the Consul namespace to use for authentication.                                                                                                                                                                                                                                                                                                                           | String  | N/A                                              |
+| `consul.ports.grpc`               | Specifies the gRPC port for Consul's xDS server.                                                                                                                                                                                                                                                                                                                                    | Integer | `8502`                                           |
+| `consul.ports.http`               | Specifies the port for Consul's HTTP server.                                                                                                                                                                                                                                                                                                                                        | Integer | `8500`                                           |
+| `consul.scheme`                   | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`.                                                                                                                                                                                                                                                                              | String  | `"http"`                                         |
+| `copyAnnotations.service`         | List of annotations to copy to the gateway service.                                                                                                                                                                                                                                                                                                                                 | Array   | `["external-dns.alpha.kubernetes.io/hostname"]`  |
+| `image.consulAPIGateway`          | The image to use for consul-api-gateway.                                                                                                                                                                                                                                                                                                                                            | String  | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` |
+| `image.envoy`                     | Specifies the container image to use for Envoy.                                                                                                                                                                                                                                                                                                                                     | String  | `"envoyproxy/envoy:v1.19-latest"`                |
+| `logLevel`                        | Specifies the error reporting level for logs. You can specify the following values: `fatal`, `error`, `warning`, `info`, `debug`, `trace`.                                                                                                                                                                                                                                          | String  | `"info"`                                         |
+| `nodeSelector`                    | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object  | N/A                                              |
+| `serviceType`                     | Specifies the ingress methods for a service. The following values are supported: <br/>`ClusterIP` <br/>`NodePort` <br/>`LoadBalancer`.                                                                                                                                                                                                                                              | String  | N/A                                              |
+| `useHostPorts`                    | If set to `true`, then the Envoy container ports are mapped to host ports.                                                                                                                                                                                                                                                                                                          | Boolean | `false`                                          |
+
+Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml) for the complete specification.
 
 ### Gateway
 
@@ -245,8 +243,7 @@ spec:
 
 </CodeBlockConfig>
 
-Refer to the Kubernetes Gateway API documentation for details about configuring gateways:
-<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway>
+Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for details about configuring gateways:
 
 #### Listeners
 
@@ -266,14 +263,17 @@ Add the `listener` object to the `gateway` configuration and specify the followi
 | `tls.options.tls_max_version"`  | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | String  | `TLS 1.3`       |
 | `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier. <br/>If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites) will be used. <br/>The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String  | See description |
 
-Refer to the Kubernetes Gateway API documentation for details about configuring listeners:
-<https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener>
+Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener) for details about configuring listeners.
 
 ### Route
 
 Routes are independent configuration objects that are associated with specific listeners.
 
-Use the `kind: HTTPRoute` option to declare a route and use the `spec` option to specify the route details.
+Declare a route with either `kind: HTTPRoute` or `kind: TCPRoute` and configure the route parameters in the `spec` block.
+Refer to the Kubernetes Gateway API documentation for each object type for details:
+
+- [HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute)
+- [TCPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute)
 
 The following example creates a route named `example-route` associated with a listener defined in `example-gateway`.
 

From 9b7468f99e503177aa08f01a4fdb3bea22609641 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Wed, 1 Dec 2021 15:39:20 -0500
Subject: [PATCH 81/98] ca/provider: remove ActiveRoot from Provider

---
 agent/connect/ca/provider.go             | 17 +++++-----
 agent/connect/ca/provider_aws.go         | 26 ++++++---------
 agent/connect/ca/provider_aws_test.go    | 36 ++++++++++----------
 agent/connect/ca/provider_consul.go      | 37 +++++++--------------
 agent/connect/ca/provider_consul_test.go | 41 +++++++++++++----------
 agent/connect/ca/provider_vault.go       | 42 +++++++++++++-----------
 agent/connect/ca/provider_vault_test.go  | 24 +++++++++-----
 agent/consul/leader_connect_ca.go        | 20 ++++-------
 agent/consul/leader_connect_ca_test.go   |  5 ++-
 9 files changed, 120 insertions(+), 128 deletions(-)

diff --git a/agent/connect/ca/provider.go b/agent/connect/ca/provider.go
index 6eab92f96e..59431fdbd7 100644
--- a/agent/connect/ca/provider.go
+++ b/agent/connect/ca/provider.go
@@ -129,14 +129,7 @@ type PrimaryProvider interface {
 	//
 	// The provider should return an existing root certificate if one exists,
 	// otherwise it should generate a new root certificate and return it.
-	GenerateRoot() error
-
-	// ActiveRoot returns the currently active root CA for this
-	// provider. This should be a parent of the certificate returned by
-	// ActiveIntermediate()
-	//
-	// TODO: currently called from secondaries, but shouldn't be so is on PrimaryProvider
-	ActiveRoot() (string, error)
+	GenerateRoot() (RootResult, error)
 
 	// GenerateIntermediate returns a new intermediate signing cert and sets it to
 	// the active intermediate. If multiple intermediates are needed to complete
@@ -189,6 +182,14 @@ type SecondaryProvider interface {
 	SetIntermediate(intermediatePEM, rootPEM string) error
 }
 
+// RootResult is the result returned by PrimaryProvider.GenerateRoot.
+//
+// TODO: rename this struct
+type RootResult struct {
+	// PEM encoded certificate that will be used as the primary CA.
+	PEM string
+}
+
 // NeedsStop is an optional interface that allows a CA to define a function
 // to be called when the CA instance is no longer in use. This is different
 // from Cleanup(), as only the local provider instance is being shut down
diff --git a/agent/connect/ca/provider_aws.go b/agent/connect/ca/provider_aws.go
index b813ef5072..25786ab409 100644
--- a/agent/connect/ca/provider_aws.go
+++ b/agent/connect/ca/provider_aws.go
@@ -134,12 +134,19 @@ func (a *AWSProvider) State() (map[string]string, error) {
 }
 
 // GenerateRoot implements Provider
-func (a *AWSProvider) GenerateRoot() error {
+func (a *AWSProvider) GenerateRoot() (RootResult, error) {
 	if !a.isPrimary {
-		return fmt.Errorf("provider is not the root certificate authority")
+		return RootResult{}, fmt.Errorf("provider is not the root certificate authority")
 	}
 
-	return a.ensureCA()
+	if err := a.ensureCA(); err != nil {
+		return RootResult{}, err
+	}
+
+	if a.rootPEM == "" {
+		return RootResult{}, fmt.Errorf("AWS CA provider not fully Initialized")
+	}
+	return RootResult{PEM: a.rootPEM}, nil
 }
 
 // ensureCA loads the CA resource to check it exists if configured by User or in
@@ -489,19 +496,6 @@ func (a *AWSProvider) signCSR(csrPEM string, templateARN string, ttl time.Durati
 		})
 }
 
-// ActiveRoot implements Provider
-func (a *AWSProvider) ActiveRoot() (string, error) {
-	err := a.ensureCA()
-	if err != nil {
-		return "", err
-	}
-
-	if a.rootPEM == "" {
-		return "", fmt.Errorf("Secondary AWS CA provider not fully Initialized")
-	}
-	return a.rootPEM, nil
-}
-
 // GenerateIntermediateCSR implements Provider
 func (a *AWSProvider) GenerateIntermediateCSR() (string, error) {
 	if a.isPrimary {
diff --git a/agent/connect/ca/provider_aws_test.go b/agent/connect/ca/provider_aws_test.go
index a090df7858..b73d4a95d5 100644
--- a/agent/connect/ca/provider_aws_test.go
+++ b/agent/connect/ca/provider_aws_test.go
@@ -46,12 +46,9 @@ func TestAWSBootstrapAndSignPrimary(t *testing.T) {
 			provider := testAWSProvider(t, testProviderConfigPrimary(t, cfg))
 			defer provider.Cleanup(true, nil)
 
-			// Generate the root
-			require.NoError(t, provider.GenerateRoot())
-
-			// Fetch Active Root
-			rootPEM, err := provider.ActiveRoot()
+			root, err := provider.GenerateRoot()
 			require.NoError(t, err)
+			rootPEM := root.PEM
 
 			// Generate Intermediate (not actually needed for this provider for now
 			// but this simulates the calls in Server.initializeRoot).
@@ -81,16 +78,12 @@ func TestAWSBootstrapAndSignPrimary(t *testing.T) {
 	}
 
 	t.Run("Test default root ttl for aws ca provider", func(t *testing.T) {
-
 		provider := testAWSProvider(t, testProviderConfigPrimary(t, nil))
 		defer provider.Cleanup(true, nil)
 
-		// Generate the root
-		require.NoError(t, provider.GenerateRoot())
-
-		// Fetch Active Root
-		rootPEM, err := provider.ActiveRoot()
+		root, err := provider.GenerateRoot()
 		require.NoError(t, err)
+		rootPEM := root.PEM
 
 		// Ensure they use the right key type
 		rootCert, err := connect.ParseCert(rootPEM)
@@ -123,8 +116,9 @@ func TestAWSBootstrapAndSignSecondary(t *testing.T) {
 
 	p1 := testAWSProvider(t, testProviderConfigPrimary(t, nil))
 	defer p1.Cleanup(true, nil)
-	rootPEM, err := p1.ActiveRoot()
+	root, err := p1.GenerateRoot()
 	require.NoError(t, err)
+	rootPEM := root.PEM
 
 	p2 := testAWSProvider(t, testProviderConfigSecondary(t, nil))
 	defer p2.Cleanup(true, nil)
@@ -151,8 +145,9 @@ func TestAWSBootstrapAndSignSecondary(t *testing.T) {
 		cfg1 := testProviderConfigPrimary(t, nil)
 		cfg1.State = p1State
 		p1 = testAWSProvider(t, cfg1)
-		newRootPEM, err := p1.ActiveRoot()
+		root, err := p1.GenerateRoot()
 		require.NoError(t, err)
+		newRootPEM := root.PEM
 
 		cfg2 := testProviderConfigPrimary(t, nil)
 		cfg2.State = p2State
@@ -184,8 +179,9 @@ func TestAWSBootstrapAndSignSecondary(t *testing.T) {
 			"ExistingARN": p1State[AWSStateCAARNKey],
 		})
 		p1 = testAWSProvider(t, cfg1)
-		newRootPEM, err := p1.ActiveRoot()
+		root, err := p1.GenerateRoot()
 		require.NoError(t, err)
+		newRootPEM := root.PEM
 
 		cfg2 := testProviderConfigPrimary(t, map[string]interface{}{
 			"ExistingARN": p2State[AWSStateCAARNKey],
@@ -222,8 +218,9 @@ func TestAWSBootstrapAndSignSecondary(t *testing.T) {
 		p2 = testAWSProvider(t, cfg2)
 		require.NoError(t, p2.SetIntermediate(newIntPEM, newRootPEM))
 
-		newRootPEM, err = p1.ActiveRoot()
+		root, err = p1.GenerateRoot()
 		require.NoError(t, err)
+		newRootPEM = root.PEM
 		newIntPEM, err = p2.ActiveIntermediate()
 		require.NoError(t, err)
 
@@ -243,7 +240,8 @@ func TestAWSBootstrapAndSignSecondaryConsul(t *testing.T) {
 		p1 := TestConsulProvider(t, delegate)
 		cfg := testProviderConfig(conf)
 		require.NoError(t, p1.Configure(cfg))
-		require.NoError(t, p1.GenerateRoot())
+		_, err := p1.GenerateRoot()
+		require.NoError(t, err)
 
 		p2 := testAWSProvider(t, testProviderConfigSecondary(t, nil))
 		defer p2.Cleanup(true, nil)
@@ -254,7 +252,9 @@ func TestAWSBootstrapAndSignSecondaryConsul(t *testing.T) {
 	t.Run("pri=aws,sec=consul", func(t *testing.T) {
 		p1 := testAWSProvider(t, testProviderConfigPrimary(t, nil))
 		defer p1.Cleanup(true, nil)
-		require.NoError(t, p1.GenerateRoot())
+
+		_, err := p1.GenerateRoot()
+		require.NoError(t, err)
 
 		conf := testConsulCAConfig()
 		delegate := newMockDelegate(t, conf)
@@ -315,11 +315,13 @@ func TestAWSProvider_Cleanup(t *testing.T) {
 	}
 
 	requirePCADeleted := func(t *testing.T, provider *AWSProvider) {
+		t.Helper()
 		deleted, err := describeCA(t, provider)
 		require.True(t, err != nil || deleted, "The AWS PCA instance has not been deleted")
 	}
 
 	requirePCANotDeleted := func(t *testing.T, provider *AWSProvider) {
+		t.Helper()
 		deleted, err := describeCA(t, provider)
 		require.NoError(t, err)
 		require.False(t, deleted, "The AWS PCA instance should not have been deleted")
diff --git a/agent/connect/ca/provider_consul.go b/agent/connect/ca/provider_consul.go
index d0e746803c..a12f70a1a0 100644
--- a/agent/connect/ca/provider_consul.go
+++ b/agent/connect/ca/provider_consul.go
@@ -149,28 +149,18 @@ func (c *ConsulProvider) State() (map[string]string, error) {
 	return c.testState, nil
 }
 
-// ActiveRoot returns the active root CA certificate.
-func (c *ConsulProvider) ActiveRoot() (string, error) {
-	providerState, err := c.getState()
-	if err != nil {
-		return "", err
-	}
-
-	return providerState.RootCert, nil
-}
-
 // GenerateRoot initializes a new root certificate and private key if needed.
-func (c *ConsulProvider) GenerateRoot() error {
+func (c *ConsulProvider) GenerateRoot() (RootResult, error) {
 	providerState, err := c.getState()
 	if err != nil {
-		return err
+		return RootResult{}, err
 	}
 
 	if !c.isPrimary {
-		return fmt.Errorf("provider is not the root certificate authority")
+		return RootResult{}, fmt.Errorf("provider is not the root certificate authority")
 	}
 	if providerState.RootCert != "" {
-		return nil
+		return RootResult{PEM: providerState.RootCert}, nil
 	}
 
 	// Generate a private key if needed
@@ -178,7 +168,7 @@ func (c *ConsulProvider) GenerateRoot() error {
 	if c.config.PrivateKey == "" {
 		_, pk, err := connect.GeneratePrivateKeyWithConfig(c.config.PrivateKeyType, c.config.PrivateKeyBits)
 		if err != nil {
-			return err
+			return RootResult{}, err
 		}
 		newState.PrivateKey = pk
 	} else {
@@ -189,12 +179,12 @@ func (c *ConsulProvider) GenerateRoot() error {
 	if c.config.RootCert == "" {
 		nextSerial, err := c.incrementAndGetNextSerialNumber()
 		if err != nil {
-			return fmt.Errorf("error computing next serial number: %v", err)
+			return RootResult{}, fmt.Errorf("error computing next serial number: %v", err)
 		}
 
 		ca, err := c.generateCA(newState.PrivateKey, nextSerial, c.config.RootCertTTL)
 		if err != nil {
-			return fmt.Errorf("error generating CA: %v", err)
+			return RootResult{}, fmt.Errorf("error generating CA: %v", err)
 		}
 		newState.RootCert = ca
 	} else {
@@ -207,10 +197,10 @@ func (c *ConsulProvider) GenerateRoot() error {
 		ProviderState: &newState,
 	}
 	if _, err := c.Delegate.ApplyCARequest(args); err != nil {
-		return err
+		return RootResult{}, err
 	}
 
-	return nil
+	return RootResult{PEM: newState.RootCert}, nil
 }
 
 // GenerateIntermediateCSR creates a private key and generates a CSR
@@ -287,18 +277,15 @@ func (c *ConsulProvider) SetIntermediate(intermediatePEM, rootPEM string) error
 	return nil
 }
 
-// We aren't maintaining separate root/intermediate CAs for the builtin
-// provider, so just return the root.
 func (c *ConsulProvider) ActiveIntermediate() (string, error) {
-	if c.isPrimary {
-		return c.ActiveRoot()
-	}
-
 	providerState, err := c.getState()
 	if err != nil {
 		return "", err
 	}
 
+	if c.isPrimary {
+		return providerState.RootCert, nil
+	}
 	return providerState.IntermediateCert, nil
 }
 
diff --git a/agent/connect/ca/provider_consul_test.go b/agent/connect/ca/provider_consul_test.go
index dd4fd12a76..a4df05b767 100644
--- a/agent/connect/ca/provider_consul_test.go
+++ b/agent/connect/ca/provider_consul_test.go
@@ -83,18 +83,17 @@ func TestConsulCAProvider_Bootstrap(t *testing.T) {
 
 	provider := TestConsulProvider(t, delegate)
 	require.NoError(t, provider.Configure(testProviderConfig(conf)))
-	require.NoError(t, provider.GenerateRoot())
 
-	root, err := provider.ActiveRoot()
+	root, err := provider.GenerateRoot()
 	require.NoError(t, err)
 
 	// Intermediate should be the same cert.
 	inter, err := provider.ActiveIntermediate()
 	require.NoError(t, err)
-	require.Equal(t, root, inter)
+	require.Equal(t, root.PEM, inter)
 
 	// Should be a valid cert
-	parsed, err := connect.ParseCert(root)
+	parsed, err := connect.ParseCert(root.PEM)
 	require.NoError(t, err)
 	require.Equal(t, parsed.URIs[0].String(), fmt.Sprintf("spiffe://%s.consul", conf.ClusterID))
 	requireNotEncoded(t, parsed.SubjectKeyId)
@@ -123,14 +122,13 @@ func TestConsulCAProvider_Bootstrap_WithCert(t *testing.T) {
 
 	provider := TestConsulProvider(t, delegate)
 	require.NoError(t, provider.Configure(testProviderConfig(conf)))
-	require.NoError(t, provider.GenerateRoot())
 
-	root, err := provider.ActiveRoot()
+	root, err := provider.GenerateRoot()
 	require.NoError(t, err)
-	require.Equal(t, root, rootCA.RootCert)
+	require.Equal(t, root.PEM, rootCA.RootCert)
 
 	// Should be a valid cert
-	parsed, err := connect.ParseCert(root)
+	parsed, err := connect.ParseCert(root.PEM)
 	require.NoError(t, err)
 
 	// test that the default root cert ttl was not applied to the provided cert
@@ -160,7 +158,8 @@ func TestConsulCAProvider_SignLeaf(t *testing.T) {
 
 			provider := TestConsulProvider(t, delegate)
 			require.NoError(t, provider.Configure(testProviderConfig(conf)))
-			require.NoError(t, provider.GenerateRoot())
+			_, err := provider.GenerateRoot()
+			require.NoError(t, err)
 
 			spiffeService := &connect.SpiffeIDService{
 				Host:       connect.TestClusterID + ".consul",
@@ -272,7 +271,8 @@ func TestConsulCAProvider_CrossSignCA(t *testing.T) {
 			conf1.Config["PrivateKeyType"] = tc.SigningKeyType
 			conf1.Config["PrivateKeyBits"] = tc.SigningKeyBits
 			require.NoError(t, provider1.Configure(testProviderConfig(conf1)))
-			require.NoError(t, provider1.GenerateRoot())
+			_, err := provider1.GenerateRoot()
+			require.NoError(t, err)
 
 			conf2 := testConsulCAConfig()
 			conf2.CreateIndex = 10
@@ -281,7 +281,8 @@ func TestConsulCAProvider_CrossSignCA(t *testing.T) {
 			conf2.Config["PrivateKeyType"] = tc.CSRKeyType
 			conf2.Config["PrivateKeyBits"] = tc.CSRKeyBits
 			require.NoError(t, provider2.Configure(testProviderConfig(conf2)))
-			require.NoError(t, provider2.GenerateRoot())
+			_, err = provider2.GenerateRoot()
+			require.NoError(t, err)
 
 			testCrossSignProviders(t, provider1, provider2)
 		})
@@ -291,9 +292,10 @@ func TestConsulCAProvider_CrossSignCA(t *testing.T) {
 func testCrossSignProviders(t *testing.T, provider1, provider2 Provider) {
 
 	// Get the root from the new provider to be cross-signed.
-	newRootPEM, err := provider2.ActiveRoot()
+	root, err := provider2.GenerateRoot()
 	require.NoError(t, err)
-	newRoot, err := connect.ParseCert(newRootPEM)
+
+	newRoot, err := connect.ParseCert(root.PEM)
 	require.NoError(t, err)
 	oldSubject := newRoot.Subject.CommonName
 	requireNotEncoded(t, newRoot.SubjectKeyId)
@@ -314,9 +316,9 @@ func testCrossSignProviders(t *testing.T, provider1, provider2 Provider) {
 	requireNotEncoded(t, xc.SubjectKeyId)
 	requireNotEncoded(t, xc.AuthorityKeyId)
 
-	oldRootPEM, err := provider1.ActiveRoot()
+	p1Root, err := provider1.GenerateRoot()
 	require.NoError(t, err)
-	oldRoot, err := connect.ParseCert(oldRootPEM)
+	oldRoot, err := connect.ParseCert(p1Root.PEM)
 	require.NoError(t, err)
 	requireNotEncoded(t, oldRoot.SubjectKeyId)
 	requireNotEncoded(t, oldRoot.AuthorityKeyId)
@@ -392,7 +394,8 @@ func TestConsulProvider_SignIntermediate(t *testing.T) {
 			conf1.Config["PrivateKeyType"] = tc.SigningKeyType
 			conf1.Config["PrivateKeyBits"] = tc.SigningKeyBits
 			require.NoError(t, provider1.Configure(testProviderConfig(conf1)))
-			require.NoError(t, provider1.GenerateRoot())
+			_, err := provider1.GenerateRoot()
+			require.NoError(t, err)
 
 			conf2 := testConsulCAConfig()
 			conf2.CreateIndex = 10
@@ -422,8 +425,9 @@ func testSignIntermediateCrossDC(t *testing.T, provider1, provider2 Provider) {
 	// Sign the CSR with provider1.
 	intermediatePEM, err := provider1.SignIntermediate(csr)
 	require.NoError(t, err)
-	rootPEM, err := provider1.ActiveRoot()
+	root, err := provider1.GenerateRoot()
 	require.NoError(t, err)
+	rootPEM := root.PEM
 
 	// Give the new intermediate to provider2 to use.
 	require.NoError(t, provider2.SetIntermediate(intermediatePEM, rootPEM))
@@ -496,7 +500,8 @@ func TestConsulCAProvider_MigrateOldID(t *testing.T) {
 
 			provider := TestConsulProvider(t, delegate)
 			require.NoError(t, provider.Configure(testProviderConfig(conf)))
-			require.NoError(t, provider.GenerateRoot())
+			_, err = provider.GenerateRoot()
+			require.NoError(t, err)
 
 			// After running Configure, the old ID entry should be gone.
 			_, providerState, err = delegate.state.CAProviderState(tc.oldID)
diff --git a/agent/connect/ca/provider_vault.go b/agent/connect/ca/provider_vault.go
index ef1920d7af..3a1d5128e7 100644
--- a/agent/connect/ca/provider_vault.go
+++ b/agent/connect/ca/provider_vault.go
@@ -12,11 +12,12 @@ import (
 	"strings"
 	"time"
 
-	"github.com/hashicorp/consul/lib/decode"
 	"github.com/hashicorp/go-hclog"
 	vaultapi "github.com/hashicorp/vault/api"
 	"github.com/mitchellh/mapstructure"
 
+	"github.com/hashicorp/consul/lib/decode"
+
 	"github.com/hashicorp/consul/agent/connect"
 	"github.com/hashicorp/consul/agent/structs"
 )
@@ -220,19 +221,14 @@ func (v *VaultProvider) State() (map[string]string, error) {
 	return nil, nil
 }
 
-// ActiveRoot returns the active root CA certificate.
-func (v *VaultProvider) ActiveRoot() (string, error) {
-	return v.getCA(v.config.RootPKIPath)
-}
-
 // GenerateRoot mounts and initializes a new root PKI backend if needed.
-func (v *VaultProvider) GenerateRoot() error {
+func (v *VaultProvider) GenerateRoot() (RootResult, error) {
 	if !v.isPrimary {
-		return fmt.Errorf("provider is not the root certificate authority")
+		return RootResult{}, fmt.Errorf("provider is not the root certificate authority")
 	}
 
 	// Set up the root PKI backend if necessary.
-	rootPEM, err := v.ActiveRoot()
+	rootPEM, err := v.getCA(v.config.RootPKIPath)
 	switch err {
 	case ErrBackendNotMounted:
 		err := v.client.Sys().Mount(v.config.RootPKIPath, &vaultapi.MountInput{
@@ -247,14 +243,14 @@ func (v *VaultProvider) GenerateRoot() error {
 			},
 		})
 		if err != nil {
-			return err
+			return RootResult{}, err
 		}
 
 		fallthrough
 	case ErrBackendNotInitialized:
 		uid, err := connect.CompactUID()
 		if err != nil {
-			return err
+			return RootResult{}, err
 		}
 		_, err = v.client.Logical().Write(v.config.RootPKIPath+"root/generate/internal", map[string]interface{}{
 			"common_name": connect.CACN("vault", uid, v.clusterID, v.isPrimary),
@@ -263,17 +259,25 @@ func (v *VaultProvider) GenerateRoot() error {
 			"key_bits":    v.config.PrivateKeyBits,
 		})
 		if err != nil {
-			return err
+			return RootResult{}, err
+		}
+
+		// retrieve the newly generated cert so that we can return it
+		// TODO: is this already available from the Local().Write() above?
+		rootPEM, err = v.getCA(v.config.RootPKIPath)
+		if err != nil {
+			return RootResult{}, err
 		}
+
 	default:
 		if err != nil {
-			return err
+			return RootResult{}, err
 		}
 
 		if rootPEM != "" {
 			rootCert, err := connect.ParseCert(rootPEM)
 			if err != nil {
-				return err
+				return RootResult{}, err
 			}
 
 			// Vault PKI doesn't allow in-place cert/key regeneration. That
@@ -285,18 +289,18 @@ func (v *VaultProvider) GenerateRoot() error {
 			// ForceWithoutCrossSigning option when changing key types.
 			foundKeyType, foundKeyBits, err := connect.KeyInfoFromCert(rootCert)
 			if err != nil {
-				return err
+				return RootResult{}, err
 			}
 			if v.config.PrivateKeyType != foundKeyType {
-				return fmt.Errorf("cannot update the PrivateKeyType field without choosing a new PKI mount for the root CA")
+				return RootResult{}, fmt.Errorf("cannot update the PrivateKeyType field without choosing a new PKI mount for the root CA")
 			}
 			if v.config.PrivateKeyBits != foundKeyBits {
-				return fmt.Errorf("cannot update the PrivateKeyBits field without choosing a new PKI mount for the root CA")
+				return RootResult{}, fmt.Errorf("cannot update the PrivateKeyBits field without choosing a new PKI mount for the root CA")
 			}
 		}
 	}
 
-	return nil
+	return RootResult{PEM: rootPEM}, nil
 }
 
 // GenerateIntermediateCSR creates a private key and generates a CSR
@@ -574,7 +578,7 @@ func (v *VaultProvider) SignIntermediate(csr *x509.CertificateRequest) (string,
 // CrossSignCA takes a CA certificate and cross-signs it to form a trust chain
 // back to our active root.
 func (v *VaultProvider) CrossSignCA(cert *x509.Certificate) (string, error) {
-	rootPEM, err := v.ActiveRoot()
+	rootPEM, err := v.getCA(v.config.RootPKIPath)
 	if err != nil {
 		return "", err
 	}
diff --git a/agent/connect/ca/provider_vault_test.go b/agent/connect/ca/provider_vault_test.go
index bba2cd04ad..4605073831 100644
--- a/agent/connect/ca/provider_vault_test.go
+++ b/agent/connect/ca/provider_vault_test.go
@@ -238,7 +238,10 @@ func TestVaultCAProvider_Bootstrap(t *testing.T) {
 		expectedRootCertTTL string
 	}{
 		{
-			certFunc:            providerWDefaultRootCertTtl.ActiveRoot,
+			certFunc: func() (string, error) {
+				root, err := providerWDefaultRootCertTtl.GenerateRoot()
+				return root.PEM, err
+			},
 			backendPath:         "pki-root/",
 			rootCaCreation:      true,
 			client:              client1,
@@ -323,8 +326,9 @@ func TestVaultCAProvider_SignLeaf(t *testing.T) {
 				Service:    "foo",
 			}
 
-			rootPEM, err := provider.ActiveRoot()
+			root, err := provider.GenerateRoot()
 			require.NoError(t, err)
+			rootPEM := root.PEM
 			assertCorrectKeyType(t, tc.KeyType, rootPEM)
 
 			intPEM, err := provider.ActiveIntermediate()
@@ -407,9 +411,9 @@ func TestVaultCAProvider_CrossSignCA(t *testing.T) {
 			defer testVault1.Stop()
 
 			{
-				rootPEM, err := provider1.ActiveRoot()
+				root, err := provider1.GenerateRoot()
 				require.NoError(t, err)
-				assertCorrectKeyType(t, tc.SigningKeyType, rootPEM)
+				assertCorrectKeyType(t, tc.SigningKeyType, root.PEM)
 
 				intPEM, err := provider1.ActiveIntermediate()
 				require.NoError(t, err)
@@ -424,9 +428,9 @@ func TestVaultCAProvider_CrossSignCA(t *testing.T) {
 			defer testVault2.Stop()
 
 			{
-				rootPEM, err := provider2.ActiveRoot()
+				root, err := provider2.GenerateRoot()
 				require.NoError(t, err)
-				assertCorrectKeyType(t, tc.CSRKeyType, rootPEM)
+				assertCorrectKeyType(t, tc.CSRKeyType, root.PEM)
 
 				intPEM, err := provider2.ActiveIntermediate()
 				require.NoError(t, err)
@@ -492,7 +496,8 @@ func TestVaultProvider_SignIntermediateConsul(t *testing.T) {
 		delegate := newMockDelegate(t, conf)
 		provider1 := TestConsulProvider(t, delegate)
 		require.NoError(t, provider1.Configure(testProviderConfig(conf)))
-		require.NoError(t, provider1.GenerateRoot())
+		_, err := provider1.GenerateRoot()
+		require.NoError(t, err)
 
 		// Ensure that we don't configure vault to try and mint leafs that
 		// outlive their CA during the test (which hard fails in vault).
@@ -786,8 +791,9 @@ func createVaultProvider(t *testing.T, isPrimary bool, addr, token string, rawCo
 	t.Cleanup(provider.Stop)
 	require.NoError(t, provider.Configure(cfg))
 	if isPrimary {
-		require.NoError(t, provider.GenerateRoot())
-		_, err := provider.GenerateIntermediate()
+		_, err := provider.GenerateRoot()
+		require.NoError(t, err)
+		_, err = provider.GenerateIntermediate()
 		require.NoError(t, err)
 	}
 
diff --git a/agent/consul/leader_connect_ca.go b/agent/consul/leader_connect_ca.go
index 51525f507e..203d3f2a40 100644
--- a/agent/consul/leader_connect_ca.go
+++ b/agent/consul/leader_connect_ca.go
@@ -482,16 +482,12 @@ func (c *CAManager) primaryInitialize(provider ca.Provider, conf *structs.CAConf
 	if err := provider.Configure(pCfg); err != nil {
 		return fmt.Errorf("error configuring provider: %v", err)
 	}
-	if err := provider.GenerateRoot(); err != nil {
+	root, err := provider.GenerateRoot()
+	if err != nil {
 		return fmt.Errorf("error generating CA root certificate: %v", err)
 	}
 
-	// Get the active root cert from the CA
-	rootPEM, err := provider.ActiveRoot()
-	if err != nil {
-		return fmt.Errorf("error getting root cert: %v", err)
-	}
-	rootCA, err := parseCARoot(rootPEM, conf.Provider, conf.ClusterID)
+	rootCA, err := parseCARoot(root.PEM, conf.Provider, conf.ClusterID)
 	if err != nil {
 		return err
 	}
@@ -863,15 +859,12 @@ func (c *CAManager) UpdateConfiguration(args *structs.CARequest) (reterr error)
 }
 
 func (c *CAManager) primaryUpdateRootCA(newProvider ca.Provider, args *structs.CARequest, config *structs.CAConfiguration) error {
-	if err := newProvider.GenerateRoot(); err != nil {
-		return fmt.Errorf("error generating CA root certificate: %v", err)
-	}
-
-	newRootPEM, err := newProvider.ActiveRoot()
+	providerRoot, err := newProvider.GenerateRoot()
 	if err != nil {
-		return err
+		return fmt.Errorf("error generating CA root certificate: %v", err)
 	}
 
+	newRootPEM := providerRoot.PEM
 	newActiveRoot, err := parseCARoot(newRootPEM, args.Config.Provider, args.Config.ClusterID)
 	if err != nil {
 		return err
@@ -925,6 +918,7 @@ func (c *CAManager) primaryUpdateRootCA(newProvider ca.Provider, args *structs.C
 		// get a cross-signed certificate.
 		// 3. Take the active root for the new provider and append the intermediate from step 2
 		// to its list of intermediates.
+		// TODO: this cert is already parsed once in parseCARoot, could we remove the second parse?
 		newRoot, err := connect.ParseCert(newRootPEM)
 		if err != nil {
 			return err
diff --git a/agent/consul/leader_connect_ca_test.go b/agent/consul/leader_connect_ca_test.go
index 5e5e1de59d..17b310cb6a 100644
--- a/agent/consul/leader_connect_ca_test.go
+++ b/agent/consul/leader_connect_ca_test.go
@@ -227,9 +227,8 @@ type mockCAProvider struct {
 
 func (m *mockCAProvider) Configure(cfg ca.ProviderConfig) error { return nil }
 func (m *mockCAProvider) State() (map[string]string, error)     { return nil, nil }
-func (m *mockCAProvider) GenerateRoot() error                   { return nil }
-func (m *mockCAProvider) ActiveRoot() (string, error) {
-	return m.rootPEM, nil
+func (m *mockCAProvider) GenerateRoot() (ca.RootResult, error) {
+	return ca.RootResult{PEM: m.rootPEM}, nil
 }
 func (m *mockCAProvider) GenerateIntermediateCSR() (string, error) {
 	m.callbackCh <- "provider/GenerateIntermediateCSR"

From ed6fd46edbd61ce3db079a7354d6baa3ac5672fb Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 10:31:02 -0800
Subject: [PATCH 82/98] reordered the installation steps

---
 website/content/docs/api-gateway.mdx | 23 ++++++++---------------
 1 file changed, 8 insertions(+), 15 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index a3a0826eca..95ef1bc5f6 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -24,6 +24,12 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
 ## Installation
 
+1. Issue the following command to install the Consul API Gateway controller:
+
+```shell-session
+$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
+```
+
 1. Create a values file for your Consul server agents that contains the following parameters:
 
   <CodeBlockConfig hideClipboard filename="values.yaml">
@@ -45,27 +51,14 @@ controller:
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
 ```shell-session
-$ helm install consul hashicorp/consul --version 0.39.0 --values values.yaml
-```
-
-The following components will be installed:
-
-     - Gateway controller
-     - CRDs required by the Kubernetes Gateway API specification
-     - `kustomize` manifests for completing the installation
-
-1. After `helm` installs Consul API Gateway packages, issue the following commands to apply the API gateway to your Kubernetes cluster:
-
-```shell-session
-$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
-$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config?ref=v0.1.0-beta"
+$ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
 ```
 
 ## Usage
 
 1. Verify that the [requirements](#requirements) have been met.
 1. Verify that the Consul API Gateway software has been installed and applied (see [Installation](#installation)).
-1. Configure the gateway, listener(s), and route(s) as described in [Configuration](#configuration).
+1. Configure the artifacts described in [Configuration](#configuration).
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
 ```shell-session

From 9d1fbd871c534f02b40827e2e40a3cf9f655329d Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 10:33:39 -0800
Subject: [PATCH 83/98] fixed formatting

---
 website/content/docs/api-gateway.mdx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 95ef1bc5f6..94ee3818c3 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -31,8 +31,7 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?
 ```
 
 1. Create a values file for your Consul server agents that contains the following parameters:
-
-  <CodeBlockConfig hideClipboard filename="values.yaml">
+   <CodeBlockConfig hideClipboard filename="values.yaml">
 
 ```yaml
 global:

From 5d1560560dc246e48c315a7ab77462a87665484d Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 10:44:14 -0800
Subject: [PATCH 84/98] removed extra quotation mark typo

---
 website/content/docs/api-gateway.mdx | 35 ++++++++++++++--------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 94ee3818c3..261fb2d239 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -31,27 +31,28 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?
 ```
 
 1. Create a values file for your Consul server agents that contains the following parameters:
-   <CodeBlockConfig hideClipboard filename="values.yaml">
 
-```yaml
-global:
-  name: consul
-  image: 'hashicorp/consul:1.11.2'
-  tls:
-    enabled: true
-connectInject:
-  enabled: true
-controller:
-  enabled: true
-```
-
-  </CodeBlockConfig>
+    <CodeBlockConfig hideClipboard filename="values.yaml">
+
+   ```yaml
+   global:
+     name: consul
+     image: 'hashicorp/consul:1.11.2'
+     tls:
+       enabled: true
+   connectInject:
+     enabled: true
+   controller:
+     enabled: true
+   ```
+
+````
+</CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
-
 ```shell-session
 $ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
-```
+````
 
 ## Usage
 
@@ -252,7 +253,7 @@ Add the `listener` object to the `gateway` configuration and specify the followi
 | `tls.certificateRefs`           | Specifies the name of secret object used for Envoy SDS (Secret Discovery Service) to support terminating TLS. Refer to the [`[]*SecretObjectReference` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference) for additional information.                                                                                                                                                                                                                                                                                                                                                                                                                        | String  | N/A             |
 | `tls.options`                   | Specifies key/value pairs to enable extended TLS configuration specific to an implementation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Object  | N/A             |
 | `tls.options.tls_min_version`   | Specifies the minimum TLS version supported for the listener. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | String  | `TLS 1.2`       |
-| `tls.options.tls_max_version"`  | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | String  | `TLS 1.3`       |
+| `tls.options.tls_max_version`   | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | String  | `TLS 1.3`       |
 | `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier. <br/>If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites) will be used. <br/>The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String  | See description |
 
 Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener) for details about configuring listeners.

From f74921283e46b7a75a5a7fdc36a447a9a59f19dc Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 10:55:13 -0800
Subject: [PATCH 85/98] still trying to fix formatting

---
 website/content/docs/api-gateway.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 261fb2d239..0e6d1e233f 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -32,7 +32,7 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?
 
 1. Create a values file for your Consul server agents that contains the following parameters:
 
-    <CodeBlockConfig hideClipboard filename="values.yaml">
+   <CodeBlockConfig hideClipboard filename="values.yaml">
 
    ```yaml
    global:
@@ -46,13 +46,13 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?
      enabled: true
    ```
 
-````
-</CodeBlockConfig>
+   </CodeBlockConfig>
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
+
 ```shell-session
 $ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
-````
+```
 
 ## Usage
 

From 61b30afa72b6074a2e23dacbf42bfef5b4043069 Mon Sep 17 00:00:00 2001
From: Thomas Kula <thomas@hashicorp.com>
Date: Thu, 27 Jan 2022 14:28:12 -0500
Subject: [PATCH 86/98] Fix #service-rules link in reference table

---
 website/content/docs/security/acl/acl-rules.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx
index f104458e68..a8899ce92d 100644
--- a/website/content/docs/security/acl/acl-rules.mdx
+++ b/website/content/docs/security/acl/acl-rules.mdx
@@ -329,7 +329,7 @@ The following table provides an overview of the resources you can use to create
 | `node`<br/>`node_prefix` &nbsp; | Controls access to node-level registration and read access to the [Catalog API](/api/catalog). <br/>See [Node Rules](#node-rules) for details. | Yes      |
 | `operator` &nbsp; &nbsp; &nbsp; | Controls access to cluster-level operations available in the [Operator API](/api/operator) excluding keyring API endpoints. <br/>See [Operator Rules](#operator-rules) for details. | No      |
 | `query`<br/>`query_prefix` | Controls access to create, update, and delete prepared queries in the [Prepared Query API](/api/query). Access to the [node](#node-rules) and [service](#service-rules) must also be granted. <br/>See [Prepared Query Rules](#prepared-query-rules) for details. | Yes      |
-| `service`<br/>`service_prefix` | Controls service-level registration and read access to the [Catalog API](/api/catalog), as well as service discovery with the [Health API](/api/health). <br/>See [Service Rules](#node-rules) for details. | Yes      |
+| `service`<br/>`service_prefix` | Controls service-level registration and read access to the [Catalog API](/api/catalog), as well as service discovery with the [Health API](/api/health). <br/>See [Service Rules](#service-rules) for details. | Yes      |
 | `session`<br/>`session_prefix` | Controls access to operations in the [Session API](/api/session). <br/>See [Session Rules](#session-rules) for details. | Yes      |
 
 The following topics provide additional details about the available resources.

From 7c65dec35a2ff36f97b2c01bb36766cccd793527 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 11:46:14 -0800
Subject: [PATCH 87/98] fixed formatting, applied Jeff's feedback

---
 website/content/docs/api-gateway.mdx | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 0e6d1e233f..accaa80001 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -10,7 +10,7 @@ This topic describes how to use the Consul API Gateway add-on module, which help
 
 ## Introduction
 
-Consul API Gateway is an implementation of the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases:
+Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases:
 
 - **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., Verisign, Let’s Encrypt).
 - **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH).
@@ -26,10 +26,14 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
 1. Issue the following command to install the Consul API Gateway controller:
 
+  <CodeBlockConfig>
+
 ```shell-session
 $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
 ```
 
+  </CodeBlockConfig>
+
 1. Create a values file for your Consul server agents that contains the following parameters:
 
    <CodeBlockConfig hideClipboard filename="values.yaml">
@@ -50,10 +54,14 @@ $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
+  <CodeBlockConfig>
+
 ```shell-session
 $ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
 ```
 
+  </CodeBlockConfig>
+
 ## Usage
 
 1. Verify that the [requirements](#requirements) have been met.
@@ -61,10 +69,14 @@ $ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
 1. Configure the artifacts described in [Configuration](#configuration).
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
+  <CodeBlockConfig>
+
 ```shell-session
 $ kubectl apply --values gateway-configuration.yaml
 ```
 
+  </CodeBlockConfig>
+
 <!--- Commented out per https://github.com/hashicorp/consul/pull/11951/files#r791204596
 
 ### Using the Consul API Gateway Binary

From f8597000316adcd177fe34fd34d1a948249c7641 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 12:02:48 -0800
Subject: [PATCH 88/98] formatting

---
 website/content/docs/api-gateway.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index accaa80001..f1f01a76f5 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -29,7 +29,7 @@ Your datacenter must meet the following requirements prior to configuring the Co
   <CodeBlockConfig>
 
 ```shell-session
-$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
+kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
 ```
 
   </CodeBlockConfig>

From 9e4fa4d9acd4c25c394f94aa29df09a9d209ca1a Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 12:21:19 -0800
Subject: [PATCH 89/98] added link to tutorial

---
 website/content/docs/api-gateway.mdx | 32 +++++++++++++++-------------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index f1f01a76f5..1ff61615f5 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -8,6 +8,8 @@ description: Using Consul API gateway functionality
 
 This topic describes how to use the Consul API Gateway add-on module, which helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol.
 
+You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway).
+
 ## Introduction
 
 Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases:
@@ -26,13 +28,13 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
 1. Issue the following command to install the Consul API Gateway controller:
 
-  <CodeBlockConfig>
+   <CodeBlockConfig>
 
-```shell-session
-kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
-```
+   ```shell-session
+   $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
+   ```
 
-  </CodeBlockConfig>
+   </CodeBlockConfig>
 
 1. Create a values file for your Consul server agents that contains the following parameters:
 
@@ -54,13 +56,13 @@ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?re
 
 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file.
 
-  <CodeBlockConfig>
+   <CodeBlockConfig>
 
-```shell-session
-$ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
-```
+   ```shell-session
+   $ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
+   ```
 
-  </CodeBlockConfig>
+   </CodeBlockConfig>
 
 ## Usage
 
@@ -69,13 +71,13 @@ $ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml
 1. Configure the artifacts described in [Configuration](#configuration).
 1. Issue the `kubectl apply` command to implement the configurations, e.g.:
 
-  <CodeBlockConfig>
+   <CodeBlockConfig>
 
-```shell-session
-$ kubectl apply --values gateway-configuration.yaml
-```
+   ```shell-session
+   $ kubectl apply --values gateway-configuration.yaml
+   ```
 
-  </CodeBlockConfig>
+   </CodeBlockConfig>
 
 <!--- Commented out per https://github.com/hashicorp/consul/pull/11951/files#r791204596
 

From 97e79e99dbbcd9047e45c5ef237c2b32ee9347ec Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 13:02:21 -0800
Subject: [PATCH 90/98] more feedback about helm chart from Jeff

---
 website/content/docs/api-gateway.mdx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 1ff61615f5..56c23ae194 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -23,6 +23,7 @@ Your datacenter must meet the following requirements prior to configuring the Co
 
 - A Kubernetes cluster must be running
 - Consul 1.11.2+
+- HashiCorp Helm chart 0.40.0+
 
 ## Installation
 
@@ -50,6 +51,9 @@ Your datacenter must meet the following requirements prior to configuring the Co
      enabled: true
    controller:
      enabled: true
+   apiGateway:
+     enabled: true
+     image: hashicorp/consul-api-gateway:0.1.0-beta
    ```
 
    </CodeBlockConfig>

From ea375742e138a60d8363caa95129c9c6cf076a41 Mon Sep 17 00:00:00 2001
From: Iryna Shustava <ishustava@users.noreply.github.com>
Date: Thu, 27 Jan 2022 14:25:06 -0700
Subject: [PATCH 91/98] docs: Add annotations for consul-sidecar resource
 overrides (#12142)

---
 website/content/docs/k8s/connect/index.mdx | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/website/content/docs/k8s/connect/index.mdx b/website/content/docs/k8s/connect/index.mdx
index eacd1ed5f7..6e825816e7 100644
--- a/website/content/docs/k8s/connect/index.mdx
+++ b/website/content/docs/k8s/connect/index.mdx
@@ -358,6 +358,15 @@ Pod annotations can be used to configure the injection behavior.
   - `consul.hashicorp.com/sidecar-proxy-memory-limit` - Override the default memory limit.
   - `consul.hashicorp.com/sidecar-proxy-memory-request` - Override the default memory request.
 
+- `consul.hashicorp.com/consul-sidecar-` - Override default resource settings for
+the `consul-sidecar` container.
+The defaults are set in Helm config via the [`global.consulSidecarContainer.resources`](/docs/k8s/helm#v-global-consulsidecarcontainer) key.
+
+  - `consul.hashicorp.com/consul-sidecar-cpu-limit` - Override the default CPU limit.
+  - `consul.hashicorp.com/consul-sidecar-cpu-request` - Override the default CPU request.
+  - `consul.hashicorp.com/consul-sidecar-memory-limit` - Override the default memory limit.
+  - `consul.hashicorp.com/consul-sidecar-memory-request` - Override the default memory request.
+
 - `consul.hashicorp.com/enable-metrics` - Override the default Helm value [`connectInject.metrics.defaultEnabled`](/docs/k8s/helm#v-connectinject-metrics-defaultenabled).
 - `consul.hashicorp.com/enable-metrics-merging` - Override the default Helm value [`connectInject.metrics.defaultEnableMerging`](/docs/k8s/helm#v-connectinject-metrics-defaultenablemerging).
 - `consul.hashicorp.com/merged-metrics-port` - Override the default Helm value [`connectInject.metrics.defaultMergedMetricsPort`](/docs/k8s/helm#v-connectinject-metrics-defaultmergedmetricsport).

From 98a280ef9aaae65ae57e3e0f42e3a00fb7d9ca73 Mon Sep 17 00:00:00 2001
From: trujillo-adam <ajosetru@gmail.com>
Date: Thu, 27 Jan 2022 13:31:03 -0800
Subject: [PATCH 92/98] added min supported kubectl

---
 website/content/docs/api-gateway.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx
index 56c23ae194..229ba0e9ec 100644
--- a/website/content/docs/api-gateway.mdx
+++ b/website/content/docs/api-gateway.mdx
@@ -22,6 +22,7 @@ Consul API Gateway implements the Kubernetes [Gateway API Specification](https:/
 Your datacenter must meet the following requirements prior to configuring the Consul API Gateway:
 
 - A Kubernetes cluster must be running
+- `kubectl` 1.21+
 - Consul 1.11.2+
 - HashiCorp Helm chart 0.40.0+
 

From 081cc68fd8005b271bc17a9a2ebb3939fb47bfb6 Mon Sep 17 00:00:00 2001
From: Karl Cardenas <kcardenas@hashicorp.com>
Date: Thu, 27 Jan 2022 19:52:42 -0700
Subject: [PATCH 93/98] fixing a confusing sentence in network segments page

---
 website/content/docs/enterprise/network-segments.mdx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/website/content/docs/enterprise/network-segments.mdx b/website/content/docs/enterprise/network-segments.mdx
index e769a60a3d..f7c011c5c0 100644
--- a/website/content/docs/enterprise/network-segments.mdx
+++ b/website/content/docs/enterprise/network-segments.mdx
@@ -52,8 +52,7 @@ in their local cluster through the gossip mechanism and make RPC requests to
 them. LAN Gossip (OSS) is an open intra-cluster networking model, and Network
 Segments (Enterprise) creates multiple segments within one cluster.
 
-**Federated Cluster:** A cluster of clusters with a Consul server group per
-cluster each set per "datacenter". These Consul servers are federated together
+**Federated Cluster:** A set of connected clusters, each representing a unique Consul “datacenter”. These Consul servers are federated together
 over the WAN. Consul clients make use of resources in federated clusters by
 forwarding RPCs through the Consul servers in their local cluster, but they
 never interact with remote Consul servers directly. There are currently two

From c1cb58bdcbafcf1db8eb43dddf8eb592d09c4fbe Mon Sep 17 00:00:00 2001
From: Dan Upton <daniel@floppy.co>
Date: Fri, 28 Jan 2022 10:57:37 +0000
Subject: [PATCH 94/98] docs: add transparent proxy visual aid (#12211)

Co-authored-by: Paul Banks <banks@banksco.de>
---
 .../docs/connect/transparent-proxy.mdx        |  29 ++++++
 .../consul-connect/with-transparent-proxy.png | Bin 0 -> 65601 bytes
 .../consul-connect/with-transparent-proxy.svg |  98 ++++++++++++++++++
 .../without-transparent-proxy.png             | Bin 0 -> 41372 bytes
 .../without-transparent-proxy.svg             |  82 +++++++++++++++
 5 files changed, 209 insertions(+)
 create mode 100644 website/public/img/consul-connect/with-transparent-proxy.png
 create mode 100644 website/public/img/consul-connect/with-transparent-proxy.svg
 create mode 100644 website/public/img/consul-connect/without-transparent-proxy.png
 create mode 100644 website/public/img/consul-connect/without-transparent-proxy.svg

diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx
index 54c672a9b1..5ddc21e2d4 100644
--- a/website/content/docs/connect/transparent-proxy.mdx
+++ b/website/content/docs/connect/transparent-proxy.mdx
@@ -9,6 +9,35 @@ description: |-
 
 # Transparent Proxy
 
+Transparent proxy allows applications to communicate through the mesh without changing their configuration.
+Transparent proxy also hardens application security by preventing direct inbound connections that bypass the mesh.
+
+#### Without Transparent Proxy
+
+![Diagram demonstrating that without transparent proxy, applications must "opt in" to connecting to their dependencies through the mesh](/img/consul-connect/without-transparent-proxy.png)
+
+Without transparent proxy, application owners need to:
+
+1. Explicitly configure upstream services, choosing a local port to access them.
+1. Change application to access `localhost:<chosen port>`.
+1. Configure application to listen only on the loopback interface to prevent unauthorized
+   traffic from bypassing the mesh.
+
+#### With Transparent Proxy
+
+![Diagram demonstrating that with transparent proxy, connections are automatically routed through the mesh](/img/consul-connect/with-transparent-proxy.png)
+
+With transparent proxy:
+
+1. Upstreams are inferred from service intentions, so no explicit configuration
+   is needed.
+1. Outbound connections pointing to a KubeDNS name "just work" — network rules
+   redirect them through the proxy.
+1. Inbound traffic is forced to go through the proxy to prevent unauthorized
+   direct access to the application.
+
+#### Overview
+
 Transparent proxy allows users to reach other services in the service mesh while ensuring that inbound and outbound
 traffic for services in the mesh are directed through the sidecar proxy. Traffic is secured
 and only reaches intended destinations since the proxy can enforce security and policy like TLS and Service Intentions.
diff --git a/website/public/img/consul-connect/with-transparent-proxy.png b/website/public/img/consul-connect/with-transparent-proxy.png
new file mode 100644
index 0000000000000000000000000000000000000000..1c51d88db2cf69dba2e82a42adfa6337f606ccc9
GIT binary patch
literal 65601
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%0A$nprmk0e&!~t+lC<k1viw8ewWG4}xb^mJ
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

literal 0
HcmV?d00001

diff --git a/website/public/img/consul-connect/with-transparent-proxy.svg b/website/public/img/consul-connect/with-transparent-proxy.svg
new file mode 100644
index 0000000000..54bfa07350
--- /dev/null
+++ b/website/public/img/consul-connect/with-transparent-proxy.svg
@@ -0,0 +1,98 @@
+<svg width="538" height="360" viewBox="0 0 538 360" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M432.75 55.3228H534C535.795 55.3228 537.25 56.7778 537.25 58.5728V347.204C537.25 348.998 535.795 350.454 534 350.454H432.75V55.3228Z" stroke="#D2D4DB" stroke-width="1.5"/>
+<path d="M434 54.5728H422C419.791 54.5728 418 56.3636 418 58.5728V347.204C418 349.413 419.791 351.204 422 351.204H434V54.5728Z" fill="url(#paint0_linear_0_1)"/>
+<path d="M138.75 58.5728C138.75 56.7778 140.205 55.3228 142 55.3228H243.25V350.454H142C140.205 350.454 138.75 348.998 138.75 347.204V58.5728Z" stroke="#D2D4DB" stroke-width="1.5"/>
+<rect x="150" y="46.5011" width="42" height="16.1432" fill="white"/>
+<rect x="444" y="46.5011" width="42" height="16.1432" fill="white"/>
+<path d="M157.497 46.1475C158.51 46.1475 159.249 46.3659 159.715 46.8027C160.18 47.236 160.413 47.834 160.413 48.5967C160.413 48.9404 160.361 49.2699 160.257 49.585C160.153 49.8965 159.983 50.174 159.747 50.4175C159.514 50.661 159.203 50.8543 158.812 50.9976C158.422 51.1372 157.941 51.207 157.368 51.207H156.653V54H154.988V46.1475H157.497ZM157.411 47.5117H156.653V49.8428H157.201C157.513 49.8428 157.783 49.8016 158.012 49.7192C158.241 49.6369 158.419 49.508 158.544 49.3325C158.669 49.1571 158.732 48.9315 158.732 48.6558C158.732 48.269 158.625 47.9826 158.41 47.7964C158.195 47.6066 157.862 47.5117 157.411 47.5117ZM169.023 50.063C169.023 50.6681 168.948 51.2196 168.797 51.7173C168.647 52.2114 168.418 52.6375 168.11 52.9956C167.806 53.3537 167.419 53.6294 166.95 53.8228C166.481 54.0125 165.926 54.1074 165.285 54.1074C164.644 54.1074 164.089 54.0125 163.62 53.8228C163.151 53.6294 162.762 53.3537 162.454 52.9956C162.15 52.6375 161.922 52.2096 161.772 51.7119C161.622 51.2142 161.546 50.661 161.546 50.0522C161.546 49.2394 161.679 48.5322 161.944 47.9307C162.212 47.3255 162.624 46.8564 163.179 46.5234C163.734 46.1904 164.44 46.0239 165.295 46.0239C166.148 46.0239 166.848 46.1904 167.396 46.5234C167.947 46.8564 168.355 47.3255 168.62 47.9307C168.889 48.5358 169.023 49.2466 169.023 50.063ZM163.292 50.063C163.292 50.6108 163.36 51.0835 163.496 51.481C163.636 51.8748 163.852 52.1792 164.146 52.394C164.44 52.6053 164.819 52.7109 165.285 52.7109C165.757 52.7109 166.14 52.6053 166.434 52.394C166.728 52.1792 166.941 51.8748 167.073 51.481C167.209 51.0835 167.277 50.6108 167.277 50.063C167.277 49.2394 167.123 48.5913 166.815 48.1187C166.507 47.646 166.001 47.4097 165.295 47.4097C164.826 47.4097 164.443 47.5171 164.146 47.7319C163.852 47.9432 163.636 48.2476 163.496 48.645C163.36 49.0389 163.292 49.5116 163.292 50.063ZM177.166 49.9985C177.166 50.883 176.995 51.6224 176.655 52.2168C176.319 52.8076 175.83 53.2534 175.189 53.5542C174.548 53.8514 173.776 54 172.874 54H170.65V46.1475H173.116C173.939 46.1475 174.654 46.2943 175.259 46.5879C175.864 46.8779 176.333 47.3094 176.666 47.8823C176.999 48.4517 177.166 49.1571 177.166 49.9985ZM175.436 50.0415C175.436 49.4614 175.35 48.9852 175.178 48.6128C175.01 48.2368 174.759 47.9593 174.426 47.7803C174.097 47.6012 173.689 47.5117 173.202 47.5117H172.315V52.625H173.03C173.843 52.625 174.446 52.4084 174.84 51.9751C175.237 51.5418 175.436 50.8973 175.436 50.0415ZM186.458 54L185.888 52.1309H183.025L182.456 54H180.662L183.434 46.1152H185.469L188.251 54H186.458ZM185.491 50.7344L184.921 48.9082C184.886 48.7865 184.837 48.6307 184.776 48.4409C184.719 48.2476 184.66 48.0524 184.599 47.8555C184.542 47.6549 184.495 47.4813 184.459 47.3345C184.424 47.4813 184.374 47.6639 184.309 47.8823C184.248 48.0972 184.189 48.3013 184.132 48.4946C184.075 48.688 184.033 48.8258 184.008 48.9082L183.444 50.7344H185.491Z" fill="#9194A0"/>
+<path d="M451.497 46.1475C452.51 46.1475 453.249 46.3659 453.715 46.8027C454.18 47.236 454.413 47.834 454.413 48.5967C454.413 48.9404 454.361 49.2699 454.257 49.585C454.153 49.8965 453.983 50.174 453.747 50.4175C453.514 50.661 453.203 50.8543 452.812 50.9976C452.422 51.1372 451.941 51.207 451.368 51.207H450.653V54H448.988V46.1475H451.497ZM451.411 47.5117H450.653V49.8428H451.201C451.513 49.8428 451.783 49.8016 452.012 49.7192C452.241 49.6369 452.419 49.508 452.544 49.3325C452.669 49.1571 452.732 48.9315 452.732 48.6558C452.732 48.269 452.625 47.9826 452.41 47.7964C452.195 47.6066 451.862 47.5117 451.411 47.5117ZM463.023 50.063C463.023 50.6681 462.948 51.2196 462.797 51.7173C462.647 52.2114 462.418 52.6375 462.11 52.9956C461.806 53.3537 461.419 53.6294 460.95 53.8228C460.481 54.0125 459.926 54.1074 459.285 54.1074C458.644 54.1074 458.089 54.0125 457.62 53.8228C457.151 53.6294 456.762 53.3537 456.454 52.9956C456.15 52.6375 455.922 52.2096 455.772 51.7119C455.622 51.2142 455.546 50.661 455.546 50.0522C455.546 49.2394 455.679 48.5322 455.944 47.9307C456.212 47.3255 456.624 46.8564 457.179 46.5234C457.734 46.1904 458.44 46.0239 459.295 46.0239C460.148 46.0239 460.848 46.1904 461.396 46.5234C461.947 46.8564 462.355 47.3255 462.62 47.9307C462.889 48.5358 463.023 49.2466 463.023 50.063ZM457.292 50.063C457.292 50.6108 457.36 51.0835 457.496 51.481C457.636 51.8748 457.852 52.1792 458.146 52.394C458.44 52.6053 458.819 52.7109 459.285 52.7109C459.757 52.7109 460.14 52.6053 460.434 52.394C460.728 52.1792 460.941 51.8748 461.073 51.481C461.209 51.0835 461.277 50.6108 461.277 50.063C461.277 49.2394 461.123 48.5913 460.815 48.1187C460.507 47.646 460.001 47.4097 459.295 47.4097C458.826 47.4097 458.443 47.5171 458.146 47.7319C457.852 47.9432 457.636 48.2476 457.496 48.645C457.36 49.0389 457.292 49.5116 457.292 50.063ZM471.166 49.9985C471.166 50.883 470.995 51.6224 470.655 52.2168C470.319 52.8076 469.83 53.2534 469.189 53.5542C468.548 53.8514 467.776 54 466.874 54H464.65V46.1475H467.116C467.939 46.1475 468.654 46.2943 469.259 46.5879C469.864 46.8779 470.333 47.3094 470.666 47.8823C470.999 48.4517 471.166 49.1571 471.166 49.9985ZM469.436 50.0415C469.436 49.4614 469.35 48.9852 469.178 48.6128C469.01 48.2368 468.759 47.9593 468.426 47.7803C468.097 47.6012 467.689 47.5117 467.202 47.5117H466.315V52.625H467.03C467.843 52.625 468.446 52.4084 468.84 51.9751C469.237 51.5418 469.436 50.8973 469.436 50.0415ZM475.65 46.1475H478.094C479.14 46.1475 479.931 46.2943 480.468 46.5879C481.005 46.8815 481.274 47.3971 481.274 48.1348C481.274 48.432 481.226 48.7005 481.129 48.9404C481.036 49.1803 480.9 49.3773 480.721 49.5312C480.542 49.6852 480.323 49.7855 480.065 49.832V49.8857C480.327 49.9395 480.563 50.0326 480.774 50.165C480.986 50.2939 481.154 50.4837 481.279 50.7344C481.408 50.9814 481.473 51.3109 481.473 51.7227C481.473 52.1989 481.356 52.6071 481.124 52.9473C480.891 53.2874 480.558 53.5488 480.125 53.7314C479.695 53.9105 479.183 54 478.588 54H475.65V46.1475ZM477.315 49.2573H478.282C478.766 49.2573 479.1 49.1821 479.287 49.0317C479.473 48.8778 479.566 48.6522 479.566 48.355C479.566 48.0542 479.455 47.8394 479.233 47.7104C479.014 47.578 478.667 47.5117 478.191 47.5117H477.315V49.2573ZM477.315 50.5786V52.625H478.4C478.902 52.625 479.251 52.5283 479.448 52.335C479.645 52.1416 479.743 51.882 479.743 51.5562C479.743 51.3628 479.7 51.1927 479.614 51.0459C479.528 50.8991 479.383 50.7845 479.179 50.7021C478.979 50.6198 478.701 50.5786 478.347 50.5786H477.315Z" fill="#9194A0"/>
+<path d="M154.75 86C154.75 85.3096 155.31 84.75 156 84.75H224C224.69 84.75 225.25 85.3096 225.25 86V154C225.25 154.69 224.69 155.25 224 155.25H156C155.31 155.25 154.75 154.69 154.75 154V86Z" fill="white" stroke="#D2D4DB" stroke-width="1.5"/>
+<rect x="172" y="101" width="36" height="37" rx="1" fill="white" stroke="black" stroke-width="2"/>
+<rect x="172" y="101" width="36" height="8" rx="1" fill="white" stroke="black" stroke-width="2"/>
+<path d="M186.965 126.766L180.156 123.752V122.591L186.947 119.187V121.188L182.781 123.085L186.947 124.817L186.965 126.766Z" fill="black"/>
+<path d="M193.521 118L189.865 128.1H187.535L191.199 118H193.521Z" fill="black"/>
+<path d="M194.016 124.791L198.182 123.059L194.016 121.197V119.196L200.807 122.6V123.752L194.016 126.766V124.791Z" fill="black"/>
+<path d="M188.046 166.434L185.867 175H183.798L182.638 170.5C182.615 170.414 182.583 170.283 182.544 170.107C182.505 169.932 182.464 169.74 182.421 169.533C182.378 169.322 182.339 169.125 182.304 168.941C182.273 168.754 182.251 168.605 182.24 168.496C182.228 168.605 182.204 168.752 182.169 168.936C182.138 169.119 182.101 169.314 182.058 169.521C182.019 169.729 181.98 169.922 181.941 170.102C181.902 170.281 181.87 170.418 181.847 170.512L180.693 175H178.63L176.445 166.434H178.232L179.327 171.109C179.359 171.25 179.394 171.418 179.433 171.613C179.476 171.809 179.517 172.014 179.556 172.229C179.599 172.439 179.636 172.645 179.667 172.844C179.702 173.039 179.728 173.209 179.744 173.354C179.763 173.205 179.788 173.033 179.82 172.838C179.851 172.639 179.884 172.438 179.919 172.234C179.958 172.027 179.997 171.836 180.036 171.66C180.076 171.484 180.111 171.342 180.142 171.232L181.39 166.434H183.107L184.355 171.232C184.382 171.338 184.413 171.48 184.449 171.66C184.488 171.836 184.527 172.027 184.566 172.234C184.605 172.441 184.64 172.645 184.671 172.844C184.706 173.039 184.732 173.209 184.747 173.354C184.775 173.158 184.812 172.922 184.859 172.645C184.91 172.363 184.962 172.084 185.017 171.807C185.076 171.529 185.126 171.297 185.169 171.109L186.259 166.434H188.046ZM194.298 175H189.364V166.434H194.298V167.922H191.181V169.803H194.081V171.291H191.181V173.5H194.298V175ZM196.331 166.434H198.997C200.138 166.434 201.001 166.594 201.587 166.914C202.173 167.234 202.466 167.797 202.466 168.602C202.466 168.926 202.413 169.219 202.307 169.48C202.206 169.742 202.057 169.957 201.862 170.125C201.667 170.293 201.429 170.402 201.147 170.453V170.512C201.432 170.57 201.69 170.672 201.921 170.816C202.151 170.957 202.335 171.164 202.472 171.438C202.612 171.707 202.682 172.066 202.682 172.516C202.682 173.035 202.556 173.48 202.302 173.852C202.048 174.223 201.684 174.508 201.212 174.707C200.743 174.902 200.184 175 199.536 175H196.331V166.434ZM198.147 169.826H199.202C199.729 169.826 200.095 169.744 200.298 169.58C200.501 169.412 200.602 169.166 200.602 168.842C200.602 168.514 200.481 168.279 200.239 168.139C200.001 167.994 199.622 167.922 199.102 167.922H198.147V169.826ZM198.147 171.268V173.5H199.331C199.878 173.5 200.259 173.395 200.474 173.184C200.688 172.973 200.796 172.689 200.796 172.334C200.796 172.123 200.749 171.938 200.655 171.777C200.561 171.617 200.403 171.492 200.181 171.402C199.962 171.312 199.659 171.268 199.272 171.268H198.147Z" fill="#6A6D7A"/>
+<path d="M449.75 86C449.75 85.3096 450.31 84.75 451 84.75L519 84.75C519.69 84.75 520.25 85.3096 520.25 86L520.25 154C520.25 154.69 519.69 155.25 519 155.25L451 155.25C450.31 155.25 449.75 154.69 449.75 154L449.75 86Z" fill="white" stroke="#D2D4DB" stroke-width="1.5"/>
+<path d="M499.999 109V130.281C499.999 131.913 498.658 133.654 495.873 135.047C493.146 136.41 489.306 137.281 485 137.281C480.694 137.281 476.853 136.41 474.127 135.047C471.342 133.654 470 131.913 470 130.281V109C470 107.368 471.342 105.627 474.127 104.234C476.853 102.871 480.694 102 485 102C489.306 102 493.146 102.871 495.873 104.234C498.658 105.627 499.999 107.368 499.999 109Z" fill="white" stroke="black" stroke-width="2" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<mask id="path-17-inside-1_0_1" fill="white">
+<path d="M500.999 119.64C500.999 124.067 493.854 127.64 485 127.64C476.145 127.64 469 124.067 469 119.64"/>
+</mask>
+<path d="M502.999 119.64C502.999 118.535 502.104 117.64 500.999 117.64C499.895 117.64 498.999 118.535 498.999 119.64H502.999ZM471 119.64C471 118.535 470.105 117.64 469 117.64C467.895 117.64 467 118.535 467 119.64H471ZM498.999 119.64C498.999 120.69 498.102 122.173 495.425 123.511C492.865 124.791 489.185 125.64 485 125.64V129.64C489.669 129.64 493.988 128.702 497.214 127.089C500.324 125.534 502.999 123.017 502.999 119.64H498.999ZM485 125.64C480.814 125.64 477.134 124.791 474.574 123.511C471.897 122.173 471 120.69 471 119.64H467C467 123.017 469.676 125.534 472.785 127.089C476.011 128.702 480.331 129.64 485 129.64V125.64Z" fill="black" mask="url(#path-17-inside-1_0_1)"/>
+<mask id="path-19-inside-2_0_1" fill="white">
+<path d="M500.999 108.763C500.999 113.19 493.854 116.763 485 116.763C476.145 116.763 469 113.19 469 108.763"/>
+</mask>
+<path d="M502.999 108.763C502.999 107.658 502.104 106.763 500.999 106.763C499.895 106.763 498.999 107.658 498.999 108.763H502.999ZM471 108.763C471 107.658 470.105 106.763 469 106.763C467.895 106.763 467 107.658 467 108.763H471ZM498.999 108.763C498.999 109.813 498.102 111.296 495.425 112.634C492.865 113.914 489.185 114.763 485 114.763V118.763C489.669 118.763 493.988 117.825 497.214 116.212C500.324 114.657 502.999 112.14 502.999 108.763H498.999ZM485 114.763C480.814 114.763 477.134 113.914 474.574 112.634C471.897 111.296 471 109.813 471 108.763H467C467 112.14 469.676 114.657 472.785 116.212C476.011 117.825 480.331 118.763 485 118.763V114.763Z" fill="black" mask="url(#path-19-inside-2_0_1)"/>
+<path d="M461.183 170.635C461.183 171.6 460.997 172.406 460.626 173.055C460.259 173.699 459.726 174.186 459.026 174.514C458.327 174.838 457.485 175 456.501 175H454.075V166.434H456.765C457.663 166.434 458.442 166.594 459.103 166.914C459.763 167.23 460.274 167.701 460.638 168.326C461.001 168.947 461.183 169.717 461.183 170.635ZM459.296 170.682C459.296 170.049 459.202 169.529 459.015 169.123C458.831 168.713 458.558 168.41 458.194 168.215C457.835 168.02 457.39 167.922 456.858 167.922H455.892V173.5H456.671C457.558 173.5 458.216 173.264 458.645 172.791C459.079 172.318 459.296 171.615 459.296 170.682ZM468.442 175L467.821 172.961H464.698L464.077 175H462.12L465.143 166.398H467.364L470.399 175H468.442ZM467.387 171.438L466.766 169.445C466.727 169.312 466.675 169.143 466.608 168.936C466.546 168.725 466.481 168.512 466.415 168.297C466.352 168.078 466.301 167.889 466.262 167.729C466.223 167.889 466.169 168.088 466.098 168.326C466.032 168.561 465.968 168.783 465.905 168.994C465.843 169.205 465.798 169.355 465.77 169.445L465.155 171.438H467.387ZM475.028 175H473.211V167.945H470.885V166.434H477.354V167.945H475.028V175ZM484.156 175L483.535 172.961H480.412L479.791 175H477.834L480.858 166.398H483.078L486.114 175H484.156ZM483.102 171.438L482.481 169.445C482.442 169.312 482.389 169.143 482.323 168.936C482.26 168.725 482.196 168.512 482.129 168.297C482.067 168.078 482.016 167.889 481.977 167.729C481.938 167.889 481.883 168.088 481.813 168.326C481.746 168.561 481.682 168.783 481.619 168.994C481.557 169.205 481.512 169.355 481.485 169.445L480.869 171.438H483.102ZM487.438 166.434H490.104C491.244 166.434 492.107 166.594 492.693 166.914C493.279 167.234 493.572 167.797 493.572 168.602C493.572 168.926 493.52 169.219 493.414 169.48C493.312 169.742 493.164 169.957 492.969 170.125C492.773 170.293 492.535 170.402 492.254 170.453V170.512C492.539 170.57 492.797 170.672 493.027 170.816C493.258 170.957 493.441 171.164 493.578 171.438C493.719 171.707 493.789 172.066 493.789 172.516C493.789 173.035 493.662 173.48 493.408 173.852C493.154 174.223 492.791 174.508 492.318 174.707C491.85 174.902 491.291 175 490.643 175H487.438V166.434ZM489.254 169.826H490.309C490.836 169.826 491.201 169.744 491.404 169.58C491.607 169.412 491.709 169.166 491.709 168.842C491.709 168.514 491.588 168.279 491.346 168.139C491.107 167.994 490.729 167.922 490.209 167.922H489.254V169.826ZM489.254 171.268V173.5H490.438C490.984 173.5 491.365 173.395 491.58 173.184C491.795 172.973 491.902 172.689 491.902 172.334C491.902 172.123 491.855 171.938 491.762 171.777C491.668 171.617 491.51 171.492 491.287 171.402C491.068 171.312 490.766 171.268 490.379 171.268H489.254ZM500.984 175L500.363 172.961H497.24L496.619 175H494.662L497.685 166.398H499.906L502.941 175H500.984ZM499.929 171.438L499.308 169.445C499.269 169.312 499.217 169.143 499.15 168.936C499.088 168.725 499.023 168.512 498.957 168.297C498.894 168.078 498.844 167.889 498.804 167.729C498.765 167.889 498.711 168.088 498.64 168.326C498.574 168.561 498.51 168.783 498.447 168.994C498.385 169.205 498.34 169.355 498.312 169.445L497.697 171.438H499.929ZM509.322 172.621C509.322 173.129 509.199 173.57 508.953 173.945C508.707 174.32 508.347 174.609 507.875 174.812C507.406 175.016 506.835 175.117 506.164 175.117C505.867 175.117 505.576 175.098 505.291 175.059C505.009 175.02 504.738 174.963 504.476 174.889C504.218 174.811 503.972 174.715 503.738 174.602V172.914C504.144 173.094 504.566 173.256 505.003 173.4C505.441 173.545 505.875 173.617 506.304 173.617C506.601 173.617 506.839 173.578 507.019 173.5C507.203 173.422 507.335 173.314 507.417 173.178C507.5 173.041 507.541 172.885 507.541 172.709C507.541 172.494 507.468 172.311 507.324 172.158C507.179 172.006 506.98 171.863 506.726 171.73C506.476 171.598 506.193 171.455 505.876 171.303C505.677 171.209 505.46 171.096 505.226 170.963C504.992 170.826 504.769 170.66 504.558 170.465C504.347 170.27 504.173 170.033 504.037 169.756C503.904 169.475 503.837 169.139 503.837 168.748C503.837 168.236 503.955 167.799 504.189 167.436C504.423 167.072 504.757 166.795 505.191 166.604C505.628 166.408 506.144 166.311 506.738 166.311C507.183 166.311 507.607 166.363 508.009 166.469C508.416 166.57 508.839 166.719 509.281 166.914L508.695 168.326C508.3 168.166 507.947 168.043 507.634 167.957C507.322 167.867 507.003 167.822 506.679 167.822C506.453 167.822 506.259 167.859 506.099 167.934C505.939 168.004 505.818 168.105 505.736 168.238C505.654 168.367 505.613 168.518 505.613 168.689C505.613 168.893 505.671 169.064 505.789 169.205C505.91 169.342 506.089 169.475 506.328 169.604C506.57 169.732 506.871 169.883 507.23 170.055C507.667 170.262 508.041 170.479 508.349 170.705C508.662 170.928 508.902 171.191 509.07 171.496C509.238 171.797 509.322 172.172 509.322 172.621ZM516.048 175H511.115V166.434H516.048V167.922H512.931V169.803H515.831V171.291H512.931V173.5H516.048V175Z" fill="#6A6D7A"/>
+<path d="M154.75 237C154.75 236.31 155.31 235.75 156 235.75H224C224.69 235.75 225.25 236.31 225.25 237V305C225.25 305.69 224.69 306.25 224 306.25H156C155.31 306.25 154.75 305.69 154.75 305V237Z" fill="white" stroke="#E07EAC" stroke-width="1.5"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M200 258L206 264L200 270" fill="white"/>
+<path d="M200 258L206 264M206 264L200 270M206 264H175" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M181 272L175 278L181 284" fill="white"/>
+<path d="M181 272L175 278M175 278L181 284M175 278H206" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M172.964 317.434C174.07 317.434 174.877 317.672 175.384 318.148C175.892 318.621 176.146 319.273 176.146 320.105C176.146 320.48 176.089 320.84 175.976 321.184C175.863 321.523 175.677 321.826 175.42 322.092C175.166 322.357 174.826 322.568 174.4 322.725C173.974 322.877 173.449 322.953 172.824 322.953H172.045V326H170.228V317.434H172.964ZM172.871 318.922H172.045V321.465H172.642C172.982 321.465 173.277 321.42 173.527 321.33C173.777 321.24 173.97 321.1 174.107 320.908C174.244 320.717 174.312 320.471 174.312 320.17C174.312 319.748 174.195 319.436 173.961 319.232C173.726 319.025 173.363 318.922 172.871 318.922ZM180.499 317.434C181.277 317.434 181.917 317.527 182.421 317.715C182.929 317.902 183.306 318.186 183.552 318.564C183.798 318.943 183.921 319.422 183.921 320C183.921 320.391 183.847 320.732 183.699 321.025C183.55 321.318 183.355 321.566 183.113 321.77C182.87 321.973 182.609 322.139 182.327 322.268L184.847 326H182.831L180.786 322.713H179.82V326H178.003V317.434H180.499ZM180.37 318.922H179.82V321.236H180.406C181.007 321.236 181.437 321.137 181.695 320.938C181.956 320.734 182.087 320.438 182.087 320.047C182.087 319.641 181.947 319.352 181.665 319.18C181.388 319.008 180.956 318.922 180.37 318.922ZM193.941 321.705C193.941 322.365 193.859 322.967 193.694 323.51C193.53 324.049 193.28 324.514 192.944 324.904C192.612 325.295 192.191 325.596 191.679 325.807C191.167 326.014 190.562 326.117 189.862 326.117C189.163 326.117 188.558 326.014 188.046 325.807C187.534 325.596 187.11 325.295 186.775 324.904C186.442 324.514 186.194 324.047 186.03 323.504C185.866 322.961 185.784 322.357 185.784 321.693C185.784 320.807 185.929 320.035 186.218 319.379C186.511 318.719 186.96 318.207 187.566 317.844C188.171 317.48 188.941 317.299 189.874 317.299C190.804 317.299 191.567 317.48 192.165 317.844C192.767 318.207 193.212 318.719 193.501 319.379C193.794 320.039 193.941 320.814 193.941 321.705ZM187.689 321.705C187.689 322.303 187.763 322.818 187.911 323.252C188.064 323.682 188.3 324.014 188.62 324.248C188.941 324.479 189.355 324.594 189.862 324.594C190.378 324.594 190.796 324.479 191.116 324.248C191.437 324.014 191.669 323.682 191.814 323.252C191.962 322.818 192.036 322.303 192.036 321.705C192.036 320.807 191.868 320.1 191.532 319.584C191.196 319.068 190.644 318.811 189.874 318.811C189.362 318.811 188.944 318.928 188.62 319.162C188.3 319.393 188.064 319.725 187.911 320.158C187.763 320.588 187.689 321.104 187.689 321.705ZM202.882 326H200.807L198.815 322.76L196.823 326H194.878L197.72 321.582L195.059 317.434H197.063L198.909 320.516L200.72 317.434H202.677L199.987 321.682L202.882 326ZM206.866 320.961L208.653 317.434H210.61L207.768 322.666V326H205.964V322.725L203.122 317.434H205.09L206.866 320.961Z" fill="#CA2171"/>
+<path d="M448.75 237C448.75 236.31 449.31 235.75 450 235.75H518C518.69 235.75 519.25 236.31 519.25 237V305C519.25 305.69 518.69 306.25 518 306.25H450C449.31 306.25 448.75 305.69 448.75 305V237Z" fill="white" stroke="#E07EAC" stroke-width="1.5"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M494 258L500 264L494 270" fill="white"/>
+<path d="M494 258L500 264M500 264L494 270M500 264H469" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M475 272L469 278L475 284" fill="white"/>
+<path d="M475 272L469 278M469 278L475 284M469 278H500" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M466.964 317.434C468.07 317.434 468.877 317.672 469.384 318.148C469.892 318.621 470.146 319.273 470.146 320.105C470.146 320.48 470.089 320.84 469.976 321.184C469.863 321.523 469.677 321.826 469.42 322.092C469.166 322.357 468.826 322.568 468.4 322.725C467.974 322.877 467.449 322.953 466.824 322.953H466.045V326H464.228V317.434H466.964ZM466.871 318.922H466.045V321.465H466.642C466.982 321.465 467.277 321.42 467.527 321.33C467.777 321.24 467.97 321.1 468.107 320.908C468.244 320.717 468.312 320.471 468.312 320.17C468.312 319.748 468.195 319.436 467.961 319.232C467.726 319.025 467.363 318.922 466.871 318.922ZM474.499 317.434C475.277 317.434 475.917 317.527 476.421 317.715C476.929 317.902 477.306 318.186 477.552 318.564C477.798 318.943 477.921 319.422 477.921 320C477.921 320.391 477.847 320.732 477.699 321.025C477.55 321.318 477.355 321.566 477.113 321.77C476.87 321.973 476.609 322.139 476.327 322.268L478.847 326H476.831L474.786 322.713H473.82V326H472.003V317.434H474.499ZM474.37 318.922H473.82V321.236H474.406C475.007 321.236 475.437 321.137 475.695 320.938C475.956 320.734 476.087 320.438 476.087 320.047C476.087 319.641 475.947 319.352 475.665 319.18C475.388 319.008 474.956 318.922 474.37 318.922ZM487.941 321.705C487.941 322.365 487.859 322.967 487.694 323.51C487.53 324.049 487.28 324.514 486.944 324.904C486.612 325.295 486.191 325.596 485.679 325.807C485.167 326.014 484.562 326.117 483.862 326.117C483.163 326.117 482.558 326.014 482.046 325.807C481.534 325.596 481.11 325.295 480.775 324.904C480.442 324.514 480.194 324.047 480.03 323.504C479.866 322.961 479.784 322.357 479.784 321.693C479.784 320.807 479.929 320.035 480.218 319.379C480.511 318.719 480.96 318.207 481.566 317.844C482.171 317.48 482.941 317.299 483.874 317.299C484.804 317.299 485.567 317.48 486.165 317.844C486.767 318.207 487.212 318.719 487.501 319.379C487.794 320.039 487.941 320.814 487.941 321.705ZM481.689 321.705C481.689 322.303 481.763 322.818 481.911 323.252C482.064 323.682 482.3 324.014 482.62 324.248C482.941 324.479 483.355 324.594 483.862 324.594C484.378 324.594 484.796 324.479 485.116 324.248C485.437 324.014 485.669 323.682 485.814 323.252C485.962 322.818 486.036 322.303 486.036 321.705C486.036 320.807 485.868 320.1 485.532 319.584C485.196 319.068 484.644 318.811 483.874 318.811C483.362 318.811 482.944 318.928 482.62 319.162C482.3 319.393 482.064 319.725 481.911 320.158C481.763 320.588 481.689 321.104 481.689 321.705ZM496.882 326H494.807L492.815 322.76L490.823 326H488.878L491.72 321.582L489.059 317.434H491.063L492.909 320.516L494.72 317.434H496.677L493.987 321.682L496.882 326ZM500.866 320.961L502.653 317.434H504.61L501.768 322.666V326H499.964V322.725L497.122 317.434H499.09L500.866 320.961Z" fill="#CA2171"/>
+<line x1="1" y1="-1" x2="11" y2="-1" transform="matrix(-1 8.74228e-08 8.74228e-08 1 239 124)" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M236.72 123L232.5 127.137L233.89 128.5L239.5 123L233.89 117.5L232.5 118.863L236.72 123Z" fill="#CA2171"/>
+<line x1="1" y1="-1" x2="37" y2="-1" transform="matrix(1.19249e-08 1 1 -1.19249e-08 485 185)" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M484 187.28L488.137 191.5L489.5 190.11L484 184.5L478.5 190.11L479.863 191.5L484 187.28Z" fill="#CA2171"/>
+<line x1="1" y1="-1" x2="74" y2="-1" transform="matrix(-1 -8.74228e-08 -8.74228e-08 1 415 120)" stroke="#E5544B" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1.5 4"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M412.72 119L408.5 123.137L409.89 124.5L415.5 119L409.89 113.5L408.5 114.863L412.72 119Z" fill="#E5544B"/>
+<path d="M305.93 149L303.867 142.279H303.814C303.822 142.439 303.834 142.682 303.85 143.006C303.869 143.326 303.887 143.668 303.902 144.031C303.918 144.395 303.926 144.723 303.926 145.016V149H302.303V140.434H304.775L306.803 146.984H306.838L308.988 140.434H311.461V149H309.768V144.945C309.768 144.676 309.771 144.365 309.779 144.014C309.791 143.662 309.805 143.328 309.82 143.012C309.836 142.691 309.848 142.451 309.855 142.291H309.803L307.594 149H305.93ZM318.557 149H313.623V140.434H318.557V141.922H315.439V143.803H318.34V145.291H315.439V147.5H318.557V149ZM325.406 146.621C325.406 147.129 325.283 147.57 325.037 147.945C324.791 148.32 324.432 148.609 323.959 148.812C323.49 149.016 322.92 149.117 322.248 149.117C321.951 149.117 321.66 149.098 321.375 149.059C321.094 149.02 320.822 148.963 320.561 148.889C320.303 148.811 320.057 148.715 319.822 148.602V146.914C320.229 147.094 320.65 147.256 321.088 147.4C321.525 147.545 321.959 147.617 322.389 147.617C322.686 147.617 322.924 147.578 323.104 147.5C323.287 147.422 323.42 147.314 323.502 147.178C323.584 147.041 323.625 146.885 323.625 146.709C323.625 146.494 323.553 146.311 323.408 146.158C323.264 146.006 323.064 145.863 322.811 145.73C322.561 145.598 322.277 145.455 321.961 145.303C321.762 145.209 321.545 145.096 321.311 144.963C321.076 144.826 320.854 144.66 320.643 144.465C320.432 144.27 320.258 144.033 320.121 143.756C319.988 143.475 319.922 143.139 319.922 142.748C319.922 142.236 320.039 141.799 320.273 141.436C320.508 141.072 320.842 140.795 321.275 140.604C321.713 140.408 322.229 140.311 322.822 140.311C323.268 140.311 323.691 140.363 324.094 140.469C324.5 140.57 324.924 140.719 325.365 140.914L324.779 142.326C324.385 142.166 324.031 142.043 323.719 141.957C323.406 141.867 323.088 141.822 322.764 141.822C322.537 141.822 322.344 141.859 322.184 141.934C322.023 142.004 321.902 142.105 321.82 142.238C321.738 142.367 321.697 142.518 321.697 142.689C321.697 142.893 321.756 143.064 321.873 143.205C321.994 143.342 322.174 143.475 322.412 143.604C322.654 143.732 322.955 143.883 323.314 144.055C323.752 144.262 324.125 144.479 324.434 144.705C324.746 144.928 324.986 145.191 325.154 145.496C325.322 145.797 325.406 146.172 325.406 146.621ZM333.979 149H332.168V145.303H328.775V149H326.959V140.434H328.775V143.791H332.168V140.434H333.979V149ZM339.264 140.434H341.93C343.07 140.434 343.934 140.594 344.52 140.914C345.105 141.234 345.398 141.797 345.398 142.602C345.398 142.926 345.346 143.219 345.24 143.48C345.139 143.742 344.99 143.957 344.795 144.125C344.6 144.293 344.361 144.402 344.08 144.453V144.512C344.365 144.57 344.623 144.672 344.854 144.816C345.084 144.957 345.268 145.164 345.404 145.438C345.545 145.707 345.615 146.066 345.615 146.516C345.615 147.035 345.488 147.48 345.234 147.852C344.98 148.223 344.617 148.508 344.145 148.707C343.676 148.902 343.117 149 342.469 149H339.264V140.434ZM341.08 143.826H342.135C342.662 143.826 343.027 143.744 343.23 143.58C343.434 143.412 343.535 143.166 343.535 142.842C343.535 142.514 343.414 142.279 343.172 142.139C342.934 141.994 342.555 141.922 342.035 141.922H341.08V143.826ZM341.08 145.268V147.5H342.264C342.811 147.5 343.191 147.395 343.406 147.184C343.621 146.973 343.729 146.689 343.729 146.334C343.729 146.123 343.682 145.938 343.588 145.777C343.494 145.617 343.336 145.492 343.113 145.402C342.895 145.312 342.592 145.268 342.205 145.268H341.08ZM349.992 143.961L351.779 140.434H353.736L350.895 145.666V149H349.09V145.725L346.248 140.434H348.217L349.992 143.961ZM357.551 140.434C358.656 140.434 359.463 140.672 359.971 141.148C360.479 141.621 360.732 142.273 360.732 143.105C360.732 143.48 360.676 143.84 360.562 144.184C360.449 144.523 360.264 144.826 360.006 145.092C359.752 145.357 359.412 145.568 358.986 145.725C358.561 145.877 358.035 145.953 357.41 145.953H356.631V149H354.814V140.434H357.551ZM357.457 141.922H356.631V144.465H357.229C357.568 144.465 357.863 144.42 358.113 144.33C358.363 144.24 358.557 144.1 358.693 143.908C358.83 143.717 358.898 143.471 358.898 143.17C358.898 142.748 358.781 142.436 358.547 142.232C358.312 142.025 357.949 141.922 357.457 141.922ZM367.594 149L366.973 146.961H363.85L363.229 149H361.271L364.295 140.398H366.516L369.551 149H367.594ZM366.539 145.438L365.918 143.445C365.879 143.312 365.826 143.143 365.76 142.936C365.697 142.725 365.633 142.512 365.566 142.297C365.504 142.078 365.453 141.889 365.414 141.729C365.375 141.889 365.32 142.088 365.25 142.326C365.184 142.561 365.119 142.783 365.057 142.994C364.994 143.205 364.949 143.355 364.922 143.445L364.307 145.438H366.539ZM375.691 146.621C375.691 147.129 375.568 147.57 375.322 147.945C375.076 148.32 374.717 148.609 374.244 148.812C373.775 149.016 373.205 149.117 372.533 149.117C372.236 149.117 371.945 149.098 371.66 149.059C371.379 149.02 371.107 148.963 370.846 148.889C370.588 148.811 370.342 148.715 370.107 148.602V146.914C370.514 147.094 370.936 147.256 371.373 147.4C371.811 147.545 372.244 147.617 372.674 147.617C372.971 147.617 373.209 147.578 373.389 147.5C373.572 147.422 373.705 147.314 373.787 147.178C373.869 147.041 373.91 146.885 373.91 146.709C373.91 146.494 373.838 146.311 373.693 146.158C373.549 146.006 373.35 145.863 373.096 145.73C372.846 145.598 372.562 145.455 372.246 145.303C372.047 145.209 371.83 145.096 371.596 144.963C371.361 144.826 371.139 144.66 370.928 144.465C370.717 144.27 370.543 144.033 370.406 143.756C370.273 143.475 370.207 143.139 370.207 142.748C370.207 142.236 370.324 141.799 370.559 141.436C370.793 141.072 371.127 140.795 371.561 140.604C371.998 140.408 372.514 140.311 373.107 140.311C373.553 140.311 373.977 140.363 374.379 140.469C374.785 140.57 375.209 140.719 375.65 140.914L375.064 142.326C374.67 142.166 374.316 142.043 374.004 141.957C373.691 141.867 373.373 141.822 373.049 141.822C372.822 141.822 372.629 141.859 372.469 141.934C372.309 142.004 372.188 142.105 372.105 142.238C372.023 142.367 371.982 142.518 371.982 142.689C371.982 142.893 372.041 143.064 372.158 143.205C372.279 143.342 372.459 143.475 372.697 143.604C372.939 143.732 373.24 143.883 373.6 144.055C374.037 144.262 374.41 144.479 374.719 144.705C375.031 144.928 375.271 145.191 375.439 145.496C375.607 145.797 375.691 146.172 375.691 146.621ZM382.301 146.621C382.301 147.129 382.178 147.57 381.932 147.945C381.686 148.32 381.326 148.609 380.854 148.812C380.385 149.016 379.814 149.117 379.143 149.117C378.846 149.117 378.555 149.098 378.27 149.059C377.988 149.02 377.717 148.963 377.455 148.889C377.197 148.811 376.951 148.715 376.717 148.602V146.914C377.123 147.094 377.545 147.256 377.982 147.4C378.42 147.545 378.854 147.617 379.283 147.617C379.58 147.617 379.818 147.578 379.998 147.5C380.182 147.422 380.314 147.314 380.396 147.178C380.479 147.041 380.52 146.885 380.52 146.709C380.52 146.494 380.447 146.311 380.303 146.158C380.158 146.006 379.959 145.863 379.705 145.73C379.455 145.598 379.172 145.455 378.855 145.303C378.656 145.209 378.439 145.096 378.205 144.963C377.971 144.826 377.748 144.66 377.537 144.465C377.326 144.27 377.152 144.033 377.016 143.756C376.883 143.475 376.816 143.139 376.816 142.748C376.816 142.236 376.934 141.799 377.168 141.436C377.402 141.072 377.736 140.795 378.17 140.604C378.607 140.408 379.123 140.311 379.717 140.311C380.162 140.311 380.586 140.363 380.988 140.469C381.395 140.57 381.818 140.719 382.26 140.914L381.674 142.326C381.279 142.166 380.926 142.043 380.613 141.957C380.301 141.867 379.982 141.822 379.658 141.822C379.432 141.822 379.238 141.859 379.078 141.934C378.918 142.004 378.797 142.105 378.715 142.238C378.633 142.367 378.592 142.518 378.592 142.689C378.592 142.893 378.65 143.064 378.768 143.205C378.889 143.342 379.068 143.475 379.307 143.604C379.549 143.732 379.85 143.883 380.209 144.055C380.646 144.262 381.02 144.479 381.328 144.705C381.641 144.928 381.881 145.191 382.049 145.496C382.217 145.797 382.301 146.172 382.301 146.621ZM309.393 156.434C310.17 156.434 310.811 156.527 311.314 156.715C311.822 156.902 312.199 157.186 312.445 157.564C312.691 157.943 312.814 158.422 312.814 159C312.814 159.391 312.74 159.732 312.592 160.025C312.443 160.318 312.248 160.566 312.006 160.77C311.764 160.973 311.502 161.139 311.221 161.268L313.74 165H311.725L309.68 161.713H308.713V165H306.896V156.434H309.393ZM309.264 157.922H308.713V160.236H309.299C309.9 160.236 310.33 160.137 310.588 159.938C310.85 159.734 310.98 159.438 310.98 159.047C310.98 158.641 310.84 158.352 310.559 158.18C310.281 158.008 309.85 157.922 309.264 157.922ZM319.752 165H314.818V156.434H319.752V157.922H316.635V159.803H319.535V161.291H316.635V163.5H319.752V165ZM328.652 160.635C328.652 161.6 328.467 162.406 328.096 163.055C327.729 163.699 327.195 164.186 326.496 164.514C325.797 164.838 324.955 165 323.971 165H321.545V156.434H324.234C325.133 156.434 325.912 156.594 326.572 156.914C327.232 157.23 327.744 157.701 328.107 158.326C328.471 158.947 328.652 159.717 328.652 160.635ZM326.766 160.682C326.766 160.049 326.672 159.529 326.484 159.123C326.301 158.713 326.027 158.41 325.664 158.215C325.305 158.02 324.859 157.922 324.328 157.922H323.361V163.5H324.141C325.027 163.5 325.686 163.264 326.115 162.791C326.549 162.318 326.766 161.615 326.766 160.682ZM330.428 165V156.434H332.244V165H330.428ZM336.896 156.434C337.674 156.434 338.314 156.527 338.818 156.715C339.326 156.902 339.703 157.186 339.949 157.564C340.195 157.943 340.318 158.422 340.318 159C340.318 159.391 340.244 159.732 340.096 160.025C339.947 160.318 339.752 160.566 339.51 160.77C339.268 160.973 339.006 161.139 338.725 161.268L341.244 165H339.229L337.184 161.713H336.217V165H334.4V156.434H336.896ZM336.768 157.922H336.217V160.236H336.803C337.404 160.236 337.834 160.137 338.092 159.938C338.354 159.734 338.484 159.438 338.484 159.047C338.484 158.641 338.344 158.352 338.062 158.18C337.785 158.008 337.354 157.922 336.768 157.922ZM347.256 165H342.322V156.434H347.256V157.922H344.139V159.803H347.039V161.291H344.139V163.5H347.256V165ZM352.688 157.822C352.34 157.822 352.031 157.891 351.762 158.027C351.496 158.16 351.271 158.354 351.088 158.607C350.908 158.861 350.771 159.168 350.678 159.527C350.584 159.887 350.537 160.291 350.537 160.74C350.537 161.346 350.611 161.863 350.76 162.293C350.912 162.719 351.146 163.045 351.463 163.271C351.779 163.494 352.188 163.605 352.688 163.605C353.035 163.605 353.383 163.566 353.73 163.488C354.082 163.41 354.463 163.299 354.873 163.154V164.678C354.494 164.834 354.121 164.945 353.754 165.012C353.387 165.082 352.975 165.117 352.518 165.117C351.635 165.117 350.908 164.936 350.338 164.572C349.771 164.205 349.352 163.693 349.078 163.037C348.805 162.377 348.668 161.607 348.668 160.729C348.668 160.08 348.756 159.486 348.932 158.947C349.107 158.408 349.365 157.941 349.705 157.547C350.045 157.152 350.465 156.848 350.965 156.633C351.465 156.418 352.039 156.311 352.688 156.311C353.113 156.311 353.539 156.365 353.965 156.475C354.395 156.58 354.805 156.727 355.195 156.914L354.609 158.391C354.289 158.238 353.967 158.105 353.643 157.992C353.318 157.879 353 157.822 352.688 157.822ZM360.006 165H358.189V157.945H355.863V156.434H362.332V157.945H360.006V165ZM368.584 165H363.65V156.434H368.584V157.922H365.467V159.803H368.367V161.291H365.467V163.5H368.584V165ZM377.484 160.635C377.484 161.6 377.299 162.406 376.928 163.055C376.561 163.699 376.027 164.186 375.328 164.514C374.629 164.838 373.787 165 372.803 165H370.377V156.434H373.066C373.965 156.434 374.744 156.594 375.404 156.914C376.064 157.23 376.576 157.701 376.939 158.326C377.303 158.947 377.484 159.717 377.484 160.635ZM375.598 160.682C375.598 160.049 375.504 159.529 375.316 159.123C375.133 158.713 374.859 158.41 374.496 158.215C374.137 158.02 373.691 157.922 373.16 157.922H372.193V163.5H372.973C373.859 163.5 374.518 163.264 374.947 162.791C375.381 162.318 375.598 161.615 375.598 160.682Z" fill="#E5544B"/>
+<circle cx="342" cy="119" r="13.25" fill="#E5544B" stroke="white" stroke-width="1.5"/>
+<path d="M342.701 120.685H341.033L340.684 114.006H343.049L342.701 120.685ZM340.657 123.022C340.657 122.594 340.773 122.293 341.006 122.12C341.242 121.947 341.527 121.86 341.86 121.86C342.184 121.86 342.462 121.947 342.694 122.12C342.931 122.293 343.049 122.594 343.049 123.022C343.049 123.433 342.931 123.729 342.694 123.911C342.462 124.093 342.184 124.185 341.86 124.185C341.527 124.185 341.242 124.093 341.006 123.911C340.773 123.729 340.657 123.433 340.657 123.022Z" fill="white"/>
+<line x1="233.5" y1="25.5" x2="233.5" y2="109.5" stroke="#999999" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M242 54.5728H254C256.209 54.5728 258 56.3636 258 58.5728V347.204C258 349.413 256.209 351.204 254 351.204H242V54.5728Z" fill="url(#paint1_linear_0_1)"/>
+<rect x="409" y="270" width="37" height="4" fill="white"/>
+<rect x="238" y="270" width="37" height="4" fill="white"/>
+<line x1="233" y1="272" x2="443" y2="272" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M441.72 272L437.5 276.137L438.89 277.5L444.5 272L438.89 266.5L437.5 267.863L441.72 272Z" fill="#CA2171"/>
+<path d="M244 123V123C247.314 123 250 125.686 250 129V191" stroke="white" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1.5 4"/>
+<path d="M420 118V118C423.314 118 426 120.686 426 124V186" stroke="white" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1.5 4"/>
+<path d="M244 202V202C247.314 202 250 199.314 250 196L250 175" stroke="white" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1.5 4"/>
+<path d="M432 257V257C428.686 257 426 254.314 426 251L426 185" stroke="white" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1.5 4"/>
+<path d="M193 231L193 210C193 205.582 196.582 202 201 202L238 202" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M193 229.72L197.137 225.5L198.5 226.89L193 232.5L187.5 226.89L188.863 225.5L193 229.72Z" fill="#CA2171"/>
+<g opacity="0.4">
+<path d="M46.7815 326H44.4729L40.7463 319.52H40.6936C40.7092 319.789 40.7229 320.061 40.7346 320.334C40.7463 320.607 40.758 320.881 40.7698 321.154C40.7815 321.424 40.7932 321.695 40.8049 321.969V326H39.1819V317.434H41.4729L45.1936 323.85H45.2346C45.2268 323.584 45.217 323.32 45.2053 323.059C45.1936 322.797 45.1819 322.535 45.1702 322.273C45.1623 322.012 45.1545 321.75 45.1467 321.488V317.434H46.7815V326ZM56.959 321.705C56.959 322.365 56.877 322.967 56.7129 323.51C56.5488 324.049 56.2988 324.514 55.9629 324.904C55.6309 325.295 55.209 325.596 54.6973 325.807C54.1855 326.014 53.5801 326.117 52.8809 326.117C52.1816 326.117 51.5762 326.014 51.0645 325.807C50.5527 325.596 50.1289 325.295 49.793 324.904C49.4609 324.514 49.2129 324.047 49.0488 323.504C48.8848 322.961 48.8027 322.357 48.8027 321.693C48.8027 320.807 48.9473 320.035 49.2363 319.379C49.5293 318.719 49.9785 318.207 50.584 317.844C51.1895 317.48 51.959 317.299 52.8926 317.299C53.8223 317.299 54.5859 317.48 55.1836 317.844C55.7852 318.207 56.2305 318.719 56.5195 319.379C56.8125 320.039 56.959 320.814 56.959 321.705ZM50.707 321.705C50.707 322.303 50.7812 322.818 50.9297 323.252C51.082 323.682 51.3184 324.014 51.6387 324.248C51.959 324.479 52.373 324.594 52.8809 324.594C53.3965 324.594 53.8145 324.479 54.1348 324.248C54.4551 324.014 54.6875 323.682 54.832 323.252C54.9805 322.818 55.0547 322.303 55.0547 321.705C55.0547 320.807 54.8867 320.1 54.5508 319.584C54.2148 319.068 53.6621 318.811 52.8926 318.811C52.3809 318.811 51.9629 318.928 51.6387 319.162C51.3184 319.393 51.082 319.725 50.9297 320.158C50.7812 320.588 50.707 321.104 50.707 321.705ZM22.8818 332.434V337.977C22.8818 338.566 22.7509 339.1 22.4892 339.576C22.2314 340.049 21.8388 340.424 21.3115 340.701C20.788 340.979 20.1279 341.117 19.331 341.117C18.1982 341.117 17.3349 340.828 16.7412 340.25C16.1474 339.672 15.8505 338.906 15.8505 337.953V332.434H17.6611V337.678C17.6611 338.385 17.8056 338.881 18.0947 339.166C18.3838 339.451 18.8115 339.594 19.3779 339.594C19.7763 339.594 20.0986 339.525 20.3447 339.389C20.5947 339.252 20.7783 339.041 20.8955 338.756C21.0127 338.471 21.0713 338.107 21.0713 337.666V332.434H22.8818ZM27.9558 332.434C29.0613 332.434 29.8679 332.672 30.3757 333.148C30.8835 333.621 31.1374 334.273 31.1374 335.105C31.1374 335.48 31.0808 335.84 30.9675 336.184C30.8542 336.523 30.6687 336.826 30.4109 337.092C30.157 337.357 29.8171 337.568 29.3913 337.725C28.9655 337.877 28.4402 337.953 27.8152 337.953H27.0359V341H25.2195V332.434H27.9558ZM27.862 333.922H27.0359V336.465H27.6335C27.9734 336.465 28.2683 336.42 28.5183 336.33C28.7683 336.24 28.9616 336.1 29.0984 335.908C29.2351 335.717 29.3034 335.471 29.3034 335.17C29.3034 334.748 29.1863 334.436 28.9519 334.232C28.7175 334.025 28.3542 333.922 27.862 333.922ZM38.0513 338.621C38.0513 339.129 37.9282 339.57 37.6821 339.945C37.436 340.32 37.0766 340.609 36.604 340.812C36.1352 341.016 35.5649 341.117 34.893 341.117C34.5962 341.117 34.3052 341.098 34.02 341.059C33.7388 341.02 33.4673 340.963 33.2055 340.889C32.9477 340.811 32.7016 340.715 32.4673 340.602V338.914C32.8735 339.094 33.2954 339.256 33.7329 339.4C34.1704 339.545 34.604 339.617 35.0337 339.617C35.3305 339.617 35.5688 339.578 35.7485 339.5C35.9321 339.422 36.0649 339.314 36.147 339.178C36.229 339.041 36.27 338.885 36.27 338.709C36.27 338.494 36.1977 338.311 36.0532 338.158C35.9087 338.006 35.7095 337.863 35.4555 337.73C35.2055 337.598 34.9223 337.455 34.6059 337.303C34.4067 337.209 34.1899 337.096 33.9555 336.963C33.7212 336.826 33.4985 336.66 33.2876 336.465C33.0766 336.27 32.9028 336.033 32.7661 335.756C32.6333 335.475 32.5669 335.139 32.5669 334.748C32.5669 334.236 32.6841 333.799 32.9184 333.436C33.1528 333.072 33.4868 332.795 33.9204 332.604C34.3579 332.408 34.8735 332.311 35.4673 332.311C35.9126 332.311 36.3364 332.363 36.7388 332.469C37.145 332.57 37.5688 332.719 38.0102 332.914L37.4243 334.326C37.0298 334.166 36.6763 334.043 36.3638 333.957C36.0513 333.867 35.7329 333.822 35.4087 333.822C35.1821 333.822 34.9888 333.859 34.8286 333.934C34.6684 334.004 34.5473 334.105 34.4653 334.238C34.3833 334.367 34.3423 334.518 34.3423 334.689C34.3423 334.893 34.4009 335.064 34.518 335.205C34.6391 335.342 34.8188 335.475 35.0571 335.604C35.2993 335.732 35.6001 335.883 35.9595 336.055C36.397 336.262 36.77 336.479 37.0786 336.705C37.3911 336.928 37.6313 337.191 37.7993 337.496C37.9673 337.797 38.0513 338.172 38.0513 338.621ZM43.1487 341H41.3323V333.945H39.0061V332.434H45.4748V333.945H43.1487V341ZM49.5293 332.434C50.3066 332.434 50.9473 332.527 51.4512 332.715C51.959 332.902 52.3359 333.186 52.582 333.564C52.8281 333.943 52.9512 334.422 52.9512 335C52.9512 335.391 52.877 335.732 52.7285 336.025C52.5801 336.318 52.3848 336.566 52.1426 336.77C51.9004 336.973 51.6387 337.139 51.3574 337.268L53.877 341H51.8613L49.8164 337.713H48.8496V341H47.0332V332.434H49.5293ZM49.4004 333.922H48.8496V336.236H49.4355C50.0371 336.236 50.4668 336.137 50.7246 335.938C50.9863 335.734 51.1172 335.438 51.1172 335.047C51.1172 334.641 50.9766 334.352 50.6953 334.18C50.418 334.008 49.9863 333.922 49.4004 333.922ZM60.1287 341H55.1951V332.434H60.1287V333.922H57.0115V335.803H59.9119V337.291H57.0115V339.5H60.1287V341ZM67.4058 341L66.7847 338.961H63.6616L63.0405 341H61.0835L64.107 332.398H66.3277L69.3628 341H67.4058ZM66.3511 337.438L65.73 335.445C65.6909 335.312 65.6382 335.143 65.5718 334.936C65.5093 334.725 65.4448 334.512 65.3784 334.297C65.3159 334.078 65.2652 333.889 65.2261 333.729C65.187 333.889 65.1323 334.088 65.062 334.326C64.9956 334.561 64.9312 334.783 64.8687 334.994C64.8062 335.205 64.7612 335.355 64.7339 335.445L64.1187 337.438H66.3511ZM74.3138 341L72.2513 334.279H72.1985C72.2063 334.439 72.218 334.682 72.2337 335.006C72.2532 335.326 72.2708 335.668 72.2864 336.031C72.302 336.395 72.3098 336.723 72.3098 337.016V341H70.6868V332.434H73.1595L75.1868 338.984H75.222L77.3723 332.434H79.845V341H78.1516V336.945C78.1516 336.676 78.1555 336.365 78.1634 336.014C78.1751 335.662 78.1888 335.328 78.2044 335.012C78.22 334.691 78.2317 334.451 78.2395 334.291H78.1868L75.9778 341H74.3138ZM28.8874 349.822C28.5398 349.822 28.2312 349.891 27.9616 350.027C27.696 350.16 27.4714 350.354 27.2878 350.607C27.1081 350.861 26.9714 351.168 26.8777 351.527C26.7839 351.887 26.737 352.291 26.737 352.74C26.737 353.346 26.8113 353.863 26.9597 354.293C27.112 354.719 27.3464 355.045 27.6628 355.271C27.9792 355.494 28.3874 355.605 28.8874 355.605C29.2351 355.605 29.5827 355.566 29.9304 355.488C30.282 355.41 30.6628 355.299 31.073 355.154V356.678C30.6941 356.834 30.321 356.945 29.9538 357.012C29.5866 357.082 29.1745 357.117 28.7175 357.117C27.8347 357.117 27.1081 356.936 26.5378 356.572C25.9714 356.205 25.5515 355.693 25.278 355.037C25.0046 354.377 24.8679 353.607 24.8679 352.729C24.8679 352.08 24.9558 351.486 25.1316 350.947C25.3073 350.408 25.5652 349.941 25.905 349.547C26.2448 349.152 26.6648 348.848 27.1648 348.633C27.6648 348.418 28.239 348.311 28.8874 348.311C29.3132 348.311 29.739 348.365 30.1648 348.475C30.5945 348.58 31.0046 348.727 31.3952 348.914L30.8093 350.391C30.489 350.238 30.1667 350.105 29.8425 349.992C29.5183 349.879 29.1999 349.822 28.8874 349.822ZM40.9165 352.705C40.9165 353.365 40.8345 353.967 40.6704 354.51C40.5063 355.049 40.2563 355.514 39.9204 355.904C39.5884 356.295 39.1665 356.596 38.6548 356.807C38.143 357.014 37.5376 357.117 36.8384 357.117C36.1391 357.117 35.5337 357.014 35.022 356.807C34.5102 356.596 34.0864 356.295 33.7505 355.904C33.4184 355.514 33.1704 355.047 33.0063 354.504C32.8423 353.961 32.7602 353.357 32.7602 352.693C32.7602 351.807 32.9048 351.035 33.1938 350.379C33.4868 349.719 33.936 349.207 34.5415 348.844C35.147 348.48 35.9165 348.299 36.8501 348.299C37.7798 348.299 38.5434 348.48 39.1411 348.844C39.7427 349.207 40.188 349.719 40.477 350.379C40.77 351.039 40.9165 351.814 40.9165 352.705ZM34.6645 352.705C34.6645 353.303 34.7388 353.818 34.8872 354.252C35.0395 354.682 35.2759 355.014 35.5962 355.248C35.9165 355.479 36.3305 355.594 36.8384 355.594C37.354 355.594 37.772 355.479 38.0923 355.248C38.4126 355.014 38.645 354.682 38.7895 354.252C38.938 353.818 39.0122 353.303 39.0122 352.705C39.0122 351.807 38.8442 351.1 38.5083 350.584C38.1723 350.068 37.6196 349.811 36.8501 349.811C36.3384 349.811 35.9204 349.928 35.5962 350.162C35.2759 350.393 35.0395 350.725 34.8872 351.158C34.7388 351.588 34.6645 352.104 34.6645 352.705ZM50.5315 357H48.2229L44.4963 350.52H44.4436C44.4592 350.789 44.4729 351.061 44.4846 351.334C44.4963 351.607 44.508 351.881 44.5198 352.154C44.5315 352.424 44.5432 352.695 44.5549 352.969V357H42.9319V348.434H45.2229L48.9436 354.85H48.9846C48.9768 354.584 48.967 354.32 48.9553 354.059C48.9436 353.797 48.9319 353.535 48.9202 353.273C48.9123 353.012 48.9045 352.75 48.8967 352.488V348.434H50.5315V357ZM54.7207 357H52.9336V348.434H57.8438V349.922H54.7207V352.131H57.627V353.613H54.7207V357ZM59.7595 357V348.434H61.5759V357H59.7595ZM67.2241 352.189H70.6226V356.631C70.1734 356.779 69.7066 356.898 69.2222 356.988C68.7378 357.074 68.189 357.117 67.5757 357.117C66.7241 357.117 66.0015 356.949 65.4077 356.613C64.814 356.277 64.3628 355.781 64.0542 355.125C63.7456 354.469 63.5913 353.662 63.5913 352.705C63.5913 351.807 63.7632 351.029 64.107 350.373C64.4546 349.717 64.9605 349.209 65.6245 348.85C66.2925 348.49 67.107 348.311 68.0679 348.311C68.521 348.311 68.9683 348.359 69.4097 348.457C69.8511 348.555 70.2515 348.682 70.6109 348.838L70.0073 350.291C69.7456 350.158 69.4468 350.047 69.1109 349.957C68.7749 349.867 68.4234 349.822 68.0562 349.822C67.5288 349.822 67.0698 349.943 66.6792 350.186C66.2925 350.428 65.9917 350.768 65.7769 351.205C65.5659 351.639 65.4605 352.15 65.4605 352.74C65.4605 353.299 65.5366 353.795 65.689 354.229C65.8413 354.658 66.0816 354.996 66.4097 355.242C66.7378 355.484 67.1656 355.605 67.6929 355.605C67.9507 355.605 68.1675 355.594 68.3433 355.57C68.523 355.543 68.6909 355.516 68.8472 355.488V353.701H67.2241V352.189Z" fill="#6A6D7A"/>
+<path d="M12.75 237C12.75 236.31 13.3096 235.75 14 235.75H82C82.6904 235.75 83.25 236.31 83.25 237V305C83.25 305.69 82.6904 306.25 82 306.25H14C13.3096 306.25 12.75 305.69 12.75 305V237Z" fill="white" stroke="#D2D4DB" stroke-width="1.5"/>
+<mask id="path-57-inside-3_0_1" fill="white">
+<rect x="34" y="255" width="28" height="32" rx="1"/>
+</mask>
+<rect x="34" y="255" width="28" height="32" rx="1" stroke="black" stroke-width="4" mask="url(#path-57-inside-3_0_1)"/>
+<rect x="39" y="263" width="18" height="2" rx="1" fill="black"/>
+<rect x="39" y="269" width="18" height="2" rx="1" fill="black"/>
+<rect x="39" y="275" width="10" height="2" rx="1" fill="black"/>
+<mask id="path-61-inside-4_0_1" fill="white">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M48 247C45.7909 247 44 248.791 44 251V252H41C39.8954 252 39 252.895 39 254L39 258C39 259.105 39.8954 260 41 260H55C56.1046 260 57 259.105 57 258V254C57 252.895 56.1046 252 55 252H52V251C52 248.791 50.2091 247 48 247Z"/>
+</mask>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M48 247C45.7909 247 44 248.791 44 251V252H41C39.8954 252 39 252.895 39 254L39 258C39 259.105 39.8954 260 41 260H55C56.1046 260 57 259.105 57 258V254C57 252.895 56.1046 252 55 252H52V251C52 248.791 50.2091 247 48 247Z" fill="white"/>
+<path d="M44 252L44 254C45.1046 254 46 253.105 46 252H44ZM39 254H41H39ZM39 258H37H39ZM41 260L41 262L41 260ZM55 260L55 258L55 260ZM57 258L55 258L57 258ZM57 254H59H57ZM52 252H50C50 253.105 50.8954 254 52 254L52 252ZM46 251C46 249.895 46.8954 249 48 249V245C44.6863 245 42 247.686 42 251H46ZM46 252V251H42V252H46ZM41 254H44L44 250H41L41 254ZM41 254L41 250C38.7909 250 37 251.791 37 254H41ZM41 258L41 254H37L37 258H41ZM41 258H41H37C37 260.209 38.7909 262 41 262L41 258ZM55 258H41L41 262H55L55 258ZM55 258L55 262C57.2091 262 59 260.209 59 258L55 258ZM55 254V258L59 258V254H55ZM55 254H59C59 251.791 57.2091 250 55 250L55 254ZM52 254H55L55 250H52L52 254ZM50 251V252H54V251H50ZM48 249C49.1046 249 50 249.895 50 251H54C54 247.686 51.3137 245 48 245V249Z" fill="black" mask="url(#path-61-inside-4_0_1)"/>
+</g>
+<path d="M3.47827 227.478L28.5218 252.522" stroke="#E5544B" stroke-width="6"/>
+<path d="M28.5217 227.478L3.47824 252.522" stroke="#E5544B" stroke-width="6"/>
+<line x1="1" y1="-1" x2="8" y2="-1" transform="matrix(-1 8.74228e-08 8.74228e-08 1 444 258)" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M441.72 257L437.5 261.137L438.89 262.5L444.5 257L438.89 251.5L437.5 252.863L441.72 257Z" fill="#CA2171"/>
+<circle cx="84" cy="238" r="13.25" fill="#CA2171" stroke="white" stroke-width="1.5"/>
+<circle cx="250" cy="103" r="13.25" fill="#CA2171" stroke="white" stroke-width="1.5"/>
+<path d="M85.5757 243H83.5514V237.458L83.571 236.547L83.6038 235.551C83.2675 235.888 83.0338 236.108 82.9028 236.213L81.8022 237.097L80.8261 235.879L83.9117 233.422H85.5757V243Z" fill="white"/>
+<path d="M253.259 108H246.564V106.592L248.968 104.161C249.453 103.663 249.842 103.248 250.134 102.916C250.431 102.58 250.645 102.274 250.776 101.999C250.912 101.724 250.98 101.429 250.98 101.115C250.98 100.735 250.873 100.451 250.659 100.263C250.449 100.071 250.167 99.9749 249.813 99.9749C249.442 99.9749 249.082 100.06 248.732 100.23C248.383 100.401 248.018 100.643 247.638 100.958L246.538 99.6539C246.813 99.418 247.103 99.1953 247.409 98.9857C247.719 98.776 248.077 98.6079 248.484 98.4812C248.894 98.3502 249.385 98.2847 249.958 98.2847C250.586 98.2847 251.126 98.3983 251.576 98.6254C252.03 98.8525 252.379 99.1626 252.624 99.5556C252.868 99.9443 252.991 100.385 252.991 100.879C252.991 101.407 252.886 101.89 252.676 102.327C252.467 102.763 252.161 103.196 251.759 103.624C251.362 104.052 250.881 104.526 250.318 105.045L249.086 106.205V106.297H253.259V108Z" fill="white"/>
+<circle cx="426" cy="186" r="13.25" fill="#CA2171" stroke="white" stroke-width="1.5"/>
+<path d="M428.886 183.564C428.886 184.006 428.794 184.388 428.611 184.711C428.427 185.034 428.178 185.298 427.864 185.504C427.554 185.709 427.204 185.86 426.816 185.956V185.995C427.584 186.091 428.167 186.327 428.565 186.702C428.967 187.078 429.168 187.58 429.168 188.209C429.168 188.768 429.03 189.268 428.755 189.709C428.484 190.151 428.065 190.498 427.497 190.751C426.929 191.004 426.198 191.131 425.302 191.131C424.774 191.131 424.28 191.087 423.822 191C423.368 190.917 422.94 190.788 422.538 190.613V188.891C422.948 189.1 423.379 189.26 423.828 189.369C424.278 189.474 424.698 189.526 425.086 189.526C425.811 189.526 426.318 189.402 426.606 189.153C426.899 188.899 427.045 188.546 427.045 188.091C427.045 187.825 426.977 187.6 426.842 187.417C426.707 187.233 426.471 187.093 426.134 186.997C425.803 186.901 425.337 186.853 424.739 186.853H424.012V185.301H424.752C425.342 185.301 425.789 185.246 426.095 185.137C426.405 185.023 426.615 184.87 426.724 184.678C426.838 184.482 426.894 184.259 426.894 184.01C426.894 183.669 426.79 183.403 426.58 183.211C426.37 183.019 426.021 182.922 425.532 182.922C425.226 182.922 424.946 182.962 424.693 183.04C424.444 183.115 424.219 183.206 424.018 183.316C423.818 183.42 423.641 183.523 423.488 183.623L422.551 182.228C422.927 181.957 423.365 181.732 423.868 181.553C424.374 181.374 424.977 181.285 425.676 181.285C426.663 181.285 427.445 181.483 428.021 181.881C428.598 182.278 428.886 182.84 428.886 183.564Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M135 1.67761C135 0.751094 135.751 0 136.678 0H330.322C331.249 0 332 0.751093 332 1.67761V18.3224C332 19.2489 331.249 20 330.322 20H136.678C135.751 20 135 19.2489 135 18.3224V1.67761Z" fill="#F7F8FA"/>
+<path d="M145.983 6.56146V14H145.238L145.158 13.3055C144.963 13.5739 144.738 13.7752 144.483 13.9094C144.228 14.0436 143.953 14.1107 143.658 14.1107C142.987 14.1107 142.48 13.8658 142.138 13.3759C141.802 12.8861 141.635 12.2117 141.635 11.3527C141.635 10.8226 141.718 10.3495 141.886 9.93346C142.054 9.51071 142.292 9.18189 142.601 8.94703C142.916 8.70545 143.285 8.58466 143.708 8.58466C144.292 8.58466 144.768 8.79604 145.137 9.2188V6.4608L145.983 6.56146ZM143.93 9.26913C143.487 9.26913 143.144 9.4436 142.903 9.79254C142.668 10.1415 142.551 10.6615 142.551 11.3527C142.551 12.0372 142.658 12.5573 142.873 12.9129C143.094 13.2618 143.413 13.4363 143.829 13.4363C144.332 13.4363 144.768 13.1545 145.137 12.5908V9.9536C144.99 9.73215 144.812 9.56439 144.604 9.45031C144.396 9.32952 144.171 9.26913 143.93 9.26913ZM151.797 12.8424C151.797 13.0505 151.831 13.2048 151.898 13.3055C151.965 13.3994 152.075 13.4699 152.23 13.5168L152.018 14.1208C151.502 14.0537 151.18 13.802 151.052 13.3659C150.864 13.6074 150.626 13.792 150.337 13.9195C150.056 14.047 149.74 14.1107 149.391 14.1107C148.861 14.1107 148.442 13.9631 148.133 13.6678C147.831 13.3726 147.68 12.9767 147.68 12.4801C147.68 11.9365 147.891 11.5171 148.314 11.2219C148.744 10.9266 149.358 10.779 150.156 10.779H150.941V10.3462C150.941 9.97037 150.834 9.70195 150.619 9.5409C150.405 9.37314 150.093 9.28926 149.683 9.28926C149.281 9.28926 148.821 9.37985 148.304 9.56103L148.073 8.91683C148.697 8.69538 149.277 8.58466 149.814 8.58466C150.458 8.58466 150.948 8.73565 151.284 9.03762C151.626 9.33959 151.797 9.75899 151.797 10.2958V12.8424ZM149.603 13.4766C149.864 13.4766 150.113 13.4095 150.348 13.2753C150.589 13.1411 150.787 12.9565 150.941 12.7217V11.3628H150.176C149.613 11.3628 149.207 11.4567 148.958 11.6446C148.71 11.8325 148.586 12.1077 148.586 12.47C148.586 13.1411 148.925 13.4766 149.603 13.4766ZM158.245 13.7282C158.064 13.849 157.843 13.943 157.581 14.0101C157.326 14.0772 157.071 14.1107 156.816 14.1107C156.259 14.1107 155.823 13.9664 155.507 13.6779C155.192 13.3826 155.034 12.9968 155.034 12.5203V9.35972H153.816V8.69538H155.034V7.49757L155.88 7.39691V8.69538H157.722L157.611 9.35972H155.88V12.5103C155.88 12.8122 155.96 13.037 156.121 13.1847C156.282 13.3323 156.541 13.4061 156.896 13.4061C157.259 13.4061 157.598 13.3222 157.913 13.1545L158.245 13.7282ZM163.868 12.8424C163.868 13.0505 163.901 13.2048 163.969 13.3055C164.036 13.3994 164.146 13.4699 164.301 13.5168L164.089 14.1208C163.573 14.0537 163.251 13.802 163.123 13.3659C162.935 13.6074 162.697 13.792 162.408 13.9195C162.127 14.047 161.811 14.1107 161.462 14.1107C160.932 14.1107 160.513 13.9631 160.204 13.6678C159.902 13.3726 159.751 12.9767 159.751 12.4801C159.751 11.9365 159.962 11.5171 160.385 11.2219C160.815 10.9266 161.429 10.779 162.227 10.779H163.012V10.3462C163.012 9.97037 162.905 9.70195 162.69 9.5409C162.475 9.37314 162.163 9.28926 161.754 9.28926C161.351 9.28926 160.892 9.37985 160.375 9.56103L160.144 8.91683C160.768 8.69538 161.348 8.58466 161.885 8.58466C162.529 8.58466 163.019 8.73565 163.355 9.03762C163.697 9.33959 163.868 9.75899 163.868 10.2958V12.8424ZM161.674 13.4766C161.935 13.4766 162.184 13.4095 162.418 13.2753C162.66 13.1411 162.858 12.9565 163.012 12.7217V11.3628H162.247C161.684 11.3628 161.278 11.4567 161.029 11.6446C160.781 11.8325 160.657 12.1077 160.657 12.47C160.657 13.1411 160.996 13.4766 161.674 13.4766ZM166.944 9.38992C167.353 8.85308 167.86 8.58466 168.464 8.58466C169.142 8.58466 169.642 8.82624 169.964 9.30939C170.286 9.79254 170.447 10.4703 170.447 11.3427C170.447 12.1748 170.262 12.8458 169.893 13.3558C169.524 13.8591 169.008 14.1107 168.343 14.1107C167.733 14.1107 167.253 13.8893 166.904 13.4464L166.843 14H166.099V6.56146L166.944 6.4608V9.38992ZM168.152 13.4263C168.595 13.4263 168.934 13.2518 169.169 12.9028C169.41 12.5539 169.531 12.0338 169.531 11.3427C169.531 10.6582 169.424 10.1415 169.209 9.79254C169.001 9.4436 168.689 9.26913 168.273 9.26913C168.004 9.26913 167.756 9.34965 167.528 9.51071C167.306 9.67176 167.112 9.87307 166.944 10.1146V12.7418C167.085 12.9565 167.259 13.1243 167.468 13.2451C167.676 13.3659 167.904 13.4263 168.152 13.4263ZM175.939 12.8424C175.939 13.0505 175.972 13.2048 176.04 13.3055C176.107 13.3994 176.217 13.4699 176.372 13.5168L176.16 14.1208C175.644 14.0537 175.322 13.802 175.194 13.3659C175.006 13.6074 174.768 13.792 174.479 13.9195C174.198 14.047 173.882 14.1107 173.533 14.1107C173.003 14.1107 172.584 13.9631 172.275 13.6678C171.973 13.3726 171.822 12.9767 171.822 12.4801C171.822 11.9365 172.033 11.5171 172.456 11.2219C172.886 10.9266 173.5 10.779 174.298 10.779H175.083V10.3462C175.083 9.97037 174.976 9.70195 174.761 9.5409C174.546 9.37314 174.234 9.28926 173.825 9.28926C173.422 9.28926 172.963 9.37985 172.446 9.56103L172.215 8.91683C172.839 8.69538 173.419 8.58466 173.956 8.58466C174.6 8.58466 175.09 8.73565 175.426 9.03762C175.768 9.33959 175.939 9.75899 175.939 10.2958V12.8424ZM173.745 13.4766C174.006 13.4766 174.255 13.4095 174.489 13.2753C174.731 13.1411 174.929 12.9565 175.083 12.7217V11.3628H174.318C173.755 11.3628 173.349 11.4567 173.1 11.6446C172.852 11.8325 172.728 12.1077 172.728 12.47C172.728 13.1411 173.067 13.4766 173.745 13.4766ZM179.981 13.4162C180.384 13.4162 180.703 13.339 180.938 13.1847C181.172 13.0303 181.29 12.8257 181.29 12.5707C181.29 12.3962 181.26 12.2553 181.199 12.1479C181.139 12.0338 181.018 11.9332 180.837 11.8459C180.656 11.752 180.381 11.6581 180.012 11.5641C179.394 11.4098 178.938 11.2252 178.643 11.0105C178.347 10.789 178.2 10.4636 178.2 10.0341C178.2 9.59123 178.384 9.23893 178.753 8.97722C179.122 8.71552 179.609 8.58466 180.213 8.58466C180.951 8.58466 181.595 8.77927 182.145 9.16847L181.763 9.75228C181.542 9.59794 181.31 9.48051 181.068 9.39998C180.827 9.31275 180.548 9.26913 180.233 9.26913C179.468 9.26913 179.086 9.50064 179.086 9.96366C179.086 10.1247 179.126 10.2556 179.206 10.3562C179.294 10.4569 179.431 10.5475 179.619 10.628C179.814 10.7018 180.102 10.7924 180.485 10.8998C181.062 11.0541 181.491 11.2521 181.773 11.4936C182.062 11.7285 182.206 12.0741 182.206 12.5304C182.206 13.0605 181.991 13.4565 181.562 13.7182C181.132 13.9799 180.605 14.1107 179.981 14.1107C179.149 14.1107 178.458 13.8725 177.908 13.3961L178.381 12.8424C178.596 13.0169 178.841 13.1578 179.116 13.2652C179.391 13.3659 179.679 13.4162 179.981 13.4162ZM184.879 11.6446C184.9 12.2284 185.051 12.668 185.332 12.9632C185.621 13.2585 185.983 13.4061 186.419 13.4061C186.681 13.4061 186.919 13.3692 187.134 13.2954C187.356 13.2149 187.59 13.0941 187.839 12.933L188.231 13.4967C187.983 13.6913 187.698 13.8423 187.376 13.9497C187.06 14.057 186.742 14.1107 186.419 14.1107C185.654 14.1107 185.057 13.8624 184.628 13.3659C184.205 12.8626 183.994 12.1915 183.994 11.3527C183.994 10.8226 184.088 10.3495 184.275 9.93346C184.463 9.51071 184.732 9.18189 185.081 8.94703C185.43 8.70545 185.836 8.58466 186.299 8.58466C186.97 8.58466 187.496 8.81953 187.879 9.28926C188.268 9.75228 188.463 10.3864 188.463 11.1917C188.463 11.346 188.456 11.497 188.443 11.6446H184.879ZM186.309 9.27919C185.899 9.27919 185.567 9.42682 185.312 9.72208C185.057 10.0106 184.913 10.4367 184.879 11.0004H187.637C187.631 10.4435 187.51 10.0173 187.275 9.72208C187.04 9.42682 186.718 9.27919 186.309 9.27919ZM191.358 13.2249C191.358 12.9767 191.442 12.7686 191.609 12.6009C191.784 12.4264 191.995 12.3392 192.244 12.3392C192.499 12.3392 192.71 12.4264 192.878 12.6009C193.045 12.7686 193.129 12.9767 193.129 13.2249C193.129 13.4799 193.045 13.6913 192.878 13.8591C192.71 14.0268 192.499 14.1107 192.244 14.1107C191.995 14.1107 191.784 14.0268 191.609 13.8591C191.442 13.6846 191.358 13.4732 191.358 13.2249ZM198.088 13.4162C198.49 13.4162 198.809 13.339 199.044 13.1847C199.279 13.0303 199.396 12.8257 199.396 12.5707C199.396 12.3962 199.366 12.2553 199.306 12.1479C199.245 12.0338 199.125 11.9332 198.943 11.8459C198.762 11.752 198.487 11.6581 198.118 11.5641C197.501 11.4098 197.044 11.2252 196.749 11.0105C196.454 10.789 196.306 10.4636 196.306 10.0341C196.306 9.59123 196.491 9.23893 196.86 8.97722C197.229 8.71552 197.715 8.58466 198.319 8.58466C199.057 8.58466 199.702 8.77927 200.252 9.16847L199.869 9.75228C199.648 9.59794 199.416 9.48051 199.175 9.39998C198.933 9.31275 198.655 9.26913 198.339 9.26913C197.574 9.26913 197.192 9.50064 197.192 9.96366C197.192 10.1247 197.232 10.2556 197.313 10.3562C197.4 10.4569 197.538 10.5475 197.725 10.628C197.92 10.7018 198.209 10.7924 198.591 10.8998C199.168 11.0541 199.598 11.2521 199.879 11.4936C200.168 11.7285 200.312 12.0741 200.312 12.5304C200.312 13.0605 200.098 13.4565 199.668 13.7182C199.239 13.9799 198.712 14.1107 198.088 14.1107C197.256 14.1107 196.565 13.8725 196.014 13.3961L196.487 12.8424C196.702 13.0169 196.947 13.1578 197.222 13.2652C197.497 13.3659 197.786 13.4162 198.088 13.4162ZM204.808 14H203.831L201.909 8.69538H202.815L204.345 13.235L205.855 8.69538H206.74L204.808 14ZM210.753 13.386C211.216 13.386 211.675 13.2317 212.132 12.923L212.534 13.4766C212.313 13.6712 212.038 13.8255 211.709 13.9396C211.38 14.0537 211.061 14.1107 210.753 14.1107C209.967 14.1107 209.353 13.8658 208.911 13.3759C208.474 12.8794 208.256 12.2117 208.256 11.3729C208.256 10.8427 208.354 10.3663 208.548 9.94353C208.75 9.52077 209.038 9.1886 209.414 8.94703C209.79 8.70545 210.236 8.58466 210.753 8.58466C211.437 8.58466 212.028 8.79269 212.524 9.20873L212.111 9.76235C211.648 9.45367 211.192 9.29933 210.743 9.29933C210.266 9.29933 209.884 9.47715 209.595 9.83281C209.313 10.1818 209.172 10.6951 209.172 11.3729C209.172 12.0506 209.313 12.5573 209.595 12.8928C209.884 13.2216 210.269 13.386 210.753 13.386ZM215.5 13.2249C215.5 12.9767 215.584 12.7686 215.751 12.6009C215.926 12.4264 216.137 12.3392 216.385 12.3392C216.64 12.3392 216.852 12.4264 217.02 12.6009C217.187 12.7686 217.271 12.9767 217.271 13.2249C217.271 13.4799 217.187 13.6913 217.02 13.8591C216.852 14.0268 216.64 14.1107 216.385 14.1107C216.137 14.1107 215.926 14.0268 215.751 13.8591C215.584 13.6846 215.5 13.4732 215.5 13.2249ZM222.824 13.386C223.287 13.386 223.746 13.2317 224.203 12.923L224.605 13.4766C224.384 13.6712 224.109 13.8255 223.78 13.9396C223.451 14.0537 223.132 14.1107 222.824 14.1107C222.038 14.1107 221.424 13.8658 220.982 13.3759C220.545 12.8794 220.327 12.2117 220.327 11.3729C220.327 10.8427 220.425 10.3663 220.619 9.94353C220.82 9.52077 221.109 9.1886 221.485 8.94703C221.861 8.70545 222.307 8.58466 222.824 8.58466C223.508 8.58466 224.099 8.79269 224.595 9.20873L224.182 9.76235C223.719 9.45367 223.263 9.29933 222.814 9.29933C222.337 9.29933 221.955 9.47715 221.666 9.83281C221.384 10.1818 221.243 10.6951 221.243 11.3729C221.243 12.0506 221.384 12.5573 221.666 12.8928C221.955 13.2216 222.34 13.386 222.824 13.386ZM228.527 12.6915C228.527 13.1679 228.819 13.4061 229.403 13.4061C229.678 13.4061 229.973 13.3457 230.288 13.2249L230.51 13.8389C230.174 14.0201 229.755 14.1107 229.252 14.1107C228.775 14.1107 228.393 13.9799 228.104 13.7182C227.822 13.4565 227.681 13.1008 227.681 12.6512V7.23586H226.051V6.56146H228.527V12.6915ZM233.334 12.46C233.334 12.8022 233.405 13.0538 233.546 13.2149C233.693 13.3692 233.922 13.4464 234.23 13.4464C234.512 13.4464 234.784 13.3659 235.046 13.2048C235.307 13.0438 235.515 12.8424 235.67 12.6009V8.69538H236.515V14H235.79L235.72 13.2853C235.512 13.547 235.254 13.7517 234.945 13.8993C234.643 14.0403 234.334 14.1107 234.019 14.1107C233.516 14.1107 233.133 13.9765 232.871 13.7081C232.616 13.4397 232.489 13.0538 232.489 12.5505V8.69538H233.334V12.46ZM240.336 13.4162C240.739 13.4162 241.058 13.339 241.292 13.1847C241.527 13.0303 241.645 12.8257 241.645 12.5707C241.645 12.3962 241.614 12.2553 241.554 12.1479C241.494 12.0338 241.373 11.9332 241.192 11.8459C241.011 11.752 240.735 11.6581 240.366 11.5641C239.749 11.4098 239.293 11.2252 238.997 11.0105C238.702 10.789 238.555 10.4636 238.555 10.0341C238.555 9.59123 238.739 9.23893 239.108 8.97722C239.477 8.71552 239.964 8.58466 240.568 8.58466C241.306 8.58466 241.95 8.77927 242.5 9.16847L242.118 9.75228C241.896 9.59794 241.665 9.48051 241.423 9.39998C241.182 9.31275 240.903 9.26913 240.588 9.26913C239.823 9.26913 239.44 9.50064 239.44 9.96366C239.44 10.1247 239.481 10.2556 239.561 10.3562C239.648 10.4569 239.786 10.5475 239.974 10.628C240.168 10.7018 240.457 10.7924 240.839 10.8998C241.417 11.0541 241.846 11.2521 242.128 11.4936C242.416 11.7285 242.561 12.0741 242.561 12.5304C242.561 13.0605 242.346 13.4565 241.916 13.7182C241.487 13.9799 240.96 14.1107 240.336 14.1107C239.504 14.1107 238.813 13.8725 238.263 13.3961L238.736 12.8424C238.95 13.0169 239.195 13.1578 239.47 13.2652C239.746 13.3659 240.034 13.4162 240.336 13.4162ZM248.777 13.7282C248.596 13.849 248.375 13.943 248.113 14.0101C247.858 14.0772 247.603 14.1107 247.348 14.1107C246.791 14.1107 246.355 13.9664 246.039 13.6779C245.724 13.3826 245.566 12.9968 245.566 12.5203V9.35972H244.348V8.69538H245.566V7.49757L246.412 7.39691V8.69538H248.254L248.143 9.35972H246.412V12.5103C246.412 12.8122 246.492 13.037 246.653 13.1847C246.814 13.3323 247.073 13.4061 247.429 13.4061C247.791 13.4061 248.13 13.3222 248.445 13.1545L248.777 13.7282ZM251.27 11.6446C251.29 12.2284 251.441 12.668 251.723 12.9632C252.011 13.2585 252.374 13.4061 252.81 13.4061C253.071 13.4061 253.31 13.3692 253.524 13.2954C253.746 13.2149 253.981 13.0941 254.229 12.933L254.622 13.4967C254.373 13.6913 254.088 13.8423 253.766 13.9497C253.451 14.057 253.132 14.1107 252.81 14.1107C252.045 14.1107 251.447 13.8624 251.018 13.3659C250.595 12.8626 250.384 12.1915 250.384 11.3527C250.384 10.8226 250.478 10.3495 250.666 9.93346C250.854 9.51071 251.122 9.18189 251.471 8.94703C251.82 8.70545 252.226 8.58466 252.689 8.58466C253.36 8.58466 253.887 8.81953 254.269 9.28926C254.658 9.75228 254.853 10.3864 254.853 11.1917C254.853 11.346 254.846 11.497 254.833 11.6446H251.27ZM252.699 9.27919C252.29 9.27919 251.957 9.42682 251.702 9.72208C251.447 10.0106 251.303 10.4367 251.27 11.0004H254.028C254.021 10.4435 253.9 10.0173 253.665 9.72208C253.43 9.42682 253.108 9.27919 252.699 9.27919ZM260.214 8.58466C260.429 8.58466 260.677 8.62157 260.959 8.69538L260.838 10.4971H260.154V9.35972H260.103C259.285 9.35972 258.704 9.94353 258.362 11.1111V13.3457H259.439V14H256.681V13.3457H257.517V9.34965H256.681V8.69538H258.151L258.312 9.9536C258.526 9.49728 258.781 9.15505 259.077 8.9269C259.379 8.69874 259.758 8.58466 260.214 8.58466ZM263.784 13.2249C263.784 12.9767 263.867 12.7686 264.035 12.6009C264.21 12.4264 264.421 12.3392 264.669 12.3392C264.924 12.3392 265.136 12.4264 265.303 12.6009C265.471 12.7686 265.555 12.9767 265.555 13.2249C265.555 13.4799 265.471 13.6913 265.303 13.8591C265.136 14.0268 264.924 14.1107 264.669 14.1107C264.421 14.1107 264.21 14.0268 264.035 13.8591C263.867 13.6846 263.784 13.4732 263.784 13.2249ZM270.775 12.6915C270.775 13.1679 271.067 13.4061 271.651 13.4061C271.926 13.4061 272.221 13.3457 272.537 13.2249L272.758 13.8389C272.423 14.0201 272.003 14.1107 271.5 14.1107C271.024 14.1107 270.641 13.9799 270.352 13.7182C270.071 13.4565 269.93 13.1008 269.93 12.6512V7.23586H268.299V6.56146H270.775V12.6915ZM276.76 8.58466C277.492 8.58466 278.052 8.83295 278.441 9.32952C278.837 9.81939 279.035 10.4904 279.035 11.3427C279.035 12.1748 278.834 12.8458 278.431 13.3558C278.035 13.8591 277.475 14.1107 276.75 14.1107C276.019 14.1107 275.455 13.8658 275.059 13.3759C274.663 12.8794 274.465 12.205 274.465 11.3527C274.465 10.5139 274.663 9.84287 275.059 9.33959C275.462 8.8363 276.029 8.58466 276.76 8.58466ZM276.76 9.27919C276.297 9.27919 275.952 9.45031 275.724 9.79254C275.495 10.1348 275.381 10.6548 275.381 11.3527C275.381 12.0506 275.492 12.5707 275.714 12.9129C275.942 13.2484 276.287 13.4162 276.75 13.4162C277.213 13.4162 277.556 13.2484 277.777 12.9129C278.005 12.5707 278.119 12.0473 278.119 11.3427C278.119 10.6448 278.005 10.1281 277.777 9.79254C277.556 9.45031 277.217 9.27919 276.76 9.27919ZM283.178 13.386C283.641 13.386 284.101 13.2317 284.557 12.923L284.96 13.4766C284.739 13.6712 284.463 13.8255 284.135 13.9396C283.806 14.0537 283.487 14.1107 283.178 14.1107C282.393 14.1107 281.779 13.8658 281.336 13.3759C280.9 12.8794 280.682 12.2117 280.682 11.3729C280.682 10.8427 280.779 10.3663 280.974 9.94353C281.175 9.52077 281.464 9.1886 281.84 8.94703C282.215 8.70545 282.662 8.58466 283.178 8.58466C283.863 8.58466 284.453 8.79269 284.95 9.20873L284.537 9.76235C284.074 9.45367 283.618 9.29933 283.168 9.29933C282.692 9.29933 282.309 9.47715 282.021 9.83281C281.739 10.1818 281.598 10.6951 281.598 11.3729C281.598 12.0506 281.739 12.5573 282.021 12.8928C282.309 13.2216 282.695 13.386 283.178 13.386ZM290.613 12.8424C290.613 13.0505 290.647 13.2048 290.714 13.3055C290.781 13.3994 290.891 13.4699 291.046 13.5168L290.834 14.1208C290.318 14.0537 289.996 13.802 289.868 13.3659C289.68 13.6074 289.442 13.792 289.153 13.9195C288.872 14.047 288.556 14.1107 288.207 14.1107C287.677 14.1107 287.258 13.9631 286.949 13.6678C286.647 13.3726 286.496 12.9767 286.496 12.4801C286.496 11.9365 286.707 11.5171 287.13 11.2219C287.56 10.9266 288.174 10.779 288.972 10.779H289.757V10.3462C289.757 9.97037 289.65 9.70195 289.435 9.5409C289.221 9.37314 288.909 9.28926 288.499 9.28926C288.097 9.28926 287.637 9.37985 287.12 9.56103L286.889 8.91683C287.513 8.69538 288.093 8.58466 288.63 8.58466C289.274 8.58466 289.764 8.73565 290.1 9.03762C290.442 9.33959 290.613 9.75899 290.613 10.2958V12.8424ZM288.419 13.4766C288.68 13.4766 288.929 13.4095 289.163 13.2753C289.405 13.1411 289.603 12.9565 289.757 12.7217V11.3628H288.992C288.429 11.3628 288.023 11.4567 287.774 11.6446C287.526 11.8325 287.402 12.1077 287.402 12.47C287.402 13.1411 287.741 13.4766 288.419 13.4766ZM294.917 12.6915C294.917 13.1679 295.209 13.4061 295.793 13.4061C296.068 13.4061 296.363 13.3457 296.679 13.2249L296.9 13.8389C296.565 14.0201 296.145 14.1107 295.642 14.1107C295.165 14.1107 294.783 13.9799 294.494 13.7182C294.213 13.4565 294.072 13.1008 294.072 12.6512V7.23586H292.441V6.56146H294.917V12.6915ZM300.077 9.66169C300.077 9.44025 300.154 9.25235 300.308 9.09801C300.463 8.93696 300.654 8.85644 300.882 8.85644C301.117 8.85644 301.312 8.93696 301.466 9.09801C301.62 9.25235 301.697 9.44025 301.697 9.66169C301.697 9.88985 301.62 10.0844 301.466 10.2455C301.312 10.4066 301.117 10.4871 300.882 10.4871C300.654 10.4871 300.463 10.4066 300.308 10.2455C300.154 10.0844 300.077 9.88985 300.077 9.66169ZM300.077 13.2954C300.077 13.074 300.154 12.8827 300.308 12.7217C300.463 12.5606 300.654 12.4801 300.882 12.4801C301.117 12.4801 301.312 12.5606 301.466 12.7217C301.62 12.876 301.697 13.0672 301.697 13.2954C301.697 13.5303 301.62 13.7249 301.466 13.8792C301.312 14.0336 301.117 14.1107 300.882 14.1107C300.654 14.1107 300.463 14.0336 300.308 13.8792C300.154 13.7249 300.077 13.5303 300.077 13.2954ZM308.689 7.74921H305.951V9.93346C306.146 9.81939 306.337 9.74222 306.525 9.70195C306.72 9.65498 306.924 9.63149 307.139 9.63149C307.716 9.63149 308.176 9.82274 308.518 10.2052C308.867 10.5877 309.042 11.1212 309.042 11.8057C309.042 12.262 308.944 12.6646 308.75 13.0136C308.562 13.3625 308.29 13.6343 307.934 13.8289C307.579 14.0168 307.166 14.1107 306.696 14.1107C305.924 14.1107 305.253 13.8356 304.683 13.2853L305.206 12.772C305.629 13.2015 306.126 13.4162 306.696 13.4162C307.159 13.4162 307.518 13.2753 307.773 12.9934C308.028 12.7116 308.156 12.3056 308.156 11.7755C308.156 11.2521 308.042 10.8763 307.813 10.6481C307.585 10.4133 307.28 10.2958 306.898 10.2958C306.716 10.2958 306.552 10.3126 306.404 10.3462C306.257 10.3797 306.062 10.4401 305.82 10.5273H305.136V7.06474H308.81L308.689 7.74921ZM315.258 12.319H314.362V14H313.547V12.319H310.668V11.695L312.701 6.95402L313.406 7.25599L311.564 11.6346H313.557L313.628 9.67176H314.362V11.6346H315.258V12.319ZM318.687 6.95402C319.109 6.95402 319.482 7.03455 319.804 7.1956C320.126 7.34994 320.374 7.56132 320.549 7.82974C320.723 8.09144 320.81 8.37999 320.81 8.69538C320.81 9.09801 320.68 9.45031 320.418 9.75228C320.156 10.0475 319.837 10.2321 319.462 10.3059C319.898 10.3394 320.267 10.5039 320.569 10.7991C320.878 11.0944 321.032 11.497 321.032 12.007C321.032 12.4029 320.931 12.7619 320.73 13.084C320.529 13.4061 320.243 13.6578 319.874 13.8389C319.512 14.0201 319.096 14.1107 318.626 14.1107C318.217 14.1107 317.821 14.0336 317.438 13.8792C317.063 13.7249 316.751 13.4967 316.502 13.1947L317.066 12.7317C317.254 12.9532 317.482 13.1243 317.751 13.2451C318.026 13.3592 318.311 13.4162 318.606 13.4162C319.089 13.4162 319.465 13.292 319.733 13.0438C320.009 12.7888 320.146 12.4432 320.146 12.007C320.146 11.1279 319.666 10.6884 318.707 10.6884H318.133L318.234 10.014H318.646C319.009 10.014 319.317 9.91333 319.572 9.71202C319.827 9.50399 319.955 9.20202 319.955 8.80611C319.955 8.43703 319.831 8.15184 319.582 7.95052C319.341 7.7425 319.029 7.63849 318.646 7.63849C318.358 7.63849 318.099 7.68882 317.871 7.78947C317.65 7.89013 317.418 8.05118 317.177 8.27263L316.714 7.75928C317.277 7.22244 317.935 6.95402 318.687 6.95402ZM324.722 6.95402C325.145 6.95402 325.514 7.0379 325.829 7.20566C326.151 7.37342 326.396 7.60494 326.564 7.9002C326.732 8.18875 326.816 8.51756 326.816 8.88663C326.816 9.3161 326.715 9.73215 326.514 10.1348C326.319 10.5374 326.004 10.9803 325.568 11.4634C325.131 11.9399 324.514 12.5438 323.716 13.2753H326.977L326.876 14H322.749V13.3155C323.655 12.4499 324.326 11.7721 324.762 11.2823C325.205 10.7924 325.511 10.373 325.678 10.0241C325.846 9.67511 325.93 9.30604 325.93 8.91683C325.93 8.52762 325.819 8.2223 325.598 8.00085C325.376 7.77941 325.071 7.66869 324.682 7.66869C324.353 7.66869 324.078 7.72572 323.856 7.8398C323.642 7.94717 323.42 8.13506 323.192 8.40348L322.608 7.95052C322.883 7.60829 323.189 7.35665 323.524 7.1956C323.867 7.03455 324.266 6.95402 324.722 6.95402Z" fill="#252937"/>
+<defs>
+<linearGradient id="paint0_linear_0_1" x1="426.5" y1="54.5728" x2="426.5" y2="351.204" gradientUnits="userSpaceOnUse">
+<stop stop-color="#E80134"/>
+<stop offset="1" stop-color="#AC0027"/>
+</linearGradient>
+<linearGradient id="paint1_linear_0_1" x1="249.5" y1="54.5728" x2="249.5" y2="351.204" gradientUnits="userSpaceOnUse">
+<stop stop-color="#E80134"/>
+<stop offset="1" stop-color="#AC0027"/>
+</linearGradient>
+</defs>
+</svg>
diff --git a/website/public/img/consul-connect/without-transparent-proxy.png b/website/public/img/consul-connect/without-transparent-proxy.png
new file mode 100644
index 0000000000000000000000000000000000000000..182af53e4356d76e264a307d682de930918ab9cc
GIT binary patch
literal 41372
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
XUbjP>u>|!6#e+*or}LC^UP=D|Hdf?I

literal 0
HcmV?d00001

diff --git a/website/public/img/consul-connect/without-transparent-proxy.svg b/website/public/img/consul-connect/without-transparent-proxy.svg
new file mode 100644
index 0000000000..21ac998e67
--- /dev/null
+++ b/website/public/img/consul-connect/without-transparent-proxy.svg
@@ -0,0 +1,82 @@
+<svg width="541" height="348" viewBox="0 0 541 348" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M145 51.6627H243C244.795 51.6627 246.25 53.1178 246.25 54.9127V343.544C246.25 345.339 244.795 346.794 243 346.794H145C143.205 346.794 141.75 345.339 141.75 343.544V54.9127C141.75 53.1178 143.205 51.6627 145 51.6627Z" stroke="#D2D4DB" stroke-width="1.5"/>
+<path d="M439 51.6627H537C538.795 51.6627 540.25 53.1178 540.25 54.9127V343.544C540.25 345.339 538.795 346.794 537 346.794H439C437.205 346.794 435.75 345.339 435.75 343.544V54.9127C435.75 53.1178 437.205 51.6627 439 51.6627Z" stroke="#D2D4DB" stroke-width="1.5"/>
+<rect x="153" y="42.8412" width="42" height="16.1432" fill="white"/>
+<rect x="447" y="42.8412" width="42" height="16.1432" fill="white"/>
+<path d="M160.497 46.1475C161.51 46.1475 162.249 46.3659 162.715 46.8027C163.18 47.236 163.413 47.834 163.413 48.5967C163.413 48.9404 163.361 49.2699 163.257 49.585C163.153 49.8965 162.983 50.174 162.747 50.4175C162.514 50.661 162.203 50.8543 161.812 50.9976C161.422 51.1372 160.941 51.207 160.368 51.207H159.653V54H157.988V46.1475H160.497ZM160.411 47.5117H159.653V49.8428H160.201C160.513 49.8428 160.783 49.8016 161.012 49.7192C161.241 49.6369 161.419 49.508 161.544 49.3325C161.669 49.1571 161.732 48.9315 161.732 48.6558C161.732 48.269 161.625 47.9826 161.41 47.7964C161.195 47.6066 160.862 47.5117 160.411 47.5117ZM172.023 50.063C172.023 50.6681 171.948 51.2196 171.797 51.7173C171.647 52.2114 171.418 52.6375 171.11 52.9956C170.806 53.3537 170.419 53.6294 169.95 53.8228C169.481 54.0125 168.926 54.1074 168.285 54.1074C167.644 54.1074 167.089 54.0125 166.62 53.8228C166.151 53.6294 165.762 53.3537 165.454 52.9956C165.15 52.6375 164.922 52.2096 164.772 51.7119C164.622 51.2142 164.546 50.661 164.546 50.0522C164.546 49.2394 164.679 48.5322 164.944 47.9307C165.212 47.3255 165.624 46.8564 166.179 46.5234C166.734 46.1904 167.44 46.0239 168.295 46.0239C169.148 46.0239 169.848 46.1904 170.396 46.5234C170.947 46.8564 171.355 47.3255 171.62 47.9307C171.889 48.5358 172.023 49.2466 172.023 50.063ZM166.292 50.063C166.292 50.6108 166.36 51.0835 166.496 51.481C166.636 51.8748 166.852 52.1792 167.146 52.394C167.44 52.6053 167.819 52.7109 168.285 52.7109C168.757 52.7109 169.14 52.6053 169.434 52.394C169.728 52.1792 169.941 51.8748 170.073 51.481C170.209 51.0835 170.277 50.6108 170.277 50.063C170.277 49.2394 170.123 48.5913 169.815 48.1187C169.507 47.646 169.001 47.4097 168.295 47.4097C167.826 47.4097 167.443 47.5171 167.146 47.7319C166.852 47.9432 166.636 48.2476 166.496 48.645C166.36 49.0389 166.292 49.5116 166.292 50.063ZM180.166 49.9985C180.166 50.883 179.995 51.6224 179.655 52.2168C179.319 52.8076 178.83 53.2534 178.189 53.5542C177.548 53.8514 176.776 54 175.874 54H173.65V46.1475H176.116C176.939 46.1475 177.654 46.2943 178.259 46.5879C178.864 46.8779 179.333 47.3094 179.666 47.8823C179.999 48.4517 180.166 49.1571 180.166 49.9985ZM178.436 50.0415C178.436 49.4614 178.35 48.9852 178.178 48.6128C178.01 48.2368 177.759 47.9593 177.426 47.7803C177.097 47.6012 176.689 47.5117 176.202 47.5117H175.315V52.625H176.03C176.843 52.625 177.446 52.4084 177.84 51.9751C178.237 51.5418 178.436 50.8973 178.436 50.0415ZM189.458 54L188.888 52.1309H186.025L185.456 54H183.662L186.434 46.1152H188.469L191.251 54H189.458ZM188.491 50.7344L187.921 48.9082C187.886 48.7865 187.837 48.6307 187.776 48.4409C187.719 48.2476 187.66 48.0524 187.599 47.8555C187.542 47.6549 187.495 47.4813 187.459 47.3345C187.424 47.4813 187.374 47.6639 187.309 47.8823C187.248 48.0972 187.189 48.3013 187.132 48.4946C187.075 48.688 187.033 48.8258 187.008 48.9082L186.444 50.7344H188.491Z" fill="#9194A0"/>
+<rect x="153" y="42.8412" width="42" height="16.1432" fill="white"/>
+<path d="M160.497 46.1475C161.51 46.1475 162.249 46.3659 162.715 46.8027C163.18 47.236 163.413 47.834 163.413 48.5967C163.413 48.9404 163.361 49.2699 163.257 49.585C163.153 49.8965 162.983 50.174 162.747 50.4175C162.514 50.661 162.203 50.8543 161.812 50.9976C161.422 51.1372 160.941 51.207 160.368 51.207H159.653V54H157.988V46.1475H160.497ZM160.411 47.5117H159.653V49.8428H160.201C160.513 49.8428 160.783 49.8016 161.012 49.7192C161.241 49.6369 161.419 49.508 161.544 49.3325C161.669 49.1571 161.732 48.9315 161.732 48.6558C161.732 48.269 161.625 47.9826 161.41 47.7964C161.195 47.6066 160.862 47.5117 160.411 47.5117ZM172.023 50.063C172.023 50.6681 171.948 51.2196 171.797 51.7173C171.647 52.2114 171.418 52.6375 171.11 52.9956C170.806 53.3537 170.419 53.6294 169.95 53.8228C169.481 54.0125 168.926 54.1074 168.285 54.1074C167.644 54.1074 167.089 54.0125 166.62 53.8228C166.151 53.6294 165.762 53.3537 165.454 52.9956C165.15 52.6375 164.922 52.2096 164.772 51.7119C164.622 51.2142 164.546 50.661 164.546 50.0522C164.546 49.2394 164.679 48.5322 164.944 47.9307C165.212 47.3255 165.624 46.8564 166.179 46.5234C166.734 46.1904 167.44 46.0239 168.295 46.0239C169.148 46.0239 169.848 46.1904 170.396 46.5234C170.947 46.8564 171.355 47.3255 171.62 47.9307C171.889 48.5358 172.023 49.2466 172.023 50.063ZM166.292 50.063C166.292 50.6108 166.36 51.0835 166.496 51.481C166.636 51.8748 166.852 52.1792 167.146 52.394C167.44 52.6053 167.819 52.7109 168.285 52.7109C168.757 52.7109 169.14 52.6053 169.434 52.394C169.728 52.1792 169.941 51.8748 170.073 51.481C170.209 51.0835 170.277 50.6108 170.277 50.063C170.277 49.2394 170.123 48.5913 169.815 48.1187C169.507 47.646 169.001 47.4097 168.295 47.4097C167.826 47.4097 167.443 47.5171 167.146 47.7319C166.852 47.9432 166.636 48.2476 166.496 48.645C166.36 49.0389 166.292 49.5116 166.292 50.063ZM180.166 49.9985C180.166 50.883 179.995 51.6224 179.655 52.2168C179.319 52.8076 178.83 53.2534 178.189 53.5542C177.548 53.8514 176.776 54 175.874 54H173.65V46.1475H176.116C176.939 46.1475 177.654 46.2943 178.259 46.5879C178.864 46.8779 179.333 47.3094 179.666 47.8823C179.999 48.4517 180.166 49.1571 180.166 49.9985ZM178.436 50.0415C178.436 49.4614 178.35 48.9852 178.178 48.6128C178.01 48.2368 177.759 47.9593 177.426 47.7803C177.097 47.6012 176.689 47.5117 176.202 47.5117H175.315V52.625H176.03C176.843 52.625 177.446 52.4084 177.84 51.9751C178.237 51.5418 178.436 50.8973 178.436 50.0415ZM189.458 54L188.888 52.1309H186.025L185.456 54H183.662L186.434 46.1152H188.469L191.251 54H189.458ZM188.491 50.7344L187.921 48.9082C187.886 48.7865 187.837 48.6307 187.776 48.4409C187.719 48.2476 187.66 48.0524 187.599 47.8555C187.542 47.6549 187.495 47.4813 187.459 47.3345C187.424 47.4813 187.374 47.6639 187.309 47.8823C187.248 48.0972 187.189 48.3013 187.132 48.4946C187.075 48.688 187.033 48.8258 187.008 48.9082L186.444 50.7344H188.491Z" fill="#9194A0"/>
+<path d="M454.497 46.1475C455.51 46.1475 456.249 46.3659 456.715 46.8027C457.18 47.236 457.413 47.834 457.413 48.5967C457.413 48.9404 457.361 49.2699 457.257 49.585C457.153 49.8965 456.983 50.174 456.747 50.4175C456.514 50.661 456.203 50.8543 455.812 50.9976C455.422 51.1372 454.941 51.207 454.368 51.207H453.653V54H451.988V46.1475H454.497ZM454.411 47.5117H453.653V49.8428H454.201C454.513 49.8428 454.783 49.8016 455.012 49.7192C455.241 49.6369 455.419 49.508 455.544 49.3325C455.669 49.1571 455.732 48.9315 455.732 48.6558C455.732 48.269 455.625 47.9826 455.41 47.7964C455.195 47.6066 454.862 47.5117 454.411 47.5117ZM466.023 50.063C466.023 50.6681 465.948 51.2196 465.797 51.7173C465.647 52.2114 465.418 52.6375 465.11 52.9956C464.806 53.3537 464.419 53.6294 463.95 53.8228C463.481 54.0125 462.926 54.1074 462.285 54.1074C461.644 54.1074 461.089 54.0125 460.62 53.8228C460.151 53.6294 459.762 53.3537 459.454 52.9956C459.15 52.6375 458.922 52.2096 458.772 51.7119C458.622 51.2142 458.546 50.661 458.546 50.0522C458.546 49.2394 458.679 48.5322 458.944 47.9307C459.212 47.3255 459.624 46.8564 460.179 46.5234C460.734 46.1904 461.44 46.0239 462.295 46.0239C463.148 46.0239 463.848 46.1904 464.396 46.5234C464.947 46.8564 465.355 47.3255 465.62 47.9307C465.889 48.5358 466.023 49.2466 466.023 50.063ZM460.292 50.063C460.292 50.6108 460.36 51.0835 460.496 51.481C460.636 51.8748 460.852 52.1792 461.146 52.394C461.44 52.6053 461.819 52.7109 462.285 52.7109C462.757 52.7109 463.14 52.6053 463.434 52.394C463.728 52.1792 463.941 51.8748 464.073 51.481C464.209 51.0835 464.277 50.6108 464.277 50.063C464.277 49.2394 464.123 48.5913 463.815 48.1187C463.507 47.646 463.001 47.4097 462.295 47.4097C461.826 47.4097 461.443 47.5171 461.146 47.7319C460.852 47.9432 460.636 48.2476 460.496 48.645C460.36 49.0389 460.292 49.5116 460.292 50.063ZM474.166 49.9985C474.166 50.883 473.995 51.6224 473.655 52.2168C473.319 52.8076 472.83 53.2534 472.189 53.5542C471.548 53.8514 470.776 54 469.874 54H467.65V46.1475H470.116C470.939 46.1475 471.654 46.2943 472.259 46.5879C472.864 46.8779 473.333 47.3094 473.666 47.8823C473.999 48.4517 474.166 49.1571 474.166 49.9985ZM472.436 50.0415C472.436 49.4614 472.35 48.9852 472.178 48.6128C472.01 48.2368 471.759 47.9593 471.426 47.7803C471.097 47.6012 470.689 47.5117 470.202 47.5117H469.315V52.625H470.03C470.843 52.625 471.446 52.4084 471.84 51.9751C472.237 51.5418 472.436 50.8973 472.436 50.0415ZM478.65 46.1475H481.094C482.14 46.1475 482.931 46.2943 483.468 46.5879C484.005 46.8815 484.274 47.3971 484.274 48.1348C484.274 48.432 484.226 48.7005 484.129 48.9404C484.036 49.1803 483.9 49.3773 483.721 49.5312C483.542 49.6852 483.323 49.7855 483.065 49.832V49.8857C483.327 49.9395 483.563 50.0326 483.774 50.165C483.986 50.2939 484.154 50.4837 484.279 50.7344C484.408 50.9814 484.473 51.3109 484.473 51.7227C484.473 52.1989 484.356 52.6071 484.124 52.9473C483.891 53.2874 483.558 53.5488 483.125 53.7314C482.695 53.9105 482.183 54 481.588 54H478.65V46.1475ZM480.315 49.2573H481.282C481.766 49.2573 482.1 49.1821 482.287 49.0317C482.473 48.8778 482.566 48.6522 482.566 48.355C482.566 48.0542 482.455 47.8394 482.233 47.7104C482.014 47.578 481.667 47.5117 481.191 47.5117H480.315V49.2573ZM480.315 50.5786V52.625H481.4C481.902 52.625 482.251 52.5283 482.448 52.335C482.645 52.1416 482.743 51.882 482.743 51.5562C482.743 51.3628 482.7 51.1927 482.614 51.0459C482.528 50.8991 482.383 50.7845 482.179 50.7021C481.979 50.6198 481.701 50.5786 481.347 50.5786H480.315Z" fill="#9194A0"/>
+<path d="M159 84.75H227C227.69 84.75 228.25 85.3096 228.25 86V154C228.25 154.69 227.69 155.25 227 155.25H159C158.31 155.25 157.75 154.69 157.75 154V86C157.75 85.3096 158.31 84.75 159 84.75Z" fill="white" stroke="#D2D4DB" stroke-width="1.5"/>
+<rect x="175" y="101" width="36" height="37" rx="1" fill="white" stroke="black" stroke-width="2"/>
+<rect x="175" y="101" width="36" height="8" rx="1" fill="white" stroke="black" stroke-width="2"/>
+<path d="M189.965 126.766L183.156 123.752V122.591L189.947 119.187V121.188L185.781 123.085L189.947 124.817L189.965 126.766Z" fill="black"/>
+<path d="M196.521 118L192.865 128.1H190.535L194.199 118H196.521Z" fill="black"/>
+<path d="M197.016 124.791L201.182 123.059L197.016 121.197V119.196L203.807 122.6V123.752L197.016 126.766V124.791Z" fill="black"/>
+<path d="M191.046 166.434L188.867 175H186.798L185.638 170.5C185.615 170.414 185.583 170.283 185.544 170.107C185.505 169.932 185.464 169.74 185.421 169.533C185.378 169.322 185.339 169.125 185.304 168.941C185.273 168.754 185.251 168.605 185.24 168.496C185.228 168.605 185.204 168.752 185.169 168.936C185.138 169.119 185.101 169.314 185.058 169.521C185.019 169.729 184.98 169.922 184.941 170.102C184.902 170.281 184.87 170.418 184.847 170.512L183.693 175H181.63L179.445 166.434H181.232L182.327 171.109C182.359 171.25 182.394 171.418 182.433 171.613C182.476 171.809 182.517 172.014 182.556 172.229C182.599 172.439 182.636 172.645 182.667 172.844C182.702 173.039 182.728 173.209 182.744 173.354C182.763 173.205 182.788 173.033 182.82 172.838C182.851 172.639 182.884 172.438 182.919 172.234C182.958 172.027 182.997 171.836 183.036 171.66C183.076 171.484 183.111 171.342 183.142 171.232L184.39 166.434H186.107L187.355 171.232C187.382 171.338 187.413 171.48 187.449 171.66C187.488 171.836 187.527 172.027 187.566 172.234C187.605 172.441 187.64 172.645 187.671 172.844C187.706 173.039 187.732 173.209 187.747 173.354C187.775 173.158 187.812 172.922 187.859 172.645C187.91 172.363 187.962 172.084 188.017 171.807C188.076 171.529 188.126 171.297 188.169 171.109L189.259 166.434H191.046ZM197.298 175H192.364V166.434H197.298V167.922H194.181V169.803H197.081V171.291H194.181V173.5H197.298V175ZM199.331 166.434H201.997C203.138 166.434 204.001 166.594 204.587 166.914C205.173 167.234 205.466 167.797 205.466 168.602C205.466 168.926 205.413 169.219 205.307 169.48C205.206 169.742 205.057 169.957 204.862 170.125C204.667 170.293 204.429 170.402 204.147 170.453V170.512C204.432 170.57 204.69 170.672 204.921 170.816C205.151 170.957 205.335 171.164 205.472 171.438C205.612 171.707 205.682 172.066 205.682 172.516C205.682 173.035 205.556 173.48 205.302 173.852C205.048 174.223 204.684 174.508 204.212 174.707C203.743 174.902 203.184 175 202.536 175H199.331V166.434ZM201.147 169.826H202.202C202.729 169.826 203.095 169.744 203.298 169.58C203.501 169.412 203.602 169.166 203.602 168.842C203.602 168.514 203.481 168.279 203.239 168.139C203.001 167.994 202.622 167.922 202.102 167.922H201.147V169.826ZM201.147 171.268V173.5H202.331C202.878 173.5 203.259 173.395 203.474 173.184C203.688 172.973 203.796 172.689 203.796 172.334C203.796 172.123 203.749 171.938 203.655 171.777C203.561 171.617 203.403 171.492 203.181 171.402C202.962 171.312 202.659 171.268 202.272 171.268H201.147Z" fill="#6A6D7A"/>
+<path d="M24.8818 317.434V322.977C24.8818 323.566 24.7509 324.1 24.4892 324.576C24.2314 325.049 23.8388 325.424 23.3115 325.701C22.788 325.979 22.1279 326.117 21.331 326.117C20.1982 326.117 19.3349 325.828 18.7412 325.25C18.1474 324.672 17.8505 323.906 17.8505 322.953V317.434H19.6611V322.678C19.6611 323.385 19.8056 323.881 20.0947 324.166C20.3838 324.451 20.8115 324.594 21.3779 324.594C21.7763 324.594 22.0986 324.525 22.3447 324.389C22.5947 324.252 22.7783 324.041 22.8955 323.756C23.0127 323.471 23.0713 323.107 23.0713 322.666V317.434H24.8818ZM29.9558 317.434C31.0613 317.434 31.8679 317.672 32.3757 318.148C32.8835 318.621 33.1374 319.273 33.1374 320.105C33.1374 320.48 33.0808 320.84 32.9675 321.184C32.8542 321.523 32.6687 321.826 32.4109 322.092C32.157 322.357 31.8171 322.568 31.3913 322.725C30.9655 322.877 30.4402 322.953 29.8152 322.953H29.0359V326H27.2195V317.434H29.9558ZM29.862 318.922H29.0359V321.465H29.6335C29.9734 321.465 30.2683 321.42 30.5183 321.33C30.7683 321.24 30.9616 321.1 31.0984 320.908C31.2351 320.717 31.3034 320.471 31.3034 320.17C31.3034 319.748 31.1863 319.436 30.9519 319.232C30.7175 319.025 30.3542 318.922 29.862 318.922ZM40.0513 323.621C40.0513 324.129 39.9282 324.57 39.6821 324.945C39.436 325.32 39.0766 325.609 38.604 325.812C38.1352 326.016 37.5649 326.117 36.893 326.117C36.5962 326.117 36.3052 326.098 36.02 326.059C35.7388 326.02 35.4673 325.963 35.2055 325.889C34.9477 325.811 34.7016 325.715 34.4673 325.602V323.914C34.8735 324.094 35.2954 324.256 35.7329 324.4C36.1704 324.545 36.604 324.617 37.0337 324.617C37.3305 324.617 37.5688 324.578 37.7485 324.5C37.9321 324.422 38.0649 324.314 38.147 324.178C38.229 324.041 38.27 323.885 38.27 323.709C38.27 323.494 38.1977 323.311 38.0532 323.158C37.9087 323.006 37.7095 322.863 37.4555 322.73C37.2055 322.598 36.9223 322.455 36.6059 322.303C36.4067 322.209 36.1899 322.096 35.9555 321.963C35.7212 321.826 35.4985 321.66 35.2876 321.465C35.0766 321.27 34.9028 321.033 34.7661 320.756C34.6333 320.475 34.5669 320.139 34.5669 319.748C34.5669 319.236 34.6841 318.799 34.9184 318.436C35.1528 318.072 35.4868 317.795 35.9204 317.604C36.3579 317.408 36.8735 317.311 37.4673 317.311C37.9126 317.311 38.3364 317.363 38.7388 317.469C39.145 317.57 39.5688 317.719 40.0102 317.914L39.4243 319.326C39.0298 319.166 38.6763 319.043 38.3638 318.957C38.0513 318.867 37.7329 318.822 37.4087 318.822C37.1821 318.822 36.9888 318.859 36.8286 318.934C36.6684 319.004 36.5473 319.105 36.4653 319.238C36.3833 319.367 36.3423 319.518 36.3423 319.689C36.3423 319.893 36.4009 320.064 36.518 320.205C36.6391 320.342 36.8188 320.475 37.0571 320.604C37.2993 320.732 37.6001 320.883 37.9595 321.055C38.397 321.262 38.77 321.479 39.0786 321.705C39.3911 321.928 39.6313 322.191 39.7993 322.496C39.9673 322.797 40.0513 323.172 40.0513 323.621ZM45.1487 326H43.3323V318.945H41.0061V317.434H47.4748V318.945H45.1487V326ZM51.5293 317.434C52.3066 317.434 52.9473 317.527 53.4512 317.715C53.959 317.902 54.3359 318.186 54.582 318.564C54.8281 318.943 54.9512 319.422 54.9512 320C54.9512 320.391 54.877 320.732 54.7285 321.025C54.5801 321.318 54.3848 321.566 54.1426 321.77C53.9004 321.973 53.6387 322.139 53.3574 322.268L55.877 326H53.8613L51.8164 322.713H50.8496V326H49.0332V317.434H51.5293ZM51.4004 318.922H50.8496V321.236H51.4355C52.0371 321.236 52.4668 321.137 52.7246 320.938C52.9863 320.734 53.1172 320.438 53.1172 320.047C53.1172 319.641 52.9766 319.352 52.6953 319.18C52.418 319.008 51.9863 318.922 51.4004 318.922ZM62.1287 326H57.1951V317.434H62.1287V318.922H59.0115V320.803H61.9119V322.291H59.0115V324.5H62.1287V326ZM69.4058 326L68.7847 323.961H65.6616L65.0405 326H63.0835L66.107 317.398H68.3277L71.3628 326H69.4058ZM68.3511 322.438L67.73 320.445C67.6909 320.312 67.6382 320.143 67.5718 319.936C67.5093 319.725 67.4448 319.512 67.3784 319.297C67.3159 319.078 67.2652 318.889 67.2261 318.729C67.187 318.889 67.1323 319.088 67.062 319.326C66.9956 319.561 66.9312 319.783 66.8687 319.994C66.8062 320.205 66.7612 320.355 66.7339 320.445L66.1187 322.438H68.3511ZM76.3138 326L74.2513 319.279H74.1985C74.2063 319.439 74.218 319.682 74.2337 320.006C74.2532 320.326 74.2708 320.668 74.2864 321.031C74.302 321.395 74.3098 321.723 74.3098 322.016V326H72.6868V317.434H75.1595L77.1868 323.984H77.222L79.3723 317.434H81.845V326H80.1516V321.945C80.1516 321.676 80.1555 321.365 80.1634 321.014C80.1751 320.662 80.1888 320.328 80.2044 320.012C80.22 319.691 80.2317 319.451 80.2395 319.291H80.1868L77.9778 326H76.3138ZM30.8874 333.822C30.5398 333.822 30.2312 333.891 29.9616 334.027C29.696 334.16 29.4714 334.354 29.2878 334.607C29.1081 334.861 28.9714 335.168 28.8777 335.527C28.7839 335.887 28.737 336.291 28.737 336.74C28.737 337.346 28.8113 337.863 28.9597 338.293C29.112 338.719 29.3464 339.045 29.6628 339.271C29.9792 339.494 30.3874 339.605 30.8874 339.605C31.2351 339.605 31.5827 339.566 31.9304 339.488C32.282 339.41 32.6628 339.299 33.073 339.154V340.678C32.6941 340.834 32.321 340.945 31.9538 341.012C31.5866 341.082 31.1745 341.117 30.7175 341.117C29.8347 341.117 29.1081 340.936 28.5378 340.572C27.9714 340.205 27.5515 339.693 27.278 339.037C27.0046 338.377 26.8679 337.607 26.8679 336.729C26.8679 336.08 26.9558 335.486 27.1316 334.947C27.3073 334.408 27.5652 333.941 27.905 333.547C28.2448 333.152 28.6648 332.848 29.1648 332.633C29.6648 332.418 30.239 332.311 30.8874 332.311C31.3132 332.311 31.739 332.365 32.1648 332.475C32.5945 332.58 33.0046 332.727 33.3952 332.914L32.8093 334.391C32.489 334.238 32.1667 334.105 31.8425 333.992C31.5183 333.879 31.1999 333.822 30.8874 333.822ZM42.9165 336.705C42.9165 337.365 42.8345 337.967 42.6704 338.51C42.5063 339.049 42.2563 339.514 41.9204 339.904C41.5884 340.295 41.1665 340.596 40.6548 340.807C40.143 341.014 39.5376 341.117 38.8384 341.117C38.1391 341.117 37.5337 341.014 37.022 340.807C36.5102 340.596 36.0864 340.295 35.7505 339.904C35.4184 339.514 35.1704 339.047 35.0063 338.504C34.8423 337.961 34.7602 337.357 34.7602 336.693C34.7602 335.807 34.9048 335.035 35.1938 334.379C35.4868 333.719 35.936 333.207 36.5415 332.844C37.147 332.48 37.9165 332.299 38.8501 332.299C39.7798 332.299 40.5434 332.48 41.1411 332.844C41.7427 333.207 42.188 333.719 42.477 334.379C42.77 335.039 42.9165 335.814 42.9165 336.705ZM36.6645 336.705C36.6645 337.303 36.7388 337.818 36.8872 338.252C37.0395 338.682 37.2759 339.014 37.5962 339.248C37.9165 339.479 38.3305 339.594 38.8384 339.594C39.354 339.594 39.772 339.479 40.0923 339.248C40.4126 339.014 40.645 338.682 40.7895 338.252C40.938 337.818 41.0122 337.303 41.0122 336.705C41.0122 335.807 40.8442 335.1 40.5083 334.584C40.1723 334.068 39.6196 333.811 38.8501 333.811C38.3384 333.811 37.9204 333.928 37.5962 334.162C37.2759 334.393 37.0395 334.725 36.8872 335.158C36.7388 335.588 36.6645 336.104 36.6645 336.705ZM52.5315 341H50.2229L46.4963 334.52H46.4436C46.4592 334.789 46.4729 335.061 46.4846 335.334C46.4963 335.607 46.508 335.881 46.5198 336.154C46.5315 336.424 46.5432 336.695 46.5549 336.969V341H44.9319V332.434H47.2229L50.9436 338.85H50.9846C50.9768 338.584 50.967 338.32 50.9553 338.059C50.9436 337.797 50.9319 337.535 50.9202 337.273C50.9123 337.012 50.9045 336.75 50.8967 336.488V332.434H52.5315V341ZM56.7207 341H54.9336V332.434H59.8438V333.922H56.7207V336.131H59.627V337.613H56.7207V341ZM61.7595 341V332.434H63.5759V341H61.7595ZM69.2241 336.189H72.6226V340.631C72.1734 340.779 71.7066 340.898 71.2222 340.988C70.7378 341.074 70.189 341.117 69.5757 341.117C68.7241 341.117 68.0015 340.949 67.4077 340.613C66.814 340.277 66.3628 339.781 66.0542 339.125C65.7456 338.469 65.5913 337.662 65.5913 336.705C65.5913 335.807 65.7632 335.029 66.107 334.373C66.4546 333.717 66.9605 333.209 67.6245 332.85C68.2925 332.49 69.107 332.311 70.0679 332.311C70.521 332.311 70.9683 332.359 71.4097 332.457C71.8511 332.555 72.2515 332.682 72.6109 332.838L72.0073 334.291C71.7456 334.158 71.4468 334.047 71.1109 333.957C70.7749 333.867 70.4234 333.822 70.0562 333.822C69.5288 333.822 69.0698 333.943 68.6792 334.186C68.2925 334.428 67.9917 334.768 67.7769 335.205C67.5659 335.639 67.4605 336.15 67.4605 336.74C67.4605 337.299 67.5366 337.795 67.689 338.229C67.8413 338.658 68.0816 338.996 68.4097 339.242C68.7378 339.484 69.1656 339.605 69.6929 339.605C69.9507 339.605 70.1675 339.594 70.3433 339.57C70.523 339.543 70.6909 339.516 70.8472 339.488V337.701H69.2241V336.189Z" fill="#6A6D7A"/>
+<path d="M454 84.75L522 84.75C522.69 84.75 523.25 85.3096 523.25 86L523.25 154C523.25 154.69 522.69 155.25 522 155.25L454 155.25C453.31 155.25 452.75 154.69 452.75 154L452.75 86C452.75 85.3096 453.31 84.75 454 84.75Z" fill="white" stroke="#D2D4DB" stroke-width="1.5"/>
+<path d="M502.999 109V130.281C502.999 131.913 501.658 133.654 498.873 135.047C496.146 136.41 492.306 137.281 488 137.281C483.694 137.281 479.853 136.41 477.127 135.047C474.342 133.654 473 131.913 473 130.281V109C473 107.368 474.342 105.627 477.127 104.234C479.853 102.871 483.694 102 488 102C492.306 102 496.146 102.871 498.873 104.234C501.658 105.627 502.999 107.368 502.999 109Z" fill="white" stroke="black" stroke-width="2" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<mask id="path-19-inside-1_0_1" fill="white">
+<path d="M503.999 119.64C503.999 124.067 496.854 127.64 488 127.64C479.145 127.64 472 124.067 472 119.64"/>
+</mask>
+<path d="M505.999 119.64C505.999 118.535 505.104 117.64 503.999 117.64C502.895 117.64 501.999 118.535 501.999 119.64H505.999ZM474 119.64C474 118.535 473.105 117.64 472 117.64C470.895 117.64 470 118.535 470 119.64H474ZM501.999 119.64C501.999 120.69 501.102 122.173 498.425 123.511C495.865 124.791 492.185 125.64 488 125.64V129.64C492.669 129.64 496.988 128.702 500.214 127.089C503.324 125.534 505.999 123.017 505.999 119.64H501.999ZM488 125.64C483.814 125.64 480.134 124.791 477.574 123.511C474.897 122.173 474 120.69 474 119.64H470C470 123.017 472.676 125.534 475.785 127.089C479.011 128.702 483.331 129.64 488 129.64V125.64Z" fill="black" mask="url(#path-19-inside-1_0_1)"/>
+<mask id="path-21-inside-2_0_1" fill="white">
+<path d="M503.999 108.763C503.999 113.19 496.854 116.763 488 116.763C479.145 116.763 472 113.19 472 108.763"/>
+</mask>
+<path d="M505.999 108.763C505.999 107.658 505.104 106.763 503.999 106.763C502.895 106.763 501.999 107.658 501.999 108.763H505.999ZM474 108.763C474 107.658 473.105 106.763 472 106.763C470.895 106.763 470 107.658 470 108.763H474ZM501.999 108.763C501.999 109.813 501.102 111.296 498.425 112.634C495.865 113.914 492.185 114.763 488 114.763V118.763C492.669 118.763 496.988 117.825 500.214 116.212C503.324 114.657 505.999 112.14 505.999 108.763H501.999ZM488 114.763C483.814 114.763 480.134 113.914 477.574 112.634C474.897 111.296 474 109.813 474 108.763H470C470 112.14 472.676 114.657 475.785 116.212C479.011 117.825 483.331 118.763 488 118.763V114.763Z" fill="black" mask="url(#path-21-inside-2_0_1)"/>
+<path d="M464.183 170.635C464.183 171.6 463.997 172.406 463.626 173.055C463.259 173.699 462.726 174.186 462.026 174.514C461.327 174.838 460.485 175 459.501 175H457.075V166.434H459.765C460.663 166.434 461.442 166.594 462.103 166.914C462.763 167.23 463.274 167.701 463.638 168.326C464.001 168.947 464.183 169.717 464.183 170.635ZM462.296 170.682C462.296 170.049 462.202 169.529 462.015 169.123C461.831 168.713 461.558 168.41 461.194 168.215C460.835 168.02 460.39 167.922 459.858 167.922H458.892V173.5H459.671C460.558 173.5 461.216 173.264 461.645 172.791C462.079 172.318 462.296 171.615 462.296 170.682ZM471.442 175L470.821 172.961H467.698L467.077 175H465.12L468.143 166.398H470.364L473.399 175H471.442ZM470.387 171.438L469.766 169.445C469.727 169.312 469.675 169.143 469.608 168.936C469.546 168.725 469.481 168.512 469.415 168.297C469.352 168.078 469.301 167.889 469.262 167.729C469.223 167.889 469.169 168.088 469.098 168.326C469.032 168.561 468.968 168.783 468.905 168.994C468.843 169.205 468.798 169.355 468.77 169.445L468.155 171.438H470.387ZM478.028 175H476.211V167.945H473.885V166.434H480.354V167.945H478.028V175ZM487.156 175L486.535 172.961H483.412L482.791 175H480.834L483.858 166.398H486.078L489.114 175H487.156ZM486.102 171.438L485.481 169.445C485.442 169.312 485.389 169.143 485.323 168.936C485.26 168.725 485.196 168.512 485.129 168.297C485.067 168.078 485.016 167.889 484.977 167.729C484.938 167.889 484.883 168.088 484.813 168.326C484.746 168.561 484.682 168.783 484.619 168.994C484.557 169.205 484.512 169.355 484.485 169.445L483.869 171.438H486.102ZM490.438 166.434H493.104C494.244 166.434 495.107 166.594 495.693 166.914C496.279 167.234 496.572 167.797 496.572 168.602C496.572 168.926 496.52 169.219 496.414 169.48C496.312 169.742 496.164 169.957 495.969 170.125C495.773 170.293 495.535 170.402 495.254 170.453V170.512C495.539 170.57 495.797 170.672 496.027 170.816C496.258 170.957 496.441 171.164 496.578 171.438C496.719 171.707 496.789 172.066 496.789 172.516C496.789 173.035 496.662 173.48 496.408 173.852C496.154 174.223 495.791 174.508 495.318 174.707C494.85 174.902 494.291 175 493.643 175H490.438V166.434ZM492.254 169.826H493.309C493.836 169.826 494.201 169.744 494.404 169.58C494.607 169.412 494.709 169.166 494.709 168.842C494.709 168.514 494.588 168.279 494.346 168.139C494.107 167.994 493.729 167.922 493.209 167.922H492.254V169.826ZM492.254 171.268V173.5H493.438C493.984 173.5 494.365 173.395 494.58 173.184C494.795 172.973 494.902 172.689 494.902 172.334C494.902 172.123 494.855 171.938 494.762 171.777C494.668 171.617 494.51 171.492 494.287 171.402C494.068 171.312 493.766 171.268 493.379 171.268H492.254ZM503.984 175L503.363 172.961H500.24L499.619 175H497.662L500.685 166.398H502.906L505.941 175H503.984ZM502.929 171.438L502.308 169.445C502.269 169.312 502.217 169.143 502.15 168.936C502.088 168.725 502.023 168.512 501.957 168.297C501.894 168.078 501.844 167.889 501.804 167.729C501.765 167.889 501.711 168.088 501.64 168.326C501.574 168.561 501.51 168.783 501.447 168.994C501.385 169.205 501.34 169.355 501.312 169.445L500.697 171.438H502.929ZM512.322 172.621C512.322 173.129 512.199 173.57 511.953 173.945C511.707 174.32 511.347 174.609 510.875 174.812C510.406 175.016 509.835 175.117 509.164 175.117C508.867 175.117 508.576 175.098 508.291 175.059C508.009 175.02 507.738 174.963 507.476 174.889C507.218 174.811 506.972 174.715 506.738 174.602V172.914C507.144 173.094 507.566 173.256 508.003 173.4C508.441 173.545 508.875 173.617 509.304 173.617C509.601 173.617 509.839 173.578 510.019 173.5C510.203 173.422 510.335 173.314 510.417 173.178C510.5 173.041 510.541 172.885 510.541 172.709C510.541 172.494 510.468 172.311 510.324 172.158C510.179 172.006 509.98 171.863 509.726 171.73C509.476 171.598 509.193 171.455 508.876 171.303C508.677 171.209 508.46 171.096 508.226 170.963C507.992 170.826 507.769 170.66 507.558 170.465C507.347 170.27 507.173 170.033 507.037 169.756C506.904 169.475 506.837 169.139 506.837 168.748C506.837 168.236 506.955 167.799 507.189 167.436C507.423 167.072 507.757 166.795 508.191 166.604C508.628 166.408 509.144 166.311 509.738 166.311C510.183 166.311 510.607 166.363 511.009 166.469C511.416 166.57 511.839 166.719 512.281 166.914L511.695 168.326C511.3 168.166 510.947 168.043 510.634 167.957C510.322 167.867 510.003 167.822 509.679 167.822C509.453 167.822 509.259 167.859 509.099 167.934C508.939 168.004 508.818 168.105 508.736 168.238C508.654 168.367 508.613 168.518 508.613 168.689C508.613 168.893 508.671 169.064 508.789 169.205C508.91 169.342 509.089 169.475 509.328 169.604C509.57 169.732 509.871 169.883 510.23 170.055C510.667 170.262 511.041 170.479 511.349 170.705C511.662 170.928 511.902 171.191 512.07 171.496C512.238 171.797 512.322 172.172 512.322 172.621ZM519.048 175H514.115V166.434H519.048V167.922H515.931V169.803H518.831V171.291H515.931V173.5H519.048V175Z" fill="#6A6D7A"/>
+<path d="M159 235.75H227C227.69 235.75 228.25 236.31 228.25 237V305C228.25 305.69 227.69 306.25 227 306.25H159C158.31 306.25 157.75 305.69 157.75 305V237C157.75 236.31 158.31 235.75 159 235.75Z" fill="white" stroke="#E07EAC" stroke-width="1.5"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M203 258L209 264L203 270" fill="white"/>
+<path d="M203 258L209 264M209 264L203 270M209 264H178" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M184 272L178 278L184 284" fill="white"/>
+<path d="M184 272L178 278M178 278L184 284M178 278H209" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M175.964 317.434C177.07 317.434 177.877 317.672 178.384 318.148C178.892 318.621 179.146 319.273 179.146 320.105C179.146 320.48 179.089 320.84 178.976 321.184C178.863 321.523 178.677 321.826 178.42 322.092C178.166 322.357 177.826 322.568 177.4 322.725C176.974 322.877 176.449 322.953 175.824 322.953H175.045V326H173.228V317.434H175.964ZM175.871 318.922H175.045V321.465H175.642C175.982 321.465 176.277 321.42 176.527 321.33C176.777 321.24 176.97 321.1 177.107 320.908C177.244 320.717 177.312 320.471 177.312 320.17C177.312 319.748 177.195 319.436 176.961 319.232C176.726 319.025 176.363 318.922 175.871 318.922ZM183.499 317.434C184.277 317.434 184.917 317.527 185.421 317.715C185.929 317.902 186.306 318.186 186.552 318.564C186.798 318.943 186.921 319.422 186.921 320C186.921 320.391 186.847 320.732 186.699 321.025C186.55 321.318 186.355 321.566 186.113 321.77C185.87 321.973 185.609 322.139 185.327 322.268L187.847 326H185.831L183.786 322.713H182.82V326H181.003V317.434H183.499ZM183.37 318.922H182.82V321.236H183.406C184.007 321.236 184.437 321.137 184.695 320.938C184.956 320.734 185.087 320.438 185.087 320.047C185.087 319.641 184.947 319.352 184.665 319.18C184.388 319.008 183.956 318.922 183.37 318.922ZM196.941 321.705C196.941 322.365 196.859 322.967 196.694 323.51C196.53 324.049 196.28 324.514 195.944 324.904C195.612 325.295 195.191 325.596 194.679 325.807C194.167 326.014 193.562 326.117 192.862 326.117C192.163 326.117 191.558 326.014 191.046 325.807C190.534 325.596 190.11 325.295 189.775 324.904C189.442 324.514 189.194 324.047 189.03 323.504C188.866 322.961 188.784 322.357 188.784 321.693C188.784 320.807 188.929 320.035 189.218 319.379C189.511 318.719 189.96 318.207 190.566 317.844C191.171 317.48 191.941 317.299 192.874 317.299C193.804 317.299 194.567 317.48 195.165 317.844C195.767 318.207 196.212 318.719 196.501 319.379C196.794 320.039 196.941 320.814 196.941 321.705ZM190.689 321.705C190.689 322.303 190.763 322.818 190.911 323.252C191.064 323.682 191.3 324.014 191.62 324.248C191.941 324.479 192.355 324.594 192.862 324.594C193.378 324.594 193.796 324.479 194.116 324.248C194.437 324.014 194.669 323.682 194.814 323.252C194.962 322.818 195.036 322.303 195.036 321.705C195.036 320.807 194.868 320.1 194.532 319.584C194.196 319.068 193.644 318.811 192.874 318.811C192.362 318.811 191.944 318.928 191.62 319.162C191.3 319.393 191.064 319.725 190.911 320.158C190.763 320.588 190.689 321.104 190.689 321.705ZM205.882 326H203.807L201.815 322.76L199.823 326H197.878L200.72 321.582L198.059 317.434H200.063L201.909 320.516L203.72 317.434H205.677L202.987 321.682L205.882 326ZM209.866 320.961L211.653 317.434H213.61L210.768 322.666V326H208.964V322.725L206.122 317.434H208.09L209.866 320.961Z" fill="#CA2171"/>
+<path d="M453 235.75H521C521.69 235.75 522.25 236.31 522.25 237V305C522.25 305.69 521.69 306.25 521 306.25H453C452.31 306.25 451.75 305.69 451.75 305V237C451.75 236.31 452.31 235.75 453 235.75Z" fill="white" stroke="#E07EAC" stroke-width="1.5"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M497 258L503 264L497 270" fill="white"/>
+<path d="M497 258L503 264M503 264L497 270M503 264H472" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M478 272L472 278L478 284" fill="white"/>
+<path d="M478 272L472 278M472 278L478 284M472 278H503" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M469.964 317.434C471.07 317.434 471.877 317.672 472.384 318.148C472.892 318.621 473.146 319.273 473.146 320.105C473.146 320.48 473.089 320.84 472.976 321.184C472.863 321.523 472.677 321.826 472.42 322.092C472.166 322.357 471.826 322.568 471.4 322.725C470.974 322.877 470.449 322.953 469.824 322.953H469.045V326H467.228V317.434H469.964ZM469.871 318.922H469.045V321.465H469.642C469.982 321.465 470.277 321.42 470.527 321.33C470.777 321.24 470.97 321.1 471.107 320.908C471.244 320.717 471.312 320.471 471.312 320.17C471.312 319.748 471.195 319.436 470.961 319.232C470.726 319.025 470.363 318.922 469.871 318.922ZM477.499 317.434C478.277 317.434 478.917 317.527 479.421 317.715C479.929 317.902 480.306 318.186 480.552 318.564C480.798 318.943 480.921 319.422 480.921 320C480.921 320.391 480.847 320.732 480.699 321.025C480.55 321.318 480.355 321.566 480.113 321.77C479.87 321.973 479.609 322.139 479.327 322.268L481.847 326H479.831L477.786 322.713H476.82V326H475.003V317.434H477.499ZM477.37 318.922H476.82V321.236H477.406C478.007 321.236 478.437 321.137 478.695 320.938C478.956 320.734 479.087 320.438 479.087 320.047C479.087 319.641 478.947 319.352 478.665 319.18C478.388 319.008 477.956 318.922 477.37 318.922ZM490.941 321.705C490.941 322.365 490.859 322.967 490.694 323.51C490.53 324.049 490.28 324.514 489.944 324.904C489.612 325.295 489.191 325.596 488.679 325.807C488.167 326.014 487.562 326.117 486.862 326.117C486.163 326.117 485.558 326.014 485.046 325.807C484.534 325.596 484.11 325.295 483.775 324.904C483.442 324.514 483.194 324.047 483.03 323.504C482.866 322.961 482.784 322.357 482.784 321.693C482.784 320.807 482.929 320.035 483.218 319.379C483.511 318.719 483.96 318.207 484.566 317.844C485.171 317.48 485.941 317.299 486.874 317.299C487.804 317.299 488.567 317.48 489.165 317.844C489.767 318.207 490.212 318.719 490.501 319.379C490.794 320.039 490.941 320.814 490.941 321.705ZM484.689 321.705C484.689 322.303 484.763 322.818 484.911 323.252C485.064 323.682 485.3 324.014 485.62 324.248C485.941 324.479 486.355 324.594 486.862 324.594C487.378 324.594 487.796 324.479 488.116 324.248C488.437 324.014 488.669 323.682 488.814 323.252C488.962 322.818 489.036 322.303 489.036 321.705C489.036 320.807 488.868 320.1 488.532 319.584C488.196 319.068 487.644 318.811 486.874 318.811C486.362 318.811 485.944 318.928 485.62 319.162C485.3 319.393 485.064 319.725 484.911 320.158C484.763 320.588 484.689 321.104 484.689 321.705ZM499.882 326H497.807L495.815 322.76L493.823 326H491.878L494.72 321.582L492.059 317.434H494.063L495.909 320.516L497.72 317.434H499.677L496.987 321.682L499.882 326ZM503.866 320.961L505.653 317.434H507.61L504.768 322.666V326H502.964V322.725L500.122 317.434H502.09L503.866 320.961Z" fill="#CA2171"/>
+<line x1="1" y1="-1" x2="37" y2="-1" transform="matrix(1.19249e-08 -1 -1 -1.19249e-08 192 223)" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M193 220.72L188.863 216.5L187.5 217.89L193 223.5L198.5 217.89L197.137 216.5L193 220.72Z" fill="#CA2171"/>
+<line x1="1" y1="-1" x2="37" y2="-1" transform="matrix(1.19249e-08 1 1 -1.19249e-08 488 185)" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M487 187.28L491.137 191.5L492.5 190.11L487 184.5L481.5 190.11L482.863 191.5L487 187.28Z" fill="#CA2171"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M68 196.678C68 195.751 68.7511 195 69.6776 195H176.322C177.249 195 178 195.751 178 196.678V214.322C178 215.249 177.249 216 176.322 216H69.6776C68.7511 216 68 215.249 68 214.322V196.678Z" fill="#F7F8FA"/>
+<path d="M83.8318 207.691C83.8318 208.168 84.1237 208.406 84.7075 208.406C84.9826 208.406 85.2779 208.346 85.5932 208.225L85.8147 208.839C85.4792 209.02 85.0598 209.111 84.5565 209.111C84.08 209.111 83.6975 208.98 83.409 208.718C83.1272 208.456 82.9862 208.101 82.9862 207.651V202.236H81.3556V201.561H83.8318V207.691ZM89.8169 203.585C90.5483 203.585 91.1087 203.833 91.4979 204.33C91.8938 204.819 92.0917 205.49 92.0917 206.343C92.0917 207.175 91.8904 207.846 91.4878 208.356C91.0919 208.859 90.5316 209.111 89.8068 209.111C89.0754 209.111 88.5117 208.866 88.1158 208.376C87.7199 207.879 87.5219 207.205 87.5219 206.353C87.5219 205.514 87.7199 204.843 88.1158 204.34C88.5184 203.836 89.0855 203.585 89.8169 203.585ZM89.8169 204.279C89.3539 204.279 89.0083 204.45 88.7801 204.793C88.552 205.135 88.4379 205.655 88.4379 206.353C88.4379 207.051 88.5486 207.571 88.7701 207.913C88.9982 208.248 89.3438 208.416 89.8068 208.416C90.2699 208.416 90.6121 208.248 90.8335 207.913C91.0617 207.571 91.1758 207.047 91.1758 206.343C91.1758 205.645 91.0617 205.128 90.8335 204.793C90.6121 204.45 90.2732 204.279 89.8169 204.279ZM96.2349 208.386C96.6979 208.386 97.1576 208.232 97.6139 207.923L98.0165 208.477C97.7951 208.671 97.5199 208.826 97.1911 208.94C96.8623 209.054 96.5436 209.111 96.2349 209.111C95.4498 209.111 94.8357 208.866 94.3929 208.376C93.9567 207.879 93.7386 207.212 93.7386 206.373C93.7386 205.843 93.8359 205.366 94.0305 204.944C94.2318 204.521 94.5204 204.189 94.8961 203.947C95.2719 203.705 95.7182 203.585 96.2349 203.585C96.9193 203.585 97.5099 203.793 98.0064 204.209L97.5937 204.762C97.1307 204.454 96.6744 204.299 96.2248 204.299C95.7484 204.299 95.3659 204.477 95.0773 204.833C94.7955 205.182 94.6546 205.695 94.6546 206.373C94.6546 207.051 94.7955 207.557 95.0773 207.893C95.3659 208.222 95.7517 208.386 96.2349 208.386ZM103.669 207.842C103.669 208.05 103.703 208.205 103.77 208.305C103.837 208.399 103.948 208.47 104.102 208.517L103.891 209.121C103.374 209.054 103.052 208.802 102.925 208.366C102.737 208.607 102.499 208.792 102.21 208.919C101.928 209.047 101.613 209.111 101.264 209.111C100.734 209.111 100.314 208.963 100.006 208.668C99.7036 208.373 99.5526 207.977 99.5526 207.48C99.5526 206.937 99.764 206.517 100.187 206.222C100.616 205.927 101.23 205.779 102.029 205.779H102.814V205.346C102.814 204.97 102.707 204.702 102.492 204.541C102.277 204.373 101.965 204.289 101.556 204.289C101.153 204.289 100.693 204.38 100.177 204.561L99.9452 203.917C100.569 203.695 101.15 203.585 101.687 203.585C102.331 203.585 102.821 203.736 103.156 204.038C103.498 204.34 103.669 204.759 103.669 205.296V207.842ZM101.475 208.477C101.737 208.477 101.985 208.409 102.22 208.275C102.462 208.141 102.66 207.957 102.814 207.722V206.363H102.049C101.485 206.363 101.079 206.457 100.831 206.645C100.583 206.833 100.459 207.108 100.459 207.47C100.459 208.141 100.797 208.477 101.475 208.477ZM107.974 207.691C107.974 208.168 108.266 208.406 108.849 208.406C109.125 208.406 109.42 208.346 109.735 208.225L109.957 208.839C109.621 209.02 109.202 209.111 108.698 209.111C108.222 209.111 107.839 208.98 107.551 208.718C107.269 208.456 107.128 208.101 107.128 207.651V202.236H105.498V201.561H107.974V207.691ZM112.781 204.43C112.989 204.162 113.244 203.954 113.546 203.806C113.848 203.658 114.16 203.585 114.482 203.585C115.475 203.585 115.972 204.108 115.972 205.155V209H115.126V205.165C115.126 204.85 115.053 204.621 114.905 204.481C114.757 204.333 114.522 204.259 114.2 204.259C113.925 204.259 113.66 204.346 113.405 204.521C113.15 204.695 112.942 204.9 112.781 205.135V209H111.936V201.572L112.781 201.481V204.43ZM119.994 203.585C120.726 203.585 121.286 203.833 121.675 204.33C122.071 204.819 122.269 205.49 122.269 206.343C122.269 207.175 122.068 207.846 121.665 208.356C121.269 208.859 120.709 209.111 119.984 209.111C119.253 209.111 118.689 208.866 118.293 208.376C117.897 207.879 117.699 207.205 117.699 206.353C117.699 205.514 117.897 204.843 118.293 204.34C118.696 203.836 119.263 203.585 119.994 203.585ZM119.994 204.279C119.531 204.279 119.186 204.45 118.958 204.793C118.729 205.135 118.615 205.655 118.615 206.353C118.615 207.051 118.726 207.571 118.947 207.913C119.176 208.248 119.521 208.416 119.984 208.416C120.447 208.416 120.789 208.248 121.011 207.913C121.239 207.571 121.353 207.047 121.353 206.343C121.353 205.645 121.239 205.128 121.011 204.793C120.789 204.45 120.451 204.279 119.994 204.279ZM125.818 208.416C126.221 208.416 126.54 208.339 126.775 208.185C127.009 208.03 127.127 207.826 127.127 207.571C127.127 207.396 127.097 207.255 127.036 207.148C126.976 207.034 126.855 206.933 126.674 206.846C126.493 206.752 126.218 206.658 125.849 206.564C125.231 206.41 124.775 206.225 124.48 206.01C124.184 205.789 124.037 205.464 124.037 205.034C124.037 204.591 124.221 204.239 124.59 203.977C124.959 203.716 125.446 203.585 126.05 203.585C126.788 203.585 127.432 203.779 127.983 204.168L127.6 204.752C127.379 204.598 127.147 204.481 126.905 204.4C126.664 204.313 126.385 204.269 126.07 204.269C125.305 204.269 124.923 204.501 124.923 204.964C124.923 205.125 124.963 205.256 125.043 205.356C125.131 205.457 125.268 205.547 125.456 205.628C125.651 205.702 125.939 205.792 126.322 205.9C126.899 206.054 127.328 206.252 127.61 206.494C127.899 206.729 128.043 207.074 128.043 207.53C128.043 208.061 127.828 208.456 127.399 208.718C126.969 208.98 126.442 209.111 125.818 209.111C124.986 209.111 124.295 208.873 123.745 208.396L124.218 207.842C124.433 208.017 124.678 208.158 124.953 208.265C125.228 208.366 125.516 208.416 125.818 208.416ZM134.26 208.728C134.078 208.849 133.857 208.943 133.595 209.01C133.34 209.077 133.085 209.111 132.83 209.111C132.273 209.111 131.837 208.966 131.522 208.678C131.206 208.383 131.049 207.997 131.049 207.52V204.36H129.831V203.695H131.049V202.498L131.894 202.397V203.695H133.736L133.625 204.36H131.894V207.51C131.894 207.812 131.975 208.037 132.136 208.185C132.297 208.332 132.555 208.406 132.911 208.406C133.273 208.406 133.612 208.322 133.927 208.154L134.26 208.728ZM137.275 204.662C137.275 204.44 137.353 204.252 137.507 204.098C137.661 203.937 137.852 203.856 138.081 203.856C138.315 203.856 138.51 203.937 138.664 204.098C138.819 204.252 138.896 204.44 138.896 204.662C138.896 204.89 138.819 205.084 138.664 205.245C138.51 205.407 138.315 205.487 138.081 205.487C137.852 205.487 137.661 205.407 137.507 205.245C137.353 205.084 137.275 204.89 137.275 204.662ZM137.275 208.295C137.275 208.074 137.353 207.883 137.507 207.722C137.661 207.561 137.852 207.48 138.081 207.48C138.315 207.48 138.51 207.561 138.664 207.722C138.819 207.876 138.896 208.067 138.896 208.295C138.896 208.53 138.819 208.725 138.664 208.879C138.51 209.034 138.315 209.111 138.081 209.111C137.852 209.111 137.661 209.034 137.507 208.879C137.353 208.725 137.275 208.53 137.275 208.295ZM146.31 208.316V209H142.314V208.316H144.015V202.991L142.435 203.947L142.063 203.353L144.126 202.065H144.871V208.316H146.31ZM149.85 201.954C150.272 201.954 150.641 202.038 150.957 202.206C151.279 202.373 151.524 202.605 151.692 202.9C151.859 203.189 151.943 203.518 151.943 203.887C151.943 204.316 151.843 204.732 151.641 205.135C151.447 205.537 151.131 205.98 150.695 206.463C150.259 206.94 149.642 207.544 148.843 208.275H152.104L152.004 209H147.877V208.316C148.783 207.45 149.454 206.772 149.89 206.282C150.333 205.792 150.638 205.373 150.806 205.024C150.974 204.675 151.057 204.306 151.057 203.917C151.057 203.528 150.947 203.222 150.725 203.001C150.504 202.779 150.199 202.669 149.809 202.669C149.481 202.669 149.205 202.726 148.984 202.84C148.769 202.947 148.548 203.135 148.32 203.403L147.736 202.951C148.011 202.608 148.316 202.357 148.652 202.196C148.994 202.035 149.393 201.954 149.85 201.954ZM155.885 201.954C156.308 201.954 156.68 202.035 157.002 202.196C157.324 202.35 157.573 202.561 157.747 202.83C157.922 203.091 158.009 203.38 158.009 203.695C158.009 204.098 157.878 204.45 157.616 204.752C157.355 205.048 157.036 205.232 156.66 205.306C157.096 205.339 157.465 205.504 157.767 205.799C158.076 206.094 158.23 206.497 158.23 207.007C158.23 207.403 158.13 207.762 157.928 208.084C157.727 208.406 157.442 208.658 157.073 208.839C156.71 209.02 156.294 209.111 155.825 209.111C155.415 209.111 155.019 209.034 154.637 208.879C154.261 208.725 153.949 208.497 153.701 208.195L154.264 207.732C154.452 207.953 154.681 208.124 154.949 208.245C155.224 208.359 155.509 208.416 155.805 208.416C156.288 208.416 156.663 208.292 156.932 208.044C157.207 207.789 157.345 207.443 157.345 207.007C157.345 206.128 156.865 205.688 155.905 205.688H155.331L155.432 205.014H155.845C156.207 205.014 156.516 204.913 156.771 204.712C157.026 204.504 157.153 204.202 157.153 203.806C157.153 203.437 157.029 203.152 156.781 202.951C156.539 202.742 156.227 202.638 155.845 202.638C155.556 202.638 155.298 202.689 155.07 202.789C154.848 202.89 154.617 203.051 154.375 203.273L153.912 202.759C154.476 202.222 155.133 201.954 155.885 201.954ZM164.528 207.319H163.632V209H162.816V207.319H159.938V206.695L161.971 201.954L162.675 202.256L160.833 206.635H162.826L162.897 204.672H163.632V206.635H164.528V207.319Z" fill="#252937"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M140 1.67761C140 0.751094 140.751 0 141.678 0H335.322C336.249 0 337 0.751093 337 1.67761V18.3224C337 19.2489 336.249 20 335.322 20H141.678C140.751 20 140 19.2489 140 18.3224V1.67761Z" fill="#F7F8FA"/>
+<path d="M150.983 6.56146V14H150.238L150.158 13.3055C149.963 13.5739 149.738 13.7752 149.483 13.9094C149.228 14.0436 148.953 14.1107 148.658 14.1107C147.987 14.1107 147.48 13.8658 147.138 13.3759C146.802 12.8861 146.635 12.2117 146.635 11.3527C146.635 10.8226 146.718 10.3495 146.886 9.93346C147.054 9.51071 147.292 9.18189 147.601 8.94703C147.916 8.70545 148.285 8.58466 148.708 8.58466C149.292 8.58466 149.768 8.79604 150.137 9.2188V6.4608L150.983 6.56146ZM148.93 9.26913C148.487 9.26913 148.144 9.4436 147.903 9.79254C147.668 10.1415 147.551 10.6615 147.551 11.3527C147.551 12.0372 147.658 12.5573 147.873 12.9129C148.094 13.2618 148.413 13.4363 148.829 13.4363C149.332 13.4363 149.768 13.1545 150.137 12.5908V9.9536C149.99 9.73215 149.812 9.56439 149.604 9.45031C149.396 9.32952 149.171 9.26913 148.93 9.26913ZM156.797 12.8424C156.797 13.0505 156.831 13.2048 156.898 13.3055C156.965 13.3994 157.075 13.4699 157.23 13.5168L157.018 14.1208C156.502 14.0537 156.18 13.802 156.052 13.3659C155.864 13.6074 155.626 13.792 155.337 13.9195C155.056 14.047 154.74 14.1107 154.391 14.1107C153.861 14.1107 153.442 13.9631 153.133 13.6678C152.831 13.3726 152.68 12.9767 152.68 12.4801C152.68 11.9365 152.891 11.5171 153.314 11.2219C153.744 10.9266 154.358 10.779 155.156 10.779H155.941V10.3462C155.941 9.97037 155.834 9.70195 155.619 9.5409C155.405 9.37314 155.093 9.28926 154.683 9.28926C154.281 9.28926 153.821 9.37985 153.304 9.56103L153.073 8.91683C153.697 8.69538 154.277 8.58466 154.814 8.58466C155.458 8.58466 155.948 8.73565 156.284 9.03762C156.626 9.33959 156.797 9.75899 156.797 10.2958V12.8424ZM154.603 13.4766C154.864 13.4766 155.113 13.4095 155.348 13.2753C155.589 13.1411 155.787 12.9565 155.941 12.7217V11.3628H155.176C154.613 11.3628 154.207 11.4567 153.958 11.6446C153.71 11.8325 153.586 12.1077 153.586 12.47C153.586 13.1411 153.925 13.4766 154.603 13.4766ZM163.245 13.7282C163.064 13.849 162.843 13.943 162.581 14.0101C162.326 14.0772 162.071 14.1107 161.816 14.1107C161.259 14.1107 160.823 13.9664 160.507 13.6779C160.192 13.3826 160.034 12.9968 160.034 12.5203V9.35972H158.816V8.69538H160.034V7.49757L160.88 7.39691V8.69538H162.722L162.611 9.35972H160.88V12.5103C160.88 12.8122 160.96 13.037 161.121 13.1847C161.282 13.3323 161.541 13.4061 161.896 13.4061C162.259 13.4061 162.598 13.3222 162.913 13.1545L163.245 13.7282ZM168.868 12.8424C168.868 13.0505 168.901 13.2048 168.969 13.3055C169.036 13.3994 169.146 13.4699 169.301 13.5168L169.089 14.1208C168.573 14.0537 168.251 13.802 168.123 13.3659C167.935 13.6074 167.697 13.792 167.408 13.9195C167.127 14.047 166.811 14.1107 166.462 14.1107C165.932 14.1107 165.513 13.9631 165.204 13.6678C164.902 13.3726 164.751 12.9767 164.751 12.4801C164.751 11.9365 164.962 11.5171 165.385 11.2219C165.815 10.9266 166.429 10.779 167.227 10.779H168.012V10.3462C168.012 9.97037 167.905 9.70195 167.69 9.5409C167.475 9.37314 167.163 9.28926 166.754 9.28926C166.351 9.28926 165.892 9.37985 165.375 9.56103L165.144 8.91683C165.768 8.69538 166.348 8.58466 166.885 8.58466C167.529 8.58466 168.019 8.73565 168.355 9.03762C168.697 9.33959 168.868 9.75899 168.868 10.2958V12.8424ZM166.674 13.4766C166.935 13.4766 167.184 13.4095 167.418 13.2753C167.66 13.1411 167.858 12.9565 168.012 12.7217V11.3628H167.247C166.684 11.3628 166.278 11.4567 166.029 11.6446C165.781 11.8325 165.657 12.1077 165.657 12.47C165.657 13.1411 165.996 13.4766 166.674 13.4766ZM171.944 9.38992C172.353 8.85308 172.86 8.58466 173.464 8.58466C174.142 8.58466 174.642 8.82624 174.964 9.30939C175.286 9.79254 175.447 10.4703 175.447 11.3427C175.447 12.1748 175.262 12.8458 174.893 13.3558C174.524 13.8591 174.008 14.1107 173.343 14.1107C172.733 14.1107 172.253 13.8893 171.904 13.4464L171.843 14H171.099V6.56146L171.944 6.4608V9.38992ZM173.152 13.4263C173.595 13.4263 173.934 13.2518 174.169 12.9028C174.41 12.5539 174.531 12.0338 174.531 11.3427C174.531 10.6582 174.424 10.1415 174.209 9.79254C174.001 9.4436 173.689 9.26913 173.273 9.26913C173.004 9.26913 172.756 9.34965 172.528 9.51071C172.306 9.67176 172.112 9.87307 171.944 10.1146V12.7418C172.085 12.9565 172.259 13.1243 172.468 13.2451C172.676 13.3659 172.904 13.4263 173.152 13.4263ZM180.939 12.8424C180.939 13.0505 180.972 13.2048 181.04 13.3055C181.107 13.3994 181.217 13.4699 181.372 13.5168L181.16 14.1208C180.644 14.0537 180.322 13.802 180.194 13.3659C180.006 13.6074 179.768 13.792 179.479 13.9195C179.198 14.047 178.882 14.1107 178.533 14.1107C178.003 14.1107 177.584 13.9631 177.275 13.6678C176.973 13.3726 176.822 12.9767 176.822 12.4801C176.822 11.9365 177.033 11.5171 177.456 11.2219C177.886 10.9266 178.5 10.779 179.298 10.779H180.083V10.3462C180.083 9.97037 179.976 9.70195 179.761 9.5409C179.546 9.37314 179.234 9.28926 178.825 9.28926C178.422 9.28926 177.963 9.37985 177.446 9.56103L177.215 8.91683C177.839 8.69538 178.419 8.58466 178.956 8.58466C179.6 8.58466 180.09 8.73565 180.426 9.03762C180.768 9.33959 180.939 9.75899 180.939 10.2958V12.8424ZM178.745 13.4766C179.006 13.4766 179.255 13.4095 179.489 13.2753C179.731 13.1411 179.929 12.9565 180.083 12.7217V11.3628H179.318C178.755 11.3628 178.349 11.4567 178.1 11.6446C177.852 11.8325 177.728 12.1077 177.728 12.47C177.728 13.1411 178.067 13.4766 178.745 13.4766ZM184.981 13.4162C185.384 13.4162 185.703 13.339 185.938 13.1847C186.172 13.0303 186.29 12.8257 186.29 12.5707C186.29 12.3962 186.26 12.2553 186.199 12.1479C186.139 12.0338 186.018 11.9332 185.837 11.8459C185.656 11.752 185.381 11.6581 185.012 11.5641C184.394 11.4098 183.938 11.2252 183.643 11.0105C183.347 10.789 183.2 10.4636 183.2 10.0341C183.2 9.59123 183.384 9.23893 183.753 8.97722C184.122 8.71552 184.609 8.58466 185.213 8.58466C185.951 8.58466 186.595 8.77927 187.145 9.16847L186.763 9.75228C186.542 9.59794 186.31 9.48051 186.068 9.39998C185.827 9.31275 185.548 9.26913 185.233 9.26913C184.468 9.26913 184.086 9.50064 184.086 9.96366C184.086 10.1247 184.126 10.2556 184.206 10.3562C184.294 10.4569 184.431 10.5475 184.619 10.628C184.814 10.7018 185.102 10.7924 185.485 10.8998C186.062 11.0541 186.491 11.2521 186.773 11.4936C187.062 11.7285 187.206 12.0741 187.206 12.5304C187.206 13.0605 186.991 13.4565 186.562 13.7182C186.132 13.9799 185.605 14.1107 184.981 14.1107C184.149 14.1107 183.458 13.8725 182.908 13.3961L183.381 12.8424C183.596 13.0169 183.841 13.1578 184.116 13.2652C184.391 13.3659 184.679 13.4162 184.981 13.4162ZM189.879 11.6446C189.9 12.2284 190.051 12.668 190.332 12.9632C190.621 13.2585 190.983 13.4061 191.419 13.4061C191.681 13.4061 191.919 13.3692 192.134 13.2954C192.356 13.2149 192.59 13.0941 192.839 12.933L193.231 13.4967C192.983 13.6913 192.698 13.8423 192.376 13.9497C192.06 14.057 191.742 14.1107 191.419 14.1107C190.654 14.1107 190.057 13.8624 189.628 13.3659C189.205 12.8626 188.994 12.1915 188.994 11.3527C188.994 10.8226 189.088 10.3495 189.275 9.93346C189.463 9.51071 189.732 9.18189 190.081 8.94703C190.43 8.70545 190.836 8.58466 191.299 8.58466C191.97 8.58466 192.496 8.81953 192.879 9.28926C193.268 9.75228 193.463 10.3864 193.463 11.1917C193.463 11.346 193.456 11.497 193.443 11.6446H189.879ZM191.309 9.27919C190.899 9.27919 190.567 9.42682 190.312 9.72208C190.057 10.0106 189.913 10.4367 189.879 11.0004H192.637C192.631 10.4435 192.51 10.0173 192.275 9.72208C192.04 9.42682 191.718 9.27919 191.309 9.27919ZM196.358 13.2249C196.358 12.9767 196.442 12.7686 196.609 12.6009C196.784 12.4264 196.995 12.3392 197.244 12.3392C197.499 12.3392 197.71 12.4264 197.878 12.6009C198.045 12.7686 198.129 12.9767 198.129 13.2249C198.129 13.4799 198.045 13.6913 197.878 13.8591C197.71 14.0268 197.499 14.1107 197.244 14.1107C196.995 14.1107 196.784 14.0268 196.609 13.8591C196.442 13.6846 196.358 13.4732 196.358 13.2249ZM203.088 13.4162C203.49 13.4162 203.809 13.339 204.044 13.1847C204.279 13.0303 204.396 12.8257 204.396 12.5707C204.396 12.3962 204.366 12.2553 204.306 12.1479C204.245 12.0338 204.125 11.9332 203.943 11.8459C203.762 11.752 203.487 11.6581 203.118 11.5641C202.501 11.4098 202.044 11.2252 201.749 11.0105C201.454 10.789 201.306 10.4636 201.306 10.0341C201.306 9.59123 201.491 9.23893 201.86 8.97722C202.229 8.71552 202.715 8.58466 203.319 8.58466C204.057 8.58466 204.702 8.77927 205.252 9.16847L204.869 9.75228C204.648 9.59794 204.416 9.48051 204.175 9.39998C203.933 9.31275 203.655 9.26913 203.339 9.26913C202.574 9.26913 202.192 9.50064 202.192 9.96366C202.192 10.1247 202.232 10.2556 202.313 10.3562C202.4 10.4569 202.538 10.5475 202.725 10.628C202.92 10.7018 203.209 10.7924 203.591 10.8998C204.168 11.0541 204.598 11.2521 204.879 11.4936C205.168 11.7285 205.312 12.0741 205.312 12.5304C205.312 13.0605 205.098 13.4565 204.668 13.7182C204.239 13.9799 203.712 14.1107 203.088 14.1107C202.256 14.1107 201.565 13.8725 201.014 13.3961L201.487 12.8424C201.702 13.0169 201.947 13.1578 202.222 13.2652C202.497 13.3659 202.786 13.4162 203.088 13.4162ZM209.808 14H208.831L206.909 8.69538H207.815L209.345 13.235L210.855 8.69538H211.74L209.808 14ZM215.753 13.386C216.216 13.386 216.675 13.2317 217.132 12.923L217.534 13.4766C217.313 13.6712 217.038 13.8255 216.709 13.9396C216.38 14.0537 216.061 14.1107 215.753 14.1107C214.967 14.1107 214.353 13.8658 213.911 13.3759C213.474 12.8794 213.256 12.2117 213.256 11.3729C213.256 10.8427 213.354 10.3663 213.548 9.94353C213.75 9.52077 214.038 9.1886 214.414 8.94703C214.79 8.70545 215.236 8.58466 215.753 8.58466C216.437 8.58466 217.028 8.79269 217.524 9.20873L217.111 9.76235C216.648 9.45367 216.192 9.29933 215.743 9.29933C215.266 9.29933 214.884 9.47715 214.595 9.83281C214.313 10.1818 214.172 10.6951 214.172 11.3729C214.172 12.0506 214.313 12.5573 214.595 12.8928C214.884 13.2216 215.269 13.386 215.753 13.386ZM220.5 13.2249C220.5 12.9767 220.584 12.7686 220.751 12.6009C220.926 12.4264 221.137 12.3392 221.385 12.3392C221.64 12.3392 221.852 12.4264 222.02 12.6009C222.187 12.7686 222.271 12.9767 222.271 13.2249C222.271 13.4799 222.187 13.6913 222.02 13.8591C221.852 14.0268 221.64 14.1107 221.385 14.1107C221.137 14.1107 220.926 14.0268 220.751 13.8591C220.584 13.6846 220.5 13.4732 220.5 13.2249ZM227.824 13.386C228.287 13.386 228.746 13.2317 229.203 12.923L229.605 13.4766C229.384 13.6712 229.109 13.8255 228.78 13.9396C228.451 14.0537 228.132 14.1107 227.824 14.1107C227.038 14.1107 226.424 13.8658 225.982 13.3759C225.545 12.8794 225.327 12.2117 225.327 11.3729C225.327 10.8427 225.425 10.3663 225.619 9.94353C225.82 9.52077 226.109 9.1886 226.485 8.94703C226.861 8.70545 227.307 8.58466 227.824 8.58466C228.508 8.58466 229.099 8.79269 229.595 9.20873L229.182 9.76235C228.719 9.45367 228.263 9.29933 227.814 9.29933C227.337 9.29933 226.955 9.47715 226.666 9.83281C226.384 10.1818 226.243 10.6951 226.243 11.3729C226.243 12.0506 226.384 12.5573 226.666 12.8928C226.955 13.2216 227.34 13.386 227.824 13.386ZM233.527 12.6915C233.527 13.1679 233.819 13.4061 234.403 13.4061C234.678 13.4061 234.973 13.3457 235.288 13.2249L235.51 13.8389C235.174 14.0201 234.755 14.1107 234.252 14.1107C233.775 14.1107 233.393 13.9799 233.104 13.7182C232.822 13.4565 232.681 13.1008 232.681 12.6512V7.23586H231.051V6.56146H233.527V12.6915ZM238.334 12.46C238.334 12.8022 238.405 13.0538 238.546 13.2149C238.693 13.3692 238.922 13.4464 239.23 13.4464C239.512 13.4464 239.784 13.3659 240.046 13.2048C240.307 13.0438 240.515 12.8424 240.67 12.6009V8.69538H241.515V14H240.79L240.72 13.2853C240.512 13.547 240.254 13.7517 239.945 13.8993C239.643 14.0403 239.334 14.1107 239.019 14.1107C238.516 14.1107 238.133 13.9765 237.871 13.7081C237.616 13.4397 237.489 13.0538 237.489 12.5505V8.69538H238.334V12.46ZM245.336 13.4162C245.739 13.4162 246.058 13.339 246.292 13.1847C246.527 13.0303 246.645 12.8257 246.645 12.5707C246.645 12.3962 246.614 12.2553 246.554 12.1479C246.494 12.0338 246.373 11.9332 246.192 11.8459C246.011 11.752 245.735 11.6581 245.366 11.5641C244.749 11.4098 244.293 11.2252 243.997 11.0105C243.702 10.789 243.555 10.4636 243.555 10.0341C243.555 9.59123 243.739 9.23893 244.108 8.97722C244.477 8.71552 244.964 8.58466 245.568 8.58466C246.306 8.58466 246.95 8.77927 247.5 9.16847L247.118 9.75228C246.896 9.59794 246.665 9.48051 246.423 9.39998C246.182 9.31275 245.903 9.26913 245.588 9.26913C244.823 9.26913 244.44 9.50064 244.44 9.96366C244.44 10.1247 244.481 10.2556 244.561 10.3562C244.648 10.4569 244.786 10.5475 244.974 10.628C245.168 10.7018 245.457 10.7924 245.839 10.8998C246.417 11.0541 246.846 11.2521 247.128 11.4936C247.416 11.7285 247.561 12.0741 247.561 12.5304C247.561 13.0605 247.346 13.4565 246.916 13.7182C246.487 13.9799 245.96 14.1107 245.336 14.1107C244.504 14.1107 243.813 13.8725 243.263 13.3961L243.736 12.8424C243.95 13.0169 244.195 13.1578 244.47 13.2652C244.746 13.3659 245.034 13.4162 245.336 13.4162ZM253.777 13.7282C253.596 13.849 253.375 13.943 253.113 14.0101C252.858 14.0772 252.603 14.1107 252.348 14.1107C251.791 14.1107 251.355 13.9664 251.039 13.6779C250.724 13.3826 250.566 12.9968 250.566 12.5203V9.35972H249.348V8.69538H250.566V7.49757L251.412 7.39691V8.69538H253.254L253.143 9.35972H251.412V12.5103C251.412 12.8122 251.492 13.037 251.653 13.1847C251.814 13.3323 252.073 13.4061 252.429 13.4061C252.791 13.4061 253.13 13.3222 253.445 13.1545L253.777 13.7282ZM256.27 11.6446C256.29 12.2284 256.441 12.668 256.723 12.9632C257.011 13.2585 257.374 13.4061 257.81 13.4061C258.071 13.4061 258.31 13.3692 258.524 13.2954C258.746 13.2149 258.981 13.0941 259.229 12.933L259.622 13.4967C259.373 13.6913 259.088 13.8423 258.766 13.9497C258.451 14.057 258.132 14.1107 257.81 14.1107C257.045 14.1107 256.447 13.8624 256.018 13.3659C255.595 12.8626 255.384 12.1915 255.384 11.3527C255.384 10.8226 255.478 10.3495 255.666 9.93346C255.854 9.51071 256.122 9.18189 256.471 8.94703C256.82 8.70545 257.226 8.58466 257.689 8.58466C258.36 8.58466 258.887 8.81953 259.269 9.28926C259.658 9.75228 259.853 10.3864 259.853 11.1917C259.853 11.346 259.846 11.497 259.833 11.6446H256.27ZM257.699 9.27919C257.29 9.27919 256.957 9.42682 256.702 9.72208C256.447 10.0106 256.303 10.4367 256.27 11.0004H259.028C259.021 10.4435 258.9 10.0173 258.665 9.72208C258.43 9.42682 258.108 9.27919 257.699 9.27919ZM265.214 8.58466C265.429 8.58466 265.677 8.62157 265.959 8.69538L265.838 10.4971H265.154V9.35972H265.103C264.285 9.35972 263.704 9.94353 263.362 11.1111V13.3457H264.439V14H261.681V13.3457H262.517V9.34965H261.681V8.69538H263.151L263.312 9.9536C263.526 9.49728 263.781 9.15505 264.077 8.9269C264.379 8.69874 264.758 8.58466 265.214 8.58466ZM268.784 13.2249C268.784 12.9767 268.867 12.7686 269.035 12.6009C269.21 12.4264 269.421 12.3392 269.669 12.3392C269.924 12.3392 270.136 12.4264 270.303 12.6009C270.471 12.7686 270.555 12.9767 270.555 13.2249C270.555 13.4799 270.471 13.6913 270.303 13.8591C270.136 14.0268 269.924 14.1107 269.669 14.1107C269.421 14.1107 269.21 14.0268 269.035 13.8591C268.867 13.6846 268.784 13.4732 268.784 13.2249ZM275.775 12.6915C275.775 13.1679 276.067 13.4061 276.651 13.4061C276.926 13.4061 277.221 13.3457 277.537 13.2249L277.758 13.8389C277.423 14.0201 277.003 14.1107 276.5 14.1107C276.024 14.1107 275.641 13.9799 275.352 13.7182C275.071 13.4565 274.93 13.1008 274.93 12.6512V7.23586H273.299V6.56146H275.775V12.6915ZM281.76 8.58466C282.492 8.58466 283.052 8.83295 283.441 9.32952C283.837 9.81939 284.035 10.4904 284.035 11.3427C284.035 12.1748 283.834 12.8458 283.431 13.3558C283.035 13.8591 282.475 14.1107 281.75 14.1107C281.019 14.1107 280.455 13.8658 280.059 13.3759C279.663 12.8794 279.465 12.205 279.465 11.3527C279.465 10.5139 279.663 9.84287 280.059 9.33959C280.462 8.8363 281.029 8.58466 281.76 8.58466ZM281.76 9.27919C281.297 9.27919 280.952 9.45031 280.724 9.79254C280.495 10.1348 280.381 10.6548 280.381 11.3527C280.381 12.0506 280.492 12.5707 280.714 12.9129C280.942 13.2484 281.287 13.4162 281.75 13.4162C282.213 13.4162 282.556 13.2484 282.777 12.9129C283.005 12.5707 283.119 12.0473 283.119 11.3427C283.119 10.6448 283.005 10.1281 282.777 9.79254C282.556 9.45031 282.217 9.27919 281.76 9.27919ZM288.178 13.386C288.641 13.386 289.101 13.2317 289.557 12.923L289.96 13.4766C289.739 13.6712 289.463 13.8255 289.135 13.9396C288.806 14.0537 288.487 14.1107 288.178 14.1107C287.393 14.1107 286.779 13.8658 286.336 13.3759C285.9 12.8794 285.682 12.2117 285.682 11.3729C285.682 10.8427 285.779 10.3663 285.974 9.94353C286.175 9.52077 286.464 9.1886 286.84 8.94703C287.215 8.70545 287.662 8.58466 288.178 8.58466C288.863 8.58466 289.453 8.79269 289.95 9.20873L289.537 9.76235C289.074 9.45367 288.618 9.29933 288.168 9.29933C287.692 9.29933 287.309 9.47715 287.021 9.83281C286.739 10.1818 286.598 10.6951 286.598 11.3729C286.598 12.0506 286.739 12.5573 287.021 12.8928C287.309 13.2216 287.695 13.386 288.178 13.386ZM295.613 12.8424C295.613 13.0505 295.647 13.2048 295.714 13.3055C295.781 13.3994 295.891 13.4699 296.046 13.5168L295.834 14.1208C295.318 14.0537 294.996 13.802 294.868 13.3659C294.68 13.6074 294.442 13.792 294.153 13.9195C293.872 14.047 293.556 14.1107 293.207 14.1107C292.677 14.1107 292.258 13.9631 291.949 13.6678C291.647 13.3726 291.496 12.9767 291.496 12.4801C291.496 11.9365 291.707 11.5171 292.13 11.2219C292.56 10.9266 293.174 10.779 293.972 10.779H294.757V10.3462C294.757 9.97037 294.65 9.70195 294.435 9.5409C294.221 9.37314 293.909 9.28926 293.499 9.28926C293.097 9.28926 292.637 9.37985 292.12 9.56103L291.889 8.91683C292.513 8.69538 293.093 8.58466 293.63 8.58466C294.274 8.58466 294.764 8.73565 295.1 9.03762C295.442 9.33959 295.613 9.75899 295.613 10.2958V12.8424ZM293.419 13.4766C293.68 13.4766 293.929 13.4095 294.163 13.2753C294.405 13.1411 294.603 12.9565 294.757 12.7217V11.3628H293.992C293.429 11.3628 293.023 11.4567 292.774 11.6446C292.526 11.8325 292.402 12.1077 292.402 12.47C292.402 13.1411 292.741 13.4766 293.419 13.4766ZM299.917 12.6915C299.917 13.1679 300.209 13.4061 300.793 13.4061C301.068 13.4061 301.363 13.3457 301.679 13.2249L301.9 13.8389C301.565 14.0201 301.145 14.1107 300.642 14.1107C300.165 14.1107 299.783 13.9799 299.494 13.7182C299.213 13.4565 299.072 13.1008 299.072 12.6512V7.23586H297.441V6.56146H299.917V12.6915ZM305.077 9.66169C305.077 9.44025 305.154 9.25235 305.308 9.09801C305.463 8.93696 305.654 8.85644 305.882 8.85644C306.117 8.85644 306.312 8.93696 306.466 9.09801C306.62 9.25235 306.697 9.44025 306.697 9.66169C306.697 9.88985 306.62 10.0844 306.466 10.2455C306.312 10.4066 306.117 10.4871 305.882 10.4871C305.654 10.4871 305.463 10.4066 305.308 10.2455C305.154 10.0844 305.077 9.88985 305.077 9.66169ZM305.077 13.2954C305.077 13.074 305.154 12.8827 305.308 12.7217C305.463 12.5606 305.654 12.4801 305.882 12.4801C306.117 12.4801 306.312 12.5606 306.466 12.7217C306.62 12.876 306.697 13.0672 306.697 13.2954C306.697 13.5303 306.62 13.7249 306.466 13.8792C306.312 14.0336 306.117 14.1107 305.882 14.1107C305.654 14.1107 305.463 14.0336 305.308 13.8792C305.154 13.7249 305.077 13.5303 305.077 13.2954ZM313.689 7.74921H310.951V9.93346C311.146 9.81939 311.337 9.74222 311.525 9.70195C311.72 9.65498 311.924 9.63149 312.139 9.63149C312.716 9.63149 313.176 9.82274 313.518 10.2052C313.867 10.5877 314.042 11.1212 314.042 11.8057C314.042 12.262 313.944 12.6646 313.75 13.0136C313.562 13.3625 313.29 13.6343 312.934 13.8289C312.579 14.0168 312.166 14.1107 311.696 14.1107C310.924 14.1107 310.253 13.8356 309.683 13.2853L310.206 12.772C310.629 13.2015 311.126 13.4162 311.696 13.4162C312.159 13.4162 312.518 13.2753 312.773 12.9934C313.028 12.7116 313.156 12.3056 313.156 11.7755C313.156 11.2521 313.042 10.8763 312.813 10.6481C312.585 10.4133 312.28 10.2958 311.898 10.2958C311.716 10.2958 311.552 10.3126 311.404 10.3462C311.257 10.3797 311.062 10.4401 310.82 10.5273H310.136V7.06474H313.81L313.689 7.74921ZM320.258 12.319H319.362V14H318.547V12.319H315.668V11.695L317.701 6.95402L318.406 7.25599L316.564 11.6346H318.557L318.628 9.67176H319.362V11.6346H320.258V12.319ZM323.687 6.95402C324.109 6.95402 324.482 7.03455 324.804 7.1956C325.126 7.34994 325.374 7.56132 325.549 7.82974C325.723 8.09144 325.81 8.37999 325.81 8.69538C325.81 9.09801 325.68 9.45031 325.418 9.75228C325.156 10.0475 324.837 10.2321 324.462 10.3059C324.898 10.3394 325.267 10.5039 325.569 10.7991C325.878 11.0944 326.032 11.497 326.032 12.007C326.032 12.4029 325.931 12.7619 325.73 13.084C325.529 13.4061 325.243 13.6578 324.874 13.8389C324.512 14.0201 324.096 14.1107 323.626 14.1107C323.217 14.1107 322.821 14.0336 322.438 13.8792C322.063 13.7249 321.751 13.4967 321.502 13.1947L322.066 12.7317C322.254 12.9532 322.482 13.1243 322.751 13.2451C323.026 13.3592 323.311 13.4162 323.606 13.4162C324.089 13.4162 324.465 13.292 324.733 13.0438C325.009 12.7888 325.146 12.4432 325.146 12.007C325.146 11.1279 324.666 10.6884 323.707 10.6884H323.133L323.234 10.014H323.646C324.009 10.014 324.317 9.91333 324.572 9.71202C324.827 9.50399 324.955 9.20202 324.955 8.80611C324.955 8.43703 324.831 8.15184 324.582 7.95052C324.341 7.7425 324.029 7.63849 323.646 7.63849C323.358 7.63849 323.099 7.68882 322.871 7.78947C322.65 7.89013 322.418 8.05118 322.177 8.27263L321.714 7.75928C322.277 7.22244 322.935 6.95402 323.687 6.95402ZM329.722 6.95402C330.145 6.95402 330.514 7.0379 330.829 7.20566C331.151 7.37342 331.396 7.60494 331.564 7.9002C331.732 8.18875 331.816 8.51756 331.816 8.88663C331.816 9.3161 331.715 9.73215 331.514 10.1348C331.319 10.5374 331.004 10.9803 330.568 11.4634C330.131 11.9399 329.514 12.5438 328.716 13.2753H331.977L331.876 14H327.749V13.3155C328.655 12.4499 329.326 11.7721 329.762 11.2823C330.205 10.7924 330.511 10.373 330.678 10.0241C330.846 9.67511 330.93 9.30604 330.93 8.91683C330.93 8.52762 330.819 8.2223 330.598 8.00085C330.376 7.77941 330.071 7.66869 329.682 7.66869C329.353 7.66869 329.078 7.72572 328.856 7.8398C328.642 7.94717 328.42 8.13506 328.192 8.40348L327.608 7.95052C327.883 7.60829 328.189 7.35665 328.524 7.1956C328.867 7.03455 329.266 6.95402 329.722 6.95402Z" fill="#252937"/>
+<line x1="239" y1="272" x2="446" y2="272" stroke="#CA2171" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M444.72 272L440.5 276.137L441.89 277.5L447.5 272L441.89 266.5L440.5 267.863L444.72 272Z" fill="#CA2171"/>
+<line x1="1" y1="-1" x2="208" y2="-1" transform="matrix(-1 -8.74228e-08 -8.74228e-08 1 447 121)" stroke="#E5544B" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1.5 4"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M444.72 120L440.5 124.137L441.89 125.5L447.5 120L441.89 114.5L440.5 115.863L444.72 120Z" fill="#E5544B"/>
+<path d="M324.783 151L322.721 144.279H322.668C322.676 144.439 322.688 144.682 322.703 145.006C322.723 145.326 322.74 145.668 322.756 146.031C322.771 146.395 322.779 146.723 322.779 147.016V151H321.156V142.434H323.629L325.656 148.984H325.691L327.842 142.434H330.314V151H328.621V146.945C328.621 146.676 328.625 146.365 328.633 146.014C328.645 145.662 328.658 145.328 328.674 145.012C328.689 144.691 328.701 144.451 328.709 144.291H328.656L326.447 151H324.783ZM337.41 151H332.477V142.434H337.41V143.922H334.293V145.803H337.193V147.291H334.293V149.5H337.41V151ZM344.26 148.621C344.26 149.129 344.137 149.57 343.891 149.945C343.645 150.32 343.285 150.609 342.812 150.812C342.344 151.016 341.773 151.117 341.102 151.117C340.805 151.117 340.514 151.098 340.229 151.059C339.947 151.02 339.676 150.963 339.414 150.889C339.156 150.811 338.91 150.715 338.676 150.602V148.914C339.082 149.094 339.504 149.256 339.941 149.4C340.379 149.545 340.812 149.617 341.242 149.617C341.539 149.617 341.777 149.578 341.957 149.5C342.141 149.422 342.273 149.314 342.355 149.178C342.438 149.041 342.479 148.885 342.479 148.709C342.479 148.494 342.406 148.311 342.262 148.158C342.117 148.006 341.918 147.863 341.664 147.73C341.414 147.598 341.131 147.455 340.814 147.303C340.615 147.209 340.398 147.096 340.164 146.963C339.93 146.826 339.707 146.66 339.496 146.465C339.285 146.27 339.111 146.033 338.975 145.756C338.842 145.475 338.775 145.139 338.775 144.748C338.775 144.236 338.893 143.799 339.127 143.436C339.361 143.072 339.695 142.795 340.129 142.604C340.566 142.408 341.082 142.311 341.676 142.311C342.121 142.311 342.545 142.363 342.947 142.469C343.354 142.57 343.777 142.719 344.219 142.914L343.633 144.326C343.238 144.166 342.885 144.043 342.572 143.957C342.26 143.867 341.941 143.822 341.617 143.822C341.391 143.822 341.197 143.859 341.037 143.934C340.877 144.004 340.756 144.105 340.674 144.238C340.592 144.367 340.551 144.518 340.551 144.689C340.551 144.893 340.609 145.064 340.727 145.205C340.848 145.342 341.027 145.475 341.266 145.604C341.508 145.732 341.809 145.883 342.168 146.055C342.605 146.262 342.979 146.479 343.287 146.705C343.6 146.928 343.84 147.191 344.008 147.496C344.176 147.797 344.26 148.172 344.26 148.621ZM352.832 151H351.021V147.303H347.629V151H345.812V142.434H347.629V145.791H351.021V142.434H352.832V151ZM307.979 158.434H310.645C311.785 158.434 312.648 158.594 313.234 158.914C313.82 159.234 314.113 159.797 314.113 160.602C314.113 160.926 314.061 161.219 313.955 161.48C313.854 161.742 313.705 161.957 313.51 162.125C313.314 162.293 313.076 162.402 312.795 162.453V162.512C313.08 162.57 313.338 162.672 313.568 162.816C313.799 162.957 313.982 163.164 314.119 163.438C314.26 163.707 314.33 164.066 314.33 164.516C314.33 165.035 314.203 165.48 313.949 165.852C313.695 166.223 313.332 166.508 312.859 166.707C312.391 166.902 311.832 167 311.184 167H307.979V158.434ZM309.795 161.826H310.85C311.377 161.826 311.742 161.744 311.945 161.58C312.148 161.412 312.25 161.166 312.25 160.842C312.25 160.514 312.129 160.279 311.887 160.139C311.648 159.994 311.27 159.922 310.75 159.922H309.795V161.826ZM309.795 163.268V165.5H310.979C311.525 165.5 311.906 165.395 312.121 165.184C312.336 164.973 312.443 164.689 312.443 164.334C312.443 164.123 312.396 163.938 312.303 163.777C312.209 163.617 312.051 163.492 311.828 163.402C311.609 163.312 311.307 163.268 310.92 163.268H309.795ZM318.707 161.961L320.494 158.434H322.451L319.609 163.666V167H317.805V163.725L314.963 158.434H316.932L318.707 161.961ZM326.266 158.434C327.371 158.434 328.178 158.672 328.686 159.148C329.193 159.621 329.447 160.273 329.447 161.105C329.447 161.48 329.391 161.84 329.277 162.184C329.164 162.523 328.979 162.826 328.721 163.092C328.467 163.357 328.127 163.568 327.701 163.725C327.275 163.877 326.75 163.953 326.125 163.953H325.346V167H323.529V158.434H326.266ZM326.172 159.922H325.346V162.465H325.943C326.283 162.465 326.578 162.42 326.828 162.33C327.078 162.24 327.271 162.1 327.408 161.908C327.545 161.717 327.613 161.471 327.613 161.17C327.613 160.748 327.496 160.436 327.262 160.232C327.027 160.025 326.664 159.922 326.172 159.922ZM336.309 167L335.688 164.961H332.564L331.943 167H329.986L333.01 158.398H335.23L338.266 167H336.309ZM335.254 163.438L334.633 161.445C334.594 161.312 334.541 161.143 334.475 160.936C334.412 160.725 334.348 160.512 334.281 160.297C334.219 160.078 334.168 159.889 334.129 159.729C334.09 159.889 334.035 160.088 333.965 160.326C333.898 160.561 333.834 160.783 333.771 160.994C333.709 161.205 333.664 161.355 333.637 161.445L333.021 163.438H335.254ZM344.406 164.621C344.406 165.129 344.283 165.57 344.037 165.945C343.791 166.32 343.432 166.609 342.959 166.812C342.49 167.016 341.92 167.117 341.248 167.117C340.951 167.117 340.66 167.098 340.375 167.059C340.094 167.02 339.822 166.963 339.561 166.889C339.303 166.811 339.057 166.715 338.822 166.602V164.914C339.229 165.094 339.65 165.256 340.088 165.4C340.525 165.545 340.959 165.617 341.389 165.617C341.686 165.617 341.924 165.578 342.104 165.5C342.287 165.422 342.42 165.314 342.502 165.178C342.584 165.041 342.625 164.885 342.625 164.709C342.625 164.494 342.553 164.311 342.408 164.158C342.264 164.006 342.064 163.863 341.811 163.73C341.561 163.598 341.277 163.455 340.961 163.303C340.762 163.209 340.545 163.096 340.311 162.963C340.076 162.826 339.854 162.66 339.643 162.465C339.432 162.27 339.258 162.033 339.121 161.756C338.988 161.475 338.922 161.139 338.922 160.748C338.922 160.236 339.039 159.799 339.273 159.436C339.508 159.072 339.842 158.795 340.275 158.604C340.713 158.408 341.229 158.311 341.822 158.311C342.268 158.311 342.691 158.363 343.094 158.469C343.5 158.57 343.924 158.719 344.365 158.914L343.779 160.326C343.385 160.166 343.031 160.043 342.719 159.957C342.406 159.867 342.088 159.822 341.764 159.822C341.537 159.822 341.344 159.859 341.184 159.934C341.023 160.004 340.902 160.105 340.82 160.238C340.738 160.367 340.697 160.518 340.697 160.689C340.697 160.893 340.756 161.064 340.873 161.205C340.994 161.342 341.174 161.475 341.412 161.604C341.654 161.732 341.955 161.883 342.314 162.055C342.752 162.262 343.125 162.479 343.434 162.705C343.746 162.928 343.986 163.191 344.154 163.496C344.322 163.797 344.406 164.172 344.406 164.621ZM351.016 164.621C351.016 165.129 350.893 165.57 350.646 165.945C350.4 166.32 350.041 166.609 349.568 166.812C349.1 167.016 348.529 167.117 347.857 167.117C347.561 167.117 347.27 167.098 346.984 167.059C346.703 167.02 346.432 166.963 346.17 166.889C345.912 166.811 345.666 166.715 345.432 166.602V164.914C345.838 165.094 346.26 165.256 346.697 165.4C347.135 165.545 347.568 165.617 347.998 165.617C348.295 165.617 348.533 165.578 348.713 165.5C348.896 165.422 349.029 165.314 349.111 165.178C349.193 165.041 349.234 164.885 349.234 164.709C349.234 164.494 349.162 164.311 349.018 164.158C348.873 164.006 348.674 163.863 348.42 163.73C348.17 163.598 347.887 163.455 347.57 163.303C347.371 163.209 347.154 163.096 346.92 162.963C346.686 162.826 346.463 162.66 346.252 162.465C346.041 162.27 345.867 162.033 345.73 161.756C345.598 161.475 345.531 161.139 345.531 160.748C345.531 160.236 345.648 159.799 345.883 159.436C346.117 159.072 346.451 158.795 346.885 158.604C347.322 158.408 347.838 158.311 348.432 158.311C348.877 158.311 349.301 158.363 349.703 158.469C350.109 158.57 350.533 158.719 350.975 158.914L350.389 160.326C349.994 160.166 349.641 160.043 349.328 159.957C349.016 159.867 348.697 159.822 348.373 159.822C348.146 159.822 347.953 159.859 347.793 159.934C347.633 160.004 347.512 160.105 347.43 160.238C347.348 160.367 347.307 160.518 347.307 160.689C347.307 160.893 347.365 161.064 347.482 161.205C347.604 161.342 347.783 161.475 348.021 161.604C348.264 161.732 348.564 161.883 348.924 162.055C349.361 162.262 349.734 162.479 350.043 162.705C350.355 162.928 350.596 163.191 350.764 163.496C350.932 163.797 351.016 164.172 351.016 164.621ZM357.502 167H352.568V158.434H357.502V159.922H354.385V161.803H357.285V163.291H354.385V165.5H357.502V167ZM366.402 162.635C366.402 163.6 366.217 164.406 365.846 165.055C365.479 165.699 364.945 166.186 364.246 166.514C363.547 166.838 362.705 167 361.721 167H359.295V158.434H361.984C362.883 158.434 363.662 158.594 364.322 158.914C364.982 159.23 365.494 159.701 365.857 160.326C366.221 160.947 366.402 161.717 366.402 162.635ZM364.516 162.682C364.516 162.049 364.422 161.529 364.234 161.123C364.051 160.713 363.777 160.41 363.414 160.215C363.055 160.02 362.609 159.922 362.078 159.922H361.111V165.5H361.891C362.777 165.5 363.436 165.264 363.865 164.791C364.299 164.318 364.516 163.615 364.516 162.682Z" fill="#E5544B"/>
+<circle cx="338" cy="121" r="13.25" fill="#E5544B" stroke="white" stroke-width="1.5"/>
+<path d="M338.701 122.685H337.033L336.684 116.006H339.049L338.701 122.685ZM336.657 125.022C336.657 124.594 336.773 124.293 337.006 124.12C337.242 123.947 337.527 123.86 337.86 123.86C338.184 123.86 338.462 123.947 338.694 124.12C338.931 124.293 339.049 124.594 339.049 125.022C339.049 125.433 338.931 125.729 338.694 125.911C338.462 126.093 338.184 126.185 337.86 126.185C337.527 126.185 337.242 126.093 337.006 125.911C336.773 125.729 336.657 125.433 336.657 125.022Z" fill="white"/>
+<line x1="238.5" y1="26.5" x2="238.5" y2="112.5" stroke="#999999" stroke-linecap="round" stroke-linejoin="round"/>
+<line x1="179.5" y1="204.5" x2="188.5" y2="204.5" stroke="#999999" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M16 235.75H84C84.6904 235.75 85.25 236.31 85.25 237V305C85.25 305.69 84.6904 306.25 84 306.25H16C15.3096 306.25 14.75 305.69 14.75 305V237C14.75 236.31 15.3096 235.75 16 235.75Z" fill="white" stroke="#D2D4DB" stroke-width="1.5"/>
+<mask id="path-54-inside-3_0_1" fill="white">
+<rect x="36" y="255" width="28" height="32" rx="1"/>
+</mask>
+<rect x="36" y="255" width="28" height="32" rx="1" stroke="black" stroke-width="4" mask="url(#path-54-inside-3_0_1)"/>
+<rect x="41" y="263" width="18" height="2" rx="1" fill="black"/>
+<rect x="41" y="269" width="18" height="2" rx="1" fill="black"/>
+<rect x="41" y="275" width="10" height="2" rx="1" fill="black"/>
+<mask id="path-58-inside-4_0_1" fill="white">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M50 247C47.7909 247 46 248.791 46 251V252H43C41.8954 252 41 252.895 41 254L41 258C41 259.105 41.8954 260 43 260L57 260C58.1046 260 59 259.105 59 258V254C59 252.895 58.1046 252 57 252H54V251C54 248.791 52.2091 247 50 247Z"/>
+</mask>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M50 247C47.7909 247 46 248.791 46 251V252H43C41.8954 252 41 252.895 41 254L41 258C41 259.105 41.8954 260 43 260L57 260C58.1046 260 59 259.105 59 258V254C59 252.895 58.1046 252 57 252H54V251C54 248.791 52.2091 247 50 247Z" fill="white"/>
+<path d="M46 252L46 254C46.5304 254 47.0391 253.789 47.4142 253.414C47.7893 253.039 48 252.53 48 252H46ZM43 252V250V252ZM43 260V258V260ZM57 260L57 262L57 260ZM54 252H52C52 253.105 52.8954 254 54 254L54 252ZM48 251C48 249.895 48.8954 249 50 249V245C46.6863 245 44 247.686 44 251H48ZM48 252V251H44V252H48ZM43 254H46L46 250H43L43 254ZM43 254L43 250C40.7909 250 39 251.791 39 254H43ZM43 258L43 254H39L39 258H43ZM43 258H43H39C39 260.209 40.7909 262 43 262L43 258ZM57 258H43L43 262H57L57 258ZM57 258L57 262C59.2091 262 61 260.209 61 258L57 258ZM57 254V258L61 258V254H57ZM57 254H61C61 251.791 59.2091 250 57 250L57 254ZM54 254H57L57 250H54L54 254ZM52 251V252H56V251H52ZM50 249C51.1046 249 52 249.895 52 251H56C56 247.686 53.3137 245 50 245V249Z" fill="black" mask="url(#path-58-inside-4_0_1)"/>
+<circle cx="14" cy="233" r="13.25" fill="#CA2171" stroke="white" stroke-width="1.5"/>
+<circle cx="14" cy="233" r="13.25" fill="#CA2171" stroke="white" stroke-width="1.5"/>
+<circle cx="210" cy="205" r="13.25" fill="#CA2171" stroke="white" stroke-width="1.5"/>
+<circle cx="435" cy="101" r="13.25" fill="#CA2171" stroke="white" stroke-width="1.5"/>
+<path d="M15.5757 238H13.5514V232.458L13.571 231.547L13.6038 230.551C13.2675 230.888 13.0338 231.108 12.9028 231.213L11.8022 232.097L10.8261 230.879L13.9117 228.422H15.5757V238Z" fill="white"/>
+<path d="M15.5757 238H13.5514V232.458L13.571 231.547L13.6038 230.551C13.2675 230.888 13.0338 231.108 12.9028 231.213L11.8022 232.097L10.8261 230.879L13.9117 228.422H15.5757V238Z" fill="white"/>
+<path d="M213.259 210H206.564V208.592L208.968 206.161C209.453 205.663 209.842 205.248 210.134 204.916C210.431 204.58 210.645 204.274 210.776 203.999C210.912 203.724 210.98 203.429 210.98 203.115C210.98 202.735 210.873 202.451 210.659 202.263C210.449 202.071 210.167 201.975 209.813 201.975C209.442 201.975 209.082 202.06 208.732 202.23C208.383 202.401 208.018 202.643 207.638 202.958L206.538 201.654C206.813 201.418 207.103 201.195 207.409 200.986C207.719 200.776 208.077 200.608 208.484 200.481C208.894 200.35 209.385 200.285 209.958 200.285C210.586 200.285 211.126 200.398 211.576 200.625C212.03 200.852 212.379 201.163 212.624 201.556C212.868 201.944 212.991 202.385 212.991 202.879C212.991 203.407 212.886 203.89 212.676 204.327C212.467 204.763 212.161 205.196 211.759 205.624C211.362 206.052 210.881 206.526 210.318 207.045L209.086 208.205V208.297H213.259V210Z" fill="white"/>
+<path d="M437.886 98.5645C437.886 99.0056 437.794 99.3877 437.611 99.7109C437.427 100.034 437.178 100.298 436.864 100.504C436.554 100.709 436.204 100.86 435.816 100.956V100.995C436.584 101.091 437.167 101.327 437.565 101.702C437.967 102.078 438.168 102.58 438.168 103.209C438.168 103.768 438.03 104.268 437.755 104.709C437.484 105.151 437.065 105.498 436.497 105.751C435.929 106.004 435.198 106.131 434.302 106.131C433.774 106.131 433.28 106.087 432.822 106C432.368 105.917 431.94 105.788 431.538 105.613V103.891C431.948 104.1 432.379 104.26 432.828 104.369C433.278 104.474 433.698 104.526 434.086 104.526C434.811 104.526 435.318 104.402 435.606 104.153C435.899 103.899 436.045 103.546 436.045 103.091C436.045 102.825 435.977 102.6 435.842 102.417C435.707 102.233 435.471 102.093 435.134 101.997C434.803 101.901 434.337 101.853 433.739 101.853H433.012V100.301H433.752C434.342 100.301 434.789 100.246 435.095 100.137C435.405 100.023 435.615 99.8703 435.724 99.6782C435.838 99.4816 435.894 99.2589 435.894 99.01C435.894 98.6693 435.79 98.4029 435.58 98.2107C435.37 98.0186 435.021 97.9225 434.532 97.9225C434.226 97.9225 433.946 97.9618 433.693 98.0404C433.444 98.1147 433.219 98.2064 433.018 98.3156C432.818 98.4204 432.641 98.523 432.488 98.6235L431.551 97.2281C431.927 96.9573 432.365 96.7324 432.868 96.5533C433.374 96.3742 433.977 96.2847 434.676 96.2847C435.663 96.2847 436.445 96.4834 437.021 96.8809C437.598 97.2783 437.886 97.8395 437.886 98.5645Z" fill="white"/>
+<path d="M51 240L51 214C51 209.582 54.5817 206 59 206L72 206" stroke="#9194A0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1.5 4"/>
+<circle cx="51" cy="236" r="4" transform="rotate(-90 51 236)" fill="white" stroke="#9194A0" stroke-width="2"/>
+<circle r="4" transform="matrix(-1 3.17865e-08 3.17865e-08 1 68 206)" fill="white" stroke="#9194A0" stroke-width="2"/>
+</svg>

From fdfe079674710684619c531e247567a7f45425ba Mon Sep 17 00:00:00 2001
From: Dan Upton <daniel@floppy.co>
Date: Fri, 28 Jan 2022 12:27:00 +0000
Subject: [PATCH 95/98] streaming: split event buffer by key (#12080)

---
 .changelog/12080.txt                         |   3 +
 agent/consul/state/catalog_events.go         |  34 ++--
 agent/consul/state/catalog_events_test.go    | 200 +++++++++----------
 agent/consul/state/store_integration_test.go |  20 +-
 agent/consul/stream/event.go                 |  53 +++--
 agent/consul/stream/event_publisher.go       | 164 ++++++++++-----
 agent/consul/stream/event_publisher_test.go  |  95 ++++++++-
 agent/consul/stream/event_test.go            | 119 -----------
 agent/consul/stream/subscription.go          |  31 ++-
 agent/consul/stream/subscription_test.go     |  26 ++-
 agent/rpc/subscribe/subscribe.go             |  15 +-
 agent/rpc/subscribe/subscribe_test.go        |  29 +++
 proto/pbsubscribe/subscribe.pb.go            |   5 +-
 proto/pbsubscribe/subscribe.proto            |   5 +-
 14 files changed, 426 insertions(+), 373 deletions(-)
 create mode 100644 .changelog/12080.txt

diff --git a/.changelog/12080.txt b/.changelog/12080.txt
new file mode 100644
index 0000000000..eab0ce5907
--- /dev/null
+++ b/.changelog/12080.txt
@@ -0,0 +1,3 @@
+```release-note:enhancement
+streaming: Improved performance when the server is handling many concurrent subscriptions and has a high number of CPU cores
+```
diff --git a/agent/consul/state/catalog_events.go b/agent/consul/state/catalog_events.go
index 7ee4e4dce4..38c37c653b 100644
--- a/agent/consul/state/catalog_events.go
+++ b/agent/consul/state/catalog_events.go
@@ -32,31 +32,26 @@ func (e EventPayloadCheckServiceNode) HasReadPermission(authz acl.Authorizer) bo
 	return e.Value.CanRead(authz) == acl.Allow
 }
 
-func (e EventPayloadCheckServiceNode) MatchesKey(key, namespace, partition string) bool {
-	if key == "" && namespace == "" && partition == "" {
-		return true
+func (e EventPayloadCheckServiceNode) Subject() stream.Subject {
+	partition := e.Value.Service.PartitionOrDefault()
+	if e.overridePartition != "" {
+		partition = e.overridePartition
 	}
+	partition = strings.ToLower(partition)
 
-	if e.Value.Service == nil {
-		return false
+	namespace := e.Value.Service.NamespaceOrDefault()
+	if e.overrideNamespace != "" {
+		namespace = e.overrideNamespace
 	}
+	namespace = strings.ToLower(namespace)
 
-	name := e.Value.Service.Service
+	key := e.Value.Service.Service
 	if e.overrideKey != "" {
-		name = e.overrideKey
-	}
-	ns := e.Value.Service.EnterpriseMeta.NamespaceOrDefault()
-	if e.overrideNamespace != "" {
-		ns = e.overrideNamespace
-	}
-	ap := e.Value.Service.EnterpriseMeta.PartitionOrDefault()
-	if e.overridePartition != "" {
-		ap = e.overridePartition
+		key = e.overrideKey
 	}
+	key = strings.ToLower(key)
 
-	return (key == "" || strings.EqualFold(key, name)) &&
-		(namespace == "" || strings.EqualFold(namespace, ns)) &&
-		(partition == "" || strings.EqualFold(partition, ap))
+	return stream.Subject(partition + "/" + namespace + "/" + key)
 }
 
 // serviceHealthSnapshot returns a stream.SnapshotFunc that provides a snapshot
@@ -67,8 +62,7 @@ func serviceHealthSnapshot(db ReadDB, topic stream.Topic) stream.SnapshotFunc {
 		defer tx.Abort()
 
 		connect := topic == topicServiceHealthConnect
-		entMeta := structs.NewEnterpriseMetaWithPartition(req.Partition, req.Namespace)
-		idx, nodes, err := checkServiceNodesTxn(tx, nil, req.Key, connect, &entMeta)
+		idx, nodes, err := checkServiceNodesTxn(tx, nil, req.Key, connect, &req.EnterpriseMeta)
 		if err != nil {
 			return 0, err
 		}
diff --git a/agent/consul/state/catalog_events_test.go b/agent/consul/state/catalog_events_test.go
index 9becf5bcb3..16269242ec 100644
--- a/agent/consul/state/catalog_events_test.go
+++ b/agent/consul/state/catalog_events_test.go
@@ -11,11 +11,106 @@ import (
 	"github.com/hashicorp/consul/agent/consul/stream"
 	"github.com/hashicorp/consul/agent/structs"
 	"github.com/hashicorp/consul/api"
-	"github.com/hashicorp/consul/proto/pbcommon"
 	"github.com/hashicorp/consul/proto/pbsubscribe"
 	"github.com/hashicorp/consul/types"
 )
 
+func TestEventPayloadCheckServiceNode_SubjectMatchesRequests(t *testing.T) {
+	// Matches.
+	for desc, tc := range map[string]struct {
+		evt EventPayloadCheckServiceNode
+		req stream.SubscribeRequest
+	}{
+		"default partition and namespace": {
+			EventPayloadCheckServiceNode{
+				Value: &structs.CheckServiceNode{
+					Service: &structs.NodeService{
+						Service: "foo",
+					},
+				},
+			},
+			stream.SubscribeRequest{
+				Key:            "foo",
+				EnterpriseMeta: structs.EnterpriseMeta{},
+			},
+		},
+		"mixed casing": {
+			EventPayloadCheckServiceNode{
+				Value: &structs.CheckServiceNode{
+					Service: &structs.NodeService{
+						Service: "FoO",
+					},
+				},
+			},
+			stream.SubscribeRequest{Key: "foo"},
+		},
+		"override key": {
+			EventPayloadCheckServiceNode{
+				Value: &structs.CheckServiceNode{
+					Service: &structs.NodeService{
+						Service: "foo",
+					},
+				},
+				overrideKey: "bar",
+			},
+			stream.SubscribeRequest{Key: "bar"},
+		},
+	} {
+		t.Run(desc, func(t *testing.T) {
+			require.Equal(t, tc.req.Subject(), tc.evt.Subject())
+		})
+	}
+
+	// Non-matches.
+	for desc, tc := range map[string]struct {
+		evt EventPayloadCheckServiceNode
+		req stream.SubscribeRequest
+	}{
+		"different key": {
+			EventPayloadCheckServiceNode{
+				Value: &structs.CheckServiceNode{
+					Service: &structs.NodeService{
+						Service: "foo",
+					},
+				},
+			},
+			stream.SubscribeRequest{
+				Key: "bar",
+			},
+		},
+		"different partition": {
+			EventPayloadCheckServiceNode{
+				Value: &structs.CheckServiceNode{
+					Service: &structs.NodeService{
+						Service: "foo",
+					},
+				},
+				overridePartition: "bar",
+			},
+			stream.SubscribeRequest{
+				Key: "foo",
+			},
+		},
+		"different namespace": {
+			EventPayloadCheckServiceNode{
+				Value: &structs.CheckServiceNode{
+					Service: &structs.NodeService{
+						Service: "foo",
+					},
+				},
+				overrideNamespace: "bar",
+			},
+			stream.SubscribeRequest{
+				Key: "foo",
+			},
+		},
+	} {
+		t.Run(desc, func(t *testing.T) {
+			require.NotEqual(t, tc.req.Subject(), tc.evt.Subject())
+		})
+	}
+}
+
 func TestServiceHealthSnapshot(t *testing.T) {
 	store := NewStateStore(nil)
 
@@ -1771,7 +1866,7 @@ func assertDeepEqual(t *testing.T, x, y interface{}, opts ...cmp.Option) {
 // all events for a particular topic are grouped together. The sort is
 // stable so events with the same key retain their relative order.
 //
-// This sort should match the logic in EventPayloadCheckServiceNode.MatchesKey
+// This sort should match the logic in EventPayloadCheckServiceNode.Subject
 // to avoid masking bugs.
 var cmpPartialOrderEvents = cmp.Options{
 	cmpopts.SortSlices(func(i, j stream.Event) bool {
@@ -2418,107 +2513,6 @@ func newTestEventServiceHealthDeregister(index uint64, nodeNum int, svc string)
 	}
 }
 
-func TestEventPayloadCheckServiceNode_FilterByKey(t *testing.T) {
-	type testCase struct {
-		name      string
-		payload   EventPayloadCheckServiceNode
-		key       string
-		namespace string
-		partition string // TODO(partitions): create test cases for this being set
-		expected  bool
-	}
-
-	fn := func(t *testing.T, tc testCase) {
-		if tc.namespace != "" && pbcommon.DefaultEnterpriseMeta.Namespace == "" {
-			t.Skip("cant test namespace matching without namespace support")
-		}
-
-		require.Equal(t, tc.expected, tc.payload.MatchesKey(tc.key, tc.namespace, tc.partition))
-	}
-
-	var testCases = []testCase{
-		{
-			name:     "no key or namespace",
-			payload:  newPayloadCheckServiceNode("srv1", "ns1"),
-			expected: true,
-		},
-		{
-			name:      "no key, with namespace match",
-			payload:   newPayloadCheckServiceNode("srv1", "ns1"),
-			namespace: "ns1",
-			expected:  true,
-		},
-		{
-			name:     "no namespace, with key match",
-			payload:  newPayloadCheckServiceNode("srv1", "ns1"),
-			key:      "srv1",
-			expected: true,
-		},
-		{
-			name:      "key match, namespace mismatch",
-			payload:   newPayloadCheckServiceNode("srv1", "ns1"),
-			key:       "srv1",
-			namespace: "ns2",
-			expected:  false,
-		},
-		{
-			name:      "key mismatch, namespace match",
-			payload:   newPayloadCheckServiceNode("srv1", "ns1"),
-			key:       "srv2",
-			namespace: "ns1",
-			expected:  false,
-		},
-		{
-			name:      "override key match",
-			payload:   newPayloadCheckServiceNodeWithOverride("proxy", "ns1", "srv1", ""),
-			key:       "srv1",
-			namespace: "ns1",
-			expected:  true,
-		},
-		{
-			name:      "override key mismatch",
-			payload:   newPayloadCheckServiceNodeWithOverride("proxy", "ns1", "srv2", ""),
-			key:       "proxy",
-			namespace: "ns1",
-			expected:  false,
-		},
-		{
-			name:      "override namespace match",
-			payload:   newPayloadCheckServiceNodeWithOverride("proxy", "ns1", "", "ns2"),
-			key:       "proxy",
-			namespace: "ns2",
-			expected:  true,
-		},
-		{
-			name:      "override namespace mismatch",
-			payload:   newPayloadCheckServiceNodeWithOverride("proxy", "ns1", "", "ns3"),
-			key:       "proxy",
-			namespace: "ns1",
-			expected:  false,
-		},
-		{
-			name:      "override both key and namespace match",
-			payload:   newPayloadCheckServiceNodeWithOverride("proxy", "ns1", "srv1", "ns2"),
-			key:       "srv1",
-			namespace: "ns2",
-			expected:  true,
-		},
-		{
-			name:      "override both key and namespace mismatch namespace",
-			payload:   newPayloadCheckServiceNodeWithOverride("proxy", "ns1", "srv2", "ns3"),
-			key:       "proxy",
-			namespace: "ns1",
-			expected:  false,
-		},
-	}
-
-	for _, tc := range testCases {
-		t.Run(tc.name, func(t *testing.T) {
-			fn(t, tc)
-		})
-	}
-}
-
 func newPayloadCheckServiceNode(service, namespace string) EventPayloadCheckServiceNode {
 	return EventPayloadCheckServiceNode{
 		Value: &structs.CheckServiceNode{
diff --git a/agent/consul/state/store_integration_test.go b/agent/consul/state/store_integration_test.go
index 60709f5fdc..edd0513896 100644
--- a/agent/consul/state/store_integration_test.go
+++ b/agent/consul/state/store_integration_test.go
@@ -419,26 +419,14 @@ type nodePayload struct {
 	node *structs.ServiceNode
 }
 
-func (p nodePayload) MatchesKey(key, _, partition string) bool {
-	if key == "" && partition == "" {
-		return true
-	}
-
-	if p.node == nil {
-		return false
-	}
-
-	if structs.PartitionOrDefault(partition) != p.node.PartitionOrDefault() {
-		return false
-	}
-
-	return p.key == key
-}
-
 func (p nodePayload) HasReadPermission(acl.Authorizer) bool {
 	return true
 }
 
+func (p nodePayload) Subject() stream.Subject {
+	return stream.Subject(p.node.PartitionOrDefault() + "/" + p.node.NamespaceOrDefault() + "/" + p.key)
+}
+
 func createTokenAndWaitForACLEventPublish(t *testing.T, s *Store) *structs.ACLToken {
 	token := &structs.ACLToken{
 		AccessorID:  "3af117a9-2233-4cf4-8ff8-3c749c9906b4",
diff --git a/agent/consul/stream/event.go b/agent/consul/stream/event.go
index 285710543e..9240f65242 100644
--- a/agent/consul/stream/event.go
+++ b/agent/consul/stream/event.go
@@ -14,6 +14,11 @@ import (
 // events which match the Topic.
 type Topic fmt.Stringer
 
+// Subject identifies a portion of a topic for which a subscriber wishes to
+// receive events (e.g. health events for a particular service) usually the
+// normalized resource name (including partition and namespace if applicable).
+type Subject string
+
 // Event is a structure with identifiers and a payload. Events are Published to
 // EventPublisher and returned to Subscribers.
 type Event struct {
@@ -26,18 +31,16 @@ type Event struct {
 // should not modify the state of the payload if the Event is being submitted to
 // EventPublisher.Publish.
 type Payload interface {
-	// MatchesKey must return true if the Payload should be included in a
-	// subscription requested with the key, namespace, and partition.
-	//
-	// Generally this means that the payload matches the key, namespace, and
-	// partition or the payload is a special framing event that should be
-	// returned to every subscription.
-	MatchesKey(key, namespace, partition string) bool
-
 	// HasReadPermission uses the acl.Authorizer to determine if the items in the
 	// Payload are visible to the request. It returns true if the payload is
 	// authorized for Read, otherwise returns false.
 	HasReadPermission(authz acl.Authorizer) bool
+
+	// Subject is used to identify which subscribers should be notified of this
+	// event - e.g. those subscribing to health events for a particular service.
+	// it is usually the normalized resource name (including the partition and
+	// namespace if applicable).
+	Subject() Subject
 }
 
 // PayloadEvents is a Payload that may be returned by Subscription.Next when
@@ -81,14 +84,6 @@ func (p *PayloadEvents) filter(f func(Event) bool) bool {
 	return true
 }
 
-// MatchesKey filters the PayloadEvents to those which match the key,
-// namespace, and partition.
-func (p *PayloadEvents) MatchesKey(key, namespace, partition string) bool {
-	return p.filter(func(event Event) bool {
-		return event.Payload.MatchesKey(key, namespace, partition)
-	})
-}
-
 func (p *PayloadEvents) Len() int {
 	return len(p.Items)
 }
@@ -101,6 +96,14 @@ func (p *PayloadEvents) HasReadPermission(authz acl.Authorizer) bool {
 	})
 }
 
+// Subject is required to satisfy the Payload interface but is not implemented
+// by PayloadEvents. PayloadEvents structs are constructed by Subscription.Next
+// *after* Subject has been used to dispatch the enclosed events to the correct
+// buffer.
+func (PayloadEvents) Subject() Subject {
+	panic("PayloadEvents does not implement Subject")
+}
+
 // IsEndOfSnapshot returns true if this is a framing event that indicates the
 // snapshot has completed. Subsequent events from Subscription.Next will be
 // streamed as they occur.
@@ -117,12 +120,15 @@ func (e Event) IsNewSnapshotToFollow() bool {
 
 type framingEvent struct{}
 
-func (framingEvent) MatchesKey(string, string, string) bool {
+func (framingEvent) HasReadPermission(acl.Authorizer) bool {
 	return true
 }
 
-func (framingEvent) HasReadPermission(acl.Authorizer) bool {
-	return true
+// Subject is required by the Payload interface but is not implemented by
+// framing events, as they are typically *manually* appended to the correct
+// buffer and do not need to be routed using a Subject.
+func (framingEvent) Subject() Subject {
+	panic("framing events do not implement Subject")
 }
 
 type endOfSnapshot struct {
@@ -137,12 +143,15 @@ type closeSubscriptionPayload struct {
 	tokensSecretIDs []string
 }
 
-func (closeSubscriptionPayload) MatchesKey(string, string, string) bool {
+func (closeSubscriptionPayload) HasReadPermission(acl.Authorizer) bool {
 	return false
 }
 
-func (closeSubscriptionPayload) HasReadPermission(acl.Authorizer) bool {
-	return false
+// Subject is required by the Payload interface but it is not implemented by
+// closeSubscriptionPayload, as this event type is handled separately and not
+// actually appended to the buffer.
+func (closeSubscriptionPayload) Subject() Subject {
+	panic("closeSubscriptionPayload does not implement Subject")
 }
 
 // NewCloseSubscriptionEvent returns a special Event that is handled by the
diff --git a/agent/consul/stream/event_publisher.go b/agent/consul/stream/event_publisher.go
index 163fa81094..0941013557 100644
--- a/agent/consul/stream/event_publisher.go
+++ b/agent/consul/stream/event_publisher.go
@@ -20,16 +20,16 @@ type EventPublisher struct {
 	// seconds.
 	snapCacheTTL time.Duration
 
-	// This lock protects the topicBuffers, and snapCache
+	// This lock protects the snapCache, topicBuffers and topicBuffer.refs.
 	lock sync.RWMutex
 
-	// topicBuffers stores the head of the linked-list buffer to publish events to
+	// topicBuffers stores the head of the linked-list buffers to publish events to
 	// for a topic.
-	topicBuffers map[Topic]*eventBuffer
+	topicBuffers map[topicSubject]*topicBuffer
 
-	// snapCache if a cache of EventSnapshots indexed by topic and key.
+	// snapCache if a cache of EventSnapshots indexed by topic and subject.
 	// TODO(streaming): new snapshotCache struct for snapCache and snapCacheTTL
-	snapCache map[Topic]map[string]*eventSnapshot
+	snapCache map[topicSubject]*eventSnapshot
 
 	subscriptions *subscriptions
 
@@ -41,6 +41,13 @@ type EventPublisher struct {
 	snapshotHandlers SnapshotHandlers
 }
 
+// topicSubject is used as a map key when accessing topic buffers and cached
+// snapshots.
+type topicSubject struct {
+	Topic   Topic
+	Subject Subject
+}
+
 type subscriptions struct {
 	// lock for byToken. If both subscription.lock and EventPublisher.lock need
 	// to be held, EventPublisher.lock MUST always be acquired first.
@@ -54,6 +61,14 @@ type subscriptions struct {
 	byToken map[string]map[*SubscribeRequest]*Subscription
 }
 
+// topicBuffer augments the eventBuffer with a reference counter, enabling
+// clean up of unused buffers once there are no longer any subscribers for
+// the given topic and key.
+type topicBuffer struct {
+	refs int // refs is guarded by EventPublisher.lock.
+	buf  *eventBuffer
+}
+
 // SnapshotHandlers is a mapping of Topic to a function which produces a snapshot
 // of events for the SubscribeRequest. Events are appended to the snapshot using SnapshotAppender.
 // The nil Topic is reserved and should not be used.
@@ -79,8 +94,8 @@ type SnapshotAppender interface {
 func NewEventPublisher(handlers SnapshotHandlers, snapCacheTTL time.Duration) *EventPublisher {
 	e := &EventPublisher{
 		snapCacheTTL: snapCacheTTL,
-		topicBuffers: make(map[Topic]*eventBuffer),
-		snapCache:    make(map[Topic]map[string]*eventSnapshot),
+		topicBuffers: make(map[topicSubject]*topicBuffer),
+		snapCache:    make(map[topicSubject]*eventSnapshot),
 		publishCh:    make(chan []Event, 64),
 		subscriptions: &subscriptions{
 			byToken: make(map[string]map[*SubscribeRequest]*Subscription),
@@ -116,36 +131,59 @@ func (e *EventPublisher) Run(ctx context.Context) {
 // publishEvent appends the events to any applicable topic buffers. It handles
 // any closeSubscriptionPayload events by closing associated subscriptions.
 func (e *EventPublisher) publishEvent(events []Event) {
-	eventsByTopic := make(map[Topic][]Event)
+	groupedEvents := make(map[topicSubject][]Event)
 	for _, event := range events {
 		if unsubEvent, ok := event.Payload.(closeSubscriptionPayload); ok {
 			e.subscriptions.closeSubscriptionsForTokens(unsubEvent.tokensSecretIDs)
 			continue
 		}
 
-		eventsByTopic[event.Topic] = append(eventsByTopic[event.Topic], event)
+		groupKey := topicSubject{event.Topic, event.Payload.Subject()}
+		groupedEvents[groupKey] = append(groupedEvents[groupKey], event)
 	}
 
 	e.lock.Lock()
 	defer e.lock.Unlock()
-	for topic, events := range eventsByTopic {
-		e.getTopicBuffer(topic).Append(events)
+	for groupKey, events := range groupedEvents {
+		// Note: bufferForPublishing returns nil if there are no subscribers for the
+		// given topic and subject, in which case events will be dropped on the floor and
+		// future subscribers will catch up by consuming the snapshot.
+		if buf := e.bufferForPublishing(groupKey); buf != nil {
+			buf.Append(events)
+		}
 	}
 }
 
-// getTopicBuffer for the topic. Creates a new event buffer if one does not
-// already exist.
+// bufferForSubscription returns the topic event buffer to which events for the
+// given topic and key will be appended. If no such buffer exists, a new buffer
+// will be created.
 //
-// EventPublisher.lock must be held to call this method.
-func (e *EventPublisher) getTopicBuffer(topic Topic) *eventBuffer {
-	buf, ok := e.topicBuffers[topic]
+// Warning: e.lock MUST be held when calling this function.
+func (e *EventPublisher) bufferForSubscription(key topicSubject) *topicBuffer {
+	buf, ok := e.topicBuffers[key]
 	if !ok {
-		buf = newEventBuffer()
-		e.topicBuffers[topic] = buf
+		buf = &topicBuffer{
+			buf: newEventBuffer(),
+		}
+		e.topicBuffers[key] = buf
 	}
+
 	return buf
 }
 
+// bufferForPublishing returns the event buffer to which events for the given
+// topic and key should be appended. nil will be returned if there are no
+// subscribers for the given topic and key.
+//
+// Warning: e.lock MUST be held when calling this function.
+func (e *EventPublisher) bufferForPublishing(key topicSubject) *eventBuffer {
+	buf, ok := e.topicBuffers[key]
+	if !ok {
+		return nil
+	}
+	return buf.buf
+}
+
 // Subscribe returns a new Subscription for the given request. A subscription
 // will receive an initial snapshot of events matching the request if req.Index > 0.
 // After the snapshot, events will be streamed as they are created.
@@ -163,7 +201,34 @@ func (e *EventPublisher) Subscribe(req *SubscribeRequest) (*Subscription, error)
 	e.lock.Lock()
 	defer e.lock.Unlock()
 
-	topicHead := e.getTopicBuffer(req.Topic).Head()
+	topicBuf := e.bufferForSubscription(req.topicSubject())
+	topicBuf.refs++
+
+	// freeBuf is used to free the topic buffer once there are no remaining
+	// subscribers for the given topic and key.
+	//
+	// Note: it's called by Subcription.Unsubscribe which has its own side-effects
+	// that are made without holding e.lock (so there's a moment where the ref
+	// counter is inconsistent with the subscription map) — in practice this is
+	// fine, we don't need these things to be strongly consistent. The alternative
+	// would be to hold both locks, which introduces the risk of deadlocks.
+	freeBuf := func() {
+		e.lock.Lock()
+		defer e.lock.Unlock()
+
+		topicBuf.refs--
+
+		if topicBuf.refs == 0 {
+			delete(e.topicBuffers, req.topicSubject())
+
+			// Evict cached snapshot too because the topic buffer will have been spliced
+			// onto it. If we don't do this, any new subscribers started before the cache
+			// TTL is reached will get "stuck" waiting on the old buffer.
+			delete(e.snapCache, req.topicSubject())
+		}
+	}
+
+	topicHead := topicBuf.buf.Head()
 
 	// If the client view is fresh, resume the stream.
 	if req.Index > 0 && topicHead.HasEventIndex(req.Index) {
@@ -173,7 +238,7 @@ func (e *EventPublisher) Subscribe(req *SubscribeRequest) (*Subscription, error)
 		// the subscription will receive new events.
 		next, _ := topicHead.NextNoBlock()
 		buf.AppendItem(next)
-		return e.subscriptions.add(req, subscriptionHead), nil
+		return e.subscriptions.add(req, subscriptionHead, freeBuf), nil
 	}
 
 	snapFromCache := e.getCachedSnapshotLocked(req)
@@ -186,7 +251,7 @@ func (e *EventPublisher) Subscribe(req *SubscribeRequest) (*Subscription, error)
 
 	// If the request.Index is 0 the client has no view, send a full snapshot.
 	if req.Index == 0 {
-		return e.subscriptions.add(req, snapFromCache.First), nil
+		return e.subscriptions.add(req, snapFromCache.First, freeBuf), nil
 	}
 
 	// otherwise the request has an Index, the client view is stale and must be reset
@@ -197,11 +262,17 @@ func (e *EventPublisher) Subscribe(req *SubscribeRequest) (*Subscription, error)
 		Payload: newSnapshotToFollow{},
 	}})
 	result.buffer.AppendItem(snapFromCache.First)
-	return e.subscriptions.add(req, result.First), nil
+	return e.subscriptions.add(req, result.First, freeBuf), nil
 }
 
-func (s *subscriptions) add(req *SubscribeRequest, head *bufferItem) *Subscription {
-	sub := newSubscription(*req, head, s.unsubscribe(req))
+func (s *subscriptions) add(req *SubscribeRequest, head *bufferItem, freeBuf func()) *Subscription {
+	// We wrap freeBuf in a sync.Once as it's expected that Subscription.unsub is
+	// idempotent, but freeBuf decrements the reference counter on every call.
+	var once sync.Once
+	sub := newSubscription(*req, head, func() {
+		s.unsubscribe(req)
+		once.Do(freeBuf)
+	})
 
 	s.lock.Lock()
 	defer s.lock.Unlock()
@@ -228,24 +299,17 @@ func (s *subscriptions) closeSubscriptionsForTokens(tokenSecretIDs []string) {
 	}
 }
 
-// unsubscribe returns a function that the subscription will call to remove
-// itself from the subsByToken.
-// This function is returned as a closure so that the caller doesn't need to keep
-// track of the SubscriptionRequest, and can not accidentally call unsubscribe with the
-// wrong pointer.
-func (s *subscriptions) unsubscribe(req *SubscribeRequest) func() {
-	return func() {
-		s.lock.Lock()
-		defer s.lock.Unlock()
-
-		subsByToken, ok := s.byToken[req.Token]
-		if !ok {
-			return
-		}
-		delete(subsByToken, req)
-		if len(subsByToken) == 0 {
-			delete(s.byToken, req.Token)
-		}
+func (s *subscriptions) unsubscribe(req *SubscribeRequest) {
+	s.lock.Lock()
+	defer s.lock.Unlock()
+
+	subsByToken, ok := s.byToken[req.Token]
+	if !ok {
+		return
+	}
+	delete(subsByToken, req)
+	if len(subsByToken) == 0 {
+		delete(s.byToken, req.Token)
 	}
 }
 
@@ -262,13 +326,7 @@ func (s *subscriptions) closeAll() {
 
 // EventPublisher.lock must be held to call this method.
 func (e *EventPublisher) getCachedSnapshotLocked(req *SubscribeRequest) *eventSnapshot {
-	topicSnaps, ok := e.snapCache[req.Topic]
-	if !ok {
-		topicSnaps = make(map[string]*eventSnapshot)
-		e.snapCache[req.Topic] = topicSnaps
-	}
-
-	snap, ok := topicSnaps[snapCacheKey(req)]
+	snap, ok := e.snapCache[req.topicSubject()]
 	if ok && snap.err() == nil {
 		return snap
 	}
@@ -280,16 +338,12 @@ func (e *EventPublisher) setCachedSnapshotLocked(req *SubscribeRequest, snap *ev
 	if e.snapCacheTTL == 0 {
 		return
 	}
-	e.snapCache[req.Topic][snapCacheKey(req)] = snap
+	e.snapCache[req.topicSubject()] = snap
 
 	// Setup a cache eviction
 	time.AfterFunc(e.snapCacheTTL, func() {
 		e.lock.Lock()
 		defer e.lock.Unlock()
-		delete(e.snapCache[req.Topic], snapCacheKey(req))
+		delete(e.snapCache, req.topicSubject())
 	})
 }
-
-func snapCacheKey(req *SubscribeRequest) string {
-	return req.Partition + "/" + req.Namespace + "/" + req.Key
-}
diff --git a/agent/consul/stream/event_publisher_test.go b/agent/consul/stream/event_publisher_test.go
index af7fc3c288..f90af0b1b0 100644
--- a/agent/consul/stream/event_publisher_test.go
+++ b/agent/consul/stream/event_publisher_test.go
@@ -56,6 +56,13 @@ func TestEventPublisher_SubscribeWithIndex0(t *testing.T) {
 		Payload: simplePayload{key: "sub-key", value: "the-published-event-payload"},
 	}
 	require.Equal(t, expected, next)
+
+	// Subscriber should not see events for other keys
+	publisher.Publish([]Event{{
+		Topic:   testTopic,
+		Payload: simplePayload{key: "other-key", value: "this-should-not-reach-the-subscriber"},
+	}})
+	assertNoResult(t, eventCh)
 }
 
 var testSnapshotEvent = Event{
@@ -70,17 +77,12 @@ type simplePayload struct {
 	noReadPerm bool
 }
 
-func (p simplePayload) MatchesKey(key, _, _ string) bool {
-	if key == "" {
-		return true
-	}
-	return p.key == key
-}
-
 func (p simplePayload) HasReadPermission(acl.Authorizer) bool {
 	return !p.noReadPerm
 }
 
+func (p simplePayload) Subject() Subject { return Subject("default/default/" + p.key) }
+
 func newTestSnapshotHandlers() SnapshotHandlers {
 	return SnapshotHandlers{
 		testTopic: func(req SubscribeRequest, buf SnapshotAppender) (uint64, error) {
@@ -190,9 +192,10 @@ func TestEventPublisher_SubscribeWithIndex0_FromCache(t *testing.T) {
 
 	publisher := NewEventPublisher(newTestSnapshotHandlers(), time.Second)
 	go publisher.Run(ctx)
+
 	sub, err := publisher.Subscribe(req)
 	require.NoError(t, err)
-	sub.Unsubscribe()
+	defer sub.Unsubscribe()
 
 	publisher.snapshotHandlers[testTopic] = func(_ SubscribeRequest, _ SnapshotAppender) (uint64, error) {
 		return 0, fmt.Errorf("error should not be seen, cache should have been used")
@@ -200,6 +203,7 @@ func TestEventPublisher_SubscribeWithIndex0_FromCache(t *testing.T) {
 
 	sub, err = publisher.Subscribe(req)
 	require.NoError(t, err)
+	defer sub.Unsubscribe()
 
 	eventCh := runSubscription(ctx, sub)
 	next := getNextEvent(t, eventCh)
@@ -233,7 +237,11 @@ func TestEventPublisher_SubscribeWithIndexNotZero_CanResume(t *testing.T) {
 
 	publisher := NewEventPublisher(newTestSnapshotHandlers(), time.Second)
 	go publisher.Run(ctx)
-	// Include the same event in the topicBuffer
+
+	simulateExistingSubscriber(t, publisher, req)
+
+	// Publish the testSnapshotEvent, to ensure that it is skipped over when
+	// splicing the topic buffer onto the snapshot.
 	publisher.publishEvent([]Event{testSnapshotEvent})
 
 	runStep(t, "start a subscription and unsub", func(t *testing.T) {
@@ -338,7 +346,11 @@ func TestEventPublisher_SubscribeWithIndexNotZero_NewSnapshotFromCache(t *testin
 
 	publisher := NewEventPublisher(newTestSnapshotHandlers(), time.Second)
 	go publisher.Run(ctx)
-	// Include the same event in the topicBuffer
+
+	simulateExistingSubscriber(t, publisher, req)
+
+	// Publish the testSnapshotEvent, to ensure that it is skipped over when
+	// splicing the topic buffer onto the snapshot.
 	publisher.publishEvent([]Event{testSnapshotEvent})
 
 	runStep(t, "start a subscription and unsub", func(t *testing.T) {
@@ -421,7 +433,11 @@ func TestEventPublisher_SubscribeWithIndexNotZero_NewSnapshot_WithCache(t *testi
 
 	publisher := NewEventPublisher(handlers, time.Second)
 	go publisher.Run(ctx)
-	// Include the same events in the topicBuffer
+
+	simulateExistingSubscriber(t, publisher, req)
+
+	// Publish the events, to ensure they are is skipped over when splicing the
+	// topic buffer onto the snapshot.
 	publisher.publishEvent([]Event{testSnapshotEvent})
 	publisher.publishEvent([]Event{nextEvent})
 
@@ -495,3 +511,60 @@ func TestEventPublisher_Unsubscribe_ClosesSubscription(t *testing.T) {
 	require.Error(t, err)
 	require.Contains(t, err.Error(), "subscription was closed by unsubscribe")
 }
+
+func TestEventPublisher_Unsubscribe_FreesResourcesWhenThereAreNoSubscribers(t *testing.T) {
+	req := &SubscribeRequest{
+		Topic: testTopic,
+		Key:   "sub-key",
+	}
+
+	publisher := NewEventPublisher(newTestSnapshotHandlers(), time.Second)
+
+	sub1, err := publisher.Subscribe(req)
+	require.NoError(t, err)
+
+	// Expect a topic buffer and snapshot to have been created.
+	publisher.lock.Lock()
+	require.NotNil(t, publisher.topicBuffers[req.topicSubject()])
+	require.NotNil(t, publisher.snapCache[req.topicSubject()])
+	publisher.lock.Unlock()
+
+	// Create another subscription and close the old one, to ensure the buffer and
+	// snapshot stick around as long as there's at least one subscriber.
+	sub2, err := publisher.Subscribe(req)
+	require.NoError(t, err)
+
+	sub1.Unsubscribe()
+
+	publisher.lock.Lock()
+	require.NotNil(t, publisher.topicBuffers[req.topicSubject()])
+	require.NotNil(t, publisher.snapCache[req.topicSubject()])
+	publisher.lock.Unlock()
+
+	// Close the other subscription and expect the buffer and snapshot to have
+	// been cleaned up.
+	sub2.Unsubscribe()
+
+	publisher.lock.Lock()
+	require.Nil(t, publisher.topicBuffers[req.topicSubject()])
+	require.Nil(t, publisher.snapCache[req.topicSubject()])
+	publisher.lock.Unlock()
+}
+
+// simulateExistingSubscriber creates a subscription that remains open throughout
+// a test to prevent the topic buffer getting garbage-collected.
+//
+// It evicts the created snapshot from the cache immediately (simulating an
+// existing subscription that has been open long enough the snapshot's TTL has
+// been reached) so you can test snapshots getting created afresh.
+func simulateExistingSubscriber(t *testing.T, p *EventPublisher, r *SubscribeRequest) {
+	t.Helper()
+
+	sub, err := p.Subscribe(r)
+	require.NoError(t, err)
+	t.Cleanup(sub.Unsubscribe)
+
+	p.lock.Lock()
+	delete(p.snapCache, r.topicSubject())
+	p.lock.Unlock()
+}
diff --git a/agent/consul/stream/event_test.go b/agent/consul/stream/event_test.go
index a3187017ca..a9b381fe4d 100644
--- a/agent/consul/stream/event_test.go
+++ b/agent/consul/stream/event_test.go
@@ -20,119 +20,6 @@ func newSimpleEvent(key string, index uint64) Event {
 	return Event{Index: index, Payload: simplePayload{key: key}}
 }
 
-func TestPayloadEvents_FilterByKey(t *testing.T) {
-	type testCase struct {
-		name        string
-		req         SubscribeRequest
-		events      []Event
-		expectEvent bool
-		expected    *PayloadEvents
-		expectedCap int
-	}
-
-	fn := func(t *testing.T, tc testCase) {
-		events := make([]Event, 0, 5)
-		events = append(events, tc.events...)
-
-		pe := &PayloadEvents{Items: events}
-		ok := pe.MatchesKey(tc.req.Key, tc.req.Namespace, tc.req.Partition)
-		require.Equal(t, tc.expectEvent, ok)
-		if !tc.expectEvent {
-			return
-		}
-
-		require.Equal(t, tc.expected, pe)
-		// test if there was a new array allocated or not
-		require.Equal(t, tc.expectedCap, cap(pe.Items))
-	}
-
-	var testCases = []testCase{
-		{
-			name: "all events match, no key or namespace",
-			req:  SubscribeRequest{Topic: testTopic},
-			events: []Event{
-				newSimpleEvent("One", 102),
-				newSimpleEvent("Two", 102)},
-			expectEvent: true,
-			expected: newPayloadEvents(
-				newSimpleEvent("One", 102),
-				newSimpleEvent("Two", 102)),
-			expectedCap: 5,
-		},
-		{
-			name: "all events match, no namespace",
-			req:  SubscribeRequest{Topic: testTopic, Key: "Same"},
-			events: []Event{
-				newSimpleEvent("Same", 103),
-				newSimpleEvent("Same", 103)},
-			expectEvent: true,
-			expected: newPayloadEvents(
-				newSimpleEvent("Same", 103),
-				newSimpleEvent("Same", 103)),
-			expectedCap: 5,
-		},
-		{
-			name: "all events match, no key",
-			req:  SubscribeRequest{Topic: testTopic, Namespace: "apps"},
-			events: []Event{
-				newNSEvent("Something", "apps"),
-				newNSEvent("Other", "apps")},
-			expectEvent: true,
-			expected: newPayloadEvents(
-				newNSEvent("Something", "apps"),
-				newNSEvent("Other", "apps")),
-			expectedCap: 5,
-		},
-		{
-			name: "some evens match, no namespace",
-			req:  SubscribeRequest{Topic: testTopic, Key: "Same"},
-			events: []Event{
-				newSimpleEvent("Same", 104),
-				newSimpleEvent("Other", 104),
-				newSimpleEvent("Same", 104)},
-			expectEvent: true,
-			expected: newPayloadEvents(
-				newSimpleEvent("Same", 104),
-				newSimpleEvent("Same", 104)),
-			expectedCap: 2,
-		},
-		{
-			name: "some events match, no key",
-			req:  SubscribeRequest{Topic: testTopic, Namespace: "apps"},
-			events: []Event{
-				newNSEvent("app1", "apps"),
-				newNSEvent("db1", "dbs"),
-				newNSEvent("app2", "apps")},
-			expectEvent: true,
-			expected: newPayloadEvents(
-				newNSEvent("app1", "apps"),
-				newNSEvent("app2", "apps")),
-			expectedCap: 2,
-		},
-		{
-			name: "no events match key",
-			req:  SubscribeRequest{Topic: testTopic, Key: "Other"},
-			events: []Event{
-				newSimpleEvent("Same", 0),
-				newSimpleEvent("Same", 0)},
-		},
-		{
-			name: "no events match namespace",
-			req:  SubscribeRequest{Topic: testTopic, Namespace: "apps"},
-			events: []Event{
-				newNSEvent("app1", "group1"),
-				newNSEvent("app2", "group2")},
-			expectEvent: false,
-		},
-	}
-
-	for _, tc := range testCases {
-		t.Run(tc.name, func(t *testing.T) {
-			fn(t, tc)
-		})
-	}
-}
-
 // TODO(partitions)
 func newNSEvent(key, namespace string) Event {
 	return Event{Index: 22, Payload: nsPayload{key: key, namespace: namespace}}
@@ -146,12 +33,6 @@ type nsPayload struct {
 	value     string
 }
 
-func (p nsPayload) MatchesKey(key, namespace, partition string) bool {
-	return (key == "" || key == p.key) &&
-		(namespace == "" || namespace == p.namespace) &&
-		(partition == "" || partition == p.partition)
-}
-
 func TestPayloadEvents_HasReadPermission(t *testing.T) {
 	t.Run("some events filtered", func(t *testing.T) {
 		ep := newPayloadEvents(
diff --git a/agent/consul/stream/subscription.go b/agent/consul/stream/subscription.go
index 9f47cd2ee3..0a42947154 100644
--- a/agent/consul/stream/subscription.go
+++ b/agent/consul/stream/subscription.go
@@ -4,7 +4,10 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 	"sync/atomic"
+
+	"github.com/hashicorp/consul/agent/structs"
 )
 
 const (
@@ -59,12 +62,9 @@ type SubscribeRequest struct {
 	// be returned by the subscription. A blank key will return all events. Key
 	// is generally the name of the resource.
 	Key string
-	// Namespace used to filter events in the topic. Only events matching the
-	// namespace will be returned by the subscription.
-	Namespace string
-	// Partition used to filter events in the topic. Only events matching the
-	// partition will be returned by the subscription.
-	Partition string // TODO(partitions): make this work
+	// EnterpriseMeta is used to filter events in the topic. Only events matching
+	// the partition and namespace will be returned by the subscription.
+	EnterpriseMeta structs.EnterpriseMeta
 	// Token that was used to authenticate the request. If any ACL policy
 	// changes impact the token the subscription will be forcefully closed.
 	Token string
@@ -74,6 +74,19 @@ type SubscribeRequest struct {
 	Index uint64
 }
 
+func (req SubscribeRequest) Subject() Subject {
+	var (
+		partition = req.EnterpriseMeta.PartitionOrDefault()
+		namespace = req.EnterpriseMeta.NamespaceOrDefault()
+		key       = strings.ToLower(req.Key)
+	)
+	return Subject(partition + "/" + namespace + "/" + key)
+}
+
+func (req SubscribeRequest) topicSubject() topicSubject {
+	return topicSubject{req.Topic, req.Subject()}
+}
+
 // newSubscription return a new subscription. The caller is responsible for
 // calling Unsubscribe when it is done with the subscription, to free resources.
 func newSubscription(req SubscribeRequest, item *bufferItem, unsub func()) *Subscription {
@@ -104,11 +117,7 @@ func (s *Subscription) Next(ctx context.Context) (Event, error) {
 		if len(next.Events) == 0 {
 			continue
 		}
-		event := newEventFromBatch(s.req, next.Events)
-		if !event.Payload.MatchesKey(s.req.Key, s.req.Namespace, s.req.Partition) {
-			continue
-		}
-		return event, nil
+		return newEventFromBatch(s.req, next.Events), nil
 	}
 }
 
diff --git a/agent/consul/stream/subscription_test.go b/agent/consul/stream/subscription_test.go
index f9a473c0c8..cf3be6393a 100644
--- a/agent/consul/stream/subscription_test.go
+++ b/agent/consul/stream/subscription_test.go
@@ -6,10 +6,32 @@ import (
 	time "time"
 
 	"github.com/stretchr/testify/require"
+
+	"github.com/hashicorp/consul/agent/structs"
 )
 
 func noopUnSub() {}
 
+func TestSubscription_Subject(t *testing.T) {
+	for desc, tc := range map[string]struct {
+		req SubscribeRequest
+		sub Subject
+	}{
+		"default partition and namespace": {
+			SubscribeRequest{Key: "foo", EnterpriseMeta: structs.EnterpriseMeta{}},
+			"default/default/foo",
+		},
+		"mixed casing": {
+			SubscribeRequest{Key: "BaZ"},
+			"default/default/baz",
+		},
+	} {
+		t.Run(desc, func(t *testing.T) {
+			require.Equal(t, tc.sub, tc.req.Subject())
+		})
+	}
+}
+
 func TestSubscription(t *testing.T) {
 	if testing.Short() {
 		t.Skip("too slow for testing.Short")
@@ -59,10 +81,6 @@ func TestSubscription(t *testing.T) {
 		"Event should have been delivered after short time, took %s", elapsed)
 	require.Equal(t, index, got.Index)
 
-	// Event with wrong key should not be delivered. Deliver a good message right
-	// so we don't have to block test thread forever or cancel func yet.
-	index++
-	publishTestEvent(index, eb, "nope")
 	index++
 	publishTestEvent(index, eb, "test")
 
diff --git a/agent/rpc/subscribe/subscribe.go b/agent/rpc/subscribe/subscribe.go
index 4c7255c620..1a9d0031ac 100644
--- a/agent/rpc/subscribe/subscribe.go
+++ b/agent/rpc/subscribe/subscribe.go
@@ -57,6 +57,10 @@ func (h *Server) Subscribe(req *pbsubscribe.SubscribeRequest, serverStream pbsub
 		return err
 	}
 
+	if req.Key == "" {
+		return status.Error(codes.InvalidArgument, "Key is required")
+	}
+
 	sub, err := h.Backend.Subscribe(toStreamSubscribeRequest(req, entMeta))
 	if err != nil {
 		return err
@@ -89,12 +93,11 @@ func (h *Server) Subscribe(req *pbsubscribe.SubscribeRequest, serverStream pbsub
 
 func toStreamSubscribeRequest(req *pbsubscribe.SubscribeRequest, entMeta structs.EnterpriseMeta) *stream.SubscribeRequest {
 	return &stream.SubscribeRequest{
-		Topic:     req.Topic,
-		Key:       req.Key,
-		Token:     req.Token,
-		Index:     req.Index,
-		Namespace: entMeta.NamespaceOrEmpty(),
-		Partition: entMeta.PartitionOrEmpty(),
+		Topic:          req.Topic,
+		Key:            req.Key,
+		EnterpriseMeta: entMeta,
+		Token:          req.Token,
+		Index:          req.Index,
 	}
 }
 
diff --git a/agent/rpc/subscribe/subscribe_test.go b/agent/rpc/subscribe/subscribe_test.go
index 5508b1571d..0c928b4203 100644
--- a/agent/rpc/subscribe/subscribe_test.go
+++ b/agent/rpc/subscribe/subscribe_test.go
@@ -30,6 +30,33 @@ import (
 	"github.com/hashicorp/consul/types"
 )
 
+func TestServer_Subscribe_KeyIsRequired(t *testing.T) {
+	backend, err := newTestBackend()
+	require.NoError(t, err)
+
+	addr := runTestServer(t, NewServer(backend, hclog.New(nil)))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	t.Cleanup(cancel)
+
+	conn, err := gogrpc.DialContext(ctx, addr.String(), gogrpc.WithInsecure())
+	require.NoError(t, err)
+	t.Cleanup(logError(t, conn.Close))
+
+	client := pbsubscribe.NewStateChangeSubscriptionClient(conn)
+
+	stream, err := client.Subscribe(ctx, &pbsubscribe.SubscribeRequest{
+		Topic: pbsubscribe.Topic_ServiceHealth,
+		Key:   "",
+	})
+	require.NoError(t, err)
+
+	_, err = stream.Recv()
+	require.Error(t, err)
+	require.Equal(t, codes.InvalidArgument.String(), status.Code(err).String())
+	require.Contains(t, err.Error(), "Key is required")
+}
+
 func TestServer_Subscribe_IntegrationWithBackend(t *testing.T) {
 	backend, err := newTestBackend()
 	require.NoError(t, err)
@@ -878,6 +905,8 @@ func assertNoEvents(t *testing.T, chEvents chan eventOrError) {
 
 func logError(t *testing.T, f func() error) func() {
 	return func() {
+		t.Helper()
+
 		if err := f(); err != nil {
 			t.Logf(err.Error())
 		}
diff --git a/proto/pbsubscribe/subscribe.pb.go b/proto/pbsubscribe/subscribe.pb.go
index 65a9ab7d41..98ad79087c 100644
--- a/proto/pbsubscribe/subscribe.pb.go
+++ b/proto/pbsubscribe/subscribe.pb.go
@@ -90,9 +90,8 @@ type SubscribeRequest struct {
 	Topic Topic `protobuf:"varint,1,opt,name=Topic,proto3,enum=subscribe.Topic" json:"Topic,omitempty"`
 	// Key is a topic-specific identifier that restricts the scope of the
 	// subscription to only events pertaining to that identifier. For example,
-	// to receive events for a single service, the service's name is
-	// specified as the key. An empty key indicates that all events in the topic
-	// are of interest.
+	// to receive events for a single service, the service's name is specified
+	// as the key.
 	Key string `protobuf:"bytes,2,opt,name=Key,proto3" json:"Key,omitempty"`
 	// Token is the ACL token to authenticate the request. The token must have
 	// sufficient privileges to read the requested information otherwise events
diff --git a/proto/pbsubscribe/subscribe.proto b/proto/pbsubscribe/subscribe.proto
index 95aac6c299..a860b874bd 100644
--- a/proto/pbsubscribe/subscribe.proto
+++ b/proto/pbsubscribe/subscribe.proto
@@ -51,9 +51,8 @@ message SubscribeRequest {
 
     // Key is a topic-specific identifier that restricts the scope of the
     // subscription to only events pertaining to that identifier. For example,
-    // to receive events for a single service, the service's name is
-    // specified as the key. An empty key indicates that all events in the topic
-    // are of interest.
+    // to receive events for a single service, the service's name is specified
+    // as the key.
     string Key = 2;
 
     // Token is the ACL token to authenticate the request. The token must have

From 2de3a6900fc300d3c0a34d4c98dc146797c7be29 Mon Sep 17 00:00:00 2001
From: Noel Quiles <3746694+EnMod@users.noreply.github.com>
Date: Fri, 28 Jan 2022 14:43:45 -0500
Subject: [PATCH 96/98] website: Add Demandbase tag to consent manager (#12197)

* chore: Add Demandbase tag to consent manager

* fix: Add services to manager options
---
 website/lib/consent-manager-services/index.ts | 15 +++++++++++++++
 website/pages/_app.js                         |  2 ++
 2 files changed, 17 insertions(+)
 create mode 100644 website/lib/consent-manager-services/index.ts

diff --git a/website/lib/consent-manager-services/index.ts b/website/lib/consent-manager-services/index.ts
new file mode 100644
index 0000000000..3a1a65171d
--- /dev/null
+++ b/website/lib/consent-manager-services/index.ts
@@ -0,0 +1,15 @@
+import { ConsentManagerService } from '@hashicorp/react-consent-manager/types'
+
+const localConsentManagerServices: ConsentManagerService[] = [
+  {
+    name: 'Demandbase Tag',
+    description:
+      'The Demandbase tag is a tracking service to identify website visitors and measure interest on our website.',
+    category: 'Analytics',
+    url: 'https://tag.demandbase.com/960ab0a0f20fb102.min.js',
+    async: true,
+  },
+]
+
+export default localConsentManagerServices
+
diff --git a/website/pages/_app.js b/website/pages/_app.js
index b018ace7e1..d4a777fc85 100644
--- a/website/pages/_app.js
+++ b/website/pages/_app.js
@@ -8,6 +8,7 @@ import rivetQuery from '@hashicorp/nextjs-scripts/dato/client'
 import NProgress from '@hashicorp/platform-util/nprogress'
 import { ErrorBoundary } from '@hashicorp/platform-runtime-error-monitoring'
 import createConsentManager from '@hashicorp/react-consent-manager/loader'
+import localConsentManagerServices from 'lib/consent-manager-services'
 import useAnchorLinkAnalytics from '@hashicorp/platform-util/anchor-link-analytics'
 import HashiHead from '@hashicorp/react-head'
 import AlertBanner from '@hashicorp/react-alert-banner'
@@ -18,6 +19,7 @@ import StandardLayout from 'layouts/standard'
 NProgress({ Router })
 const { ConsentManager } = createConsentManager({
   preset: 'oss',
+  otherServices: [...localConsentManagerServices],
 })
 
 export default function App({ Component, pageProps, layoutData }) {

From 66f01733557e74fd816fe73260a9a78732b021ec Mon Sep 17 00:00:00 2001
From: Fulvio <fulviodenza823@gmail.com>
Date: Fri, 28 Jan 2022 21:01:47 +0100
Subject: [PATCH 97/98] URL-encode/decode resource names for HTTP API part 4
 (#12190)

---
 agent/ui_endpoint.go | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/agent/ui_endpoint.go b/agent/ui_endpoint.go
index dd10d5577c..4c6b3e7686 100644
--- a/agent/ui_endpoint.go
+++ b/agent/ui_endpoint.go
@@ -133,7 +133,11 @@ func (s *HTTPHandlers) UINodeInfo(resp http.ResponseWriter, req *http.Request) (
 	}
 
 	// Verify we have some DC, or use the default
-	args.Node = strings.TrimPrefix(req.URL.Path, "/v1/internal/ui/node/")
+	var err error
+	args.Node, err = getPathSuffixUnescaped(req.URL.Path, "/v1/internal/ui/node/")
+	if err != nil {
+		return nil, err
+	}
 	if args.Node == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing node name")
@@ -245,7 +249,11 @@ func (s *HTTPHandlers) UIGatewayServicesNodes(resp http.ResponseWriter, req *htt
 	}
 
 	// Pull out the service name
-	args.ServiceName = strings.TrimPrefix(req.URL.Path, "/v1/internal/ui/gateway-services-nodes/")
+	var err error
+	args.ServiceName, err = getPathSuffixUnescaped(req.URL.Path, "/v1/internal/ui/gateway-services-nodes/")
+	if err != nil {
+		return nil, err
+	}
 	if args.ServiceName == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing gateway name")
@@ -287,7 +295,11 @@ func (s *HTTPHandlers) UIServiceTopology(resp http.ResponseWriter, req *http.Req
 		return nil, err
 	}
 
-	args.ServiceName = strings.TrimPrefix(req.URL.Path, "/v1/internal/ui/service-topology/")
+	var err error
+	args.ServiceName, err = getPathSuffixUnescaped(req.URL.Path, "/v1/internal/ui/service-topology/")
+	if err != nil {
+		return nil, err
+	}
 	if args.ServiceName == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing service name")
@@ -566,7 +578,11 @@ func (s *HTTPHandlers) UIGatewayIntentions(resp http.ResponseWriter, req *http.R
 	}
 
 	// Pull out the service name
-	name := strings.TrimPrefix(req.URL.Path, "/v1/internal/ui/gateway-intentions/")
+	var err error
+	name, err := getPathSuffixUnescaped(req.URL.Path, "/v1/internal/ui/gateway-intentions/")
+	if err != nil {
+		return nil, err
+	}
 	if name == "" {
 		resp.WriteHeader(http.StatusBadRequest)
 		fmt.Fprint(resp, "Missing gateway name")
@@ -647,7 +663,10 @@ func (s *HTTPHandlers) UIMetricsProxy(resp http.ResponseWriter, req *http.Reques
 	// here.
 
 	// Replace prefix in the path
-	subPath := strings.TrimPrefix(req.URL.Path, "/v1/internal/ui/metrics-proxy")
+	subPath, err := getPathSuffixUnescaped(req.URL.Path, "/v1/internal/ui/metrics-proxy")
+	if err != nil {
+		return nil, err
+	}
 
 	// Append that to the BaseURL (which might contain a path prefix component)
 	newURL := cfg.BaseURL + subPath

From 4e013158b311cf567460da40544aeddaa8517001 Mon Sep 17 00:00:00 2001
From: Luke Kysow <1034429+lkysow@users.noreply.github.com>
Date: Fri, 28 Jan 2022 21:44:42 -0800
Subject: [PATCH 98/98] Document new escape tag ability for k8s (#12175)

---
 website/content/docs/k8s/connect/index.mdx | 29 ++++++++++++----------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/website/content/docs/k8s/connect/index.mdx b/website/content/docs/k8s/connect/index.mdx
index 6e825816e7..7d33fbb7df 100644
--- a/website/content/docs/k8s/connect/index.mdx
+++ b/website/content/docs/k8s/connect/index.mdx
@@ -231,29 +231,29 @@ Pod annotations can be used to configure the injection behavior.
   injector's configuration if desired.
 
 - `consul.hashicorp.com/transparent-proxy` - If this is "true", this Pod
-   will run with transparent proxy enabled. This means you can use Kubernetes
-   DNS to access upstream services and all inbound and outbound traffic within
-   the pod is redirected to go through the proxy.
+  will run with transparent proxy enabled. This means you can use Kubernetes
+  DNS to access upstream services and all inbound and outbound traffic within
+  the pod is redirected to go through the proxy.
 
 - `consul.hashicorp.com/transparent-proxy-overwrite-probes` - If this is "true"
-   and transparent proxy is enabled, the Connect injector will overwrite Kubernetes
-   HTTP probes to point to the Envoy proxy.
+  and transparent proxy is enabled, the Connect injector will overwrite Kubernetes
+  HTTP probes to point to the Envoy proxy.
 
 - `consul.hashicorp.com/transparent-proxy-exclude-inbound-ports` - A comma-separated
-   list of inbound ports to exclude from traffic redirection when running in transparent proxy
-   mode.
+  list of inbound ports to exclude from traffic redirection when running in transparent proxy
+  mode.
 
 - `consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs` - A comma-separated
-   list of outbound CIDRs to exclude from traffic redirection when running in transparent proxy
-   mode.
+  list of outbound CIDRs to exclude from traffic redirection when running in transparent proxy
+  mode.
 
 - `consul.hashicorp.com/transparent-proxy-exclude-outbound-ports` - A comma-separated
-   list of outbound ports to exclude from traffic redirection when running in transparent proxy
-   mode.
+  list of outbound ports to exclude from traffic redirection when running in transparent proxy
+  mode.
 
 - `consul.hashicorp.com/transparent-proxy-exclude-uids` - A comma-separated
-   list of additional user IDs to exclude from traffic redirection when running in transparent proxy
-   mode.
+  list of additional user IDs to exclude from traffic redirection when running in transparent proxy
+  mode.
 
 - `consul.hashicorp.com/connect-service` - For pods that accept inbound
   connections, this specifies the name of the service that is being
@@ -338,6 +338,9 @@ Pod annotations can be used to configure the injection behavior.
     consul.hashicorp.com/service-tags: foo,bar,baz
   ```
 
+  If you need your tag to have a comma in it you can escape the comma with `\,`. For example,
+  `consul.hashicorp.com/service-tags: foo\,bar\,baz` will become the single tag `foo,bar,baz`.
+
 - `consul.hashicorp.com/service-meta-<YOUR_KEY>` - Set Consul meta key/value
   pairs that will be applied to the Consul service and its sidecar.
   The key will be what comes after `consul.hashicorp.com/service-meta-`, e.g.