This page shows Cloud Run-specific details for developers who want to use gRPC to connect a Cloud Run service with other services, for example, to provide simple, high performance communication between internal microservices. You can use all gRPC types, streaming or unary, with Cloud Run.
Possible use cases include:
- Communication between internal microservices.
- High loads of data (gRPC uses protocol 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 full client library.
- Use streaming gRPCs in your gRPC server to build more responsive applications and APIs.
To integrate your service with gRPC:
- Configure your service to use HTTP/2 if you are using streaming gRPC. HTTP/2 is 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 listen
to the
PORT
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 recommends configuring your service to use HTTP/2 if you use gRPC with Cloud Run. Although some simple gRPC features work without 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 proto definitions. Just as with any other use of gRPC, you use gRPC protocol buffers for service definitions and data serialization.
Creating a gRPC client
There are no extra or Cloud Run specific things to add to a client that uses gRPC: follow the gRPC docs on using service definitions in client code, and the sample clients provided in the language-specific gRPC tutorials.
Autoscaling and load balancing
Cloud Run uses Google-managed load balancers that keep separate connections between clients and your Cloud Run instances. With gRPC, autoscaling behaves as follows:
- gRPC connections from clients end at the edge load balancer. Adjusting
KeepAlive
settings only affects the connection to the load balancer, not the Cloud Run instances. The client doesn't recognize when an instance drops. - During scale-in, the load balancer closes connections by sending GOAWAY messages to the backend instances as they shut down.
- During scale-out, the load balancer creates new connections to the backend instances. All these operations are transparent to clients.
- During autoscaling, many instances can start up and multiplex into a single connection between the client and the proxy load balancer.
- Concurrency is determined by the maximum concurrent requests per instance for messages. In streaming, each stream is counted once against the maximum concurrent requests.
Listening for gRPC requests in a Cloud Run service
The only special requirement for a gRPC server running in
Cloud Run is to listen at the port specified by the PORT
environment variable as shown in the following code:
Go
Opening a gRPC connection to a service
To open a gRPC connection to a service so you can send gRPC messages, you need to specify the host domain, which is the URL of the Cloud Run service or the custom domain mapped to that service, along with the port 443, which is the port expected to be used by gRPC.
Go
Sending gRPC requests without authentication
The following sample shows how to send a request without authentication, using a gRPC connection configured as mentioned previously.
Go
Sending gRPC requests with authentication
The following sample shows how to use authentication between services, if the calling service has invoker permission to the receiving service. Notice that this code creates an authorization header that has the proper identity token: this is required. The required permissions and the authorization header are described in detail in service to service authentication.
Go
Sample code for gRPC streaming
For sample code, refer to the RouteGuide
implementation in the
gRPC Basics tutorial for the
language of your choice. When using Go, for example, refer to
Implementing RouteGuide.