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.

• Kind: string | must be "tcp-route"
• Name: string | no default
• Namespace: string | no default
  Enterprise
• Partition: string | no default
  Enterprise
• Meta: map | no default
• Services: list | no default
  • Name: string | no default
  • Namespace: string | no default
    Enterprise
  • Partition: string | no default
    Enterprise
  • TLS: map | no default
    • SDS: map | no default
      • ClusterName: string | inherited from listener/gateway TLS SDS cluster when omitted
      • CertResource: string | required when SDS is configured
  • Limits: map | none
    • MaxConnections: number | none
    • MaxPendingRequests: number | none
    • MaxConcurrentRequests: number | none
• Parents: list | no default
  • Kind: string | must be "api-gateway"
  • Name: string | no default
  • Namespace: string | no default
    Enterprise
  • Partition: string | no default
    Enterprise
  • SectionName: string | no default

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

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

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

• Default: none
• Data type: list of maps with these fields:
  • Name
  • Namespace
    Enterprise
  • Partition
    Enterprise
  • TLS
  • Limits

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

• Default: none. If unspecified, Consul uses the gateway-level default for the same field when available. Otherwise the proxy default applies.
• Data type: Map that can contain the following fields:
  • MaxConnections
  • MaxPendingRequests
  • MaxConcurrentRequests

Services.Limits.MaxConnections

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

Values

• Default: none. If unspecified, Consul uses Defaults.MaxConnections when available.
• Data type: Integer

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

• Default: none. If unspecified, Consul uses Defaults.MaxPendingRequests when available.
• Data type: Integer

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

• Default: none. If unspecified, Consul uses Defaults.MaxConcurrentRequests when available.
• Data type: Integer

Parents[]

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

Values

• Default: none
• Data type: list of maps with the following fields:
  • Kind
  • Name
  • Namespace
    Enterprise
  • Partition
    Enterprise
  • SectionName

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.

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

• api-gateway configuration entry
• http-route configuration entry