From 7573b804544d9e542d18ca48bf0944952b99906a Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 18 Jan 2022 15:40:43 -0800 Subject: [PATCH] applied final feedback --- .../config-entries/ingress-gateway.mdx | 115 +++++++++--------- 1 file changed, 58 insertions(+), 57 deletions(-) diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index a14a364f34..21f14daea8 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -8,7 +8,7 @@ description: >- # Ingress Gateway -This topic provides reference information for the `ingress-gateway` configuration entry. +This topic provides reference information for the `ingress-gateway` configuration entry. ## Introduction @@ -20,20 +20,20 @@ For other platforms, see [Ingress Gateway](/docs/connect/ingress-gateway). ## Requirements -* Consul versions 1.8.4+ is required to use the `IngressGateway` custom resource on Kubernetes. -* Consul versions 1.8.0+ is required to use the `ingress-gateway` custom resource on all other platforms. +- Consul versions 1.8.4+ is required to use the `IngressGateway` custom resource on Kubernetes. +- Consul versions 1.8.0+ is required to use the `ingress-gateway` custom resource on all other platforms. ## Usage 1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). -1. Specify the `ingress-gateway` (`IngressGateway`) configuration in the agent configuration file (see [config_entries](/docs/agent/options#config_entries)) as described in [Configuration](#configuration). -1. Apply the configuration using one of the following methods: - * Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. - * Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. +1. Create a file containing the configuration entry settings (see [Configuration](#configuration)). +1. Apply the configuration settings using one of the following methods: + - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. + - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. -## Configuration +## Configuration -Use the following syntax to configure an ingress gateway. +Use the following syntax to configure an ingress gateway. @@ -153,11 +153,12 @@ spec: ] } ``` + - + -Refer to the [Available Fields](#available-fields) section for complete information about all ingress gateway configuration entry options and to the [Example Configurations](#example-configurations) section for example use-cases. +Refer to the [Available Fields](#available-fields) section for complete information about all ingress gateway configuration entry options and to the [Example Configurations](#example-configurations) section for example use-cases. ### Scope @@ -202,7 +203,6 @@ The following examples describe possible use-cases for ingress gateway configura The following example sets up a TCP listener on an ingress gateway named `us-east-ingress` to proxy traffic to the `db` service. The Consul Enterprise version also posits the gateway listener inside the `default` [namespace](/docs/enterprise/namespaces) and the `team-frontend` [admin partition](/docs/enterprise/admin-partitions): - @@ -326,14 +326,14 @@ spec: In the following example, two listeners are configured on an ingress gateway named `us-east-ingress`: -* The first listener is configured to listen on port `8080` and uses a wildcard (`*`) to proxy traffic to all services in the datacenter. -* The second listener exposes the `api` and `web` services on port `4567` at user-provided hosts. -* TLS is enabled on every listener. +- The first listener is configured to listen on port `8080` and uses a wildcard (`*`) to proxy traffic to all services in the datacenter. +- The second listener exposes the `api` and `web` services on port `4567` at user-provided hosts. +- TLS is enabled on every listener. The Consul Enterprise version implements the following additional configurations: -* The ingress gateway is set up in the `default` [namespace](/docs/enterprise/namespaces) and proxies traffic to all services in the `frontend` namespace. -* The `api` and `web` services are proxied to team-specific [admin partitions](/docs/enterprise/admin-partitions): +- The ingress gateway is set up in the `default` [namespace](/docs/enterprise/namespaces) and proxies traffic to all services in the `frontend` namespace. +- The `api` and `web` services are proxied to team-specific [admin partitions](/docs/enterprise/admin-partitions): @@ -557,7 +557,7 @@ spec: The following example sets up an HTTP listener on an ingress gateway named `us-east-ingress` to proxy traffic to a virtual service named `api`. In the Consul Enterprise version, `us-east-ingress` is set up in the `default` namespace and `default` partition. -In this use-case, internal-only debug headers should be stripped before responding to external clients. +In this use-case, internal-only debug headers should be stripped before responding to external clients. Requests to internal services should also be labelled to indicate which gateway they came through. @@ -693,7 +693,7 @@ spec: { "Name": "api", "Namespace": "frontend", - "RequestHeaders": { + "RequestHeaders": { "Add": { "x-gateway": "us-east-ingress" } @@ -899,7 +899,7 @@ spec: ## Available Fields -You can specify the following parameters to configure ingress gateway configuration entries. +You can specify the following parameters to configure ingress gateway configuration entries. ', - 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.

SDS properties defined in this field are 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.

SDS properties defined in this field are used as defaults for all listeners on the gateway.', children: [ { name: 'ClusterName', type: 'string', - 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).", + 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: "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.", + 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.', }, ], }, @@ -1094,34 +1091,36 @@ You can specify the following parameters to configure ingress gateway configurat 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: `Defines a set of parameters that configures the SDS source for the certificate for this specific service. + name: 'TLS', + yaml: false, + type: 'ServiceTLSConfig: ', + description: 'TLS configuration for this service.', + children: [ + { + name: 'SDS', + type: 'SDSConfig: ', + 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\`. 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: [ - { - 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.", + 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', @@ -1142,17 +1141,20 @@ You can specify the following parameters to configure ingress gateway configurat { name: 'SDS', type: 'SDSConfig: ', - 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.

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.

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).", + 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.", + description: + 'The SDS resource name to request when fetching the certificate from the SDS service.', }, ], }, @@ -1162,4 +1164,3 @@ You can specify the following parameters to configure ingress gateway configurat }, ]} /> -