HashiConf 2024 Now streaming live from Boston! Attend for free
Consul
Consul Home

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.

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        = <number>
  MaxPendingRequests    = <number>
  MaxConcurrentRequests = <number>
  PassiveHealthCheck = {
    Interval                = "<the time between checks>"
    MaxFailures             = <number>
    EnforcingConsecutive5xx = <number>
    MaxEjectionPercent      = <number>
    BaseEjectionTime        = "<the base time that a host is ejected for>"
  }
}
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                = "<the time between checks>"
          MaxFailures             = <number>
          EnforcingConsecutive5xx = <number>
          MaxEjectionPercent      = <number>
          BaseEjectionTime        = "<the base time that a host is ejected for>"
        }
    }]
    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 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

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

Values

The following table describes how to configure SDS parameters.

ParameterDescriptionData type
ClusterNameSpecifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration.String
CertResourceSpecifies 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

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:

ParameterDescriptionData typeDefault
IntervalSpecifies the time between checks.string0s
MaxFailuresSpecifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer.integer0
EnforcingConsecutive5xxSpecifies 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.integer100
MaxEjectionPercentSpecifies 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.integer10
BaseEjectionTimeSpecifies 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.string30s

Listeners[]

Specifies a list of listeners in the mesh for the gateway. Listeners are uniquely identified by their port number.

Values

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

  • Default: tcp

  • Data type: String that contains one of the following 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

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

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

RuleDescriptionData type
AddDefines 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
SetDefines 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
RemoveDefines 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:

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

RuleDescriptionData type
AddDefines 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
SetDefines 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
RemoveDefines 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

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:

ParameterDescriptionData typeDefault
IntervalSpecifies the time between checks.string0s
MaxFailuresSpecifies the number of consecutive failures allowed per check interval. If exceeded, Consul removes the host from the load balancer.integer0
EnforcingConsecutive5xxSpecifies 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.integer100
MaxEjectionPercentSpecifies 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.integer10
BaseEjectionTimeSpecifies 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.string30s

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

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:

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:

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:

ParameterDescriptionData type
ClusterNameSpecifies the name of the SDS cluster where Consul should retrieve certificates. The cluster must be specified in the gateway's bootstrap configuration.String
CertResourceSpecifies 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

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

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 CE

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

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"
      }
    ]
  }
]
Edit this page on GitHub