diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx
index 6be29df290..4eb07f7ebc 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.
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.
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.
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.
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: ',
+ 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.
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: ',
- 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: ',
+ description: 'TLS configuration for this service.',
+ children: [
+ {
+ name: 'SDS',
+ type: 'SDSConfig: ',
+ 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: ',
+ 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.
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.
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: ',
+ 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.
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 ec969d9a63..83c6d17249 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.
+
+
+
+
+## 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 = <