HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul
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>"
}

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

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.

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.

Values

TLS.Enabled

Enables TLS at the gateway default level.

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

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.

Values

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

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