Cloud Service Mesh service routing APIs overview

This document is intended for mesh or platform administrators and servicedevelopers who have an intermediate to advanced level of familiarity withCloud Service Mesh and service mesh concepts and who are deployingCloud Service Mesh on Compute Engine with VM instances. This document applies todeployments using Envoy and gRPC clients. For more information onCloud Service Mesh concepts, see thegeneral overview.

Cloud Service Mesh provides service networking capabilities to yourapplications, including advanced traffic management, observability, andsecurity. However, configuring and operating a service mesh is a complextask for mesh administrators and service developers.

This document describes the service routing APIs for configuringCloud Service Mesh. These APIs are designed to simplify and improve your overall mesh configuration experience.

The service routing model uses API resources calledMesh,Gateway, andRoute.These resources provide a contextually-relevant configurationexperience when you define your service networking control plane.

This document introduces the following service routing API model andresources.

• Meshresource
  • Service-to-service (east-west) traffic management and securityconfiguration for Envoy sidecar proxies and proxyless gRPC clients.

• Gatewayresource

  • Traffic management and security configuration for Envoy proxiesacting as ingress gateways, allowing external clients to connect tothe service mesh (north-south).

• Route resources with the following types:

  • HTTPRoute
  • GRPCRoute
  • TCPRoute
  • TLSRoute

The Google Cloud console does not provide support for the service routingAPIs. You must implement these API resources using the Google Cloud CLI or theREST APIs.

Use cases and benefits

The service routing APIs let you configure Cloud Service Mesh for bothproxyless gRPC and Envoy proxy deployments. The service routing API modelenables several key benefits.

In the following diagram, two services in the service mesh are connected by aMesh resource. The twoHTTPRoute resources configure routing. The mesh orplatform administrator manages theMesh resource and the two service owners create therouting configuration for their services.

Role-oriented API design enables clear separation of responsibilities

The service routing APIs let you separate mesh configurationresponsibilities based on organizational roles:

• Mesh administrators can define the logical mesh as well as the ingressgateway infrastructure.
• Service owners (application developers) can independently define accesspatterns for their services. They can also define and apply trafficmanagement policies for their services.

In the following diagram, Cloud Load Balancing and aGateway resourceprovide an ingress gateway for traffic entering the mesh from a client that isnot in the mesh. The mesh administrator configures and manages theGatewayresource, while the service owners configure and manage their own services andtraffic routing.

Enhanced reliability with self-serve model

The service routing APIs use per-protocol, per-route resources that can beconfigured and owned by independent service owners. This approach has severaladvantages.

• Service owners have autonomy over how they want to configurepolicies and traffic management for the services they own.
• Updating oneRoute resource does not affect otherRoute resources in themesh. The update process is more reliable because service ownersmanage small configurations.
• The service owner who is responsible for the destination service orhostname owns eachRoute resource.
• Service owners don't have to depend on mesh administrators to updaterouting.

Enable a service mesh spanning multiple projects in Shared VPC environments

The service routing API model lets service owners participate in a shared meshinfrastructure using Shared VPC and other means of connectivity whilemaintaining independent control over their services. For example, service ownerscan define theRoute resources in their own projects. Platform administratorscan define aMesh in a centrally administered host project, then grant serviceowners IAM permissions to attach theirRoute resources to a sharedMesh orGateway. The following diagram shows an example with Shared VPC.

The service routing APIs also let you have service mesh clients connected to differentnetworks using VPC Network Peering.

Route traffic based on the server name indicator

TheTLSRoute resource lets you route TLS-encrypted traffic based on the ServerName Indication (SNI) in the TLS handshake. You can configure TLS traffic to berouted to the appropriate backend services by configuring the SNI match in theTLSRoute resource. In these deployments, proxies only route traffic and theTLS session is terminated at the destination backend instance.

TheTLSRoute resource is supported only with Envoy proxies that are deployedas sidecar proxies or gateways.

TLSRoute resource attached to aMesh resource

The deployment shown in the following diagram routes any service mesh trafficwhere the SNI extension has the valueservice1 to the backend serviceservice1. Additionally, any service mesh traffic where the SNI extension has thevalueservice2 is routed to the backend serviceservice2. The SNI extensionvalue and the backend service name are independent of each other.

TLSRoute resource attached to aGateway resource

The deployment shown in the following diagram routes any inbound traffic to theGateway resource where the SNI extension has the valueserviceA to thebackend serviceserviceA. Additionally, any inbound traffic to theGateway where the SNI extension has the valueserviceB is routed to thebackend serviceserviceB. The SNI extension value and the backend service nameare independent of each other. The SNI extension value and the header in HTTPrequests are also independent.

TheGateway resource does not terminate the TLS connection at theGateway'sEnvoy proxy. Instead, the TLS connection is terminated at the correspondingbackend service. TheGateway cannot inspect any information encrypted in theTLS layer, other than seeing theClientHello, which contains a plain text SNIextension. TheGateway performs TLS passthrough in this mode. Note thatencryptedClientHello is unsupported.

Core gRPC support

You can configure proxyless gRPC clients by using core gRPC attributessuch as matching by method.

Traffic splitting for TCP traffic

You can implement weight-based traffic splitting for TCP traffic acrossmultiple backend services. You can configure patterns such as canary (blue-green) rollouts when you update your service. Traffic splitting also lets youmigrate traffic in a controlled manner without downtime.

Traffic interception

When you use the service routing APIMesh andGateway resources,all traffic is automatically intercepted. For more information, seeOptions for Compute Engine VM setup with automatic Envoy deployment.

Architecture and resources

This section describes the service routing API model and its resources, and helps you tounderstand how the service routing API resources work together.

Mesh resource

TheMesh resource represents an instance of a service mesh. You use it tocreate a logical service mesh in your project. EachMesh resource must have aunique name in the project. After aMesh resource is created, its name cannotbe modified.

TheMesh resource is referenced in theRoute resource to add routes forservices that are part of the mesh.

Envoy proxy and proxyless gRPC clients receive configuration fromCloud Service Mesh by joining the service mesh identified by theMeshresource's name. TheMesh resource supports the following data plane deployments:

• Envoy running alongside the application as sidecar proxies
• Proxyless gRPC clients
• Mix of Envoy sidecar and proxyless gRPC clients

Route resource

TheRoute resource is used to set up routing to the services. There are fourdifferent types of theRoute API resource. They define the protocol used toroute traffic to a backend service.

• HTTPRoute
• GRPCRoute
• TCPRoute
• TLSRoute

The API doesn't contain aRoute API verbatim. The only configurable APIresources areHTTPRoute,GRPCRoute,TCPRoute, andTLSRoute.

TheRoute resource references one or moreMesh andGateway resourcesto add the routes that are part of the correspondingMesh orGateway configuration. ARoute resource can reference bothGateway andMesh resources.

TheRoute resource also references one or morebackend service resources. The services are configured using the backend service API. You create a backend service resource that points to one or more MIG or NEG backends.

The following diagram shows the relationships among theMesh,Gateway,andRoute resources and the backend service resource and its backends.

You define other traffic management capabilities, such as routing, headermodifications, timeouts, and weight-based traffic splitting inRoute resources.For example, in the following diagram, anHTTPRoute resource defines a 70% / 30%traffic split between two backend services.

To simplify administration of your service mesh, you can list allRouteresources attached to aMesh orGateway resource.

TLSRoute resource

Use theTLSRoute resource to route TLS traffic to backend services based onSNI hostnames and Application-Layer Protocol Negotiation (ALPN) name.TLSRouteconfiguration implies TLS passthrough, in which the Envoy proxy does notterminate TLS traffic.

TheTLSRoute resource references one or moreMesh andGateway resources toadd the routes that are part of the corresponding Mesh or Gateway configuration.

TheTLSRoute resource also references one or more backend service resources.The services are configured using the backend service API resource.

Gateway resource

TheGateway resource is used to represent Envoy proxies acting as ingressgateways, allowing external clients to connect to the service mesh (north-southtraffic). This resource has listening ports along with ascope parameter. TheEnvoy proxy that acts as an ingress gateway binds to the ports specified and to0.0.0.0, which represents all of the IP addresses on the local VM. The followingdiagram shows Envoy proxies deployed as an ingress service and configured by theGateway resource. In this particular example, Envoy proxies are configured tolisten on port 80 for incoming connections from clients.

TheGateway API resource only supports the Envoy proxy data plane. It doesnot support proxyless gRPC.gRPCRoutes are supported in theGateway resource,but the gRPC traffic is routed by the Envoy proxy, acting as a middle-proxy.

What are aGateway scope and mergedGateway configuration?

AGateway resource instance represents the ports and configuration specificto traffic received on those ports. TheGateway API resource has a parameter,scope, that is used to logically group and merge the configuration of two ormoreGateway resources.

For example, If you want theGateway proxies to listen on ports 80 and 443 toreceive HTTP and HTTPS traffic respectively, you create twoGateway resources.Configure oneGateway resource with port 80, for HTTP traffic, and the otherwith 443, for HTTPS traffic. Give thescope field in each the same value.Cloud Service Mesh dynamically merges the individual configurations of allGateways that have the same scope. On the data plane side, the Envoy proxiesthat run in the ingress gateway mode must also present the same scope parameterto Cloud Service Mesh to receive theGateway configuration. Note that youspecify the scope when you create theGateway resource, and you specify thesame scope as the bootstrap parameter for the proxies.

The following are key considerations for theGateway resource:

• TheGateway scope parameter is mandatory. Specify the scope in theGateway resource and in the bootstrap configuration of the Envoy proxieseven when only oneGateway exists.
• Creating aGateway resource does not deploy a service with an Envoyproxy. Deploying the Envoy proxy is a separate step.
• TheGateway resource has atype that represents the type of ingressdeployment. This field is reserved for future use. The onlycurrently-supported value isOPEN_MESH, which is the default value andwhich cannot be modified.

Mesh deployments with mixed protocols and data planes

You can have a mixed data plane deployment, with Envoy proxy and proxyless gRPCin the same mesh. When you create such deployments, consider the following.

• Envoy sidecar deployments support all Routes (HTTPRoute,GRPCRoute,TCPRoute, andTLSRoute).
• Proxyless gRPC deployments only supportGRPCRoute.
• GRPCRoute is limited to features supported only by gRPC proxylessdeployments.

Supported topologies in multi-project Shared VPC environments

Cloud Service Mesh supports addingRoute resources that are defined in otherprojects to aMesh orGateway resource defined in a centralized administrationproject. Authorized service owners can directly add their service routingconfigurations to theMesh orGateway.

In a typical cross-project scenario, you choose a project (host project orcentrally controlled administration project) as the mesh administration project where you createaMesh resource. The mesh administration project owner authorizesRoute resources from otherprojects to reference theMesh resource, allowing the routing configurationfrom other projects to be part of the mesh. A mesh data plane, whether Envoy orgRPC, requests configuration from the administration project and receives a union of allof the routes attached to theMesh. For aGateway, the routesare also merged across allGateways that use the same scope.

TheMesh administration project can be any project that you choose, and theconfiguration works as long as the underlying projects have VPCnetwork connectivity, either through Shared VPC orVPC Network Peering.

IAM permissions and roles

The following are the IAM permissions that are required to securely get,create, update, delete, list, and use theMesh andRoute resources.

• Mesh administrators need to havenetworkservices.mesh.* permissions.
• Gateway administrators need to havenetworkservices.gateways.* permissions.
• Service owners need to havenetworkservices.grpcRoutes.*,networkservices.httpRoutes.*, ornetworkservices.tcpRoutes.* permissions.

Mesh administrators need to grant thenetworkservices.mesh.use permission to serviceowners so that the service owners can attach theirRoute resources to theMesh resource. The same model applies toGateway resources.

To see all IAM permissions forMesh resources, go to theIAM permissions reference page and search formeshes.

There are no additional predefined roles required. The existing, predefined roleCompute Network Admin (roles/compute.networkAdmin) hasnetworkservices.* permissions by default.You might need to add the previously described permissions to your customroles.

Considerations and limitations

• The Google Cloud console does not support the service routing APIs.
• Use thexDS API version 3 or later.
  • Minimum Envoy version of 1.20.0 (since the service routing APIs aresupported only on xDS version 3)
  • Minimum gRPC bootstrap generator version of v0.14.0
• TheTLSRoute resource is supported only with Envoy proxies that aredeployed as sidecar proxies or gateways.
• Only Compute Engine VMs with automatic Envoy deployment andGKE Pods with automatic Envoy injection are supported.You cannot use manual deployment with the service routing APIs.
• The service routing APIs are not backward compatible with the older APIs.
• When aTCPRoute resource is attached to aMesh resource, the port used to matchTCP traffic cannot be used to serve anything except the traffic describedby thisTCPRoute.
  • For example, your deployments might include aTCPRoute resourcethat matches port "8000" and an HttpRoute resource. When both areattached to the sameMesh resource, traffic routed by theHTTPRoute resourcecannot use port 8000 even when the underlying IP addresses aredifferent. This limitation comes from Envoy proxy implementation, whichassigns precedence to the port-matched route first.
• TheGateway resource does not provision a managed load balancer and itdoes not dynamically create an Envoy service.
• Automatically deployed Envoys serving as ingress gateways must not have theserving_ports argument to the--service-proxy flag.
• Automatically deployed Envoy does not support providing a project numberdifferent from the project of the VM.

What's next

• For information about listing route resources associated with aMesh orGateway resource, seeListRoute resources.
• For information about the service routing APIs, read the documentation for thenetwork services APIs.