Ingress gateway configuration entry 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 be ingress-gateway | required
• Name: string | required
• Namespace: string | default | EnterpriseEnterprise
• Meta: map of strings
• Partition: string | default | EnterpriseEnterprise
• TLS: map
  • Enabled: boolean | false
  • TLSMinVersion: string | TLSv1_2
  • TLSMaxVersion: string
  • CipherSuites: list of strings
  • SDS: map of strings
    • ClusterName: string
    • CertResource: string
• Defaults: map
  • MaxConnections: number
  • MaxPendingRequests: number
  • MaxConcurrentRequests: number
  • PassiveHealthCheck: map
    • interval: number
    • max_failures: number
    • enforcing_consecutive_5xx: number

• Listeners: list of maps

  • Port: number | 0
  • Protocol: number | tcp
  • Services: list of objects
    • Name: string
    • Namespace: string | EnterpriseEnterprise
    • Partition: string | EnterpriseEnterprise
    • Hosts: List of strings | .ingress.*
    • RequestHeaders: map
      • Add: map of strings
      • Set: map of strings
      • Remove: list of strings
    • ResponseHeaders: map
      • Add: map of strings
      • Set: map of strings
      • Remove: list of strings
    • TLS: map
      • SDS: map of strings
        • ClusterName: string
        • CertResource: string
    • MaxConnections: number | 0
    • MaxPendingRequests: number | 0
    • MaxConcurrentRequests: number | 0
    • PassiveHealthCheck: map
      • interval: number
      • max_failures: number
      • enforcing_consecutive_5xx: number
  • TLS: map
    • Enabled: boolean | false
    • TLSMinVersion: string | TLSv1_2
    • TLSMaxVersion: string
    • CipherSuites: list of strings
    • SDS: map of strings
      • ClusterName: string
      • CertResource: string

• apiVersion: string | must be set to consul.hashicorp.com/v1alpha1 | required

• kind: string | must be IngressGateway | required
• metadata: map of strings
  • name: string | required
  • namespace: string | default | EnterpriseEnterprise
• spec: map
  • tls: map
    • enabled: boolean | false
    • tlsMinVersion: string | TLSv1_2
    • tlsMaxVersion: string
    • cipherSuites: list of strings
    • sds: map of strings
      • clusterName: string
      • certResource: string
  • defaults: map
    • maxConnections: number
    • maxPendingRequests: number
    • maxConcurrentRequests: number
    • passiveHealthCheck: map
      • interval: number | no proxy’s default value
      • max_failures: number | no proxy’s default value
      • enforcing_consecutive_5xx: number | proxy’s default value
  • listeners: list of maps
    • port: number | 0
    • protocol: number | tcp
    • services: list of maps
      • name: string
      • namespace: string | current namespace | EnterpriseEnterprise
      • partition: string | current partition | EnterpriseEnterprise
      • hosts: list of strings | .ingress.*
      • requestHeaders: map
        • add: map of strings
        • set: map of strings
        • remove: list of strings
      • responseHeaders: map
        • add: map of strings
        • set: map of strings
        • remove: list of strings
      • tls: map
        • sds: map of strings
          • clusterName: string
          • certResource: string
      • maxConnections: number | 0
      • maxPendingRequests: number | 0
      • maxConcurrentRequests: number | 0
      • passiveHealthCheck: map
        • interval: number
        • max_failures: number
        • enforcing_consecutive_5xx: number
    • tls: map
      • enabled: boolean | false
      • tlsMinVersion: string | TLSv1_2
      • tlsMaxVersion: string
      • cipherSuites: list of strings
      • sds: map of strings
        • clusterName: string
        • certResource: string

Complete configuration

When every field is defined, an ingress gateway configuration entry has the following form:

Kind      = "ingress-gateway"          
Name      = "<name of the gateway>"    
Namespace = "<namespace to register the gateway>" 
Partition = "<partition to register the gateway>" 
Meta = {       
  <key> = "<value>"
}
TLS = {        
  Enabled       = false         
  TLSMinVersion = "TLSv1_2"     
  TLSMaxVersion = "<max version of TLS supported for this gateway>"  
  CipherSuites = [   
    "<cipher>"
  ]
  SDS = {      
    ClusterName  = "<name of SDS cluster>"   
    CertResource = "<SDS resource name>"     
  }
}
Defaults = {         
  MaxConnections        = 0      
  MaxPendingRequests    = 0      
  MaxConcurrentRequests = 0      
  PassiveHealthCheck = {            
    interval                  = 10  
    max_failures              = 5   
    enforcing_consecutive_5xx = 100 
  }
}
Listeners = [           
  {                     
    Port     = 0        
    Protocol = "tcp"    
    Services = [        
      {                 
        Name      = "<name of external service>"                  
        Namespace = "<namespace containing the external service>" 
        Partition = "<partition containing the external service>" 
        Hosts = [       
          ".ingress.*"  
        ]
        RequestHeaders = {    
          Add = {             
            RequestHeaderName = "<request header value to add>"  
          }
          Set = {             
            RequestHeaderName = "<request header value to set>" 
          }
          Remove = [          
            "<request header to remove>"    
          ]
        }
        ResponseHeaders = {   
          Add = {             
            ResponseHeaderName = "<response header value to add>"  
          }
          Set = {             
            ResponseHeaderName = "<response header value to set>"  
          }
          Remove = [          
            "<response header remove>"   
          ]
        }
        TLS = {            
          SDS = {            
            ClusterName  = "<name of SDS cluster>"   
            CertResource = "<name of SDS source>"    
          }
        }
        MaxConnections        = <number>      
        MaxPendingRequests    = <number>      
        MaxConcurrentRequests = <number>      
        PassiveHealthCheck = {            
          interval                  = 10  
          max_failures              = 5   
          enforcing_consecutive_5xx = 100 
        }
    }]
    TLS = {                       
      Enabled       = false      
      TLSMinVersion = "TLSv1_2"  
      TLSMaxVersion = "<max supported version for the listener>" 
      CipherSuites = [     
        "<ciphersuite>"    
      ]
      SDS = {                    
        ClusterName  = "<name of SDS cluster>" 
        CertResource = "<SDS resource name>"   
      }
    }
  }
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway          
metadata:
  name: <name of the gateway>    
  namespace: "<namespace to register the gateway>" 
spec: 
  tls:         
    enabled: false         
    tlsSMinVersion: TLSv1_2     
    tlsMaxVersion: "<max version of TLS supported for this gateway>"  
    cipherSuites:    
     - <cipher>
    sds:      
      clusterName: <name of SDS cluster>   
      certResource: <SDS resource name>     
  defaults:          
    maxConnections: 0      
    maxPendingRequests: 0      
    maxConcurrentRequests: 0      
    passiveHealthCheck:            
      interval: 10  
      max_failures: 5   
      enforcing_consecutive_5xx: 100 
  listeners:                     
    - port: 0        
      protocol: tcp    
      services:         
        - name: <name of external service>                  
          namespace: <namespace containing the external service> 
          partition: <partition containing the external service>
          hosts:       
            - .ingress.*  
          requestHeaders:     
            add:             
              requestHeaderName: <request header value to add>
            set:
              requestHeaderName: <request header value to set>
     remove:           
              - <request header to remove>    
          responseHeaders:  
            add:             
              responseHeaderName: <response header value to add>  
            set:             
              responseHeaderName: <response header value to set>
            remove:
              - <response header remove>   
          tls:            
            sds:            
              clusterName: <name of SDS cluster>
              certResource: <name of SDS source>    
            maxConnections: <number>      
            maxPendingRequests: <number>      
            maxConcurrentRequests: <number>      
            passiveHealthCheck:            
              interval: 10  
              max_failures: 5   
              enforcing_consecutive_5xx: 100        
      tls:                       
        enabled: false      
        tlsMinVersion: TLSv1_2  
        tlsMaxVersion: <max supported version for the listener> 
        cipherSuites:      
          - <ciphersuite>    
        sds:                    
          clusterName: <name of SDS cluster> 
          certResource: <SDS resource name>

{
  "Kind" : "ingress-gateway",          
  "Name" : "<name of the gateway>",    
  "Namespace" : "<namespace to register the gateway>", 
  "Partition" : "<partition to register the gateway>", 
  "Meta": {       
    "<key>" : "<value>"
  },
  "TLS" : {        
    "Enabled" : false,         
    "TLSMinVersion" : "TLSv1_2",     
    "TLSMaxVersion" : "<max version of TLS supported for this gateway>",  
    "CipherSuites" : [   
      "<cipher>"
    ],
    "SDS": {      
      "ClusterName" : "<name of SDS cluster>",   
      "CertResource" : "<SDS resource name>"     
    }
  },
  "Defaults" : {         
    "MaxConnections" : 0,      
    "MaxPendingRequests" : 0,      
    "MaxConcurrentRequests": 0,      
    "PassiveHealthCheck" : {            
      "interval" : 10,  
      "max_failures" : 5,   
      "enforcing_consecutive_5xx" : 100 
    }
  },
  "Listeners" : [           
    {                     
      "Port" : 0,        
      "Protocol" : "tcp",    
      "Services" : [        
        {                 
          "Name" : "<name of external service>",                  
          "Namespace" : "<namespace containing the external service>", 
          "Partition" : "<partition containing the external service>", 
          "Hosts" :  [       
            ".ingress.*"  
          ],
          "RequestHeaders" : {    
            "Add" : {             
              "RequestHeaderName" : "<request header value to add>"  
            },
            "Set" : {             
              "RequestHeaderName" : "<request header value to set>" 
            },
            "Remove" : [          
              "<request header to remove>"    
            ]
          },
          "ResponseHeaders" : {   
            "Add" : {             
              "ResponseHeaderName" : "<response header value to add>"  
            },
            "Set" : {             
              "ResponseHeaderName" : "<response header value to set>"  
            },
            "Remove" : [          
              "<response header remove>"   
            ]
          },
          "TLS" : {            
            "SDS" : {            
              "ClusterName" : "<name of SDS cluster>",   
              "CertResource" : "<name of SDS source>"    
            }
          },
          "MaxConnections" : <number>,      
          "MaxPendingRequests" : <number>,      
          "MaxConcurrentRequests" : <number>,      
          "PassiveHealthCheck" : {            
            "interval" : 10,  
            "max_failures" : 5,   
            "enforcing_consecutive_5xx" : 100 
          }
        }
      ],
      "TLS" : {                       
        "Enabled" : false,      
        "TLSMinVersion" : "TLSv1_2",  
        "TLSMaxVersion" : "<max supported version for the listener>", 
        "CipherSuites" : [     
          "<ciphersuite>"    
        ],
        "SDS" : {                    
          "ClusterName" : "<name of SDS cluster>", 
          "CertResource" : "<SDS resource name>"   
        }
      }
    }
  ]
}

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 EnterpriseEnterprise

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 EnterpriseEnterprise

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:
  • Enabled
  • TLSMinVersion
  • TLSMaxVersion
  • CipherSuites
  • SDS

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
• Data type: String with one of the following values:
  • TLS_AUTO
  • TLSv1_0
  • TLSv1_1
  • TLSv1_2
  • TLSv1_3

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

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.

TSL.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:
  • ClusterName
  • CertResource

The following table describes how to configure SDS parameters.

Defaults

Specifies default configurations for connecting upstream services.

Values

• Default: None

• The data type is a map containing the following parameters:

  • MaxConnnections
  • MaxPendingRequests
  • 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.

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.

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:

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
  • Protocol
  • Services[]
  • TLS

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:

• 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
  • Namespace EnterpriseEnterprise
  • Partition EnterpriseEnterprise
  • Hosts
  • RequestHeaders
  • ResponseHeaders`
  • TLS
  • MaxConnections
  • MaxPendingRequests
  • MaxConcurrentRequests
  • 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 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 for additional information.

Values

• Default: None
• Data type: String

Listeners[].Services[].Namespace EnterpriseEnterprise

Specifies the namespace to use when resolving the location of the service.

Values

• Default: Current namespace
• Data type: String

Listeners[].Services[].Partition EnterpriseEnterprise

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:

  • 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:

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:

  • 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:

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:

  • ClusterName
  • CertResource

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:

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:
  • Enabled
  • TLSMinVersion
  • TLSMaxVersion
  • CipherSuites
  • 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 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 and CertResource fields.

The following table describes how to configure SDS parameters. Refer to Configure static SDS clusters for usage information:

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
  • 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.

Values

• Default: None
• This field is required.
• Data type: String

metadata.namespace EnterpriseEnterprise

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

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
  • defaults
  • 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
  • tlsMinVersion
  • tlsMaxVersion
  • cipherSuites
  • 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 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 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: Configures SDS settings for all services in the listener.
• 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.

spec.defaults

Specifies default configurations for upstream connections.

Values

• Default: None

• The data type is a map containing the following parameters:

  • maxConnnections
  • maxPendingRequests
  • 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.

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.

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:

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
  • protocol
  • services[]
  • 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 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 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
  • namespace EnterpriseEnterprise
  • partition EnterpriseEnterprise
  • hosts
  • requestHeaders
  • responseHeaders`
  • tlsLS
  • maxConnections
  • maxPendingRequests
  • maxConcurrentRequests
  • 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 for additional information. Refer to 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 for additional information.

Values

• Default: None
• Data type: String

spec.listeners[].services[].namespace EnterpriseEnterprise

Specifies the namespace to use when resolving the location of the service.

Values

• Default: Current namespace
• Data type: String

spec.listeners[].services[].partition EnterpriseEnterprise

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 <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 *

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 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:

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 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:

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 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 for additional information.

If unspecified, Consul applies the sds settings configured for the ingress gateway. If both are specified, this configuration overrides the settings for configuration entry.

Values

• 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 for usage information:

spec-listeners[].services[].maxConnections

Specifies the maximum number of HTTP/1.1 connections a service instance is allowed to establish against the upstream.

A value specified in this field overrides the maxConnections field specified in the defaults configuration.

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 field specified in the defaults configuration.

Listeners must use an L7 protocol for this configuration to take effect. Refer to 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 field specified in the defaults configuration entry.

Listeners must use an L7 protocol for this configuration to take effect. Refer to 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 configuration.

Values

• Default: None
• Data type: Map

The following table describes the configurations for passive health checks:

spec.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:
  • enabled
  • tlsMinVersion
  • tlsMaxVersion
  • cipherSuites
  • 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 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 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 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 for usage information:

Examples

Refer to the following examples for common ingress gateway configuration patterns:

• Define a TCP listener
• Use wildcards to define listeners
• HTTP listener with path-based routes

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

Kind = "ingress-gateway"
Name = "us-east-ingress"
Listeners = [
  {
    Port     = 3456
    Protocol = "tcp"
    Services = [
      {
        Name = "db"
      }
    ]
  }
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
  name: us-east-ingress
spec:
  listeners:
    - port: 3456
      protocol: tcp
      services:
        - name: db

{
  "Kind": "ingress-gateway",
  "Name": "us-east-ingress",
  "Listeners": [
    {
      "Port": 3456,
      "Protocol": "tcp",
      "Services": [
        {
          "Name": "db"
        }
      ]
    }
  ]
}

Consul Enterprise

Kind = "ingress-gateway"
Name = "us-east-ingress"
Namespace = "default"
Partition = "team-frontend"
Listeners = [
  {
    Port     = 3456
    Protocol = "tcp"
    Services = [
      {
        Namespace = "ops"
        Name = "db"
      }
    ]
  }
]

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

{
  "Kind": "ingress-gateway",
  "Name": "us-east-ingress",
  "Namespace": "default",
  "Partition": "team-frontend",
  "Listeners": [
    {
      "Port": 3456,
      "Protocol": "tcp",
      "Services": [
        {
          "Namespace": "ops",
          "Name": "db"
        }
      ]
    }
  ]
}

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 the frontend namespace.
• The api and web services are proxied to team-specific admin partitions:

Consul OSS

Kind = "ingress-gateway"
Name = "us-east-ingress"
TLS {
  Enabled = true
}
Defaults {
  MaxConnections = 4096
}
Listeners = [
  {
    Port     = 8080
    Protocol = "http"
    Services = [
      {
        Name = "*"
      }
    ]
  },
  {
    Port     = 4567
    Protocol = "http"
    Services = [
      {
        Name  = "api"
        Hosts = ["foo.example.com"]
      },
      {
        Name  = "web"
        Hosts = ["website.example.com"]
      }
    ]
  }
]

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']

{
  "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"]
        }
      ]
    }
  ]
}

Consul Enterprise

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"
      }
    ]
  }
]

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

{
  "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"
        }
      ]
    }
  ]
}