Consul
GRPCRoute resource configuration reference
This page provides reference information for the GRPCRoute
resource, which defines L7 gRPC traffic within the service mesh.
This custom resource definition (CRD) describes a resource related to the Kubernetes GAMMA initiative 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 a gRPC route 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 toGRPCRoute
metadata
: map | requiredspec
: map | requiredparentRefs
: map | requiredrules
: map | requiredbackendRefs
: mapbackendRef
: mapdatacenter
: stringport
: stringref
: mapname
: stringtype
: mapgroup
: stringgroupVersion
: stringkind
: string
filters
: maprequestHeaderModifier
: mapresponseHeaderModifier
: mapurlRewrite
: mappathPrefix
: string
weight
: number |1
filters
: maprequestHeaderModifier
: mapresponseHeaderModifier
: mapurlRewrite
: mappathPrefix
: string
matches
: mapretries
: mapnumber
: mapvalue
: number
onConditions
: map of stringsonConnectFailure
: boolean |false
onStatusCodes
: map of numbers
timeouts
: map
Complete configuration
When every field is defined, a gRPC route resource CRD has the following form:
apiVersion: mesh.consul.hashicorp.com/v2beta1 # required
kind: GRPCRoute # required
metadata:
name: <CRDName>
namespace: <namespace>
spec:
parentRefs:
port: <portRoutedFrom>
- ref:
name: <nameRoutedFrom>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
rules:
- backendRefs:
- backendRef:
datacenter: <datacenterRoutedTo>
port: "<portRoutedTo>"
ref:
name: <nameRoutedTo>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
filters:
- requestHeaderModifier:
add:
name: <headerName>
value: <headerValue>
- responseHeaderModifier:
set:
name: <headerName>
value: <headerValue>
urlRewrite:
pathPrefix: <path/prefix>
weight: 1
filters:
requestHeaderModifier:
remove:
name: <headerName>
value: <headerValue>
responseHeaderModifier:
add:
name: <headerName>
value: <headerValue>
urlRewrite:
pathPrefix: <path/prefix>
matches:
headers:
name: <nameToMatch>
type: <typeToMatch>
value: <valueToMatch>
method:
method: <methodToMatch>
service: <serviceToMatch>
type: <typeToMatch>
retries:
number:
value: 1
onConditions: ["cancelled", "unavailable"]
onConnectFailure: false
onStatusCodes: [400, 404]
timeouts:
idle: <1s>
request: <1s>
Specification
This section provides details about the fields you can configure in the GRPCRoute
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 GRPCRoute
.
Values
- Default: None
- This field is required.
- Data type: String value that must be set to
GRPCRoute
.
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 GRPCRoute
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 closely resembles the GRPCRoute
GAMMA resource. Refer to GRPCRoute in the Kubernetes documentation.
Values
- Default: None
- This field is required.
- Data type: Map
spec.parentRefs
Specifies the services and other resources to attach the route to. You can only define one parentsRefs
configuration for each route. To attach the route to multiple resources, specify additional spec.parentRefs.ref
configurations in the parentsRefs
block. You can only specify the name of one port for the route. Any resources that send traffic through the route use the same port.
Values
- Default: None
- This field is required.
- Data type: Map
spec.parentRefs.port
Specifies the port for the Consul service that the configuration applies to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
Values
- Default: None
- Data type: String
spec.parentRefs.ref
Specifies the resource that the route attaches 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.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 Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to v2beta1
.String 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 gRPC traffic within the service mesh, including filtering, retry, and timeout behavior.
Values
- Default: None
- Data type: Map
spec.rules.backendRefs
Specifies the Kubernetes Service backend to direct GRPC 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 in spec.rules.backendRefs.weight
and one of the backends is invalid, Consul continues to apply the specified weights instead of adjusting the relative weights to exclude traffic to the invalid backend. 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 port for the Consul service that the configuration routes traffic to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
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.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 to catalog
.String None groupVersion
Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to v2beta1
.String None kind
Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter to Service
.String None
spec.rules.backendRefs.filters
Specifies filtering behavior for services configured in the same spec.rules.backendRefs
block.
Values
- Default: None
- Data type: Map
spec.rules.backendRefs.filters.requestHeaderModifier
Specifies a set of header modification rules applied to requests routed with the gRPC route resource.
Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
The following table describes how to configure values for request headers:
Rule | Description | Type |
---|---|---|
add | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can use variable placeholders. | Map of strings |
set | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can use variable placeholders. | Map of strings |
remove | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
Use variable placeholders
For add
and set
, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable %DOWNSTREAM_REMOTE_ADDRESS%
allows you to pass a value that is generated when the split occurs.
spec.rules.backendRefs.filters.responseHeaderModifier
Specifies a set of header modification rules applied to responses routed with the gRPC route resource.
Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
The following table describes how to configure values for request headers:
Rule | Description | Type |
---|---|---|
add | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can use variable placeholders. | Map of strings |
set | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can use variable placeholders. | Map of strings |
remove | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
Use variable placeholders
For add
and set
, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable %DOWNSTREAM_REMOTE_ADDRESS%
allows you to pass a value that is generated when the split occurs.
spec.rules.backendRefs.filters.urlRewrite
Specifies a path to modify the URL with when a request is forwarded.
Values
Default: None
Data type: Map containing the following parameter:
Parameter Description Data type Default pathPrefix
Specifies the path that is prepended to the URL. 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, Consul forwards 100% of traffic to the backend.
When this parameter is not specified, Consul defaults to 1
.
Values
- Default:
1
- Data type: Integer
spec.rules.filters
Specifies filtering behavior for all requests that match the service defined in spec.parentRefs
.
Values
- Default: None
- Data type: Map
spec.rules.filters.requestHeaderModifier
Specifies a set of header modification rules applied to requests that match the service defined in spec.parentRefs
.
Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
The following table describes how to configure values for request headers:
Rule | Description | Type |
---|---|---|
add | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can use variable placeholders. | Map of strings |
set | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can use variable placeholders. | Map of strings |
remove | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
Use variable placeholders
For add
and set
, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable %DOWNSTREAM_REMOTE_ADDRESS%
allows you to pass a value that is generated when the split occurs.
spec.rules.filters.responseHeaderModifier
Specifies a set of header modification rules applied to responses from services matching spec.parentRefs
.
Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
The following table describes how to configure values for request headers:
Rule | Description | Type |
---|---|---|
add | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can use variable placeholders. | Map of strings |
set | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can use variable placeholders. | Map of strings |
remove | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
Use variable placeholders
For add
and set
, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable %DOWNSTREAM_REMOTE_ADDRESS%
allows you to pass a value that is generated when the split occurs.
spec.rules.filters.urlRewrite
Specifies a path to modify the URL with when a request matching spec.parentRefs
is forwarded.
Values
Default: None
Data type: Map containing the following parameter:
Parameter Description Data type Default pathPrefix
Specifies a path to prepend to the URL when a request matching spec.parentRefs
is forwarded.String None
spec.rules.matches
Specifies rules for matching traffic to services described in spec.parentRefs
according to the request header or method.
Values
- Default: None
- Data type: Map
spec.rules.matches.headers
Specifies criteria for matching gRPC request headers.
When [spec.rules.matches.headers.value
] is specified multiple times, a request must match all of the specified values for the route to be selected.
Values
- Default: None
- Data type: Map
spec.rules.matches.headers.name
Specifies the name of a gRPC request header to match on.
Values
- Default: None
- Data type: String
spec.rules.matches.headers.type
Specifies a type of match to perform on the gRPC request header. Supported match types include: unspecified, exact, regex, present, prefix, and suffix.
Values
Default: None
Data type: String that should match one of the following values:
spec.rules.matches.headers.value
Specifies the value of the gRPC request header to match. When this field is specified multiple times, a request must match all of the specified values for the route to be selected.
Values
- Default: None
- Data type: String
spec.rules.matches.method
Specifies criteria for matching a service and a gRPC request method. When configuring this field, either spec.rules.matches.method.method
or spec.rules.matches.method.service
must be a non-empty string.
Values
- Default: None
- Data type: Map
spec.rules.matches.method.method
Specifies the value of the method to match. When empty or omitted, all methods match.
Values
- Default: None
- Data type: String
spec.rules.matches.method.service
Specifies the value of the service to match. When empty or omitted, all services match.
Values
- Default: None
- Data type: String
spec.rules.matches.method.type
Specifies a type of match to perform on the gRPC request method. Supported match types include: unspecified, exact, and regex.
Values
Default: None
Data type: String that should match one of the following values:
spec.rules.retries
Specifies retry logic for routing gRPC traffic.
Values
- Default: None
- Data type: Map
spec.rules.retries.number
Specifies the number of retries to attempt when a request fails.
Values
Default: None
Data type: Map that contains the following parameter:
Parameter Description Data type Default value
Specifies the number of retries to attempt. Integer None
spec.rules.retries.onConditions
Specifies Envoy conditions that cause an automatic retry attempt.
Values
- Default: None
- Data type: Map of strings
spec.rules.retries.onConnectFailure
Enables an automatic retry attempt when a connection failure error occurs.
Values
- Default:
false
- Data type: Boolean
spec.rules.retries.onStatusCodes
Specifies the response status codes that are eligible for retry attempts.
Values
- Default: None
- Data type: Map of integers
spec.rules.timeouts
Specifies timeout logic when routing gRPC traffic
Values
- Default: None
- Data type: Map
spec.rules.timeouts.idle
Specifies the total amount of time permitted for the request stream to be idle before a timeout occurs.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with 5s
and five milliseconds with 0.005s
.
Values
- Default: None
- Data type: String
spec.rules.timeouts.request
Specifies the total amount of time spent processing the entire downstream request, including retries, before triggering a timeout.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with 5s
and five milliseconds with 0.005s
.
Values
- Default: None
- Data type: String
Examples
The following examples demonstrate common GRPCRoute CRD configuration patterns for specific use cases.
Split gRPC traffic between two ports
The following example splits traffic for the api
service. GRPC 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.
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: GRPCRoute
metadata:
name: api-split
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
weight: 50
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "admin-workload" target port.
port: "90"
weight: 50
Route traffic by matching header
The following example routes gRPC traffic for the api
service according to its header. GRPC traffic for services registered to the Consul catalog that are available at the api-workload
port are routed according to the following criteria:
- For traffic with a header that contains a
x-debug
value of exactly1
, Consul modifies the response and request headers and routes to theapi
service at theapi-workload
port. - For traffic with a header that contains a
x-debug
value of exactly2
, Consul modifies the response and request headers and routes to theapi-admin
service at theadmin-workload
port.
This example also includes how to include filters that modify request or response headers.
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: GRPCRoute
metadata:
name: api-match-split
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "1"
filters:
- requestHeaderModifier:
add:
- name: "request-foo"
value: "request-bar"
- responseHeaderModifier:
add:
- name: "response-foo"
value: "response-bar"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "2"
filters:
- requestHeaderModifier:
add:
- name: "request-foo"
value: "request-bar"
- responseHeaderModifier:
add:
- name: "response-foo"
value: "response-bar"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api-admin
# The virtual port number for the "admin-workload" target port.
port: "90"