Ingress gateway configuration reference
Note
Ingress gateway is deprecated and will not be enhanced beyond its current capabilities. Ingress gateway is fully supported in this version but will be removed in a future release of Consul.
Consul's API gateway is the recommended alternative to ingress gateway.
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 for additional information.
Configuration model
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.
Kind
: string | must beingress-gateway
| requiredName
: string | requiredNamespace
: string |default
| EnterpriseMeta
: map of stringsPartition
: string |default
| EnterpriseTLS
: mapEnabled
: boolean |false
TLSMinVersion
: string |TLSv1_2
TLSMaxVersion
: stringCipherSuites
: list of stringsSDS
: map of stringsClusterName
: stringCertResource
: string
Defaults
: mapMaxConnections
: numberMaxPendingRequests
: numberMaxConcurrentRequests
: numberPassiveHealthCheck
: mapInterval
: numberMaxFailures
: numberEnforcingConsecutive5xx
: numberMaxEjectionPercent
: numberBaseEjectionTime
: string
Listeners
: list of mapsPort
: number |0
Protocol
: number |tcp
Services
: list of objectsName
: stringNamespace
: string | EnterprisePartition
: string | EnterpriseHosts
: List of strings |.ingress.*
RequestHeaders
: mapResponseHeaders
: mapTLS
: mapSDS
: map of stringsClusterName
: stringCertResource
: string
MaxConnections
: number |0
MaxPendingRequests
: number |0
MaxConcurrentRequests
: number |0
PassiveHealthCheck
: mapInterval
: numberMaxFailures
: numberEnforcingConsecutive5xx
: numberMaxEjectionPercent
: numberBaseEjectionTime
: string
TLS
: mapEnabled
: boolean |false
TLSMinVersion
: string |TLSv1_2
TLSMaxVersion
: stringCipherSuites
: list of stringsSDS
: map of stringsClusterName
: stringCertResource
: string
Complete configuration
When every field is defined, an ingress gateway configuration entry has the following form:
Specification
This section provides details about the fields you can configure in the ingress gateway configuration entry.
Kind
Specifies the type of configuration entry. Must be set to ingress-gateway
.
Values
- Default: None
- This field is required.
- Data type: String value that must be set to
ingress-gateway
.
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.
Values
- Default: None
- This field is required.
- Data type: String
Namespace
Enterprise
Specifies the namespace to apply the configuration entry in. Refer to 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 to register the configuration entry by specifying the ns
query parameter.
Values
- Default:
default
, - Data type: String
Partition
Enterprise
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 for additional information.
If unspecified, the ingress gateway is applied to the default
partition. You can override the partition when using the /config
API endpoint to register the configuration entry by specifying the partition
query parameter.
Values
- Default: `default
- Data type: String
Meta
Defines an arbitrary set of key-value pairs to store in the Consul KV.
Values
- Default: None
- Data type: Map of one or more key-value pairs.
- keys: String
- values: String, integer, or float
TLS
Specifies the TLS configuration settings for the gateway.
Values
- Default: No default
- Data type: Object that can contain the following fields:
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
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
- Envoy v1.22.0 and later:
- Data type: String with one of the following values:
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
- Envoy v1.22.0 and later:
- Data type: String with one of the following values:
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 for a list of supported ciphers.
TLS.SDS
Specifies parameters for loading the TLS certificates from an external SDS service. Refer to Serve custom TLS certificates from an 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:
Listeners.TLS.SDS
: Configures SDS settings for all services in the listener.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:
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:
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 is1024
. - 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
.
Values
- Default value is
0
, which instructs Consul to use the proxy's configuration. For Envoy, the default is1024
. - 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
.
Values
- Default value is
0
, which instructs Consul to use the proxy's configuration. For Envoy, the default is1024
. - 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 between checks. | string | 0s |
MaxFailures | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | 0 |
EnforcingConsecutive5xx | 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 | 100 |
MaxEjectionPercent | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | 10 |
BaseEjectionTime | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the BaseEjectionTime multiplied by the number of times the host has been ejected. | string | 30s |
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:
Listeners[].Port
Specifies the port that the listener receives traffic on. The port is bound to the IP address specified in the -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:
Values
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:
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 for additional information.
- Provide a
*
wildcard to expose all services in the datacenter. Wild cards are not supported for listeners configured for TCP. Refer toListeners[].Protocol
for additional information.
Values
- Default: None
- Data type: String
Listeners[].Services[].Namespace
Enterprise
Specifies the namespace to use when resolving the location of the service.
Values
- Default: Current namespace
- Data type: String
Listeners[].Services[].Partition
Enterprise
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 <service>.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 for an example configuration.
Values
Default: None
Data type: Object containing one or more fields that define header modification rules:
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. | 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. | 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 for an example configuration.
Values
Default: None
Data type: Map containing one or more fields that define header modification rules:
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. | 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. | 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
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 for additional information.
This configuration overrides the main TLS.SDS
settings for configuration entry. If unspecified, Consul applies the top-level TLS.SDS
settings.
Values
Default: None
Data type: Map containing the following fields:
The following table describes how to configure SDS parameters. Refer to 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
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
field of the configuration entry.
Listeners must use an L7 protocol for this configuration to take effect. Refer to 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
field of the configuration entry.
Listeners must use an L7 protocol for this configuration to take effect. Refer to 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
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 between checks. | string | 0s |
MaxFailures | Specifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer. | integer | 0 |
EnforcingConsecutive5xx | 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 | 100 |
MaxEjectionPercent | Specifies the maximum percentage of an upstream cluster that Consul ejects when the proxy reports an outlier. Consul ejects at least one host when an outlier is detected regardless of the value. | integer | 10 |
BaseEjectionTime | Specifies the minimum amount of time that an ejected host must remain outside the cluster before rejoining. The real time is equal to the value of the BaseEjectionTime multiplied by the number of times the host has been ejected. | string | 30s |
Listeners[].TLS
Specifies the TLS configuration for the listener. If unspecified, Consul applies any service-specific TLS configurations. If neither the listener- nor service-specific TLS configurations are specified, Consul applies the main TLS
settings for the configuration entry.
Values
- Default: None
- Data type: Map that can contain the following fields:
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
- Envoy v1.22.0 and later:
- Data type: String with one of the following values:
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
- Envoy v1.22.0 and later:
- Data type: String with one of the following values:
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 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 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
settings for each service.
Values
- Default: None
- The data type is a map containing
ClusterName
andCertResource
fields.
The following table describes how to configure SDS parameters. Refer to 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 |
Examples
Refer to the following examples for common ingress gateway configuration patterns:
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 CE
Consul Enterprise
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:
- The ingress gateway is set up in the
default
namespace and proxies traffic to all services in thefrontend
namespace. - The
api
andweb
services are proxied to team-specific admin partitions:
Consul CE
Consul Enterprise