From c1b9601a9460c1883f5c38dc8b22b94150901c81 Mon Sep 17 00:00:00 2001
From: Paul Banks <pbanks@hashicorp.com>
Date: Tue, 28 Sep 2021 13:31:42 +0100
Subject: [PATCH 1/4] Add documentation for SDS support in ingress gateways.

---
 .../config-entries/ingress-gateway.mdx        |  90 +++++++-
 .../docs/connect/gateways/ingress-gateway.mdx | 209 ++++++++++++++++++
 2 files changed, 295 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx
index 6be29df29..4eb07f7eb 100644
--- a/website/content/docs/connect/config-entries/ingress-gateway.mdx
+++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx
@@ -810,11 +810,29 @@ spec:
           type: 'bool: false',
           description: {
             hcl:
-              "Set this configuration to enable TLS for every listener on the gateway.<br><br>If TLS is enabled, then each host defined in the `Host` field will be added as a DNSSAN to the gateway's x509 certificate.",
+              "Set this configuration 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.",
             yaml:
-              "Set this configuration to enable TLS for every listener on the gateway.<br><br>If TLS is enabled, then each host defined in the `host` field will be added as a DNSSAN to the gateway's x509 certificate.",
+              "Set this configuration 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: 'SDS',
+          yaml: false,
+          type: 'SDSConfig: <optional>',
+          description: "Configures the gateway to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all listeners on the gateway.",
+          children: [
+            {
+              name: 'ClusterName',
+              type: 'string',
+              description: "The SDS cluster name to connect to to retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
+            },
+            {
+              name: 'CertResource',
+              type: 'string',
+              description: "The SDS resource name to request when fetching the certificate from the SDS service. Setting this causes all listeners to be served exclusively over TLS with this certificate unless overridden by listener-specific TLS configuration.",
+            },
+          ],
+        },
       ],
     },
     {
@@ -843,8 +861,9 @@ spec:
         {
           name: 'Services',
           type: 'array<IngressService>: <optional>',
-          description:
-            'A list of services to be exposed via this listener. For `tcp` listeners, only a single service is allowed.',
+          description: `A list of services to be exposed via this listener.
+            For \`tcp\` listeners, only a single service is allowed.
+            Each service must have a unique name (and namespace in Enterprise).`,
           children: [
             {
               name: 'Name',
@@ -896,6 +915,69 @@ spec:
               that will be applied to responses from this service.
               This cannot be used with a \`tcp\` listener.`,
             },
+            {
+          name: 'TLS',
+          yaml: false,
+          type: 'ServiceTLSConfig: <optional>',
+          description: 'TLS configuration for this service.',
+          children: [
+            {
+              name: 'SDS',
+              type: 'SDSConfig: <optional>',
+              description: `Configures the SDS source for the certificate for this specific service.
+                  At least one custom host must be specified in \`Hosts\`.
+                  This certificate will be served to all requests identifying one of the
+                  \`Hosts\` values in the TLS Server Name Indication (SNI) header.`,
+              children: [
+                {
+                  name: 'ClusterName',
+                  type: 'string',
+                  description: "The SDS cluster name to connect to to retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
+                },
+                {
+                  name: 'CertResource',
+                  type: 'string',
+                  description: "The SDS resource name to request when fetching the certificate from the SDS service.",
+                },
+              ],
+            },
+          ],
+        },
+          ],
+        },
+        {
+          name: 'TLS',
+          yaml: false,
+          type: 'TLSConfig: <optional>',
+          description: 'TLS configuration for this listener.',
+          children: [
+            {
+              name: 'Enabled',
+              type: 'bool: false',
+              description: {
+                hcl:
+                  "Set this configuration 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.",
+                yaml:
+                  "Set this configuration to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in the `hosta` 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.",
+              },
+            },
+            {
+              name: 'SDS',
+              type: 'SDSConfig: <optional>',
+              description: "Configures the listener to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all services on this listener.",
+              children: [
+                {
+                  name: 'ClusterName',
+                  type: 'string',
+                  description: "The SDS cluster name to connect to to retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
+                },
+                {
+                  name: 'CertResource',
+                  type: 'string',
+                  description: "The SDS resource name to request when fetching the certificate from the SDS service.",
+                },
+              ],
+            },
           ],
         },
       ],
diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx
index ec969d9a6..83c6d1724 100644
--- a/website/content/docs/connect/gateways/ingress-gateway.mdx
+++ b/website/content/docs/connect/gateways/ingress-gateway.mdx
@@ -69,3 +69,212 @@ must also provide `agent:read` for its node's name in order to discover the agen
 ~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
 across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different
 sets of services within their datacenter then the ingress gateways **must** be registered with different names.
+
+<!-- Add a "permalink" anchor here since this title is long and may be edited
+     but we need to deep-link to it elsewhere -->
+<a name="sds"></a>
+
+## Custom TLS Certificates via Secret Discovery Service (SDS)
+
+~> **Advanced Topic!** This is a low-level feature designed for developers
+building integrations with custom TLS management solutions.
+
+Consul 1.11 added support for Ingress Gateways to serve TLS certificates to
+inbound traffic that are sourced from an external service. The external service
+must implement Envoy's [gRPC Secret Discovery
+Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret)
+(or SDS) API.
+
+The steps below are necessary to fully configure an Ingress Gateway with TLS
+certificates from an SDS source. They assume the operator is familiar with Envoy
+ configuration and the SDS protocol.
+
+### 1. Configure Static SDS Cluster(s).
+
+Each Ingress Gateway Envoy instance must have one or more additional [static
+clusters](/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) defined
+when registering the ingress gateway to specify how to connect to the external
+service. This requires a manual registration of the Ingress Gateway proxy rather
+than relying on `-register` flag to `consul connect envoy -gateway=ingress`.
+
+The cluster(s) must provide connection information and any necessary
+authentication information such as mTLS credentials.
+
+In this example we will show:
+ - A DNS name to discover the SDS service addresses
+ - Local certificate files for TLS client authentication with the SDS server
+   (the certificates are assumed to be created and managed by some other
+   process)
+
+#### 1.1 Registering the Proxy Service
+
+The following Proxy Service Definition defines the bootstrap overrides needed to
+add this configuration to Envoy when it starts. With this TLS configuration,
+Envoy will detect changes to the certificate and key files on disk so an
+external process may maintain and rotate them without needing an Envoy restart.
+
+```hcl
+// public-ingress.hcl
+Services {
+  Name = "public-ingress"
+  Kind = "ingress-gateway"
+
+  Proxy {
+    Config {
+      envoy_extra_static_clusters_json = <<EOF
+{
+  "name": "sds-cluster",
+  "connect_timeout": "5s",
+  "http2_protocol_options": {},
+  "type": "LOGICAL_DNS",
+  "transport_socket": {
+    "name":"tls",
+    "typed_config": {
+      "@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
+      "common_tls_context":{
+        "tls_certificate_sds_secret_configs": [
+          {
+            "name":"tls_sds",
+            "sds_config":{
+              "path":"/certs/sds-auth-cert.json"
+            }
+          }
+        ],
+        "validation_context_sds_secret_config": {
+          "name":"validation_context_sds",
+          "sds_config":{
+              "path":"/certs/sds-validation.json"
+          }
+        }
+      }
+    }
+  },
+  "load_assignment": {
+    "cluster_name": "sds-cluster",
+    "endpoints": [
+      {
+        "lb_endpoints": [
+          {
+            "endpoint": {
+              "address": {
+                "socket_address": {
+                  "address": "sds-server.svc.cluster.local",
+                  "port_value": 8080,
+                }
+              }
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+    }
+  }
+}
+```
+
+**Run `consul services register public-ingress.hcl`** to create the
+registration. This must be run on the node where the Envoy proxy is going to run
+to register the proxy with the local Consul agent.
+
+#### 1.2 Setup TLS Client Authentication for SDS
+
+This configuration relies on files like the following being present on disk
+where the Envoy proxy will run, along with the actual certificates and keys
+referenced.
+
+ * `sds-client-auth.{crt,key}` are the PEM-encoded certificate and key
+files to be used for TLS Client Authentication with the SDS service.
+ * `sds-ca.crt` is the Certificate Authority certificate used to validate the the
+SDS server's TLS credentials.
+
+Please refer to [Envoy's
+documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap)
+for more details on this configuration and other possible authentication
+options.
+
+```json
+// /certs/sds-auth-cert.json
+{
+  "resources": [
+    {
+      "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
+      "name": "tls_sds",
+      "tls_certificate": {
+        "certificate_chain": {
+          "filename": "/certs/sds-client-auth.crt"
+        },
+        "private_key": {
+          "filename": "/certs/sds-client-auth.key"
+        }
+      }
+    }
+  ]
+}
+```
+```json
+// /certs/sds-validation.json
+{
+  "resources": [
+    {
+      "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
+      "name": "validation_context_sds",
+      "validation_context": {
+        "trusted_ca": {
+          "filename": "/certs/sds-ca.crt"
+        }
+      }
+    }
+  ]
+}
+```
+
+#### 1.3 Start Envoy
+
+**Start Envoy** with:
+
+```bash
+$ consul connect envoy -gateway=ingress -service public-ingress
+```
+
+### 2. Configure the Ingress Gateway to use certificates from SDS
+
+SDS certificates may now be configured in the `ingress-gateway` Config Entry.
+
+The following example shows a single default certificate and key being used for
+all listeners.
+
+```hcl
+// public-ingress-cfg.hcl
+Kind = "ingress-gateway"
+Name = "public-ingress"
+
+TLS {
+  SDS {
+    # This must match the name of the static cluster from step #1
+    ClusterName = "sds-cluster"
+    # This is the name of the certificate resource to load.
+    CertResource = "example.com-public-cert"
+  }
+}
+
+Listeners = [
+  {
+    Port = 8443
+    Protocol = "http"
+    Services = ["*"]
+  }
+]
+
+```
+
+Run `consul config write public-ingress-cfg.hcl` to write this configuration.
+
+The Envoy instance will now start a listener on port 8443 and attempt to fetch
+the TLS certificate named from the SDS server.
+
+Separate certificates may be loaded per listener or per-service with hostname
+(SNI) switching. See the [Config Entry
+reference](/docs/connect/config-entries/ingress-gateway) for more details.
\ No newline at end of file

From d149311ceee85b1818a2ad6134dfb098807cfbbe Mon Sep 17 00:00:00 2001
From: Paul Banks <banks@banksco.de>
Date: Tue, 28 Sep 2021 17:22:44 +0100
Subject: [PATCH 2/4] Apply suggestions from code review

Co-authored-by: mrspanishviking <kcardenas@hashicorp.com>
---
 .../docs/connect/config-entries/ingress-gateway.mdx        | 2 +-
 website/content/docs/connect/gateways/ingress-gateway.mdx  | 7 +++----
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx
index 4eb07f7eb..0e8ff785b 100644
--- a/website/content/docs/connect/config-entries/ingress-gateway.mdx
+++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx
@@ -819,7 +819,7 @@ spec:
           name: 'SDS',
           yaml: false,
           type: 'SDSConfig: <optional>',
-          description: "Configures the gateway to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all listeners on the gateway.",
+          description: "Configures the gateway to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all listeners on the gateway.",
           children: [
             {
               name: 'ClusterName',
diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx
index 83c6d1724..017cb928b 100644
--- a/website/content/docs/connect/gateways/ingress-gateway.mdx
+++ b/website/content/docs/connect/gateways/ingress-gateway.mdx
@@ -68,7 +68,7 @@ must also provide `agent:read` for its node's name in order to discover the agen
 
 ~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
 across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different
-sets of services within their datacenter then the ingress gateways **must** be registered with different names.
+sets of services within their datacenter, then the ingress gateways **must** be registered with different names.
 
 <!-- Add a "permalink" anchor here since this title is long and may be edited
      but we need to deep-link to it elsewhere -->
@@ -76,7 +76,7 @@ sets of services within their datacenter then the ingress gateways **must** be r
 
 ## Custom TLS Certificates via Secret Discovery Service (SDS)
 
-~> **Advanced Topic!** This is a low-level feature designed for developers
+~> **Advanced Topic** This is a low-level feature designed for developers
 building integrations with custom TLS management solutions.
 
 Consul 1.11 added support for Ingress Gateways to serve TLS certificates to
@@ -176,8 +176,7 @@ EOF
 ```
 
 **Run `consul services register public-ingress.hcl`** to create the
-registration. This must be run on the node where the Envoy proxy is going to run
-to register the proxy with the local Consul agent.
+registration. The command must be executed on the node where the Envoy proxy will register the proxy with the local Consul agent.
 
 #### 1.2 Setup TLS Client Authentication for SDS
 

From 15ece49126f0bf68b6a29ac8eacb28ce843d2286 Mon Sep 17 00:00:00 2001
From: Paul Banks <banks@banksco.de>
Date: Wed, 29 Sep 2021 15:55:32 +0100
Subject: [PATCH 3/4] Apply suggestions from code review

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---
 .../config-entries/ingress-gateway.mdx        | 20 +++++++++----------
 .../docs/connect/gateways/ingress-gateway.mdx | 16 ++++++---------
 2 files changed, 16 insertions(+), 20 deletions(-)

diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx
index 0e8ff785b..48e021372 100644
--- a/website/content/docs/connect/config-entries/ingress-gateway.mdx
+++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx
@@ -810,26 +810,26 @@ spec:
           type: 'bool: false',
           description: {
             hcl:
-              "Set this configuration 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.",
+              "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.",
             yaml:
-              "Set this configuration 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.",
+              "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: 'SDS',
           yaml: false,
           type: 'SDSConfig: <optional>',
-          description: "Configures the gateway to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all listeners on the gateway.",
+          description: "Defines a set of parameters that configures the gateway to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ingress-gateway#sds) for more details on usage.<br><br>SDS properties defined in this field are used as defaults for all listeners on the gateway.",
           children: [
             {
               name: 'ClusterName',
               type: 'string',
-              description: "The SDS cluster name to connect to to retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
+              description: "Specifies the name of the SDS cluster from which Consul should retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
             },
             {
               name: 'CertResource',
               type: 'string',
-              description: "The SDS resource name to request when fetching the certificate from the SDS service. Setting this causes all listeners to be served exclusively over TLS with this certificate unless overridden by listener-specific TLS configuration.",
+              description: "Specifies an SDS resource name. Consul will request the SDS resource name when fetching the certificate from the SDS service. Setting this causes all listeners to be served exclusively over TLS with this certificate unless overridden by listener-specific TLS configuration.",
             },
           ],
         },
@@ -924,9 +924,9 @@ spec:
             {
               name: 'SDS',
               type: 'SDSConfig: <optional>',
-              description: `Configures the SDS source for the certificate for this specific service.
+              description: `Defines a set of parameters that configures the SDS source for the certificate for this specific service.
                   At least one custom host must be specified in \`Hosts\`.
-                  This certificate will be served to all requests identifying one of the
+                  The certificate retrieved from SDS will be served for all requests identifying one of the
                   \`Hosts\` values in the TLS Server Name Indication (SNI) header.`,
               children: [
                 {
@@ -956,15 +956,15 @@ spec:
               type: 'bool: false',
               description: {
                 hcl:
-                  "Set this configuration 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.",
                 yaml:
-                  "Set this configuration to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in the `hosta` 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.",
               },
             },
             {
               name: 'SDS',
               type: 'SDSConfig: <optional>',
-              description: "Configures the listener to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all services on this listener.",
+              description: "Defines a set of parameters that configures the listener to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all services on this listener.",
               children: [
                 {
                   name: 'ClusterName',
diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx
index 017cb928b..f8791638b 100644
--- a/website/content/docs/connect/gateways/ingress-gateway.mdx
+++ b/website/content/docs/connect/gateways/ingress-gateway.mdx
@@ -85,17 +85,13 @@ must implement Envoy's [gRPC Secret Discovery
 Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret)
 (or SDS) API.
 
-The steps below are necessary to fully configure an Ingress Gateway with TLS
-certificates from an SDS source. They assume the operator is familiar with Envoy
- configuration and the SDS protocol.
+The following procedure describes how to configure an ingress gateway with TLS certificates from an SDS source. The instructions assume that you are familiar with Envoy configuration and the SDS protocol.
 
-### 1. Configure Static SDS Cluster(s).
+### 1. Configure Static SDS Cluster(s)
 
-Each Ingress Gateway Envoy instance must have one or more additional [static
-clusters](/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) defined
-when registering the ingress gateway to specify how to connect to the external
-service. This requires a manual registration of the Ingress Gateway proxy rather
-than relying on `-register` flag to `consul connect envoy -gateway=ingress`.
+Each Envoy proxy that makes up this Ingress Gateway must define one or more additional [static
+clusters](/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) when registering. These additional clusters define how Envoy should connect to the required SDS service(s). Defining extra clusters in Envoy's bootstrap configuration requires a manual registration of the Ingress Gateway with Consul proxy.
+It's not possible to use the `-register` flag with `consul connect envoy -gateway=ingress` to automatically register the proxy in this case.
 
 The cluster(s) must provide connection information and any necessary
 authentication information such as mTLS credentials.
@@ -238,7 +234,7 @@ options.
 $ consul connect envoy -gateway=ingress -service public-ingress
 ```
 
-### 2. Configure the Ingress Gateway to use certificates from SDS
+### 2. Configure the Ingress Gateway to Use Certificates from SDS
 
 SDS certificates may now be configured in the `ingress-gateway` Config Entry.
 

From 5015e9a733f3e6dc8826164762eaf281ae2b7d53 Mon Sep 17 00:00:00 2001
From: Paul Banks <pbanks@hashicorp.com>
Date: Fri, 8 Oct 2021 12:19:45 +0100
Subject: [PATCH 4/4] Reformatting suggestions from review

---
 .../config-entries/ingress-gateway.mdx        |   3 +-
 .../docs/connect/gateways/ingress-gateway.mdx | 258 +++++++++---------
 2 files changed, 135 insertions(+), 126 deletions(-)

diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx
index 48e021372..cdfe9e6c7 100644
--- a/website/content/docs/connect/config-entries/ingress-gateway.mdx
+++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx
@@ -863,7 +863,8 @@ spec:
           type: 'array<IngressService>: <optional>',
           description: `A list of services to be exposed via this listener.
             For \`tcp\` listeners, only a single service is allowed.
-            Each service must have a unique name (and namespace in Enterprise).`,
+            Each service must have a unique name. A namespace is also required for
+            Consul Enterprise.`,
           children: [
             {
               name: 'Name',
diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx
index f8791638b..50d654233 100644
--- a/website/content/docs/connect/gateways/ingress-gateway.mdx
+++ b/website/content/docs/connect/gateways/ingress-gateway.mdx
@@ -76,10 +76,10 @@ sets of services within their datacenter, then the ingress gateways **must** be
 
 ## Custom TLS Certificates via Secret Discovery Service (SDS)
 
-~> **Advanced Topic** This is a low-level feature designed for developers
-building integrations with custom TLS management solutions.
+~> **Advanced Topic:** This topic describes a low-level feature designed for
+developers building integrations with custom TLS management solutions.
 
-Consul 1.11 added support for Ingress Gateways to serve TLS certificates to
+Consul 1.11 added support for ingress gateways to serve TLS certificates to
 inbound traffic that are sourced from an external service. The external service
 must implement Envoy's [gRPC Secret Discovery
 Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret)
@@ -87,7 +87,7 @@ Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secr
 
 The following procedure describes how to configure an ingress gateway with TLS certificates from an SDS source. The instructions assume that you are familiar with Envoy configuration and the SDS protocol.
 
-### 1. Configure Static SDS Cluster(s)
+### Configure Static SDS Cluster(s)
 
 Each Envoy proxy that makes up this Ingress Gateway must define one or more additional [static
 clusters](/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) when registering. These additional clusters define how Envoy should connect to the required SDS service(s). Defining extra clusters in Envoy's bootstrap configuration requires a manual registration of the Ingress Gateway with Consul proxy.
@@ -96,145 +96,153 @@ It's not possible to use the `-register` flag with `consul connect envoy -gatewa
 The cluster(s) must provide connection information and any necessary
 authentication information such as mTLS credentials.
 
-In this example we will show:
+The following example will demonstrate how to use:
  - A DNS name to discover the SDS service addresses
- - Local certificate files for TLS client authentication with the SDS server
-   (the certificates are assumed to be created and managed by some other
-   process)
+ - Local certificate files for TLS client authentication with the SDS server.
+   The certificates are assumed to be created and managed by some other
+   process.
 
-#### 1.1 Registering the Proxy Service
+ 1. **Register the proxy service.**
 
-The following Proxy Service Definition defines the bootstrap overrides needed to
-add this configuration to Envoy when it starts. With this TLS configuration,
-Envoy will detect changes to the certificate and key files on disk so an
-external process may maintain and rotate them without needing an Envoy restart.
+    The following Proxy Service Definition defines the additional cluster
+    configuration that will be provided to Envoy when it starts. With this TLS
+    configuration, Envoy will detect changes to the certificate and key files on
+    disk so an external process may maintain and rotate them without needing an
+    Envoy restart.
 
-```hcl
-// public-ingress.hcl
-Services {
-  Name = "public-ingress"
-  Kind = "ingress-gateway"
+    ```hcl
+    // public-ingress.hcl
+    Services {
+      Name = "public-ingress"
+      Kind = "ingress-gateway"
 
-  Proxy {
-    Config {
-      envoy_extra_static_clusters_json = <<EOF
-{
-  "name": "sds-cluster",
-  "connect_timeout": "5s",
-  "http2_protocol_options": {},
-  "type": "LOGICAL_DNS",
-  "transport_socket": {
-    "name":"tls",
-    "typed_config": {
-      "@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
-      "common_tls_context":{
-        "tls_certificate_sds_secret_configs": [
-          {
-            "name":"tls_sds",
-            "sds_config":{
-              "path":"/certs/sds-auth-cert.json"
-            }
-          }
-        ],
-        "validation_context_sds_secret_config": {
-          "name":"validation_context_sds",
-          "sds_config":{
-              "path":"/certs/sds-validation.json"
-          }
-        }
-      }
-    }
-  },
-  "load_assignment": {
-    "cluster_name": "sds-cluster",
-    "endpoints": [
-      {
-        "lb_endpoints": [
-          {
-            "endpoint": {
-              "address": {
-                "socket_address": {
-                  "address": "sds-server.svc.cluster.local",
-                  "port_value": 8080,
+      Proxy {
+        Config {
+          envoy_extra_static_clusters_json = <<EOF
+    {
+      "name": "sds-cluster",
+      "connect_timeout": "5s",
+      "http2_protocol_options": {},
+      "type": "LOGICAL_DNS",
+      "transport_socket": {
+        "name":"tls",
+        "typed_config": {
+          "@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
+          "common_tls_context":{
+            "tls_certificate_sds_secret_configs": [
+              {
+                "name":"tls_sds",
+                "sds_config":{
+                  "path":"/certs/sds-auth-cert.json"
                 }
               }
+            ],
+            "validation_context_sds_secret_config": {
+              "name":"validation_context_sds",
+              "sds_config":{
+                  "path":"/certs/sds-validation.json"
+              }
             }
           }
+        }
+      },
+      "load_assignment": {
+        "cluster_name": "sds-cluster",
+        "endpoints": [
+          {
+            "lb_endpoints": [
+              {
+                "endpoint": {
+                  "address": {
+                    "socket_address": {
+                      "address": "sds-server.svc.cluster.local",
+                      "port_value": 8080,
+                    }
+                  }
+                }
+              }
+            ]
+          }
         ]
       }
-    ]
-  }
-}
-EOF
     }
-  }
-}
-```
-
-**Run `consul services register public-ingress.hcl`** to create the
-registration. The command must be executed on the node where the Envoy proxy will register the proxy with the local Consul agent.
-
-#### 1.2 Setup TLS Client Authentication for SDS
-
-This configuration relies on files like the following being present on disk
-where the Envoy proxy will run, along with the actual certificates and keys
-referenced.
-
- * `sds-client-auth.{crt,key}` are the PEM-encoded certificate and key
-files to be used for TLS Client Authentication with the SDS service.
- * `sds-ca.crt` is the Certificate Authority certificate used to validate the the
-SDS server's TLS credentials.
-
-Please refer to [Envoy's
-documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap)
-for more details on this configuration and other possible authentication
-options.
-
-```json
-// /certs/sds-auth-cert.json
-{
-  "resources": [
-    {
-      "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
-      "name": "tls_sds",
-      "tls_certificate": {
-        "certificate_chain": {
-          "filename": "/certs/sds-client-auth.crt"
-        },
-        "private_key": {
-          "filename": "/certs/sds-client-auth.key"
+    EOF
         }
       }
     }
-  ]
-}
-```
-```json
-// /certs/sds-validation.json
-{
-  "resources": [
+    ```
+
+ 1. **Issue the following command to create the registration.**
+
+    ```
+    consul services register public-ingress.hcl
+    ```
+
+    The command must be executed against the Consul agent on the Envoy proxy's node.
+
+#### Setup TLS Client Authentication for SDS
+
+Configuration files similar to the following examples must be available on the
+disk where the Envoy proxy will run. The actual certificates and keys referenced
+in the configuration files must also be present.
+
+ 1. **Configure TLS client authentication for SDS.**
+ 
+    The certificates and keys must be saved to the same disk where the Envoy
+    proxy will run. The following example files reference the PEM-encoded
+    certificate and key files to be used for TLS Client Authentication with the
+    SDS service (`sds-client-auth.{crt,key}`) and the certificate authority
+    certificate used to validate the SDS server's TLS credentials
+    (`sds-ca.crt`).
+    
+    Refer to [Envoy's documentation]
+    https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap) for
+    more details on this configuration and other possible authentication
+    options.
+
+    ```json
+    // /certs/sds-auth-cert.json
     {
-      "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
-      "name": "validation_context_sds",
-      "validation_context": {
-        "trusted_ca": {
-          "filename": "/certs/sds-ca.crt"
+      "resources": [
+        {
+          "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
+          "name": "tls_sds",
+          "tls_certificate": {
+            "certificate_chain": {
+              "filename": "/certs/sds-client-auth.crt"
+            },
+            "private_key": {
+              "filename": "/certs/sds-client-auth.key"
+            }
+          }
         }
-      }
+      ]
     }
-  ]
-}
-```
+    ```
+    ```json
+    // /certs/sds-validation.json
+    {
+      "resources": [
+        {
+          "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
+          "name": "validation_context_sds",
+          "validation_context": {
+            "trusted_ca": {
+              "filename": "/certs/sds-ca.crt"
+            }
+          }
+        }
+      ]
+    }
+    ```
 
-#### 1.3 Start Envoy
+ 1. **Issue the following command to start Envoy.**
 
-**Start Envoy** with:
+    ```bash
+    $ consul connect envoy -gateway=ingress -service public-ingress
+    ```
 
-```bash
-$ consul connect envoy -gateway=ingress -service public-ingress
-```
-
-### 2. Configure the Ingress Gateway to Use Certificates from SDS
+### Configure the Ingress Gateway to Use Certificates from SDS
 
 SDS certificates may now be configured in the `ingress-gateway` Config Entry.
 
@@ -265,10 +273,10 @@ Listeners = [
 
 ```
 
-Run `consul config write public-ingress-cfg.hcl` to write this configuration.
+ 1. **Run `consul config write public-ingress-cfg.hcl` to write this configuration.**
 
-The Envoy instance will now start a listener on port 8443 and attempt to fetch
-the TLS certificate named from the SDS server.
+    The Envoy instance will now start a listener on port 8443 and attempt to fetch
+    the TLS certificate named from the SDS server.
 
 Separate certificates may be loaded per listener or per-service with hostname
 (SNI) switching. See the [Config Entry