This page shows Cloud Run-specific details for developers whowant to usegRPC to connect aCloud Run service with other services, for example, to providesimple, high performance communication between internalmicroservices. You can useall gRPC types,streaming or unary, with Cloud Run.

Possible use cases include:

• Communication between internal microservices.
• High loads of data (gRPC usesprotocol buffers,which are up to seven times faster than REST calls).
• Only a simple service definition is needed, you don't want to write a fullclient library.
• Use streaming gRPCs in your gRPC server to build more responsive applicationsand APIs.

To integrate your service with gRPC:

• Configure your service to use HTTP/2 if you are using streaming gRPC. HTTP/2is the transport method for gRPC streaming.
• Define the request messages and responses in a proto file and compile them.
• Create a gRPC server to handle requests and return responses: it should listento thePORT environment variable.
• Create a client that sends requests and handles responses from the gRPC server.
• Optionally, add authentication.
• Build and deploy your service.

Configuring your service to use HTTP/2

Google recommendsconfiguring your service to use HTTP/2 if youuse gRPC with Cloud Run. Although some simple gRPC features workwithout using HTTP/2, many gRPC features, such as streaming and metadata, require HTTP/2.

Defining and compiling messages in a proto file

There are no extra or Cloud Run-specific things to add to your protodefinitions. Just as with any other use of gRPC, you usegRPC protocol buffersfor service definitions and data serialization.

Creating a gRPC client

There are no extra or Cloud Run specific things to add to a clientthat uses gRPC: follow the gRPC docs on using service definitions inclient code, and thesample clients provided in the language-specificgRPC tutorials.

Autoscaling and load balancing

Cloud Run uses Google-managed load balancers that keep separateconnections between clients and your Cloud Run instances.With gRPC, autoscaling behaves as follows:

• gRPC connections from clients end at the edge load balancer. AdjustingKeepAlive settings only affects the connection to the load balancer, not theCloud Run instances. The client doesn't recognize when aninstance drops.
• During scale-in, the load balancer closes connections by sending GOAWAYmessages to the backend instances as they shut down.
• During scale-out, the load balancer creates new connections to the backendinstances.All these operations are transparent to clients.
• During autoscaling, many instances can start up and multiplex into a singleconnection between the client and the proxy load balancer.
• Concurrency is determined by themaximum concurrent requests per instancefor messages. In streaming, each stream is counted once against the maximumconcurrent requests.

Listening for gRPC requests in a Cloud Run service

The only special requirement for a gRPC server running inCloud Run is to listen at the port specified by thePORTenvironment variable as shown in the following code:

funcmain(){log.Printf("grpc-ping: starting server...")port:=os.Getenv("PORT")ifport==""{port="8080"log.Printf("Defaulting to port %s",port)}listener,err:=net.Listen("tcp",":"+port)iferr!=nil{log.Fatalf("net.Listen: %v",err)}grpcServer:=grpc.NewServer()pb.RegisterPingServiceServer(grpcServer,&pingService{})iferr=grpcServer.Serve(listener);err!=nil{log.Fatal(err)}}

Opening a gRPC connection to a service

To open a gRPC connection to a service so you can send gRPC messages, you needto specify the host domain, which is the URL of the Cloud Run serviceor the custom domainmapped to that service,along with the port 443, which is the port expected to be used by gRPC.

import("crypto/tls""crypto/x509""google.golang.org/grpc""google.golang.org/grpc/credentials")// NewConn creates a new gRPC connection.// host should be of the form domain:port, e.g., example.com:443funcNewConn(hoststring,insecurebool)(*grpc.ClientConn,error){varopts[]grpc.DialOptionifhost!=""{opts=append(opts,grpc.WithAuthority(host))}ifinsecure{opts=append(opts,grpc.WithInsecure())}else{// Note: On the Windows platform, use of x509.SystemCertPool() requires// Go version 1.18 or higher.systemRoots,err:=x509.SystemCertPool()iferr!=nil{returnnil,err}cred:=credentials.NewTLS(&tls.Config{RootCAs:systemRoots,})opts=append(opts,grpc.WithTransportCredentials(cred))}returngrpc.Dial(host,opts...)}

Sending gRPC requests without authentication

The following sample shows how to send a request without authentication, usingagRPC connection configured as mentioned previously.

import("context""time"pb"github.com/GoogleCloudPlatform/golang-samples/run/grpc-ping/pkg/api/v1""google.golang.org/grpc")// pingRequest sends a new gRPC ping request to the server configured in the connection.funcpingRequest(conn*grpc.ClientConn,p*pb.Request)(*pb.Response,error){ctx,cancel:=context.WithTimeout(context.Background(),30*time.Second)defercancel()client:=pb.NewPingServiceClient(conn)returnclient.Send(ctx,p)}

Sending gRPC requests with authentication

The following sample shows how to use authentication between services, if thecalling service has invoker permission to the receiving service. Notice thatthis code creates an authorization header that has the proper identity token:this is required. The required permissions and the authorization header aredescribed in detail inservice to service authentication.

import("context""fmt""time""google.golang.org/api/idtoken""google.golang.org/grpc"grpcMetadata"google.golang.org/grpc/metadata"pb"github.com/GoogleCloudPlatform/golang-samples/run/grpc-ping/pkg/api/v1")// pingRequestWithAuth mints a new Identity Token for each request.// This token has a 1 hour expiry and should be reused.// audience must be the auto-assigned URL of a Cloud Run service or HTTP Cloud Function without port number.funcpingRequestWithAuth(conn*grpc.ClientConn,p*pb.Request,audiencestring)(*pb.Response,error){ctx,cancel:=context.WithTimeout(context.Background(),30*time.Second)defercancel()// Create an identity token.// With a global TokenSource tokens would be reused and auto-refreshed at need.// A given TokenSource is specific to the audience.tokenSource,err:=idtoken.NewTokenSource(ctx,audience)iferr!=nil{returnnil,fmt.Errorf("idtoken.NewTokenSource: %w",err)}token,err:=tokenSource.Token()iferr!=nil{returnnil,fmt.Errorf("TokenSource.Token: %w",err)}// Add token to gRPC Request.ctx=grpcMetadata.AppendToOutgoingContext(ctx,"authorization","Bearer "+token.AccessToken)// Send the request.client:=pb.NewPingServiceClient(conn)returnclient.Send(ctx,p)}

Sample code for gRPC streaming

For sample code, refer to theRouteGuide implementation in thegRPC Basics tutorial for thelanguage of your choice. When using Go, for example, refer toImplementing RouteGuide.