REST Resource: projects.locations.grpcRoutes

Resource: GrpcRoute

GrpcRoute is the resource defining how gRPC traffic routed by a Mesh or Gateway resource is routed.

JSON representation 
{
  "name": string,
  "selfLink": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "description": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
Fields
name

string

Required. Name of the GrpcRoute resource. It matches pattern projects/*/locations/global/grpcRoutes/<grpc_route_name>
createTime

string (Timestamp format)

Output only. The timestamp when the resource was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Output only. The timestamp when the resource was updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
labels

map (key: string, value: string)

Optional. Set of label tags associated with the GrpcRoute resource.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
description

string

Optional. A free-text description of the resource. Max length 1024 characters.
hostnames[]

string

Required. Service hostnames with an optional port for which this route describes traffic.

Format: [:]

Hostname is the fully qualified domain name of a network host. This matches the RFC 1123 definition of a hostname with 2 notable exceptions: - IPs are not allowed. - A hostname may be prefixed with a wildcard label (*.). The wildcard label must appear by itself as the first label.

Hostname can be "precise" which is a domain name without the terminating dot of a network host (e.g. "foo.example.com") or "wildcard", which is a domain name prefixed with a single wildcard label (e.g. *.example.com).

Note that as per RFC1035 and RFC1123, a label must consist of lower case alphanumeric characters or '-', and must start and end with an alphanumeric character. No other punctuation is allowed.

The routes associated with a Mesh or Gateway must have unique hostnames. If you attempt to attach multiple routes with conflicting hostnames, the configuration will be rejected.

For example, while it is acceptable for routes for the hostnames "*.foo.bar.com" and "*.bar.com" to be associated with the same route, it is not possible to associate two routes both with "*.bar.com" or both with "bar.com".

If a port is specified, then gRPC clients must use the channel URI with the port to match this rule (i.e. "xds:///service:123"), otherwise they must supply the URI without a port (i.e. "xds:///service").
meshes[]

string

Optional. Meshes defines a list of meshes this GrpcRoute is attached to, as one of the routing rules to route the requests served by the mesh.

Each mesh reference should match the pattern: projects/*/locations/global/meshes/<mesh_name>
gateways[]

string

Optional. Gateways defines a list of gateways this GrpcRoute is attached to, as one of the routing rules to route the requests served by the gateway.

Each gateway reference should match the pattern: projects/*/locations/global/gateways/<gateway_name>
rules[]

object (RouteRule)

Required. A list of detailed rules defining how to route traffic.

Within a single GrpcRoute, the GrpcRoute.RouteAction associated with the first matching GrpcRoute.RouteRule will be executed. At least one rule must be supplied.

RouteRule

Describes how to route traffic.

JSON representation 
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
Fields
matches[]

object (RouteMatch)

Optional. Matches define conditions used for matching the rule against incoming gRPC requests. Each match is independent, i.e. this rule will be matched if ANY one of the matches is satisfied. If no matches field is specified, this rule will unconditionally match traffic.
action

object (RouteAction)

Required. A detailed rule defining how to route traffic. This field is required.

RouteMatch

Criteria for matching traffic. A RouteMatch will be considered to match when all supplied fields match.

JSON representation 
{
  "headers": [
    {
      object (HeaderMatch)
    }
  ],

  // Union field _method can be only one of the following:
  "method": {
    object (MethodMatch)
  }
  // End of list of possible types for union field _method.
}
Fields
headers[]

object (HeaderMatch)

Optional. Specifies a collection of headers to match.

Union field _method.

_method can be only one of the following:
method

object (MethodMatch)

Optional. A gRPC method to match against. If this field is empty or omitted, will match all methods.

MethodMatch

Specifies a match against a method.

JSON representation 
{
  "type": enum (Type),
  "grpcService": string,
  "grpcMethod": string,

  // Union field _case_sensitive can be only one of the following:
  "caseSensitive": boolean
  // End of list of possible types for union field _case_sensitive.
}
Fields
type

enum (Type)

Optional. Specifies how to match against the name. If not specified, a default value of "EXACT" is used.
grpcService

string

Required. Name of the service to match against. If unspecified, will match all services.
grpcMethod

string

Required. Name of the method to match against. If unspecified, will match all methods.

Union field _case_sensitive.

_case_sensitive can be only one of the following:
caseSensitive

boolean

Optional. Specifies that matches are case sensitive. The default value is true. caseSensitive must not be used with a type of REGULAR_EXPRESSION.

Type

The type of the match.

Enums
TYPE_UNSPECIFIED Unspecified.
EXACT Will only match the exact name provided.
REGULAR_EXPRESSION Will interpret grpcMethod and grpcService as regexes. RE2 syntax is supported.

HeaderMatch

A match against a collection of headers.

JSON representation 
{
  "type": enum (Type),
  "key": string,
  "value": string
}
Fields
type

enum (Type)

Optional. Specifies how to match against the value of the header. If not specified, a default value of EXACT is used.
key

string

Required. The key of the header.
value

string

Required. The value of the header.

Type

The type of match.

Enums
TYPE_UNSPECIFIED Unspecified.
EXACT Will only match the exact value provided.
REGULAR_EXPRESSION Will match paths conforming to the prefix specified by value. RE2 syntax is supported.

RouteAction

Specifies how to route matched traffic.

JSON representation 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  }
}
Fields
destinations[]

object (Destination)

Optional. The destination services to which traffic should be forwarded. If multiple destinations are specified, traffic will be split between Backend Service(s) according to the weight field of these destinations.
faultInjectionPolicy

object (FaultInjectionPolicy)

Optional. The specification for fault injection introduced into traffic to test the resiliency of clients to destination service failure. As part of fault injection, when clients send requests to a destination, delays can be introduced on a percentage of requests before sending those requests to the destination service. Similarly requests from clients can be aborted by for a percentage of requests.

timeout and retryPolicy will be ignored by clients that are configured with a faultInjectionPolicy
timeout

string (Duration format)

Optional. Specifies the timeout for selected route. Timeout is computed from the time the request has been fully processed (i.e. end of stream) up until the response has been completely processed. Timeout includes all retries.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
retryPolicy

object (RetryPolicy)

Optional. Specifies the retry policy associated with this route.

Destination

The destination to which traffic will be routed.

JSON representation 
{

  // Union field destination_type can be only one of the following:
  "serviceName": string
  // End of list of possible types for union field destination_type.

  // Union field _weight can be only one of the following:
  "weight": integer
  // End of list of possible types for union field _weight.
}
Fields
Union field destination_type. Specifies the kind of destination to which traffic will be routed. destination_type can be only one of the following:
serviceName

string

Required. The URL of a destination service to which to route traffic. Must refer to either a BackendService or ServiceDirectoryService.

Union field _weight.

_weight can be only one of the following:
weight

integer

Optional. Specifies the proportion of requests forwarded to the backend referenced by the serviceName field. This is computed as: weight/Sum(weights in this destination list). For non-zero values, there may be some epsilon from the exact proportion defined here depending on the precision an implementation supports.

If only one serviceName is specified and it has a weight greater than 0, 100% of the traffic is forwarded to that backend.

If weights are specified for any one service name, they need to be specified for all of them.

If weights are unspecified for all services, then, traffic is distributed in equal proportions to all of them.

FaultInjectionPolicy

The specification for fault injection introduced into traffic to test the resiliency of clients to destination service failure. As part of fault injection, when clients send requests to a destination, delays can be introduced on a percentage of requests before sending those requests to the destination service. Similarly requests from clients can be aborted by for a percentage of requests.

JSON representation 
{

  // Union field _delay can be only one of the following:
  "delay": {
    object (Delay)
  }
  // End of list of possible types for union field _delay.

  // Union field _abort can be only one of the following:
  "abort": {
    object (Abort)
  }
  // End of list of possible types for union field _abort.
}
Fields

Union field _delay.

_delay can be only one of the following:
delay

object (Delay)

The specification for injecting delay to client requests.

Union field _abort.

_abort can be only one of the following:
abort

object (Abort)

The specification for aborting to client requests.

Delay

Specification of how client requests are delayed as part of fault injection before being sent to a destination.

JSON representation 
{

  // Union field _fixed_delay can be only one of the following:
  "fixedDelay": string
  // End of list of possible types for union field _fixed_delay.

  // Union field _percentage can be only one of the following:
  "percentage": integer
  // End of list of possible types for union field _percentage.
}
Fields

Union field _fixed_delay.

_fixed_delay can be only one of the following:
fixedDelay

string (Duration format)

Specify a fixed delay before forwarding the request.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

Union field _percentage.

_percentage can be only one of the following:
percentage

integer

The percentage of traffic on which delay will be injected.

The value must be between [0, 100]

Abort

Specification of how client requests are aborted as part of fault injection before being sent to a destination.

JSON representation 
{

  // Union field _http_status can be only one of the following:
  "httpStatus": integer
  // End of list of possible types for union field _http_status.

  // Union field _percentage can be only one of the following:
  "percentage": integer
  // End of list of possible types for union field _percentage.
}
Fields

Union field _http_status.

_http_status can be only one of the following:
httpStatus

integer

The HTTP status code used to abort the request.

The value must be between 200 and 599 inclusive.

Union field _percentage.

_percentage can be only one of the following:
percentage

integer

The percentage of traffic which will be aborted.

The value must be between [0, 100]

RetryPolicy

The specifications for retries.

JSON representation 
{
  "retryConditions": [
    string
  ],
  "numRetries": integer
}
Fields
retryConditions[]

string

  • connect-failure: Router will retry on failures connecting to Backend Services, for example due to connection timeouts.
  • refused-stream: Router will retry if the backend service resets the stream with a REFUSED_STREAM error code. This reset type indicates that it is safe to retry.
  • cancelled: Router will retry if the gRPC status code in the response header is set to cancelled
  • deadline-exceeded: Router will retry if the gRPC status code in the response header is set to deadline-exceeded
  • resource-exhausted: Router will retry if the gRPC status code in the response header is set to resource-exhausted
  • unavailable: Router will retry if the gRPC status code in the response header is set to unavailable
numRetries

integer (uint32 format)

Specifies the allowed number of retries. This number must be > 0. If not specified, default to 1.

Methods

create

 Creates a new GrpcRoute in a given project and location.

delete

 Deletes a single GrpcRoute.

get

 Gets details of a single GrpcRoute.

getIamPolicy

 Gets the access control policy for a resource.

list

 Lists GrpcRoutes in a given project and location.

patch

 Updates the parameters of a single GrpcRoute.

setIamPolicy

 Sets the access control policy on the specified resource.

testIamPermissions

 Returns permissions that a caller has on the specified resource.