diff --git a/website/content/api-docs/agent/service.mdx b/website/content/api-docs/agent/service.mdx index acaa2e8d0f..b17348fda3 100644 --- a/website/content/api-docs/agent/service.mdx +++ b/website/content/api-docs/agent/service.mdx @@ -630,12 +630,12 @@ The `/agent/service/register` endpoint supports camel case and _snake case_ for - `Port` `(int: 0)` - Specifies the port of the service. -- `Kind` `(string: "")` - The kind of service. Defaults to "" which is a - typical Consul service. This value may also be "connect-proxy" for - [service mesh](/consul/docs/connect) proxies representing another service, - "mesh-gateway" for instances of a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration), - "terminating-gateway" for instances of a [terminating gateway](/consul/docs/connect/gateways/terminating-gateway), - or "ingress-gateway" for instances of a [ingress gateway](/consul/docs/connect/gateways/ingress-gateway). +- `Kind` `(string: "")` - The kind of service. Defaults to `""`, which is a + typical Consul service. You can specify the following values: + - `"connect-proxy"` for [service mesh](/consul/docs/connect) proxies representing another service + - `"mesh-gateway"` for instances of a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) + - `"terminating-gateway"` for instances of a [terminating gateway](/consul/docs/connect/gateways/terminating-gateway) + - `"ingress-gateway"` for instances of an [ingress gateway](/consul/docs/connect/gateways/ingress-gateway) - `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a service mesh proxy instance. This is only valid if `Kind` defines a proxy or gateway. diff --git a/website/content/commands/connect/envoy.mdx b/website/content/commands/connect/envoy.mdx index a8f70c291d..bb2cc5d77e 100644 --- a/website/content/commands/connect/envoy.mdx +++ b/website/content/commands/connect/envoy.mdx @@ -165,11 +165,9 @@ compatibility with Envoy and prevent potential issues. Default is `false`. If Envoy is configured as a terminating or mesh gateway, traffic from services within the mesh will be received at the specified IP and port. - If Envoy is configured as an ingress gateway, a `/ready` HTTP endpoint will be - instantiated at the specified IP and port. Consul uses `/ready` HTTP endpoints - to check gateway health. The specified IP will also be used by the ingress - gateway when instantiating user-defined listeners configured in the - [ingress gateway](/consul/docs/connect/gateways/ingress-gateway) configuration entry. + If Envoy is configured as an ingress gateway, Consul instantiates a `/ready` HTTP endpoint at the specified IP and port. Consul uses `/ready` HTTP endpoints + to check gateway health. Ingress gateways also use the specified IP when instantiating user-defined listeners configured in the + [ingress gateway configuration entry](/consul/docs/connect/config-entries/ingress-gateway). ~> **Note**: Ensure that user-defined ingress gateway listeners use a different port than the port specified in `-address` so that they do not diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index 07f01a03b1..dc36c9fb0b 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -1,567 +1,1501 @@ --- layout: docs -page_title: Ingress Gateway - Configuration Entry Reference +page_title: Ingress gateway configuration entry reference description: >- - The ingress gateway configuration entry kind defines behavior to secure incoming communication between the service mesh and external sources. Use the reference guide to learn about `""ingress-gateway""` config entry parameters and exposing TCP and HTTP listeners. + The ingress gateway configuration entry kind defines behavior for securing incoming communication between the service mesh and external sources. Learn about `""ingress-gateway""` config entry parameters for exposing TCP and HTTP listeners. --- -# Ingress Gateway Configuration Entry +# Ingress gateway configuration entry reference -This topic provides reference information for the `ingress-gateway` configuration entry. +This topic provides configuration reference information for the ingress gateway configuration entry. An ingress gateway is a type of proxy you register as a service in Consul to enable network connectivity from external services to services inside of the service mesh. Refer to [Ingress gateways overview](/consul/docs/connect/gateways/ingress-gateway) for additional information. -## Introduction +## Configuration model -You can define an `ingress-gateway` configuration entry to connect the Consul service mesh to a set of external services. The specification for ingress gateways include a `listeners` configuration, which exposes the service mesh to the external services. Use camel case (`IngressGateway`) to declare an ingress gateway configuration entry on Kubernetes. +The following list describes the configuration hierarchy, language-specific data types, default values if applicable, and requirements for the configuration entry. Click on a property name to view additional details. -Refer to the [Kubernetes Ingress Gateway](/consul/docs/k8s/connect/ingress-gateways) documentation for information about configuring ingress gateways on Kubernetes. + + + +- [`Kind`](#kind): string | must be `ingress-gateway` | required +- [`Name`](#name): string | required +- [`Namespace`](#namespace): string | `default` | +- [`Meta`](#meta): map of strings +- [`Partition`](#partition): string | `default` | +- [`TLS`](#tls): map + - [`Enabled`](#tls-enabled): boolean | `false` + - [`TLSMinVersion`](#tls-tlsminversion): string | `TLSv1_2` + - [`TLSMaxVersion`](#tls-tlsmaxversion): string + - [`CipherSuites`](#tls-ciphersuites): list of strings + - [`SDS`](#tls-sds): map of strings + - [`ClusterName`](#tls-sds): string + - [`CertResource`](#tls-sds): string +- [`Defaults`](#defaults): map + - [`MaxConnections`](#defaults-maxconnections): number + - [`MaxPendingRequests`](#defaults-maxpendingrequests): number + - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests): number + - [`PassiveHealthCheck`](#defaults-passivehealthcheck): map + - [`interval`](#defaults-passivehealthcheck): number + - [`max_failures`](#defaults-passivehealthcheck): number + - [`enforcing_consecutive_5xx`](#defaults-passivehealthcheck): number +- [`Listeners`](#listeners): list of maps + - [`Port`](#listeners-port): number | `0` + - [`Protocol`](#listeners-protocol): number | `tcp` + - [`Services`](#listeners-services): list of objects + - [`Name`](#listeners-services-name): string + - [`Namespace`](#listeners-services-namespace): string | + - [`Partition`](#listeners-services-partition): string | + - [`Hosts`](#listeners-services-hosts): List of strings | `.ingress.*` + - [`RequestHeaders`](#listeners-services-requestheaders): map + - [`Add`](#listeners-services-requestheaders): map of strings + - [`Set`](#listeners-services-requestheaders): map of strings + - [`Remove`](#listeners-services-requestheaders): list of strings + - [`ResponseHeaders`](#listeners-services-responseheaders): map + - [`Add`](#listeners-services-responseheaders): map of strings + - [`Set`](#listeners-services-responseheaders): map of strings + - [`Remove`](#listeners-services-responseheaders): list of strings + - [`TLS`](#listeners-services-tls): map + - [`SDS`](#listeners-services-tls-sds): map of strings + - [`ClusterName`](#listeners-services-tls-sds): string + - [`CertResource`](#listeners-services-tls-sds): string + - [`MaxConnections`](#listeners-services-maxconnections): number | `0` + - [`MaxPendingRequests`](#listeners-services-maxconnections): number | `0` + - [`MaxConcurrentRequests`](#listeners-services-maxconnections): number | `0` + - [`PassiveHealthCheck`](#listeners-services-passivehealthcheck): map + - [`interval`](#listeners-services-passivehealthcheck): number + - [`max_failures`](#listeners-services-passivehealthcheck): number + - [`enforcing_consecutive_5xx`](#listeners-services-passivehealthcheck): number + - [`TLS`](#listeners-tls): map + - [`Enabled`](#listeners-tls-enabled): boolean | `false` + - [`TLSMinVersion`](#listeners-tls-tlsminversion): string | `TLSv1_2` + - [`TLSMaxVersion`](#listeners-tls-tlsmaxversion): string + - [`CipherSuites`](#listeners-tls-ciphersuites): list of strings + - [`SDS`](#listeners-tls-sds): map of strings + - [`ClusterName`](#listeners-tls-sds): string + - [`CertResource`](#listeners-tls-sds): string + + -For other platforms, see [Ingress Gateway](/consul/docs/connect/gateways/ingress-gateway). + + +- [ `apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1` | required +- [`kind`](#kind): string | must be `IngressGateway` | required +- [`metadata`](#metadata): map of strings + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | `default` | +- [`spec`](#spec): map + - [`tls`](#spec-tls): map + - [`enabled`](#spec-tls-enabled): boolean | `false` + - [`tlsMinVersion`](#spec-tls-tlsminversion): string | `TLSv1_2` + - [`tlsMaxVersion`](#spec-tls-tlsmaxversion): string + - [`cipherSuites`](#spec-tls-ciphersuites): list of strings + - [`sds`](#spec-tls-sds): map of strings + - [`clusterName`](#spec-tls-sds): string + - [`certResource`](#spec-tls-sds): string + - [`defaults`](#spec-defaults): map + - [`maxConnections`](#spec-defaults-maxconnections): number + - [`maxPendingRequests`](#spec-defaults-maxpendingrequests): number + - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests): number + - [`passiveHealthCheck`](#spec-defaults-passivehealthcheck): map + - [`interval`](#spec-defaults-passivehealthcheck): number | no proxy's default value + - [`max_failures`](#spec-defaults-passivehealthcheck): number | no proxy's default value + - [`enforcing_consecutive_5xx`](#spec-defaults-passivehealthcheck): number | proxy's default value + - [`listeners`](#spec-listeners): list of maps + - [`port`](#spec-listeners-port): number | `0` + - [`protocol`](#spec-listeners-protocol): number | `tcp` + - [`services`](#spec-listeners-services): list of maps + - [`name`](#spec-listeners-services-name): string + - [`namespace`](#spec-listeners-services-namespace): string | current namespace | + - [`partition`](#spec-listeners-services-partition): string | current partition | + - [`hosts`](#spec-listeners-services-hosts): list of strings | `.ingress.*` + - [`requestHeaders`](#spec-listeners-services-requestheaders): map + - [`add`](#spec-listeners-services-requestheaders): map of strings + - [`set`](#spec-listeners-services-requestheaders): map of strings + - [`remove`](#spec-listeners-services-requestheaders): list of strings + - [`responseHeaders`](#spec-listeners-services-responseheaders): map + - [`add`](#spec-listeners-services-responseheaders): map of strings + - [`set`](#spec-listeners-services-responseheaders): map of strings + - [`remove`](#spec-listeners-services-responseheaders): list of strings + - [`tls`](#spec-listeners-services-tls): map + - [`sds`](#spec-listeners-services-tls-sds): map of strings + - [`clusterName`](#spec-listeners-services-tls-sds): string + - [`certResource`](#spec-listeners-services-tls-sds): string + - [`maxConnections`](#spec-listeners-services-maxconnections): number | `0` + - [`maxPendingRequests`](#spec-listeners-services-maxconnections): number | `0` + - [`maxConcurrentRequests`](#spec-listeners-services-maxconnections): number | `0` + - [`passiveHealthCheck`](#spec-listeners-services-passivehealthcheck): map + - [`interval`](#spec-listeners-services-passivehealthcheck): number + - [`max_failures`](#spec-listeners-services-passivehealthcheck): number + - [`enforcing_consecutive_5xx`](#spec-listeners-services-passivehealthcheck): number + - [`tls`](#spec-listeners-tls): map + - [`enabled`](#spec-listeners-tls-enabled): boolean | `false` + - [`tlsMinVersion`](#spec-listeners-tls-tlsminversion): string | `TLSv1_2` + - [`tlsMaxVersion`](#spec-listeners-tls-tlsmaxversion): string + - [`cipherSuites`](#spec-listeners-tls-ciphersuites): list of strings + - [`sds`](#spec-listeners-tls-sds): map of strings + - [`clusterName`](#spec-listeners-tls-sds): string + - [`certResource`](#spec-listeners-tls-sds): string -## Usage + -1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). -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](/consul/docs/k8s/crds) documentation for details. - - Issue the `consul config write` command: Refer to the [Consul Config Write](/consul/commands/config/write) documentation for details. + -## Configuration +## Complete configuration -Use the following syntax to configure an ingress gateway. +When every field is defined, an ingress gateway configuration entry has the following form: - - -```hcl -Kind = "ingress-gateway" -Name = "" + -Listeners = [ - { - Port = - Protocol = "" - Services = [ - { - Name = "" +```hcl +Kind = "ingress-gateway" +Name = "" +Namespace = "" +Partition = "" +Meta = { + = "" +} +TLS = { + Enabled = false + TLSMinVersion = "TLSv1_2" + TLSMaxVersion = "" + CipherSuites = [ + "" + ] + SDS = { + ClusterName = "" + CertResource = "" + } +} +Defaults = { + MaxConnections = 0 + MaxPendingRequests = 0 + MaxConcurrentRequests = 0 + PassiveHealthCheck = { + interval = 10 + max_failures = 5 + enforcing_consecutive_5xx = 100 + } +} +Listeners = [ + { + Port = 0 + Protocol = "tcp" + Services = [ + { + Name = "" + Namespace = "" + Partition = "" + Hosts = [ + ".ingress.*" + ] + RequestHeaders = { + Add = { + RequestHeaderName = "" + } + Set = { + RequestHeaderName = "" + } + Remove = [ + "" + ] + } + ResponseHeaders = { + Add = { + ResponseHeaderName = "" + } + Set = { + ResponseHeaderName = "" + } + Remove = [ + "" + ] + } + TLS = { + SDS = { + ClusterName = "" + CertResource = "" + } + } + MaxConnections = + MaxPendingRequests = + MaxConcurrentRequests = + PassiveHealthCheck = { + interval = 10 + max_failures = 5 + enforcing_consecutive_5xx = 100 + } + }] + TLS = { + Enabled = false + TLSMinVersion = "TLSv1_2" + TLSMaxVersion = "" + CipherSuites = [ + "" + ] + SDS = { + ClusterName = "" + CertResource = "" } - ] - + } } ] - ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway +kind: IngressGateway metadata: - name: -spec: - listeners: - - port: - protocol: - services: - - name: + name: + namespace: "" +spec: + tls: + enabled: false + tlsSMinVersion: TLSv1_2 + tlsMaxVersion: "" + cipherSuites: + - + sds: + clusterName: + certResource: + defaults: + maxConnections: 0 + maxPendingRequests: 0 + maxConcurrentRequests: 0 + passiveHealthCheck: + interval: 10 + max_failures: 5 + enforcing_consecutive_5xx: 100 + listeners: + - port: 0 + protocol: tcp + services: + - name: + namespace: + partition: + hosts: + - .ingress.* + requestHeaders: + add: + requestHeaderName: + set: + requestHeaderName: + remove: + - + responseHeaders: + add: + responseHeaderName: + set: + responseHeaderName: + remove: + - + tls: + sds: + clusterName: + certResource: + maxConnections: + maxPendingRequests: + maxConcurrentRequests: + passiveHealthCheck: + interval: 10 + max_failures: 5 + enforcing_consecutive_5xx: 100 + tls: + enabled: false + tlsMinVersion: TLSv1_2 + tlsMaxVersion: + cipherSuites: + - + sds: + clusterName: + certResource: ``` + + + + ```json { - "Kind": "ingress-gateway", - "Name": "", - "Listeners": [ - { - "Port": , - "Protocol": "", - "Services": [ - { - "Name": "" + "Kind" : "ingress-gateway", + "Name" : "", + "Namespace" : "", + "Partition" : "", + "Meta": { + "" : "" + }, + "TLS" : { + "Enabled" : false, + "TLSMinVersion" : "TLSv1_2", + "TLSMaxVersion" : "", + "CipherSuites" : [ + "" + ], + "SDS": { + "ClusterName" : "", + "CertResource" : "" + } + }, + "Defaults" : { + "MaxConnections" : 0, + "MaxPendingRequests" : 0, + "MaxConcurrentRequests": 0, + "PassiveHealthCheck" : { + "interval" : 10, + "max_failures" : 5, + "enforcing_consecutive_5xx" : 100 + } + }, + "Listeners" : [ + { + "Port" : 0, + "Protocol" : "tcp", + "Services" : [ + { + "Name" : "", + "Namespace" : "", + "Partition" : "", + "Hosts" : [ + ".ingress.*" + ], + "RequestHeaders" : { + "Add" : { + "RequestHeaderName" : "" + }, + "Set" : { + "RequestHeaderName" : "" + }, + "Remove" : [ + "" + ] + }, + "ResponseHeaders" : { + "Add" : { + "ResponseHeaderName" : "" + }, + "Set" : { + "ResponseHeaderName" : "" + }, + "Remove" : [ + "" + ] + }, + "TLS" : { + "SDS" : { + "ClusterName" : "", + "CertResource" : "" + } + }, + "MaxConnections" : , + "MaxPendingRequests" : , + "MaxConcurrentRequests" : , + "PassiveHealthCheck" : { + "interval" : 10, + "max_failures" : 5, + "enforcing_consecutive_5xx" : 100 + } } - ] + ], + "TLS" : { + "Enabled" : false, + "TLSMinVersion" : "TLSv1_2", + "TLSMaxVersion" : "", + "CipherSuites" : [ + "" + ], + "SDS" : { + "ClusterName" : "", + "CertResource" : "" + } + } } ] -} - +} ``` - - + -For Kubernetes environments, the configuration entry is always created in the same partition as the Kubernetes cluster. +## Specification - +This section provides details about the fields you can configure in the ingress gateway configuration entry. -```hcl -Kind = "ingress-gateway" -Name = "" -Namespace = "" -Partition = "" + -Listeners = [ - { - Port = - Protocol = "" - Services = [ - { - Name = "" - } - ] + - } -] +### `Kind` -``` +Specifies the type of configuration entry. Must be set to `ingress-gateway`. -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: - namespace: +#### Values -spec: - listeners: - - port: - protocol: - services: - - name: -``` +- Default: None +- This field is required. +- Data type: String value that must be set to `ingress-gateway`. -```json -{ - "Kind": "ingress-gateway", - "Name": "", - "Namespace": "", - "Partition": "", +### `Name` - "Listeners": [ - { - "Port": , - "Protocol": "", - "Services": [ - { - "Name": "" - } - ] - } - ] -} -``` +Specifies a name for the gateway. The name is metadata that you can use to reference the configuration entry when performing Consul operations with the [`consul config` command](/consul/commands/config). - - - +#### Values -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. +- Default: None +- This field is required. +- Data type: String -### Scope +### `Namespace` -[Configuration entries](/consul/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies across the default partition of 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 or partitions. See [Ingress Gateway](/consul/docs/connect/gateways/ingress-gateway) for more information. +Specifies the namespace to apply the configuration entry in. Refer to [Namespaces](/consul/docs/enterprise/namespaces) for additional information about Consul namespaces. -### Wildcard Service Specification +If unspecified, the ingress gateway is applied to the `default` namespace. You can override the namespace when using the [`/config` API endpoint](/consul/api-docs/config) to register the configuration entry by specifying the `ns` query parameter. -Ingress gateways can optionally target all services within a Consul namespace by -specifying a wildcard `*` as the service name. A wildcard specifier allows -for a single listener to route traffic to all available services on the -Consul service mesh, differentiating between the services by their host/authority -header. +#### Values -A wildcard specifier provides the following properties for an ingress -gateway: +- Default: `default`, +- Data type: String -- All services with the same - [protocol](/consul/docs/connect/config-entries/ingress-gateway#protocol) as the - listener will be routable. -- The ingress gateway routes traffic based on the host or authority header and expects a value matching either `.ingress.*` or - `.ingress..*`. The query matches the [Consul DNS - ingress subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups). +### `Partition` -A wildcard specifier cannot be set on a listener of protocol `tcp`. +Specifies the admin partition that the ingress gateway applies to. The value must match the partition in which the gateway is registered. Refer to [Admin partitions](/consul/docs/enterprise/admin-partitions) for additional information. -### ACLs +If unspecified, the ingress gateway is applied to the `default` partition. You can override the partition when using the [`/config` API endpoint](/consul/api-docs/config) to register the configuration entry by specifying the `partition` query parameter. -Configuration entries may be protected by [ACLs](/consul/docs/security/acl). +#### Values -Reading an `ingress-gateway` config entry requires `service:read` on the `Name` -field of the config entry. +- Default: `default +- Data type: String -Creating, updating, or deleting an `ingress-gateway` config entry requires -`operator:write`. +### `Meta` -### Example Configurations +Defines an arbitrary set of key-value pairs to store in the Consul KV. -The following examples describe possible use-cases for ingress gateway configuration entries. +#### Values -#### TCP listener +- Default: None +- Data type: Map of one or more key-value pairs. + - keys: String + - values: String, integer, or float -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](/consul/docs/enterprise/namespaces) and the `team-frontend` [admin partition](/consul/docs/enterprise/admin-partitions): +### `TLS` - - - +Specifies the TLS configuration settings for the gateway. -```hcl -Kind = "ingress-gateway" -Name = "us-east-ingress" +#### Values -Listeners = [ - { - Port = 3456 - Protocol = "tcp" - Services = [ - { - Name = "db" - } - ] - } -] -``` +- Default: No default +- Data type: Object that can contain the following fields: + - [`Enabled`](#tls-enabled) + - [`TLSMinVersion`](#tls-tlsminversion) + - [`TLSMaxVersion`](#tls-tlsmaxversion) + - [`CipherSuites`](#tls-ciphersuites) + - [`SDS`](#tls-sds) -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: us-east-ingress -spec: - listeners: - - port: 3456 - protocol: tcp - services: - - name: db -``` +### `TLS.Enabled` -```json -{ - "Kind": "ingress-gateway", - "Name": "us-east-ingress", - "Listeners": [ - { - "Port": 3456, - "Protocol": "tcp", - "Services": [ - { - "Name": "db" - } - ] - } - ] -} -``` +Enables and disables TLS for the configuration entry. Set to `true` to enable built-in TLS for every listener on the gateway. TLS is disabled by default. - +When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). - - - +#### Values -```hcl -Kind = "ingress-gateway" -Name = "us-east-ingress" -Namespace = "default" -Partition = "team-frontend" + - Default: `false` + - Data type: boolean -Listeners = [ - { - Port = 3456 - Protocol = "tcp" - Services = [ - { - Namespace = "ops" - Name = "db" - } - ] - } -] -``` +### `TLS.TLSMinVersion` -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: us-east-ingress - namespace: default -spec: - listeners: - - port: 3456 - protocol: tcp - services: - - name: db - namespace: ops -``` +Specifies the minimum TLS version supported for gateway listeners. -```json -{ - "Kind": "ingress-gateway", - "Name": "us-east-ingress", - "Namespace": "default", - "Partition": "team-frontend", - "Listeners": [ - { - "Port": 3456, - "Protocol": "tcp", - "Services": [ - { - "Namespace": "ops", - "Name": "db" - } - ] - } - ] -} -``` +#### Values - +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` - - +### `TLS.TLSMaxVersion` -#### Wildcard HTTP Listener +Specifies the maximum TLS version supported for gateway listeners. -In the following example, two listeners are configured on an ingress gateway named `us-east-ingress`: +#### Values -- 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 `max_connections` of the ingress gateway proxy to each upstream cluster is set to 4096. +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` -The Consul Enterprise version implements the following additional configurations: +### `TLS.CipherSuites[]` -- The ingress gateway is set up in the `default` [namespace](/consul/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](/consul/docs/enterprise/admin-partitions): +Specifies a list of cipher suites that gateway listeners support when negotiating connections using TLS 1.2 or older. If unspecified, the Consul applies the default for the version of Envoy in use. Refer to the [Envoy documentation](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-tls parameters-cipher-suites) for details. - - - +#### Values -```hcl -Kind = "ingress-gateway" -Name = "us-east-ingress" +- Default: None +- Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. -TLS { - Enabled = true -} +### `TSL.SDS` -Defaults { - MaxConnections = 4096 -} +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. -Listeners = [ - { - Port = 8080 - Protocol = "http" - Services = [ - { - Name = "*" - } - ] - }, - { - Port = 4567 - Protocol = "http" - Services = [ - { - Name = "api" - Hosts = ["foo.example.com"] - }, - { - Name = "web" - Hosts = ["website.example.com"] - } - ] - } -] -``` +Consul applies the SDS configuration specified in this field as defaults for all listeners defined in the gateway. You can override the SDS settings for per listener or per service defined in the listener. Refer to the following configurations for additional information: -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: us-east-ingress -spec: - tls: - enabled: true - listeners: - - port: 8080 - protocol: http - services: - - name: '*' - - port: 4567 - protocol: http - services: - - name: api - hosts: ['foo.example.com'] - - name: web - hosts: ['website.example.com'] -``` +- [`Listeners.TLS.SDS`](#listeners-tls-sds): Configures SDS settings for all services in the listener. +- [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. + +#### Values + +- Default: None +- Data type: Map containing the following fields: + - `ClusterName` + - `CertResource` + +The following table describes how to configure SDS parameters. + +| Parameter | Description | Data type | +| --- | --- | --- | +| `ClusterName` | Specifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration. | String | +| `CertResource` | Specifies an SDS resource name. Consul requests the SDS resource name when fetching the certificate from the SDS service. When set, Consul serves the certificate to all listeners over TLS unless a listener-specific TLS configuration overrides the SDS configuration. | String | + +### `Defaults` + +Specifies default configurations for connecting upstream services. + +#### Values + +- Default: None +- The data type is a map containing the following parameters: + + - [`MaxConnnections`](#defaults-maxconnections) + - [`MaxPendingRequests`](#defaults-maxpendingrequests) + - [`MaxConcurrentRequests`](#defaults-maxconcurrentrequests) + +### `Defaults.MaxConnections` + +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. + +#### Values + +- Default value is `0`, which instructs Consul to use the proxy's configuration. For Envoy, the default is `1024`. +- Data type: Integer + +### `Defaults.MaxPendingRequests` + +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). + +#### Values + +- Default value is `0`, which instructs Consul to use the proxy's configuration. For Envoy, the default is `1024`. +- Data type: Integer + +### `Defaults.MaxConcurrentRequests` + +Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol). + +#### Values + +- Default value is `0`, which instructs Consul to use the proxy's configuration. For Envoy, the default is `1024`. +- Data type: Integer + +### `Defaults.PassiveHealthCheck` + +Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. + +#### Values + +- Default: None +- Data type: Map + +The following table describes the configurations for passive health checks: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | +| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | +| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + +### `Listeners[]` + +Specifies a list of listeners in the mesh for the gateway. Listeners are uniquely identified by their port number. + +#### Values + +- Default: None +- Data type: List of maps containing the following fields: + - [`Port`](#listeners-port) + - [`Protocol`](#listeners-protocol) + - [`Services[]`](#listeners-services) + - [`TLS`](#listeners-tls) + +### `Listeners[].Port` + +Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. + +#### Values + +- Default: `0` +- Data type: Integer + +### `Listeners[].Protocol` + +Specifies the protocol associated with the listener. To enable L7 network management capabilities, specify one of the following values: + +- `http` +- `http2` +- `grpc` + +#### Values + +- Default: `tcp` +- Data type: String that contains one of the following values: + + - `tcp` + - `http` + - `http2` + - `grpc` + +### `Listeners[].Services[]` + +Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `Namespace` field is required for Consul Enterprise datacenters. If the [`Listeners.Protocol`] field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. + +#### Values + +- Default: None +- Data type: List of maps that can contain the following fields: + - [`Name`](#listeners-services-name) + - [`Namespace`](#listeners-services-namespace) + - [`Partition`](#listeners-services-partition) + - [`Hosts`](#listeners-services-hosts) + - [`RequestHeaders`](#listeners-services-requestheaders) + - [`ResponseHeaders`](#listeners-services-responseheaders)` + - [`TLS`](#listeners-services-tls) + - [`MaxConnections`](#listeners-services-maxconnections) + - [`MaxPendingRequests`](#listeners-services-maxpendingrequests) + - [`MaxConcurrentRequests`](#listeners-services-maxconcurrentrequests) + - [`PassiveHealthCheck`](#listeners-services-passivehealthcheck) + +### `Listeners[].Services[].Name` + +Specifies the name of a service to expose to the listener. You can specify services in the following ways: + +- Provide the name of a service registered in the Consul catalog. +- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. +- Provide a `*` wildcard to expose all services in the datacenter. Wild cards are not supported for listeners configured for TCP. Refer to [`Listeners[].Protocol`](#listeners-protocol) for additional information. + +#### Values + +- Default: None +- Data type: String + +### `Listeners[].Services[].Namespace` + +Specifies the namespace to use when resolving the location of the service. + +#### Values + +- Default: Current namespace +- Data type: String + +### `Listeners[].Services[].Partition` + +Specifies the admin partition to use when resolving the location of the service. + +#### Values + +- Default: Current partition +- Data type: String + +### `Listeners[].Services[].Hosts[]` + +Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. + +If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. + +When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. + +You can use the wildcard in the left-most DNS label to match a set of hosts. For example, `*.example.com` is valid, but `example.*` and `*-suffix.example.com` are invalid. + +#### Values + +- Default: None +- Data type: List of strings or `*` + +### `Listeners[].Services[].RequestHeaders` + +Specifies a set of HTTP-specific header modification rules applied to requests routed through the gateway. You cannot configure request headers if the listener protocol is set to `tcp`. Refer to [HTTP listener with Path-based Routing](#http-listener-with-path-based-routing) for an example configuration. + +#### Values + +- Default: None +- Data type: Object containing one or more fields that define header modification rules: + + - `Add`: Map of one or more key-value pairs + - `Set`: Map of one or more key-value pairs + - `Remove`: Map of one or more key-value pairs + +The following table describes how to configure values for request headers: + +| Rule | Description | Data type | +| --- | --- | --- | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings | + +##### Use variable placeholders + +For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated at runtime. + +### `Listeners[].Services[].ResponseHeaders` + +Specifies a set of HTTP-specific header modification rules applied to responses routed through the gateway. You cannot configure response headers if the listener protocol is set to `tcp`. Refer to [HTTP listener with Path-based Routing](#http-listener-with-path-based-routing) for an example configuration. + +#### Values + +- Default: None +- Data type: Map containing one or more fields that define header modification rules: + + - `Add`: Map of one or more key-value pairs + - `Set`: Map of one or more key-value pairs + - `Remove`: Map of one or more key-value pairs + +The following table describes how to configure values for request headers: + +| Rule | Description | Data type | +| --- | --- | --- | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `Set` | Defines a set of key-value pairs to add to the response header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings | + +##### Use variable placeholders + +For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated at runtime. + +### `Listeners[].Services[].TLS` + +Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`TLS`](#tls) settings for the configuration entry. + +#### Values + +- Default: None +- Data type: Map + +### `Listeners[].Services[].TLS.SDS` + +Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. + +This configuration overrides the main [`TLS.SDS`](#tls-sds) settings for configuration entry. If unspecified, Consul applies the top-level [`TLS.SDS`](#tls-sds) settings. + +#### Values + +- Default: None +- Data type: Map containing the following fields: + + - `ClusterName` + - `CertResource` + +The following table describes how to configure SDS parameters. Refer to [Configure static SDS clusters](/consul/docs/connect/gateways/ingress-gateway/tls-external-service#configure-static-sds-clusters) for usage information: + +| Parameter | Description | Data type | +| `ClusterName` | Specifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration. | String | +| `CertResource` | Specifies an SDS resource name. Consul requests the SDS resource name when fetching the certificate from the SDS service. When set, Consul serves the certificate to all listeners over TLS unless a listener-specific TLS configuration overrides the SDS configuration. | String | + +### `Listeners[].Services[].MaxConnections` + +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. + +When defined, this field overrides the [`Defaults.MaxConnections`](#defaults-maxconnections) configuration. + +#### Values + +- Default: None +- Data type: Integer + +### `Listeners[].Services.MaxPendingRequests` + +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. When defined, this field overrides the value specified in the [`Defaults.MaxPendingRequests`](#defaults-maxpendingrequests) field of the configuration entry. + +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. + +#### Values + +- Default: None +- Data type: Integer + +### `Listeners[].Services[].MaxConcurrentRequests` + +Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. This field overrides the value set in the [`Defaults.MaxConcurrentRequests`](#defaults-maxconcurrentrequests) field of the configuration entry. + +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`Listeners.Protocol`](#listeners-protocol) for more information. + +#### Values + +- Default: None +- Data type: Integer + +### `Listeners[].Services[].PassiveHealthCheck` + +Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. This field overrides the value set in the [`Defaults.PassiveHealthCheck`](#defaults-passivehealthcheck) field of the configuration entry. + +#### Values + +- Default: None +- Data type: Map + +The following table describes the configurations for passive health checks: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | +| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | +| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + +### `Listeners[].TLS` + +Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`TLS`](#tls) settings for the configuration entry. + +#### Values + +- Default: None +- Data type: Map that can contain the following fields: + - [`Enabled`](#listeners-tls-enabled) + - [`TLSMinVersion`](#listeners-tls-tlsminversion) + - [`TLSMaxVersion`](#listeners-tls-tlsmaxversion) + - [`CipherSuites`](#listeners-tls-ciphersuites) + - [`SDS`](#listeners-tls-sds) + +### `Listeners[].TLS.Enabled` + +Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). + +#### Values + + - Default: `false` + - Data type: boolean + +### `Listeners[].TLS.TLSMinVersion` + +Specifies the minimum TLS version supported for the listener. + +#### Values + +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` + +### `Listeners[].TLS.TLSMaxVersion` + +Specifies the maximum TLS version supported for the listener. + +#### Values + +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` + +### `Listeners[].TLS.CipherSuites` + +Specifies a list of cipher suites that the listener supports when negotiating connections using TLS 1.2 or older. If unspecified, the Consul applies the default for the version of Envoy in use. Refer to the [Envoy documentation](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-tls parameters-cipher-suites) for details. + +#### Values + +- Default: None +- Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. + +### `Listeners[].TLS.SDS` + +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. + +Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `Listeners.TLS.SDS` configuration per service by configuring the [`Listeners.Services.TLS.SDS`](#listeners-services-tls-sds) settings for each service. + +#### Values + +- Default: None +- The data type is a map containing `ClusterName` and `CertResource` fields. + +The following table describes how to configure SDS parameters. Refer to [Configure static SDS clusters](/consul/docs/connect/gateways/ingress-gateway/tls-external-service#configure-static-sds-clusters) for usage information: + +| Parameter | Description | Data type | +| --- | --- | --- | +| `ClusterName` | Specifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration. | String | +| `CertResource` | Specifies an SDS resource name. Consul requests the SDS resource name when fetching the certificate from the SDS service. When set, Consul serves the certificate to all listeners over TLS unless a listener-specific TLS configuration overrides the SDS configuration. | String | + + + + + +### `apiVersion` + +Kubernetes-only parameter that specifies the version of the Consul API that the configuration entry maps to Kubernetes configurations. The value must be `consul.hashicorp.com/v1alpha1`. + +### `kind` + +Specifies the type of configuration entry to implement. Must be set to `IngressGatewa`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `IngressGateway`. + +### `metadata` + +Specifies metadata for the gateway. + +#### Values + +- Default: None +- This field is required +- Data type: Map the contains the following fields: + - [`name`](#metadata-name) + - [`namespace`](#metadata-namespace) + +### `metadata.name` + +Specifies a name for the gateway. The name is metadata that you can use to reference the configuration entry when performing Consul operations with the [`consul config` command](/consul/commands/config). + +#### Values + +- Default: None +- This field is required. +- Data type: String + +### `metadata.namespace` + +Specifies the namespace to apply the configuration entry in. Refer to [Namespaces](/consul/docs/enterprise/namespaces) for additional information about Consul namespaces. + +If unspecified, the ingress gateway is applied to the `default` namespace. You can override the namespace when using the [`/config` API endpoint](/consul/api-docs/config) to register the configuration entry by specifying the `ns` query parameter. + +#### Values + +- Default: `default`, +- Data type: String + +### `spec` + +Kubernetes-only field that contains all of the configurations for ingress gateway pods. + +#### Values + +- Default: None +- This field is required. +- Data type: Map containing the following fields: + - [`tls`](#tls) + - [`defaults`](#defaults) + - [`listeners`](#listeners) + +### `spec.tls` + +Specifies the TLS configuration settings for the gateway. + +#### Values + +- Default: No default +- Data type: Object that can contain the following fields: + - [`enabled`](#tls-enabled) + - [`tlsMinVersion`](#spec-tls-tlsminversion) + - [`tlsMaxVersion`](#spec-tls-tlsmaxversion) + - [`cipherSuites`](#spec-tls-tlsciphersuites) + - [`sds`](#spec-tls-sds) + +### `spec.tls.enabled` + +Enables and disables TLS for the configuration entry. Set to `true` to enable built-in TLS for every listener on the gateway. TLS is disabled by default. + +When enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). + +#### Values + + - Default: `false` + - Data type: boolean + +### `spec.tls.tlsMinVersion` + +Specifies the minimum TLS version supported for gateway listeners. + +#### Values + +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` + +### `spec.tls.tlsMaxVersion` + +Specifies the maximum TLS version supported for gateway listeners. + +#### Values + +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` + +### `spec.tls.cipherSuites[]` + +Specifies a list of cipher suites that gateway listeners support when negotiating connections using TLS 1.2 or older. If unspecified, the Consul applies the default for the version of Envoy in use. Refer to the [Envoy documentation](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-tls parameters-cipher-suites) for details. + +#### Values + +- Default: None +- Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. + +### `spec.tls.sds` + +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. + +Consul applies the SDS configuration specified in this field as defaults for all listeners defined in the gateway. You can override the SDS settings for per listener or per service defined in the listener. Refer to the following configurations for additional information: + +- [`spec.listeners.tls.sds`](#spec-listeners-tls-sds): Configures SDS settings for all services in the listener. +- [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds): Configures SDS settings for a specific service defined in the listener. + +#### Values + +- Default: None +- Data type: Map containing the following fields: + - [`clusterName`] + - [`certResource`] + +The following table describes how to configure SDS parameters. + +| Parameter | Description | Data type | +| --- | --- | --- | +| `clusterName` | Specifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration. | String | +| `certResource` | Specifies an SDS resource name. Consul requests the SDS resource name when fetching the certificate from the SDS service. When set, Consul serves the certificate to all listeners over TLS unless a listener-specific TLS configuration overrides the SDS configuration. | String | + +### `spec.defaults` + +Specifies default configurations for upstream connections. + +#### Values + +- Default: None +- The data type is a map containing the following parameters: + + - [`maxConnnections`](#spec-defaults-maxconnections) + - [`maxPendingRequests`](#spec-defaults-maxpendingrequests) + - [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) + +### `spec.defaults.maxConnections` + +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. If unspecified, Consul uses Envoy's configuration. The default configuration for Envoy is `1024`. + +#### Values + +- Default: `0` +- Data type: Integer + +### `spec.defaults.maxPendingRequests` + +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.Protocol`](#spec-listeners-protocol). + +If unspecified, Consul uses Envoy's configuration. The default for Envoy is `1024`. + +#### Values + +- Default: `0` +- Data type: Integer + +### `spec.defaults.maxConcurrentRequests` + +Specifies the maximum number of concurrent HTTP/2 traffic requests that are allowed at a single point in time. Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol). + +If unspecified, Consul uses Envoy's configuration. The default for Envoy is `1024`. + +#### Values + +- Default: `0` +- Data type: Integer + +### `spec.defaults.passiveHealthCheck` + +Defines a passive health check configuration. Passive health checks remove hosts from the upstream cluster when they are unreachable or return errors. + +#### Values + +- Default: None +- Data type: Map + +The following table describes the configurations for passive health checks: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | +| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | +| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + +### `spec.listeners[]` + +Specifies a list of listeners in the mesh for the gateway. Listeners are uniquely identified by their port number. + +#### Values + +- Default: None +- Data type: List of maps containing the following fields: + - [`port`](#spec-listeners-port) + - [`protocol`](#spec-listeners-protocol) + - [`services[]`](#spec-listeners-services) + - [`tls`](#spec-listeners-tls) + +### `spec.listeners[].port` + +Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the [`-address`](/consul/commands/connect/envoy#address) flag when starting the gateway. The listener port must not conflict with the health check port. + +#### Values + +- Default: `0` +- Data type: Integer + +### `spec.listeners[].protocol` + +Specifies the protocol associated with the listener. To enable L7 network management capabilities, specify one of the following values: + +- `http` +- `http2` +- `grpc` + +#### Values + +- Default: `tcp` +- Data type: String that contains one of the following values: + + - `tcp` + - `http` + - `http2` + - `grpc` + +### `spec.listeners[].services[]` + +Specifies a list of services that the listener exposes to services outside the mesh. Each service must have a unique name. The `namespace` field is required for Consul Enterprise datacenters. If the listener's [`protocol`](#spec-listeners-protocol) field is set to `tcp`, then Consul can only expose one service. You can expose multiple services if the listener uses any other supported protocol. + +#### Values + +- Default: None +- Data type: List of maps that can contain the following fields: + - [`name`](#spec-listeners-services-name) + - [`namespace`](#spec-listeners-services-namespace) + - [`partition`](#spec-listeners-services-partition) + - [`hosts`](#spec-listeners-services-hosts) + - [`requestHeaders`](#spec-listeners-services-requestheaders) + - [`responseHeaders`](#spec-listeners-services-responseheaders)` + - [`tlsLS`](#spec-listeners-services-tls) + - [`maxConnections`](#spec-listeners-services-maxconnections) + - [`maxPendingRequests`](#spec-listeners-services-maxpendingrequests) + - [`maxConcurrentRequests`](#spec-listeners-services-maxconcurrentrequests) + - [`passiveHealthCheck`](#spec-listeners-services-passivehealthcheck) + +### `spec.listeners[].services[].name` + +Specifies the name of a service to expose to the listener. You can specify services in the following ways: + +- Provide the name of a service registered in the Consul catalog. +- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. Refer to [HTTP listener with path-based routes](#http-listener-with-path-based-routes) for an example. +- Provide a `*` wildcard to expose all services in the datacenter. Wild cards are not supported for listeners configured for TCP. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for additional information. + +#### Values + +- Default: None +- Data type: String + +### `spec.listeners[].services[].namespace` + +Specifies the namespace to use when resolving the location of the service. + +#### Values + +- Default: Current namespace +- Data type: String + +### `spec.listeners[].services[].partition` + +Specifies the admin partition to use when resolving the location of the service. + +#### Values + +- Default: Current partition +- Data type: String + +### `spec.listeners[].services[].hosts[]` + +Specifies one or more hosts that the listening services can receive requests on. The ingress gateway proxies external traffic to the specified services when external requests include `host` headers that match a host specified in this field. + +If unspecified, Consul matches requests to services using the `.ingress.*` domain. You cannot specify a host for listeners that communicate over TCP. You cannot specify a host when service names are specified with a `*` wildcard. Requests must include the correct host for Consul to proxy traffic to the service. + +When TLS is disabled, you can use the `*` wildcard to match all hosts. Disabling TLS may be suitable for testing and learning purposes, but we recommend enabling TLS in production environments. + +You can use the wildcard in the left-most DNS label to match a set of hosts. For example, `*.example.com` is valid, but `example.*` and `*-suffix.example.com` are invalid. + +#### Values + +- Default: None +- Data type: List of strings or `*` + +### `spec.listeners[].services[].requestHeaders` + +Specifies a set of HTTP-specific header modification rules applied to requests routed through the gateway. You cannot configure request headers if the listener protocol is set to `tcp`. Refer to [HTTP listener with path-based routing](#http-listener-with-path-based-routing) for an example configuration. + +#### Values + +- Default: None +- Data type: Object containing one or more fields that define header modification rules: + + - `add`: Map of one or more key-value pairs + - `set`: Map of one or more key-value pairs + - `remove`: Map of one or more key-value pairs + +The following table describes how to configure values for request headers: + +| Rule | Description | Data type | +| --- | --- | --- | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings | + +##### Use variable placeholders + +For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated at runtime. + +### `spec.listeners[].services[].responseHeaders` + +Specifies a set of HTTP-specific header modification rules applied to responses routed through the gateway. You cannot configure response headers if the listener protocol is set to `tcp`. Refer to [HTTP listener with path-based routing](#http-listener-with-path-based-routing) for an example configuration. + +#### Values + +- Default: None +- Data type: Map containing one or more fields that define header modification rules: + + - `add`: Map of one or more key-value pairs + - `set`: Map of one or more key-value pairs + - `remove`: Map of one or more key-value pairs + +The following table describes how to configure values for request headers: + +| Rule | Description | Data type | +| --- | --- | --- | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings | +| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings | + +##### Use variable placeholders + +For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated at runtime. + +### `spec.listeners[].services[].tls` + +Specifies a TLS configuration for a specific service. The settings in this configuration overrides the main [`tls`](#spec.tls) settings for the configuration entry. + +#### Values + +- Default: None +- Data type: Map + +### `spec.listeners[].services[].tls.sds` + +Specifies parameters that configure the listener to load TLS certificates from an external SDS. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. + +If unspecified, Consul applies the [`sds`](#spec-tls-sds) settings configured for the ingress gateway. If both are specified, this configuration overrides the settings for configuration entry. + +#### Values -```json -{ - "Kind": "ingress-gateway", - "Name": "us-east-ingress", - "TLS": { - "Enabled": true - }, - "Listeners": [ - { - "Port": 8080, - "Protocol": "http", - "Services": [ - { - "Name": "*" - } - ] - }, - { - "Port": 4567, - "Protocol": "http", - "Services": [ - { - "Name": "api", - "Hosts": ["foo.example.com"] - }, - { - "Name": "web", - "Hosts": ["website.example.com"] - } - ] - } - ] -} -``` +- Default: None +- Data type: Map containing the following fields: - + - `clusterName` + - `certResource` - - - +The following table describes how to configure SDS parameters. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for usage information: -```hcl -Kind = "ingress-gateway" -Name = "us-east-ingress" -Namespace = "default" +| Parameter | Description | Data type | +| --- | --- | --- | +| `clusterName` | Specifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration. | String | +| `certResource` | Specifies an SDS resource name. Consul requests the SDS resource name when fetching the certificate from the SDS service. When set, Consul serves the certificate to all listeners over TLS unless a listener-specific TLS configuration overrides the SDS configuration. | String | -TLS { - Enabled = true -} +### `spec-listeners[].services[].maxConnections` -Listeners = [ - { - Port = 8080 - Protocol = "http" - Services = [ - { - Namespace = "frontend" - Name = "*" - } - ] - }, - { - Port = 4567 - Protocol = "http" - Services = [ - { - Namespace = "frontend" - Name = "api" - Hosts = ["foo.example.com"] - Partition = "api-team" - }, - { - Namespace = "frontend" - Name = "web" - Hosts = ["website.example.com"] - Partition = "web-team" - } - ] - } -] -``` +Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream. -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: IngressGateway -metadata: - name: us-east-ingress - namespace: default -spec: - tls: - enabled: true - listeners: - - port: 8080 - protocol: http - services: - - name: '*' - namespace: frontend - - port: 4567 - protocol: http - services: - - name: api - namespace: frontend - hosts: ['foo.example.com'] - partition: api-team - - name: web - namespace: frontend - hosts: ['website.example.com'] - partition: web-team -``` +A value specified in this field overrides the [`maxConnections`](#spec-defaults-maxconnections) field specified in the `defaults` configuration. -```json -{ - "Kind": "ingress-gateway", - "Name": "us-east-ingress", - "Namespace": "default", - "TLS": { - "Enabled": true - }, - "Listeners": [ - { - "Port": 8080, - "Protocol": "http", - "Services": [ - { - "Namespace": "frontend", - "Name": "*" - } - ] - }, - { - "Port": 4567, - "Protocol": "http", - "Services": [ - { - "Namespace": "frontend", - "Name": "api", - "Hosts": ["foo.example.com"], - "Partition": "api-team" - }, - { - "Namespace": "frontend", - "Name": "web", - "Hosts": ["website.example.com"], - "Partition": "web-team" - } - ] - } - ] -} -``` +#### Values - +- Default: None +- Data type: Integer + +### `spec.listeners[].services.maxPendingRequests` + +Specifies the maximum number of requests that are allowed to queue while waiting to establish a connection. A value specified in this field overrides the [`maxPendingRequests`](#spec-defaults-maxpendingrequests) field specified in the `defaults` configuration. + +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. + +#### Values + +- Default: None +- Data type: Integer + +### `spec.listeners[].services[].maxConcurrentRequests` + +Specifies the maximum number of concurrent HTTP/2 traffic requests that the service is allowed at a single point in time. A value specified in this field overrides the [`maxConcurrentRequests`](#spec-defaults-maxconcurrentrequests) field specified in the `defaults` configuration entry. + +Listeners must use an L7 protocol for this configuration to take effect. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for more information. + +#### Values + +- Default: None +- Data type: Integer + +### `spec.listeners[].services[].passiveHealthCheck` + +Defines a passive health check configuration for the service. Passive health checks remove hosts from the upstream cluster when the service is unreachable or returns errors. Health checks specified for services override the health checks defined in the [`spec.defaults.passiveHealthCheck`](#spec-defaults-passivehealthcheck) configuration. + +#### Values + +- Default: None +- Data type: Map + +The following table describes the configurations for passive health checks: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `interval` | Specifies the time in nanoseconds between checks. | Integer | Proxy's default configuration, which is `10` for Envoy | +| `max_failures` | Specifies the number of consecutive failures that cause a host to be removed from the upstream cluster. | Integer | Proxy's default configuration, which is `5` for Envoy | +| `enforcing_consecutive_5xx` | Specifies a percentage that indicates how many times out of 100 that Consul ejects the host when it detects an outlier status. The outlier status is determined by consecutive errors in the 500-599 response range. | Integer | Proxy's default configuration, which is `100` for Envoy | + +### `spec.listeners[].tls` + +Specifies the TLS configuration for the listener. If unspecified, Consul applies any [service-specific TLS configurations](#spec-listeners-services-tls). If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main [`tls`](#tls) settings for the configuration entry. + +#### Values + +- Default: None +- Data type: Map that can contain the following fields: + - [`enabled`](#spec-listeners-tls-enabled) + - [`tlsMinVersion`](#spec-listeners-tls-tlsminversion) + - [`tlsMaxVersion`](#spec-listeners-tls-tlsmaxversion) + - [`cipherSuites`](#spec-listeners-tls-ciphersuites) + - [`sds`](#spec-listeners-tls-sds) + +### `spec.listeners[].tls.enabled` + +Set to `true` to enable built-in TLS for the listener. If enabled, Consul adds each host defined in every service's `Hosts` field to the gateway's x509 certificate as a DNS subject alternative name (SAN). + +#### Values + + - Default: `false` + - Data type: boolean + +### `spec.listeners[].tls.tlsMinVersion` + +Specifies the minimum TLS version supported for the listener. + +#### Values + +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` + +### `spec.listeners[].tls.tlsMaxVersion` + +Specifies the maximum TLS version supported for the listener. + +#### Values + +- Default: Depends on the version of Envoy: + - Envoy v1.22.0 and later: `TLSv1_2` + - Older versions: `TLSv1_0` +- Data type: String with one of the following values: + - `TLS_AUTO` + - `TLSv1_0` + - `TLSv1_1` + - `TLSv1_2` + - `TLSv1_3` + +### `spec.listeners[].tls.cipherSuites` + +Specifies a list of cipher suites that the listener supports when negotiating connections using TLS 1.2 or older. If unspecified, the Consul applies the default for the version of Envoy in use. Refer to the [Envoy documentation](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-tls parameters-cipher-suites) for details. + +#### Values + +- Default: None +- Data type: List of string values. Refer to the [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169) for a list of supported ciphers. + +### `spec.listeners[].tls.sds` + +Specifies parameters for loading the TLS certificates from an external SDS service. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. + +Consul applies the SDS configuration specified in this field to all services in the listener. You can override the `spec.listeners[].tls.sds` configuration per service by configuring the [`spec.listeners.services.tls.sds`](#spec-listeners-services-tls-sds) settings for each service. + +#### Values + +- Default: None +- Data type: Map containing the following fields + - `clusterName` + - `certResource` + +The following table describes how to configure SDS parameters. Refer to [Configure static SDS clusters](/consul/docs/connect/gateways/ingress-gateway/tls-external-service#configure-static-sds-clusters) for usage information: + +| Parameter | Description | Data type | +| --- | --- | --- | +| `clusterName` | Specifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration. | String | +| `certResource` | Specifies an SDS resource name. Consul requests the SDS resource name when fetching the certificate from the SDS service. When set, Consul serves the certificate to all listeners over TLS unless a listener-specific TLS configuration overrides the SDS configuration. | String | + -#### HTTP listener with Path-based Routing +## Examples -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. +Refer to the following examples for common ingress gateway configuration patterns: +- [Define a TCP listener](#define-a-tcp-listener) +- [Use wildcards to define listeners](#use-wilcards-to-define-an-http-listener) +- [HTTP listener with path-based routes](#http-listener-with-path-based-routes) -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. +### Define a TCP listener + +The following example sets up a TCP listener on an ingress gateway named `us-east-ingress` that proxies traffic to the `db` service. For Consul Enterprise, the `db` service can only listen for traffic in the `default` namespace inside the `team-frontend` admin partition: + +#### Consul OSS - - ```hcl @@ -570,19 +1504,11 @@ Name = "us-east-ingress" Listeners = [ { - Port = 80 - Protocol = "http" + Port = 3456 + Protocol = "tcp" Services = [ { - Name = "api" - RequestHeaders { - Add { - "x-gateway" = "us-east-ingress" - } - } - ResponseHeaders { - Remove = ["x-debug"] - } + Name = "db" } ] } @@ -596,16 +1522,10 @@ metadata: name: us-east-ingress spec: listeners: - - port: 80 - protocol: http + - port: 3456 + protocol: tcp services: - - name: api - requestHeaders: - add: - x-gateway: us-east-ingress - responseHeaders: - remove: - - x-debug + - name: db ``` ```json @@ -614,19 +1534,11 @@ spec: "Name": "us-east-ingress", "Listeners": [ { - "Port": 80, - "Protocol": "http", + "Port": 3456, + "Protocol": "tcp", "Services": [ { - "Name": "api", - "RequestHeaders": { - "Add": { - "x-gateway": "us-east-ingress" - } - }, - "ResponseHeaders": { - "Remove": ["x-debug"] - } + "Name": "db" } ] } @@ -636,32 +1548,24 @@ spec: - - +#### Consul Enterprise + ```hcl Kind = "ingress-gateway" Name = "us-east-ingress" Namespace = "default" -Partition = "default" +Partition = "team-frontend" Listeners = [ { - Port = 80 - Protocol = "http" + Port = 3456 + Protocol = "tcp" Services = [ { - Name = "api" - Namespace = "frontend" - RequestHeaders { - Add { - "x-gateway" = "us-east-ingress" - } - } - ResponseHeaders { - Remove = ["x-debug"] - } + Namespace = "ops" + Name = "db" } ] } @@ -676,17 +1580,11 @@ metadata: namespace: default spec: listeners: - - port: 80 - protocol: http + - port: 3456 + protocol: tcp services: - - name: api - namespace: frontend - requestHeaders: - add: - x-gateway: us-east-ingress - responseHeaders: - remove: - - x-debug + - name: db + namespace: ops ``` ```json @@ -694,23 +1592,15 @@ spec: "Kind": "ingress-gateway", "Name": "us-east-ingress", "Namespace": "default", - "Partition": "default", + "Partition": "team-frontend", "Listeners": [ { - "Port": 80, - "Protocol": "http", + "Port": 3456, + "Protocol": "tcp", "Services": [ { - "Name": "api", - "Namespace": "frontend", - "RequestHeaders": { - "Add": { - "x-gateway": "us-east-ingress" - } - }, - "ResponseHeaders": { - "Remove": ["x-debug"] - } + "Namespace": "ops", + "Name": "db" } ] } @@ -720,88 +1610,112 @@ spec: - - +### Use wildcards to define an HTTP listener + +The following example gateway is named `us-east-ingress` and defines two listeners. 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 `max_connections` of the ingress gateway proxy to each upstream cluster is set to `4096`. + +The Consul Enterprise version implements the following additional configurations: -For this use-case, the `api` service is not an actual registered service. It exists as a virtual service for L7 configuration only. A `service-router` (`ServiceRouter` on Kubernetes) is defined for the virtual service that uses path-based routing to route requests to different backend services: +- The ingress gateway is set up in the `default` [namespace](/consul/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](/consul/docs/enterprise/admin-partitions): + +#### Consul OSS + + + +```hcl +Kind = "ingress-gateway" +Name = "us-east-ingress" - - +TLS { + Enabled = true +} - +Defaults { + MaxConnections = 4096 +} -```hcl -Kind = "service-router" -Name = "api" -Routes = [ +Listeners = [ { - Match { - HTTP { - PathPrefix = "/billing" + Port = 8080 + Protocol = "http" + Services = [ + { + Name = "*" } - } - - Destination { - Service = "billing-api" - } + ] }, { - Match { - HTTP { - PathPrefix = "/payments" + Port = 4567 + Protocol = "http" + Services = [ + { + Name = "api" + Hosts = ["foo.example.com"] + }, + { + Name = "web" + Hosts = ["website.example.com"] } - } - - Destination { - Service = "payments-api" - } + ] } ] ``` ```yaml apiVersion: consul.hashicorp.com/v1alpha1 -kind: ServiceRouter +kind: IngressGateway metadata: - name: api + name: us-east-ingress spec: - routes: - - match: - http: - pathPrefix: '/billing' - destination: - service: billing-api - - match: - http: - pathPrefix: '/payments' - destination: - service: payments-api + tls: + enabled: true + listeners: + - port: 8080 + protocol: http + services: + - name: '*' + - port: 4567 + protocol: http + services: + - name: api + hosts: ['foo.example.com'] + - name: web + hosts: ['website.example.com'] ``` ```json { - "Kind": "service-router", - "Name": "api", - "Routes": [ + "Kind": "ingress-gateway", + "Name": "us-east-ingress", + "TLS": { + "Enabled": true + }, + "Listeners": [ { - "Match": { - "HTTP": { - "PathPrefix": "/billing" + "Port": 8080, + "Protocol": "http", + "Services": [ + { + "Name": "*" } - }, - "Destination": { - "Service": "billing-api" - } + ] }, { - "Match": { - "HTTP": { - "PathPrefix": "/payments" + "Port": 4567, + "Protocol": "http", + "Services": [ + { + "Name": "api", + "Hosts": ["foo.example.com"] + }, + { + "Name": "web", + "Hosts": ["website.example.com"] } - }, - "Destination": { - "Service": "payments-api" - } + ] } ] } @@ -809,512 +1723,118 @@ spec: - - +#### Consul Enterprise ```hcl -Kind = "service-router" -Name = "api" +Kind = "ingress-gateway" +Name = "us-east-ingress" Namespace = "default" -Partition = "default" -Routes = [ + +TLS { + Enabled = true +} + +Listeners = [ { - Match { - HTTP { - PathPrefix = "/billing" + Port = 8080 + Protocol = "http" + Services = [ + { + Namespace = "frontend" + Name = "*" } - } - - Destination { - Service = "billing-api" - Namespace = "frontend" - } + ] }, { - Match { - HTTP { - PathPrefix = "/payments" + Port = 4567 + Protocol = "http" + Services = [ + { + Namespace = "frontend" + Name = "api" + Hosts = ["foo.example.com"] + Partition = "api-team" + }, + { + Namespace = "frontend" + Name = "web" + Hosts = ["website.example.com"] + Partition = "web-team" } - } - - Destination { - Service = "payments-api" - Namespace = "frontend" - } + ] } ] ``` ```yaml apiVersion: consul.hashicorp.com/v1alpha1 -kind: ServiceRouter +kind: IngressGateway metadata: - name: api + name: us-east-ingress namespace: default spec: - routes: - - match: - http: - pathPrefix: '/billing' - destination: - service: billing-api - namespace: frontend - - match: - http: - pathPrefix: '/payments' - destination: - service: payments-api - namespace: frontend + tls: + enabled: true + listeners: + - port: 8080 + protocol: http + services: + - name: '*' + namespace: frontend + - port: 4567 + protocol: http + services: + - name: api + namespace: frontend + hosts: ['foo.example.com'] + partition: api-team + - name: web + namespace: frontend + hosts: ['website.example.com'] + partition: web-team ``` ```json { - "Kind": "service-router", - "Name": "api", + "Kind": "ingress-gateway", + "Name": "us-east-ingress", "Namespace": "default", - "Partition": "default", - "Routes": [ + "TLS": { + "Enabled": true + }, + "Listeners": [ { - "Match": { - "HTTP": { - "PathPrefix": "/billing" + "Port": 8080, + "Protocol": "http", + "Services": [ + { + "Namespace": "frontend", + "Name": "*" } - }, - "Destination": { - "Service": "billing-api", - "Namespace": "frontend" - } + ] }, { - "Match": { - "HTTP": { - "PathPrefix": "/payments" + "Port": 4567, + "Protocol": "http", + "Services": [ + { + "Namespace": "frontend", + "Name": "api", + "Hosts": ["foo.example.com"], + "Partition": "api-team" + }, + { + "Namespace": "frontend", + "Name": "web", + "Hosts": ["website.example.com"], + "Partition": "web-team" } - }, - "Destination": { - "Service": "payments-api", - "Namespace": "frontend" - } + ] } ] } ``` - - - - - -## Available Fields - -You can specify the following parameters to configure ingress gateway configuration entries. - -', - yaml: false, - }, - { - name: 'Namespace', - type: 'string: `default`', - enterprise: true, - description: - 'Specifies the namespace in which the configuration entry will apply. The value must match the namespace in which the gateway is registered.' + - ' If omitted, the namespace will be inherited from the `ns` request parameter (refer to the [`config` API endpoint documentation](/consul/api-docs/config#ns)).' + - ' or will default to the `default` namespace.', - yaml: false, - }, - { - name: 'Meta', - type: 'map: nil', - description: - 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.', - yaml: false, - }, - { - name: 'Partition', - type: `string: "default"`, - enterprise: true, - description: - 'Specifies the admin partition in which the configuration will apply. The value must match the partition in which the gateway is registered.' + - ' If omitted, the partition will be inherited from the request (refer to the [`config` API endpoint documentation](/consul/api-docs/config)).' + - ' See [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information.', - yaml: false, - }, - { - name: 'metadata', - children: [ - { - name: 'name', - description: 'Set to the name of the service being configured.', - }, - { - name: 'namespace', - enterprise: true, - description: - 'Refer to the [Kubernetes Namespaces documentation for Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise). The `namespace` parameter is not supported in Consul OSS (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)).', - }, - ], - hcl: false, - }, - { - name: 'TLS', - type: 'TLSConfig: ', - description: 'TLS configuration for this gateway.', - children: [ - { - name: 'Enabled', - type: 'bool: false', - description: { - hcl: - "Set this configuration to `true` 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 `true` 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: '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: ', - 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', - type: 'SDSConfig: ', - description: - 'Defines a set of parameters that configures the gateway to load TLS certificates from an external SDS service. See [SDS](/consul/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](/consul/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.', - }, - ], - }, - ], - }, - { - name: 'Defaults', - type: 'IngressServiceConfig: ', - description: `Default configuration that applies to all upstreams.`, - children: [ - { - name: 'MaxConnections', - type: 'int: 0', - description: `The maximum number of connections a service instance - will be allowed to establish against the given upstream. Use this to limit - HTTP/1.1 traffic, since HTTP/1.1 has a request per connection. - If not specified, it uses the default value. For example, 1024 for Envoy proxy.`, - }, - { - name: 'MaxPendingRequests', - type: 'int: 0', - description: `The maximum number of requests that will be queued - while waiting for a connection to be established. For this configuration to - be respected, a L7 protocol must be defined in the \`protocol\` field. - If not specified, it uses the default value. For example, 1024 for Envoy proxy.`, - }, - { - name: 'MaxConcurrentRequests', - type: 'int: 0', - description: `The maximum number of concurrent requests that - will be allowed at a single point in time. Use this to limit HTTP/2 traffic, - since HTTP/2 has many requests per connection. For this configuration to be - respected, a L7 protocol must be defined in the \`protocol\` field. - If not specified, it uses the default value. For example, 1024 for Envoy proxy.`, - }, - { - name: 'PassiveHealthCheck', - type: 'PassiveHealthCheck: ', - description: - 'Passive health checks remove hosts from the upstream cluster that are unreachable or that return errors.', - children: [ - { - name: 'interval', - type: 'int: ', - description: - "The time in nanosecond between checks. Each check will cause hosts which have exceeded `max_failures` to be removed from the load balancer, and any hosts which have passed their ejection time to be returned to the load balancer. If not specified, it uses the default value. For example, 10s for Envoy proxy.", - }, - { - name: 'max_failures', - type: 'int: ', - description: - 'The number of consecutive failures that cause a host to be removed from the upstream cluster. If not specified, Consul uses the proxy\'s default value. For example, `5` for Envoy proxy.', - }, - { - name: 'enforcing_consecutive_5xx', - type: 'int: ', - description: - 'A percentage representing the chance that a host will be actually ejected when the proxy detects an outlier status through consecutive errors in the 500 code range. If not specified, Consul uses the proxy\'s default value. For example, `100` for Envoy proxy.', - }, - ], - }, - ], - }, - { - name: 'Listeners', - type: 'array: )', - description: - 'A list of listeners that the ingress gateway should setup, uniquely identified by their port number.', - children: [ - { - name: 'Port', - type: 'int: 0', - description: `The port on which the ingress listener should receive - traffic. The port will be bound to the IP address that - was specified in the [\`-address\`](/consul/commands/connect/envoy#address) - flag when starting the gateway. - Note: The ingress listener port must not conflict - with the health check port specified in the \`-address\` - flag.`, - }, - { - name: 'Protocol', - type: 'string: "tcp"', - description: - 'The protocol associated with the listener. One of `tcp`, `http`, `http2`, or `grpc`.', - }, - { - name: 'Services', - type: 'array: ', - 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. A namespace is also required for - Consul Enterprise.`, - children: [ - { - name: 'Name', - type: 'string: ""', - description: `The name of the service that should be exposed - through this listener. This can be either a service registered in the - catalog, or a service defined only by [other config entries](/consul/docs/connect/l7-traffic). If the wildcard specifier, - \`*\`, is provided, then ALL services will be exposed through the listener. - This is not supported for listeners with protocol \`tcp\`.`, - }, - { - name: 'Namespace', - type: 'string: ""', - enterprise: true, - description: - 'The namespace from which to resolve the service if different than the existing namespace. The current namespace is used if unspecified.', - }, - { - name: 'Partition', - type: 'string: ""', - enterprise: true, - description: - 'The admin partition from which to resolve the service if different than the existing partition. The current partition is used if unspecified.', - }, - { - name: 'Hosts', - type: 'array: ', - description: `A list of hosts that specify what - requests will match this service. This cannot be used with a \`tcp\` - listener, and cannot be specified alongside a \`*\` service name. If not - specified, the default domain \`\.ingress.*\` will be used to - match services. Requests must send the correct host to be routed to - the defined service.

- The wildcard specifier, \`*\`, can be used by itself to match all traffic - coming to the ingress gateway, if TLS is not enabled. This allows a user - to route all traffic to a single service without specifying a host, - allowing simpler tests and demos. Otherwise, the wildcard specifier can - be used as part of the host to match multiple hosts, but only in the - leftmost DNS label. This ensures that all defined hosts are valid DNS - records. For example, \`*.example.com\` is valid, while \`example.*\` and - \`*-suffix.example.com\` are not.`, - }, - { - name: 'RequestHeaders', - type: 'HTTPHeaderModifiers: ', - description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers) - that will be applied to requests routed to this service. - This cannot be used with a \`tcp\` listener.`, - }, - { - name: 'ResponseHeaders', - type: 'HTTPHeaderModifiers: ', - description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers) - that will be applied to responses from this service. - This cannot be used with a \`tcp\` listener.`, - }, - { - name: 'TLS', - 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](/consul/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: 'MaxConnections', - type: 'int: 0', - description: 'overrides for the [`Defaults` field](#available-fields)', - }, - { - name: 'MaxPendingRequests', - type: 'int: 0', - description: 'overrides for the [`Defaults` field](#available-fields)', - }, - { - name: 'MaxConcurrentRequests', - type: 'int: 0', - description: 'overrides for the [`Defaults` field](#available-fields)', - }, - { - name: 'PassiveHealthCheck', - type: 'PassiveHealthCheck: ', - description: 'overrides for the [`Defaults` field](#available-fields)', - children: [ - { - name: 'interval', - type: 'int: ', - }, - { - name: 'max_failures', - type: 'int: ', - }, - { - name: 'enforcing_consecutive_5xx', - type: 'int: ', - }, - ], - }, - ], - }, - { - name: 'TLS', - type: 'TLSConfig: ', - description: 'TLS configuration for this listener.', - children: [ - { - name: 'Enabled', - type: 'bool: false', - description: { - hcl: - "Set this configuration to `true` 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. 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.

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.", - }, - }, - { - 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: - '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`.', - }, - { - name: 'CipherSuites', - type: 'array: ', - 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: ', - description: - 'Defines a set of parameters that configures the listener to load TLS certificates from an external SDS service. See [SDS](/consul/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](/consul/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.', - }, - ], - }, - ], - }, - ], - }, - ]} -/> + \ No newline at end of file diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx deleted file mode 100644 index b5a8cc213f..0000000000 --- a/website/content/docs/connect/gateways/ingress-gateway.mdx +++ /dev/null @@ -1,281 +0,0 @@ ---- -layout: docs -page_title: Ingress Gateway | Service Mesh -description: >- - Ingress gateways listen for requests from external network locations and route authorized traffic to destinations in the service mesh. Use custom TLS certificates with ingress gateways through Envoy's gRPC Secret Discovery Service (SDS). ---- - -# Ingress Gateways - --> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. - -Ingress gateways enable connectivity within your organizational network from services outside the Consul -service mesh to services in the mesh. An ingress gateway is -a type of proxy and must be registered as a service in Consul, with the -[kind](/consul/api-docs/agent/service#kind) set to "ingress-gateway". They are an -entrypoint for outside traffic and allow you to define what services should be -exposed and on what port. You configure an ingress gateway by defining a set of -[listeners](/consul/docs/connect/config-entries/ingress-gateway#listeners) that each map -to a set of backing -[services](/consul/docs/connect/config-entries/ingress-gateway#services). - -To enable easier service discovery, a new Consul [DNS -subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups) is provided, on -`.ingress.`. - -For listeners with a -[protocol](/consul/docs/connect/config-entries/ingress-gateway#protocol) other than -`tcp`, multiple services can be specified for a single listener. In this -case, the ingress gateway relies on host/authority headers to decide the -service that should receive the traffic. The host used to match traffic -defaults to the [Consul DNS ingress -subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups), but can be changed using -the [hosts](/consul/docs/connect/config-entries/ingress-gateway#hosts) field. - -![Ingress Gateway Architecture](/img/ingress-gateways.png) - -## Prerequisites - -Ingress gateways also require that your Consul datacenters are configured correctly: - -- You'll need to use Consul version 1.8.0 or newer. -- Consul [service mesh](/consul/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers. -- [gRPC](/consul/docs/agent/config/config-files#grpc_port) must be enabled on all client agents. - -Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul. - -## Running and Using an Ingress Gateway - -For a complete example of how to allow external traffic inside your Consul service mesh, -review the [ingress gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-ingress-gateways). - -## Ingress Gateway Configuration - -Ingress gateways are configured in service definitions and registered with Consul like other services, with two exceptions. -The first is that the [kind](/consul/api-docs/agent/service#kind) must be "ingress-gateway". Second, -the ingress gateway service definition may contain a `Proxy.Config` entry just like a -service mesh proxy service, to define opaque configuration parameters useful for the actual proxy software. -For Envoy there are some supported [gateway options](/consul/docs/connect/proxies/envoy#gateway-options) as well as -[escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides). - --> **Note:** If ACLs are enabled, ingress gateways must be registered with a token granting `service:write` for the ingress gateway's service name, -`service:read` for all services in the ingress gateway's configuration entry, and `node:read` for all nodes of the services -in the ingress gateway's configuration entry. These privileges authorize the token to route communications to other mesh services. -If the Consul client agent on the gateway's node is not configured to use the default gRPC port, 8502, then the gateway's token -must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies. - -~> [Configuration entries](/consul/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 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 -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 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. - -### Configure Static SDS Cluster(s) - -Each Envoy proxy that makes up this Ingress Gateway must define one or more additional [static -clusters](/consul/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. - -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. - - 1. **Register the proxy service.** - - 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" - - Proxy { - Config { - envoy_extra_static_clusters_json = <- + Ingress gateways enable you to connect external services to services in your mesh. Ingress gateways are a type of proxy that listens for requests from external network locations and route authorized traffic to destinations in the service mesh. +--- + +# Ingress gateways overview + +An ingress gateway is a type of proxy that enables network connectivity from external services to services inside the mesh. The following diagram describes the ingress gateway workflow: + +![Ingress Gateway Architecture](/img/ingress-gateways.png) + +## Workflow + +The following stages describe how to add an ingress gateway to your service mesh: + +1. Configure ingress gateway listeners: Create an ingress gateway configuration entry and specify which services to expose to external requests. The configuration entry allows you to define what services should be exposed, on what port, and by what hostname. You can expose services registered with Consul or expose virtual services defined in other configuration entries. Refer to [Ingress gateway configuration entry reference](/consul/docs/connect/config-entries/ingress-gateway) for details on the configuration parameters you can specify. + +1. Define an ingress gateway proxy service: Ingress gateways are a special-purpose proxy service that you can define and register in a similar manner to other services. When you register the ingress gateway service, Consul applies the configurations defined in the ingress gateway configuration reference. Refer to [Implement an ingress gateway](/consul/docs/connect/gateways/ingress-gateway/usage) for additional information. + +1. Start the network proxy: The ingress gateway proxy service accepts configurations from the configuration entry and directs requests to the exposed services. When the external traffic passes through the ingress gateway, your sidecar proxy handles the inbound and outbound connections between the exposed services and the gateway. Refer to [Service mesh proxy overview](/consul/docs/connect/proxies) to learn more about the proxies Consul supports. + +## Integrations with custom TLS management solutions + +You can configure the ingress gateway to retrieve and serve custom TLS certificates from external systems. This functionality is designed to help you integrate with custom TLS management software. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information. \ No newline at end of file diff --git a/website/content/docs/connect/gateways/ingress-gateway/tls-external-service.mdx b/website/content/docs/connect/gateways/ingress-gateway/tls-external-service.mdx new file mode 100644 index 0000000000..d1e480b446 --- /dev/null +++ b/website/content/docs/connect/gateways/ingress-gateway/tls-external-service.mdx @@ -0,0 +1,246 @@ +--- +layout: docs +page_title: Serve custom TLS certificates from an external service +description: Learn how to configure ingress gateways to serve TLS certificates from an external service to using secret discovery service. The SDS feature is designed for developers building integrations with custom TLS management solutions. +--- + +# Serve custom TLS certificates from an external service + +This is an advanced topic that describes how to configure ingress gateways to serve TLS certificates sourced from an external service to inbound traffic using secret discovery service (SDS). SDS is a low-level feature designed for developers building integrations with custom TLS management solutions. For instructions on more common ingress gateway implementations, refer to [Implement an ingress gateway](/consul/docs/connect/gateways/ingress-gateway/usage). + +## Overview + +The following process describes the general procedure for configuring ingress gateways to serve TLS certificates sourced from external services: + +1. Configure static SDS clusters in the ingress gateway service definition. +1. Register the service definition. +1. Configure TLS client authentication +1. Start Envoy. +1. Configure SDS settings in an ingress gateway configuration entry. +1. Register the ingress gateway configuration entry with Consul. + +## Requirements + +- The external service must implement Envoy's [gRPC secret discovery service (SDS) API](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret). +- You should have some familiarity with Envoy configuration and the SDS protocol. +- The [`connect.enabled` parameter](/consul/docs/agent/config/config-files#connect) must be set to `true` for all server agents in the Consul datacenter. +- The [`ports.grpc` parameter](/consul/docs/agent/config/config-files#connect) must be configured for all server agents in the Consul datacenter. + +### ACL requirements + +If ACLs are enabled, you must present a token when registering ingress gateways that grant the following permissions: + +- `service:write` for the ingress gateway's service name +- `service:read` for all services in the ingress gateway's configuration entry +- `node:read` for all nodes of the services in the ingress gateway's configuration entry. + +These privileges authorize the token to route communications to other services in the mesh. If the Consul client agent on the gateway's node is not configured to use the default gRPC port, `8502`, then the gateway's token must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies. + +## Configure static SDS clusters + +You must define one or more additional static clusters in the ingress gateway service definition for each Envoy proxy associated with the gateway. The additional clusters define how Envoy should connect to the required SDS services. + +Configure the static clusters in the [`Proxy.Config.envoy_envoy_extra_static_clusters_json`](/consul/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) parameter in the service definition. + +The clusters must provide connection information and any necessary authentication information, such as mTLS credentials. + +You must manually register the ingress gateway with Consul proxy to define extra clusters in Envoy's bootstrap configuration. You can not use the `-register` flag with `consul connect envoy -gateway=ingress` to automatically register the proxy to define static clusters. + +In the following example, the `public-ingress` gateway includes a static cluster named `sds-cluster` that specifies paths to the SDS certificate and SDS certification validation files: + + + + +```hcl +Services { + Name = "public-ingress" + Kind = "ingress-gateway" + + Proxy { + Config { + envoy_extra_static_clusters_json = < + +Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-clusters) for details about configuration parameters for SDS clusters. + +## Register the ingress gateway service definition + +Issue the `consul services register` command on the Consul agent on the Envoy proxy's node to register the service. The following example command registers an ingress gateway proxy from a `public-ingress.hcl` file: + +```shell-session +$ consul services register public-ingress.hcl +``` + +Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for additional information about registering services in Consul. + +## Configure TLS client authentication + +Store TLS client authentication files, certificate files, and keys on disk where the Envoy proxy runs and ensure that they are available to Consul. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap) for details on configuring authentication files. + +The following example specifies certificate chain: + + + + +```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" + } + } + } + ] +} +``` + + + +The following example specifies the validation context: + + + +```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" + } + } + } + ] +} +``` + + + +## Start Envoy + +Issue the `consul connect envoy` command to bootstrap Envoy. The following example starts Envoy and registers it as a service called `public-ingress`: + +```shell-session +$ ​​consul connect envoy -gateway=ingress -service public-ingress +``` + +Refer to [Consul Connect Envoy](/consul/commands/connect/envoy) for additional information about using the `consul connect envoy` command. + +## Define an ingress gateway configuration entry + +Create an ingress gateway configuration entry that enables the gateway to use certificates from SDS. The configuration entry also maps downstream ingress listeners to upstream services. Configure the following fields: + +- [`Kind`](/consul/docs/connect/config-entries/ingress-gateway#kind): Set the value to `ingress-gateway`. +- [`Name`](/consul/docs/connect/config-entries/ingress-gateway#name): Consul applies the configuration entry settings to ingress gateway proxies with names that match the `Name` field. +- [`TLS`](/consul/docs/connect/config-entries/ingress-gateway#tls): The main `TLS` parameter for the configuration entry holds the SDS configuration. You can also specify TLS configurations per listener and per service. + - [`TLS.SDS`](/consul/docs/connect/config-entries/ingress-gateway#tls-sds): The `SDS` map includes the following configuration settings: + - [`ClusterName`](/consul/docs/connect/config-entries/ingress-gateway#tls-sds-clustername): Specifies the name of the cluster you specified when [configuring the SDS cluster](#configure-static-SDS-clusters). + - [`CertResource`](/consul/docs/connect/config-entries/ingress-gateway#tls-sds-certresource): Specifies the name of the certificate resource to load. +- [`Listeners`](/consul/docs/connect/config-entries/ingress-gateway#listeners): Specify one or more listeners. + - [`Listeners.Port`](/consul/docs/connect/config-entries/ingress-gateway#listeners-port): Specify a port for the listener. Each listener is uniquely identified by its port number. + - [`Listeners.Protocol`](/consul/docs/connect/config-entries/ingress-gateway#listeners-protocol): The default protocol is `tcp`, but you must specify the protocol used by the services you want to allow traffic from. + - [`Listeners.Services`](/consul/docs/connect/config-entries/ingress-gateway#listeners-services): The `Services` field contains the services that you want to expose to upstream services. The field contains several options and sub-configurations that enable granular control over ingress traffic, such as health check and TLS configurations. + +For Consul Enterprise service meshes, you may also need to configure the [`Partition`](/consul/docs/connect/config-entries/ingress-gateway#partition) and [`Namespace`](/consul/docs/connect/config-entries/ingress-gateway#namespace) fields for the gateway and for each exposed service. + +Refer to [Ingress gateway configuration entry reference](/consul/docs/connect/config-entries/ingress-gateway) for details about the supported parameters. + +The following example directs Consul to retrieve `example.com-public-cert` certificates from an SDS cluster named `sds-cluster` and serve them to all listeners: + + + +```hcl +Kind = "ingress-gateway" +Name = "public-ingress" + +TLS { + SDS { + ClusterName = "sds-cluster" + CertResource = "example.com-public-cert" + } +} + +Listeners = [ + { + Port = 8443 + Protocol = "http" + Services = ["*"] + } +] +``` + + + +## Register the ingress gateway configuration entry + +You can register the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). Refer to [How to Use Configuration Entries](/consul/docs/agent/config-entries) for details about applying configuration entries. + +The following example registers an ingress gateway configuration entry named `public-ingress-cfg.hcl` that is stored on the local system: + +```shell-session +$ consul config write public-ingress-cfg.hcl +``` + +The Envoy instance starts a listener on the port specified in the configuration entry and fetches the TLS certificate named from the SDS server. \ No newline at end of file diff --git a/website/content/docs/connect/gateways/ingress-gateway/usage.mdx b/website/content/docs/connect/gateways/ingress-gateway/usage.mdx new file mode 100644 index 0000000000..2b4c55e279 --- /dev/null +++ b/website/content/docs/connect/gateways/ingress-gateway/usage.mdx @@ -0,0 +1,127 @@ +--- +layout: docs +page_title: Implement an ingress gateway +description: Learn how to implement ingress gateways, which are Consul service mesh constructs that listen for requests from external network locations and route authorized traffic to destinations in the service mesh. +--- + +# Implement an ingress gateway + +This topic describes how to add ingress gateways to your Consul service mesh. Ingress gateways enable connectivity within your organizational network by allowing services outside of the service mesh to send traffic to services in the mesh. Refer to [Ingress gateways overview](/consul/docs/connect/gateways/ingress-gateway/) for additional information about ingress gateways. + +This topic describes ingress gateway usage for virtual machine (VM) environments. Refer to [Configure ingress gateways for Consul on Kubernetes](/consul/docs/k8s/connect/ingress-gateways) for instructions on how to implement ingress gateways in Kubernetes environments. + +## Overview + +Ingress gateways are a type of proxy service included with Consul. Complete the following steps to set up an ingress gateway: + +1. Define listeners and the services they expose. Specify these details in an ingress gateway configuration entry. +1. Register an ingress gateway service. Define the services in a service definition file. +1. Start the ingress gateway. This step deploys the Envoy proxy that functions as the ingress gateway. + +After specifying listeners and services in the ingress gateway configuration entry, you can register the gateway service and start Envoy with a single CLI command instead of completing these steps separately. Refer [Register an ingress service on Envoy startup](#register-an-ingress-service-on-envoy-startup). + +## Requirements + +- Service mesh must be enabled for all agents. Set the [`connect.enabled` parameter](/consul/docs/agent/config/config-files#connect) to `true` to enable service mesh. +- The gRPC port must be configured for all server agents in the datacenter. Specify the gRPC port in the [`ports.grpc` parameter](/consul/docs/agent/config/config-files#grpc_port). We recommend setting the port to `8502` to simplify configuration when ACLs are enabled. Refer to [ACL requirements](#acl-requirements) for additional information. +- You must use Envoy for sidecar proxies in your service mesh. Refer to [Envoy Proxy Configuration for Service Mesh](/consul/docs/connect/proxies/envoy) for supported versions. + +### ACL requirements + +If ACLs are enabled, you must present a token when registering ingress gateways that grant the following permissions: + +`service:write` for the ingress gateway's service name +`service:read` for all services in the ingress gateway's configuration entry +`node:read` for all nodes of the services in the ingress gateway's configuration entry. + +These privileges authorize the token to route communications to other services in the mesh. If the Consul client agent on the gateway's node is not configured to use the default `8502` gRPC port, then the gateway's token must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies. + +## Expose services + +Define and apply an ingress gateway configuration entry to specify which services in the mesh to expose to external services. + +### Define an ingress gateway configuration entry + +Ingress gateway configuration entries map downstream ingress listeners to upstream services. When you register an ingress gateway proxy that matches the configuration entry name, Consul applies the settings specified in the configuration entry. Configure the following fields: + +- [`Kind`](/consul/docs/connect/config-entries/ingress-gateway#kind): Set the value to `ingress-gateway`. +- [`Name`](/consul/docs/connect/config-entries/ingress-gateway#name): Consul applies the configuration entry settings to ingress gateway proxies with names that match the `Name` field. +- [`Listeners`](/consul/docs/connect/config-entries/ingress-gateway#listeners): Specify one or more listeners. + - [`Listeners.Port`](/consul/docs/connect/config-entries/ingress-gateway#listeners-port): Specify a port for the listener. Each listener is uniquely identified by its port number. + - [`Listeners.Protocol`](/consul/docs/connect/config-entries/ingress-gateway#listeners-protocol): The default protocol is `tcp`, but you must specify the protocol used by the services you want to allow traffic from. + - [`Listeners.Services`](/consul/docs/connect/config-entries/ingress-gateway#listeners-services): The `Services` field contains the services that you want to expose to upstream services. The field contains several options and sub-configurations that enable granular control over ingress traffic, such as health check and TLS configurations. + +For Consul Enterprise service meshes, you may also need to configure the [`Partition`](/consul/docs/connect/config-entries/ingress-gateway#partition) and [`Namespace`](/consul/docs/connect/config-entries/ingress-gateway#namespace) fields for the gateway and for each exposed service. + +Refer to [Ingress gateway configuration entry reference](/consul/docs/connect/config-entries/ingress-gateway) for details about the supported parameters. + +### Register an ingress gateway configuration entry + +You can register the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). Refer to [How to Use Configuration Entries](/consul/docs/agent/config-entries) for details about applying configuration entries. + +The following example registers an ingress gateway configuration entry named `public-ingress.hcl` that is stored on the local system: + +```shell-session +$ consul config write public-ingress.hcl +``` + +## Deploy an ingress gateway service + +To deploy an ingress gateway service, create a service definition and register it with Consul. + +You can also define an ingress gateway service and register it with Consul while starting an Envoy proxy from the command line. Refer to [Register an ingress service on Envoy startup](#register-an-ingress-service-on-envoy-startup) for details. + +### Create a service definition for the ingress gateway + +Consul applies the settings defined in the ingress gateway configuration entry to ingress gateway services that match the configuration entry name. Refer to [Define services](/consul/docs/services/usage/define-services) for additional information about defining services in Consul. + +The following fields are required for the ingress gateway service definition: + +- [`Kind`](/consul/docs/services/configuration/services-configuration-reference#kind): The field must be set to `ingress-gateway`. +- [`Name`](/consul/docs/services/configuration/services-configuration-reference#name): The name should match the value specified for the `Name` field in the configuration entry. + +All other service definition fields are optional, but we recommend defining health checks to verify the health of the gateway. Refer to [Services configuration reference](/consul/docs/services/configuration/services-configuration-reference) for information about defining services. + +### Register the ingress gateway proxy service + +You can register the ingress gateway using API or CLI. Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions on registering services in Consul. + +The following example registers an ingress gateway defined in `ingress-gateway.hcl` from the Consul CLI: + +```shell-session +$ consul services register ingress-service.hcl +``` + +## Start an Envoy proxy + +Run the `consul connect envoy` command to start Envoy. Specify the name of the ingress gateway service and include the `-gateway=ingress` flag. Refer to [Consul Connect Envoy](/consul/commands/connect/envoy) for details about using the command. + +The following example starts Envoy for the `ingress-service` gateway service: + +```shell-session +$ consul connect envoy -gateway=ingress ingress-service +``` + +### Register an ingress service on Envoy startup + +You can also automatically register the ingress gateway service when starting the Envoy proxy. Specify the following flags with the `consul connect envoy` command: + +- `-gateway=ingress` +- `-register` +- `-service=` + +The following example starts Envoy and registers an ingress gateway service named `ingress-service` bound to the agent address at port `8888`: + +```shell-session +$ consul connect envoy -gateway=ingress -register \ + -service ingress-service \ + -address '{{ GetInterfaceIP "eth0" }}:8888' +``` +You cannot register the ingress gateway service and start the proxy at the same time if you configure the gateway to retrieve and serve TLS certificates from their external downstreams. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for more information. + +## Additional Envoy configurations + +Ingress gateways support additional Envoy gateway options and escape-hatch overrides. Specify gateway options in the ingress gateway service definition to use them. To use escape-hatch overrides, you must add them to your global proxy defaults configuration entry. Refer to the following documentation for additional information: + +- [Gateway options](/consul/docs/connect/proxies/envoy#gateway-options) +- [Escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index ec1afef6f1..e8f3ce7d59 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -674,7 +674,24 @@ }, { "title": "Ingress Gateways", - "path": "connect/gateways/ingress-gateway" + "routes": [ + { + "title": "Overview", + "path": "connect/gateways/ingress-gateway" + }, + { + "title": "Implement an ingress gateway", + "path": "connect/gateways/ingress-gateway/usage" + }, + { + "title": "Serve TLS certificates from an external service", + "path": "connect/gateways/ingress-gateway/tls-external-service" + }, + { + "title": "Configuration", + "href": "/consul/docs/connect/config-entries/ingress-gateway" + } + ] }, { "title": "Terminating Gateways",