Set up proxyless gRPC services

This guide demonstrates how to set up a proxyless gRPC service mesh withMesh andGRPCRoute resources.

Before you begin

Make sure that you readPrepare to set up with Envoy and proxyless workloads and complete the prerequisites describedin that document.

Configure theMesh resource

When a proxyless gRPC application connects to anxds://hostname, the gRPCclient library establishes a connection to Cloud Service Mesh. The client libraryuses the connection to obtain the routing configuration that is needed to routerequests for the hostname.

Make sure that you note the name of theMesh resource, which is the key thatthe proxyless gRPC application uses to request the configuration associated withthis Mesh.

1. Create theMesh specification and save it in a file called mesh.yaml.

   name: grpc-mesh

2. Create theMesh resource using themesh.yaml specification:

   gcloud network-services meshes import grpc-mesh \  --source=mesh.yaml \  --location=global

After theMesh resource is created, Cloud Service Mesh is ready to serve theconfiguration, but because there are no services defined yet, the configurationis empty. In the next section, you define the services and attach them to theMesh resource.

Configure the gRPC server

For demonstration purposes, you create a backend service with autoscaled VMsin amanaged instance group. The VMs serve thephrasehello world using the gRPC protocol on port50051.

1. Create the Compute Engine VM instance template with ahelloworld gRPC service that is exposed on port50051:

   gcloud compute instance-templates create grpc-td-vm-template \   --scopes=https://www.googleapis.com/auth/cloud-platform \   --tags=allow-health-checks \   --image-family=debian-10 \   --image-project=debian-cloud \   --metadata-from-file=startup-script=<(echo '#! /bin/bash set -e cd /root sudo apt-get update -y sudo apt-get install -y openjdk-11-jdk-headless curl -L https://github.com/grpc/grpc-java/archive/v1.38.0.tar.gz | tar -xz cd grpc-java-1.38.0/examples/example-hostname ../gradlew --no-daemon installDist sudo systemd-run ./build/install/hostname-server/bin/hostname-server')

2. Create a managed instance group based on the template:

   gcloud compute instance-groups managed create grpc-td-mig-us-east1 \  --zone=ZONE \  --size=2 \  --template=grpc-td-vm-template

3. Create the named port for the gRPC service. The named port is the porton which the gRPC service listens for requests. In the following example, thenamed port is50051:

   gcloud compute instance-groups set-named-ports grpc-td-mig-us-east1 \ --named-ports=grpc-helloworld-port:50051 \ --zone=ZONE

4. Create a gRPC health check. The services must implement thegRPC health checking protocolso that gRPC health checks work properly. For more information, seehealth checks.

   gcloud compute health-checks create grpc grpc-helloworld-health-check \  --use-serving-port

5. Create a firewall rule to allow health check connections to instancesin your network:

   gcloud compute firewall-rules create grpc-vm-allow-health-checks \  --network=default \  --action=ALLOW \  --direction=INGRESS \  --source-ranges=35.191.0.0/16,130.211.0.0/22 \  --target-tags allow-health-checks \  --rules=tcp:50051

6. Create aglobal backend servicewith a load balancing scheme ofINTERNAL_SELF_MANAGED and add the healthcheck to the backend service. The port specified here is used to connect tothe VMs in the managed instance group.

   gcloud compute backend-services create grpc-helloworld-service \  --global \  --load-balancing-scheme=INTERNAL_SELF_MANAGED \  --protocol=GRPC \  --port-name=grpc-helloworld-port \  --health-checks grpc-helloworld-health-check

7. Add the managed instance group to the backend service.

   gcloud compute backend-services add-backend \  grpc-helloworld-service \  --instance-group=grpc-td-mig-us-east1 \  --instance-group-zone=ZONE \  --global

TheMesh resource and services are configured. In the next section, you setup routing.

Set up routing withGRPCRoute

Use the following instructions to set up routing.

1. Create theGRPCRoute specification and save it in a file calledgrpc_route.yaml.

   You can use eitherPROJECT_ID orPROJECT_NUMBER.

   name: helloworld-grpc-routehostnames:- helloworld-gcemeshes:- projects/PROJECT_NUMBER/locations/global/meshes/grpc-meshrules:- action:    destinations:    - serviceName: projects/PROJECT_NUMBER/locations/global/backendServices/grpc-helloworld-service

2. Create theGrpcRoute resource using thegrpc_route.yaml specification:

   gcloud network-services grpc-routes import helloworld-grpc-route \  --source=grpc_route.yaml \  --location=global

Cloud Service Mesh is now configured to load balance traffic for the servicesspecified in theGRPCRoute resource across backends in the managed instancegroup.

Create a gRPC client

You can verify the configuration by instantiating a proxyless gRPCapplication and connecting it to Cloud Service Mesh. In its bootstrap file, theapplication must specify the VPC network indicated in the Mesh.

After it is configured, the application can send a request to the instancesor endpoints associated withhelloworld-gce using thexds:///helloworld-gceservice URI.

In the following examples, you use the grpcurl tool to test the gRPCservice.

1. Create a client VM.

   gcloud compute instances create grpc-client \  --zone=ZONE\  --scopes=https://www.googleapis.com/auth/cloud-platform \  --image-family=debian-10 \  --image-project=debian-cloud \  --metadata-from-file=startup-script=<(echo '#! /bin/bashset -eexport GRPC_XDS_BOOTSTRAP=/run/td-grpc-bootstrap.jsonecho export GRPC_XDS_BOOTSTRAP=$GRPC_XDS_BOOTSTRAP | sudo tee /etc/profile.d/grpc-xds-bootstrap.shcurl -L https://storage.googleapis.com/traffic-director/td-grpc-bootstrap-0.16.0.tar.gz | tar -xz./td-grpc-bootstrap-0.16.0/td-grpc-bootstrap --config-mesh-experimental grpc-mesh | tee $GRPC_XDS_BOOTSTRAP')

Set up the bootstrap file

The client application must have a bootstrap configuration file. The startupscript in the previous section sets theGRPC_XDS_BOOTSTRAPenvironment variable and uses a helper script to generate the bootstrap file.The values forTRAFFICDIRECTOR_GCP_PROJECT_NUMBER and zone in thegenerated bootstrap file are obtained from the metadata server that knows thesedetails about your VM instances. You can provide these values to the helperscript manually using the--gcp-project-number option. You mustprovide a mesh name matching theMesh resource using the--config-mesh-experimental option.

To verify the configuration, sign in to the client VM and run thefollowing.

1. SSH to the client VM.

   gcloud compute ssh grpc-client

2. Download and install thegrpcurl tool.

   curl -L https://github.com/fullstorydev/grpcurl/releases/download/v1.8.1/grpcurl_1.8.1_linux_x86_64.tar.gz | tar -xz

3. Run thegrpcurl tool withxds:///helloworld-gce as the service URI andhelloworld.Greeter/SayHello as the service name and method to invoke. Theparameters to theSayHello method are passed using the-d option.

   ./grpcurl --plaintext \  -d '{"name": "world"}' \  xds:///helloworld-gce helloworld.Greeter/SayHello

You should see output similar to the following, whereINSTANCE_HOSTNAME is thename of the VM instance:

   Greeting: Hello world, from INSTANCE_HOSTNAME

The output verifies that the proxyless gRPC client successfully connected toCloud Service Mesh and learned about the backends for thehelloworld-gce service using thexds name resolver.The client sent a request to one of the service's backends without needing toknow about the IP address or performing DNS resolution.

What's next

• For information about listing route resources associated with aMesh orGateway resource, seeListRoute resources.