TCPRoute resource configuration reference
This page provides reference information for the TCPRoute resource, which defines L7 TCP traffic within the service mesh.
This custom resource definition (CRD) describes a GAMMA resource that requires the v2 catalog API. It is not compatible with the v1 catalog API. For more information about GAMMA resources, refer to the Kubernetes Gateway API documentation.
Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in an TCPRoute CRD. Click on a property name to view additional details, including default values.
apiVersion
: string | required | must be set tomesh.consul.hashicorp.com/v2beta1
kind
: string | required | must be set toTCPRoute
metadata
: object | requiredspec
: object | requiredparentRefs
: map | requiredrules
: map | requiredbackendRefs
: mapbackendRef
: mapweight
: integer
Complete configuration
When every field is defined, a TCPRoute CRD has the following form:
Specification
This section provides details about the fields you can configure in the TCPRoute custom resource definition (CRD).
apiVersion
Specifies the version of the Consul API for integrating with Kubernetes. The value must be mesh.consul.hashicorp.com/v2beta1
.
Values
- Default: None
- This field is required.
- String value that must be set to
mesh.consul.hashicorp.com/v2beta1
.
kind
Specifies the type of CRD to implement. Must be set to TCPRoute
.
Values
- Default: None
- This field is required.
- Data type: String value that must be set to
TCPRoute
.
metadata
Map that contains an arbitrary name for the CRD and the namespace it applies to.
Values
- Default: None
- Data type: Map
metadata.name
Specifies a name for the CRD. The name is metadata that you can use to reference the resource when performing Consul operations, such as using the consul resource
command. Refer to consul resource
for more information.
Values
- Default: None
- This field is required.
- Data type: String
metadata.namespace
Enterprise
Specifies the namespace that the service resolver applies to. Refer to namespaces for more information.
Values
- Default: None
- Data type: String
spec
Map that contains the details about the TCPRoute
CRD. The apiVersion
, kind
, and metadata
fields are siblings of the spec field. All other configurations are children.
When using this CRD, the spec
field must align with GAMMAs resource. Refer to TCPRoute in the Kubernetes documentation.
Values
- Default: None
- This field is required.
- Data type: Map
spec.parentRefs
Specifies the resources to attach the route to. Usually these are services. You cannot reference the same parentsRefs
multiple times. Instead, specify each spec.parentRefs.ref
in the same block.
Values
- Default: None
- This field is required.
- Data type: Map
spec.parentRefs.port
Specifies the name of the Consul service's port that the configuration applies to.
Values
- Default: None
- Data type: String
spec.parentRefs.ref
Specifies the resource that the configuration applies to.
Values
- Default: None
- Data type: Map
spec.parentRefs.ref.name
Specifies the user-defined name of the resource that the configuration applies to.
Values
- Default: None
- Data type: String
spec.parentRefs.ref.section
Specifies the section of the resource that the configuration applies to.
Values
- Default: None
- Data type: String
spec.parentRefs.ref.tenancy
Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration applies to.
Values
Default: None
Data type: Map containing the following parameters:
Parameter Description Data type Default namespace
Identifies the namespace of the resource the configuration applies to. String None partition
Identifies the admin partition of the resource the configuration applies to. String None peerName
Identifies the name of a cluster peer the resource is imported from that the configuration applies to. String None
spec.parentRefs.ref.type
Specifies the type of resource that the configuration applies to. To reference a service in the Consul catalog, configure the resource type as catalog.v2beta1.Service
.
Values
Default: None
Data type: Map containing the following parameters:
Parameter Description Data type Default group
Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to catalog
.String None groupVersion
Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to v2beta1
.String (in code, should be int based on desc.) None kind
Specifies the kind of the Kubernetes object the resource applies to. To reference a service in the Consul catalog, set this parameter to Service
.String None
spec.rules
Specifies rules for sidecar proxies to direct a service's TCP traffic within the service mesh.
Values
- Default: None
- Data type: Map
spec.rules.backendRefs
Specifies the Kubernetes Service backend to direct TCP traffic to when a request matches the service described in spec.parentRefs
. The Service backend is the collection of endpoint IPs for the service. Refer to the Kubernetes Gateway API specification for more information about Service backends.
When a valid Service backend cannot be reached and no additional filters apply, traffic that matches the rule returns a 500 status code.
When different Service backends are specified with spec.rules.backendRefs.weight
and one is invalid, the relative weights are maintained and traffic is not adjusted automatically. For example, when traffic is configured in a 50-50 split between api
and admin
and no valid endpoints for admin
can be reached, the 50% of traffic intended for admin
returns with a 500 status code.
Values
- Default: None
- Data type: Map
spec.rules.backendRefs.backendRef
Specifies an individual Service backend where matching requests should be sent.
Values
- Default: None
- Data type: Map
spec.rules.backendRefs.backendRef.datacenter
Specifies the name of the Consul datacenter that registered the Service backend that the configuration routes traffic to.
Values
- Default: None
- Data type: String
spec.rules.backendRefs.backendRef.port
Specifies the name of the port for the Consul service that the configuration routes traffic to.
Values
- Default: None
- Data type: String
spec.rules.backendRefs.backendRef.ref
The Consul service that the configuration routes traffic to.
Values
- Default: None
- Data type: Map
spec.rules.backendRefs.backendRef.ref.name
Specifies the user-defined name of the resource that the configuration routes traffic to.
Values
- Default: None
- Data type: String
spec.rules.backendRefs.backendRef.ref.section
Specifies the section the resource that the configuration routes traffic to.
Values
- Default: None
- Data type: String
spec.rules.backendRefs.backendRef.ref.tenancy
Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration routes to.
Values
Default: None
Data type: Map containing the following parameters:
Parameter Description Data type Default namespace
Identifies the namespace of the resource the configuration routes traffic to. String None partition
Identifies the admin partition of the resource the configuration routes traffic to. String None peerName
Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. String None
spec.rules.backendRefs.backendRef.ref.type
Specifies the type of resource that the configuration routes traffic to. To reference a service in the Consul catalog, configure the resource type as catalog.v2beta1.Service
.
Values
Default: None
Data type: Map containing the following parameters:
| Parameter | Description | Data type | Default | |
group
| Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter tocatalog
. | String | None | |groupVersion
| Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter tov2beta1
. | String (in code, should be int based on desc.) | None | |kind
| Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter toService
. | String | None |
spec.rules.backendRefs.weight
Specifies the proportion of requests routed to the specified service.
This proportion is relative to the sum of all weights in the spec.rules.backendRefs
block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, 100% of traffic is forwarded.
When this parameter is not specified, it assumes the default value 1
.
Values
- Default:
1
- Data type: Integer
Examples
The following examples demonstrate common TCPRoute CRD configuration patterns for specific use cases.
Split TCP traffic between two ports
The following example splits traffic for the api
service. TCP traffic for services registered to the Consul catalog that are available at the api-workload
port is split so that 50% of the traffic routes to the service at the api-workload
port and 50% routes to the service at the admin-workload
port.