HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul Home

API gateway configuration reference

This topic provides reference information for the API gateway configuration entry that you can deploy to networks in virtual machine (VM) environments. For reference information about configuring Consul API gateways on Kubernetes, refer to Gateway Resource Configuration.

Introduction

A gateway is a type of network infrastructure that determines how service traffic should be handled. Gateways contain one or more listeners that bind to a set of hosts and ports. An HTTP Route or TCP Route can then attach to a gateway listener to direct traffic from the gateway to a service.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in an api-gateway configuration entry. Click on a property name to view additional details, including default values.

TLS SDS precedence

For downstream certificate selection, Consul resolves the effective TLS/SDS source in this order:

  1. Route service override (http-route/tcp-route service TLS.SDS)
  2. Listener TLS.SDS
  3. Gateway top-level TLS.SDS

When route service TLS.SDS.ClusterName is omitted, Consul inherits from the effective listener TLS/SDS config.

Complete configuration

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

Kind = "api-gateway"
Name = "<name of api gateway>"
Namespace = "<enterprise: namespace of the gateway>"
Partition = "<enterprise: partition of the gateway>"

Meta = {
  <any key> = "<any value>"
}

ExtAuthz = {
  Enabled = true
}

TLS = {
  Enabled = true
  SDS = {
    ClusterName  = "<sds cluster>"
    CertResource = "<gateway default cert resource>"
  }
  TLSMinVersion = "<version of TLS>"
  TLSMaxVersion = "<version of TLS>"
  CipherSuites = [
    "<cipher suite>"
  ]
}
Defaults = {
  MaxConnections = <number>
  MaxPendingRequests = <number>
  MaxConcurrentRequests = <number>
  PassiveHealthCheck = {
    Interval = "<time between ejection analysis sweeps>"
    MaxFailures = <number>
    Consecutive5xx = <number>
    ConsecutiveGatewayFailure = <number>
    EnforcingConsecutive5xx = <percentage>
    EnforcingConsecutiveGatewayFailure = <percentage>
    MaxEjectionPercent = <percentage>
    BaseEjectionTime = "<base ejection duration>"
  }
}

Listeners = [
  {
    Port = <external service port>
    Name = "<unique name for this listener>"
    Protocol = "<protocol used by external service>"
    MaxRequestHeadersKB = <maximum header size in kilobytes>
    TLS = {
      MaxVersion = "<version of TLS>"
      MinVersion = "<version of TLS>"
      CipherSuites = [
        "<cipher suite>"
      ]
      SDS = {
        ClusterName  = "<listener sds cluster>"
        CertResource = "<listener cert resource>"
      }
      # Certificates and SDS are mutually exclusive on the same listener.
      # Certificates = [
      #   {
      #     Kind = "file-system-certificate"
      #     Name = "<name of file-system-certificate>"
      #     Namespace = "<enterprise: namespace of the certificate>"
      #     Partition = "<enterprise: partition of the certificate>"
      #   }
      # ]
    }
    default = {
      JWT = {
        Providers = [
          {
            Name = "<provider>"
            VerifyClaims = {
              Path = ["<path to claim>"]
              Value = "<value of claim>"
            }
          }
        ]
      }
    }
    override = {
      JWT = {
        Providers = [
          {
            Name = "<provider>"
            VerifyClaims = {
              Path = ["<path to claim>"]
              Value = "<value of claim>"
            }
          }
        ]
      }
    }
  }
]

Specification

This section provides details about the fields you can configure in the api-gateway configuration entry.

Kind

Specifies the type of configuration entry to implement. This must be api-gateway.

Values

  • Default: none
  • This field is required.
  • Data type: string value that must be set to "api-gateway".

Name

Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster.

Values

  • Default: none
  • This field is required.
  • Data type: string

Namespace
Enterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

  • Default: "default" in Enterprise
  • Data type: string

Partition
Enterprise

Specifies the Enterprise admin partition to apply to the configuration entry.

Values

  • Default: "default" in Enterprise
  • Data type: string

Meta

Specifies an arbitrary set of key-value pairs to associate with the gateway.

Values

  • Default: none
  • Data type: map containing one or more keys and string values.

ExtAuthz
Enterprise

Specifies the default external authorization behavior for routes behind the gateway. When set to true, Envoy runs the external authorization check for every route unless a route opts out with an http-route ExtAuthz filter. When set to false, Envoy skips the external authorization check by default and routes must opt-in.

Values

  • Default: none
  • Data type: map

ExtAuthz.Enabled
Enterprise

Specifies the default external authorization behavior for routes behind the gateway. When set to true, Envoy runs the external authorization check for every route unless a route opts out with an http-route ExtAuthz filter. When set to false, Envoy skips the external authorization check by default and routes must opt-in.

Values

  • Default: true
  • Data type: boolean

TLS

Specifies top-level TLS defaults for the API gateway. Listener TLS settings can override these defaults.

Defaults

Specifies default upstream circuit-breaker limits for services reached through routes attached to the API gateway.

Service-specific limits configured on http-route destination services or tcp-route destination services override these values. When multiple attached routes reference the same upstream service, Consul applies the lowest non-zero value for each limit so the generated Envoy cluster remains consistent.

Defaults can also contain a PassiveHealthCheck map that configures the default passive health check, or Envoy outlier detection, for services reached through routes attached to the API gateway.

Values

TLS.Enabled

Enables TLS at the gateway default level.

When set to true, the gateway terminates downstream TLS on every listener. If a listener does not reference a certificate in Listeners[].TLS.Certificates and no SDS certificate applies to it, the gateway uses its Consul service mesh leaf certificate. Consul issues and rotates the leaf certificate automatically, so you do not need to provide a certificate or private key.

The leaf certificate includes the following DNS subject alternative names (SANs) so that clients can verify the gateway certificate against the Consul service mesh CA:

When routes target services in a non-default namespace or admin partition, the wildcard SANs include the namespace and partition, for example *.api-gateway.<namespace>.<partition>.<domain>. When you configure an alt_domain, the certificate also includes the equivalent SANs for the alternate domain.

Certificates that you configure on a listener take precedence for requests whose server name indication (SNI) matches the certificate hosts. The leaf certificate serves all other requests. When you configure a gateway-level TLS.SDS certificate, the SDS certificate remains the default certificate and the gateway does not serve the leaf certificate.

Refer to Terminate TLS with Consul-managed certificates for more information.

Values

  • Default: false
  • Data type: boolean

TLS.SDS

Specifies top-level SDS configuration used as fallback for listeners that do not define listener-level TLS.SDS.

Values

TLS.SDS.ClusterName

Specifies the Envoy cluster name used to connect to SDS.

Values

  • Default: none
  • Required when CertResource is set.
  • Data type: string

TLS.SDS.CertResource

Specifies the SDS certificate resource name requested by Envoy.

Values

  • Default: none
  • Required when ClusterName is set.
  • Data type: string

TLS.TLSMinVersion

Specifies the minimum TLS version for top-level gateway defaults.

Values

  • Default: none
  • Data type: one of TLS_AUTO, TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3

TLS.TLSMaxVersion

Specifies the maximum TLS version for top-level gateway defaults.

Values

  • Default: none
  • Data type: one of TLS_AUTO, TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3

TLS.CipherSuites[]

Specifies default cipher suites for top-level gateway defaults.

Values

Defaults.MaxConnections

Specifies the maximum number of upstream connections route destination services are allowed to establish.

Values

  • Default: 0, which instructs Consul to use the proxy's default 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 an upstream connection.

Attached listeners must use an L7 protocol such as http, http2, or grpc for this configuration to take effect.

Values

  • Default: 0, which instructs Consul to use the proxy's default configuration. For Envoy, the default is 1024.
  • Data type: Integer

Defaults.MaxConcurrentRequests

Specifies the maximum number of concurrent upstream requests that are allowed at a single point in time.

Attached listeners must use an L7 protocol such as http, http2, or grpc for this configuration to take effect.

Values

  • Default: 0, which instructs Consul to use the proxy's default configuration. For Envoy, the default is 1024.
  • Data type: Integer

Defaults.PassiveHealthCheck

Specifies the default passive health check for services reached through routes attached to the API gateway. Passive health checks configure Envoy outlier detection, which removes upstream service instances that return consecutive errors from the gateway's load balancing pool.

The passive health check applies to every route destination service that does not define its own passive health check. A passive health check configured on an http-route destination service or tcp-route destination service replaces the gateway default for that service. Consul does not merge individual fields from the gateway default into the service-level passive health check.

Values

Defaults.PassiveHealthCheck.Interval

Specifies the time between outlier detection analysis sweeps. Each sweep can eject hosts from the load balancing pool or return them to the pool.

Values

  • Default: none. Envoy uses 10s.
  • Data type: String duration, such as "10s". The value cannot be negative.

Defaults.PassiveHealthCheck.MaxFailures

Specifies the number of consecutive 5xx errors that cause Envoy to eject a host from the load balancing pool.

Values

  • Default: none. Envoy uses 5.
  • Data type: Integer

Defaults.PassiveHealthCheck.Consecutive5xx

Specifies the number of consecutive 5xx errors that cause Envoy to eject a host. When set, this value overrides MaxFailures.

Values

  • Default: none
  • Data type: Integer greater than 0

Defaults.PassiveHealthCheck.ConsecutiveGatewayFailure

Specifies the number of consecutive gateway failures, such as 502, 503, or 504 errors, that cause Envoy to detect an outlier. Envoy ejects the host only when EnforcingConsecutiveGatewayFailure is greater than 0.

Values

  • Default: none. Envoy uses 5.
  • Data type: Integer greater than 0

Defaults.PassiveHealthCheck.EnforcingConsecutive5xx

Specifies the percent chance that Envoy ejects a host when it detects an outlier status through consecutive 5xx errors. Use this setting to turn off ejection or ramp it up gradually.

Values

  • Default: none. Envoy uses 100.
  • Data type: Integer from 0 to 100

Defaults.PassiveHealthCheck.EnforcingConsecutiveGatewayFailure

Specifies the percent chance that Envoy ejects a host when it detects an outlier status through consecutive gateway failures.

Values

  • Default: none. Envoy uses 0, which turns off ejection for consecutive gateway failures.
  • Data type: Integer from 0 to 100

Defaults.PassiveHealthCheck.MaxEjectionPercent

Specifies the maximum percentage of hosts in an upstream cluster that Envoy can eject at the same time. Envoy ejects at least one host regardless of the value.

Values

  • Default: none. Envoy uses 10.
  • Data type: Integer from 0 to 100

Defaults.PassiveHealthCheck.BaseEjectionTime

Specifies the base amount of time that an ejected host stays out of the load balancing pool. The actual ejection time equals the base ejection time multiplied by the number of times Envoy has ejected the host, up to a maximum of 300s.

Values

  • Default: none. Envoy uses 30s.
  • Data type: String duration, such as "30s". The value cannot be negative.

Listeners[]

Specifies a list of listeners that gateway should set up. Listeners are uniquely identified by their port number.

Values

  • Default: none
  • This field is required.
  • Data type: List of maps. Each member of the list contains the following fields:

Listeners[].Name

Specifies the unique name for the listener. This field accepts letters, numbers, and hyphens.

Values

  • Default: none
  • This field is required.
  • Data type: string

Listeners[].Port

Specifies the port number that the listener receives traffic on.

Values

  • Default: 0
  • This field is required.
  • Data type: integer

Listeners[].Hostname

Specifies the hostname that the listener receives traffic on.

Values

  • Default: "*"
  • This field is optional.
  • Data type: string

Listeners[].Protocol

Specifies the protocol associated with the listener.

The following table describes the supported protocols:

ProtocolDownstream connectionUpstream connection to servicesSupported routes
httpHTTP/1.1HTTP/1.1http-route
http2HTTP/2. TLS listeners advertise the h2 and http/1.1 ALPN protocols.HTTP/2http-route
grpcHTTP/2 with gRPC support. TLS listeners advertise the h2 and http/1.1 ALPN protocols.HTTP/2http-route
tcpTCPTCPtcp-route

The http, http2, and grpc protocols are compatible for routing, so you can bind an http-route to a listener that uses any of them. You can only bind a tcp-route to a tcp listener.

When a listener uses the http2 or grpc protocol, Consul compiles the discovery chain for each routed service with the listener protocol so that the connection from the gateway to the service also uses HTTP/2. We recommend that you set the Protocol in the service defaults configuration entry for each routed service to the same protocol as the listener.

Listeners that share a port must use the same protocol.

Values

  • Default: none
  • This field is required.
  • The data type is one of the following string values: "tcp", "http", "http2", or "grpc".

Listeners[].MaxRequestHeadersKB

Specifies the maximum size in kilobytes for request headers sent from downstream clients to upstream services. This setting applies to HTTP-based protocols only (HTTP, HTTP/2, gRPC). When requests exceed this limit, the gateway returns an HTTP 431 (Request Header Fields Too Large) error. If not specified, uses Envoy's default limit (60KB).

Values

  • Default: 60 (Envoy's default value)
  • Data type: Integer

Listeners[].TLS

Specifies TLS configuration for the listener.

Values

Listeners[].TLS.SDS

Specifies listener-level SDS configuration.

Values

Listeners[].TLS.SDS and Listeners[].TLS.Certificates are mutually exclusive.

Listeners[].TLS.SDS.ClusterName

Specifies the Envoy cluster name used by the listener for SDS.

Values

  • Default: none
  • Required when CertResource is set.
  • Data type: string

Listeners[].TLS.SDS.CertResource

Specifies the SDS certificate resource name for the listener.

Values

  • Default: none
  • Required when ClusterName is set.
  • Data type: string

Listeners[].TLS.Certificates[]

The list of references to file system or inline certificates that the listener uses for TLS termination. You should create the configuration entry for the certificate separately and then reference the configuration entry in the Name field.

Values

  • Default: None
  • Data type: List of maps.

Listeners[].default

Specifies a block of default configurations to apply to the gateway listener. All routes attached to the listener inherit the default configurations. You can specify override configurations that have precedence over default configurations in the override block as well as in the JWT block in the HTTP route configuration entry.

Values

  • Default: None
  • Data type: Map

Listeners[].override

Specifies a block of configurations to apply to the gateway listener. The override settings have precedence over the configurations in the Listeners[].default block.

Values

  • Default: None
  • Data type: Map

Examples

The following examples demonstrate common API gateway configuration patterns for specific use cases.

Configure JWT verification settings

The following example configures listener-one to verify that requests include a token with Okta user permissions by default. The listener also verifies that the token has an audience of api.apps.organization.com.

Kind = "api-gateway"
Name = "api-gateway"
Listeners = [
  {
    name = "listener-one"
    port = 9001
    protocol = "http"
    override = {
      JWT = {
        Providers = [
          {
            Name = "okta"
            VerifyClaims = {
              Path = ["aud"]
              Value = "api.apps.organization.com"
            }
          }
        ]
      }
    }
    default = {
      JWT = {
        Providers = [
          {
            Name = "okta"
            VerifyClaims = {
              Path = ["perms", "role"]
              Value = "user"
            }
          }
        ]
      }
    }
  }
]

Terminate TLS with Consul-managed certificates

The following example enables TLS at the gateway level and does not reference a certificate on listener-one. The gateway terminates HTTPS on port 8443 with its Consul service mesh leaf certificate, which is valid for *.api-gateway.consul and *.api-gateway.<datacenter>.consul hostnames.

Kind = "api-gateway"
Name = "api-gateway"

TLS = {
  Enabled = true
}

Listeners = [
  {
    Name     = "listener-one"
    Port     = 8443
    Protocol = "http"
  }
]

Configure passive health checks for upstream services

The following example configures a default passive health check for all services reached through the api-gateway gateway. Envoy ejects a service instance after three consecutive 5xx errors, and can eject up to 25 percent of the instances of a service at the same time.

Kind = "api-gateway"
Name = "api-gateway"

Listeners = [
  {
    Name     = "listener-one"
    Port     = 9999
    Protocol = "http"
  }
]

Defaults = {
  PassiveHealthCheck = {
    Interval                = "10s"
    MaxFailures             = 3
    EnforcingConsecutive5xx = 80
    MaxEjectionPercent      = 25
    BaseEjectionTime        = "30s"
  }
}

To override the passive health check for a specific service, configure Limits.PassiveHealthCheck on the service in an http-route or tcp-route configuration entry.

Configure HTTP/2 and gRPC listeners

The following example configures a grpc listener on port 9999 and an http2 listener on port 9998. Bind an http-route to each listener to route traffic to gRPC and HTTP/2 services.

Kind = "api-gateway"
Name = "my-gateway"

Listeners = [
  {
    Name     = "grpc-listener"
    Port     = 9999
    Protocol = "grpc"
  },
  {
    Name     = "http2-listener"
    Port     = 9998
    Protocol = "http2"
  }
]
Edit this page on GitHub