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

TCP route configuration entry reference

This topic provides reference information for the gateway TCP routes configuration entry. Refer to Route Resource Configuration for information about configuring API gateways in Kubernetes environments.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in a tcp-route configuration entry.

Complete configuration

When every field is defined, a tcp-route configuration entry has the following form:

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

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

Services = [
  {
    Name = "<name of service>"
    Namespace = "<enterprise: namespace of the service>"
    Partition = "<enterprise: partition of the service>"
    TLS = {
      SDS = {
        ClusterName = "<optional SDS cluster name>"
        CertResource = "<required SDS certificate resource>"
      }
    }
    Limits = {
      MaxConnections = <number>
      MaxPendingRequests = <number>
      MaxConcurrentRequests = <number>
      PassiveHealthCheck = {
        Interval = "<time between ejection analysis sweeps>"
        MaxFailures = <number>
        EnforcingConsecutive5xx = <percentage>
        MaxEjectionPercent = <percentage>
        BaseEjectionTime = "<base ejection duration>"
      }
    }
  }
]

Parents = [
  {
    Kind = "api-gateway"
    Name = "<name of the api-gateway to bind to>"
    Namespace = "<enterprise: namespace of the parent>"
    Partition = "<enterprise: partition of the parent>"
    SectionName = "<listener on the api-gateway to bind to>"
  }
]

Specification

This section provides details about the fields you can configure in the tcp-route configuration entry.

Kind

Specifies the type of configuration entry to implement. This must be set to "tcp-route".

Values

  • Default: none
  • This field is required.
  • Data type: string value that must be set to tcp-route.

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

Values

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

Services[]

Specifies the TCP service that the API gateway routes incoming requests to.

Values

Note: tcp-route currently supports a maximum of one service.

Services[].Name

Specifies the TCP-based service to route to.

Values

  • Default: none
  • Data type: string

Services[].Namespace
Enterprise

Specifies the Enterprise namespace where the service is located.

Values

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

Services[].Partition
Enterprise

Specifies the Enterprise admin partition where the service is located.

Values

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

Services[].TLS

Specifies service-level TLS settings for this TCP route service.

Values

  • Default: none
  • Data type: map

Services[].TLS.SDS

Specifies SDS certificate selection for this route service.

Values

  • Default: none
  • Data type: map

Services[].TLS.SDS.ClusterName

Specifies the SDS cluster used to fetch the certificate resource.

Values

  • Default: inherits the effective listener SDS cluster (Listeners[].TLS.SDS.ClusterName, falling back to top-level api-gateway.TLS.SDS.ClusterName)
  • Data type: string

Services[].TLS.SDS.CertResource

Specifies the SDS certificate resource name for this route service.

Values

  • Default: none
  • This field is required when Services[].TLS.SDS is set.
  • Data type: string

Services.Limits

Specifies upstream circuit-breaker limits for the routed destination service.

These values override any gateway-level defaults configured in the parent api-gateway configuration entry. If the same upstream service is referenced by multiple routes or listeners attached to the same gateway, Consul applies the lowest non-zero value for each limit when generating the shared Envoy cluster.

Values

Services.Limits.MaxConnections

Specifies the maximum number of upstream connections this routed service is allowed to establish.

Values

Services.Limits.MaxPendingRequests

Specifies the maximum number of requests that are allowed to queue while waiting to establish an upstream connection.

The attached API gateway listener must use an L7 protocol such as http, http2, or grpc for this configuration to take effect.

Values

Services.Limits.MaxConcurrentRequests

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

The attached API gateway listener must use an L7 protocol such as http, http2, or grpc for this configuration to take effect.

Values

Services.Limits.PassiveHealthCheck

Specifies the passive health check for this routed destination service. Passive health checks configure Envoy outlier detection, which removes service instances that return consecutive errors from the gateway's load balancing pool.

This value replaces the Defaults.PassiveHealthCheck value configured in the parent api-gateway configuration entry for this service. Consul does not merge individual fields from the gateway default into this value. When multiple routes or listeners attached to the same gateway reference the same upstream service with different passive health checks, Consul applies only one of them to the shared Envoy cluster. Configure the same passive health check for a service across all routes on a gateway.

The map can contain the following fields:

Refer to Defaults.PassiveHealthCheck in the API gateway configuration reference for more information about the gateway default.

Values

  • Default: none. If unspecified, Consul uses Defaults.PassiveHealthCheck when available. Otherwise, Envoy uses its default outlier detection settings.
  • Data type: Map

Services.Limits.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.

Services.Limits.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

Services.Limits.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

Services.Limits.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

Services.Limits.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

Services.Limits.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

Services.Limits.PassiveHealthCheck.MaxEjectionPercent

Specifies the maximum percentage of hosts in the 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

Services.Limits.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.

Parents[]

Specifies the list of gateways that the route is bound to.

Values

Parents[].Kind

Specifies the type of resource to bind to. This field is required and must be set to "api-gateway".

Values

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

Parents[].Name

Specifies the name of the API gateway to bind to.

Values

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

Parents[].Namespace
Enterprise

Specifies the Enterprise namespace where the parent is located.

Values

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

Parents[].Partition
Enterprise

Specifies the Enterprise admin partition where the parent is located.

Values

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

Parents[].SectionName

Specifies the name of the listener in the parent api-gateway configuration entry. If this field is empty, the route binds to all listeners on the parent gateway.

A tcp-route can only bind to API gateway listeners that use the tcp protocol. To route traffic from listeners that use the http, http2, or grpc protocol, use an http-route.

Values

  • Default: ""
  • Data type: string

TLS SDS behavior and precedence

For certificate selection, Consul applies this order:

  1. tcp-route service Services[].TLS.SDS
  2. API gateway listener Listeners[].TLS.SDS
  3. API gateway top-level TLS.SDS

Additional behavior:

  • If Services[].TLS.SDS is set, CertResource must be provided.
  • For TCP routes, hostnames are not required for service-level SDS.
  • If ClusterName is omitted at service level, it is inherited from listener or gateway SDS.
  • A TCP listener can only have one distinct effective service override; conflicting overrides on the same listener are rejected.

Example: inherit listener/gateway SDS cluster

Kind = "tcp-route"
Name = "tcp-route-inherit"

Parents = [
  {
    Kind = "api-gateway"
    Name = "api-gateway"
    SectionName = "tcp"
  }
]

Services = [
  {
    Name = "payments"
    TLS = {
      SDS = {
        CertResource = "payments.internal.example.com"
      }
    }
  }
]

Example: explicit service SDS cluster override

Kind = "tcp-route"
Name = "tcp-route-explicit"

Parents = [
  {
    Kind = "api-gateway"
    Name = "api-gateway"
    SectionName = "tcp"
  }
]

Services = [
  {
    Name = "orders"
    TLS = {
      SDS = {
        ClusterName = "local_sds_cluster"
        CertResource = "orders.internal.example.com"
      }
    }
  }
]

Related pages

Edit this page on GitHub