Cloud Runner

Get up and running with Go and gRPC on Google Cloud Platform, with this lightweight, opinionated, batteries-included service SDK.


Run your application with cloudrunner.Run, and you get:

To help you build gRPC microservices, you also get:

Get up and running

Install the package:

$ go get

Try out a minimal example:

package main

import (


func main() {
	if err := cloudrunner.Run(func(ctx context.Context) error {
		cloudrunner.Logger(ctx).Info("hello world")
		grpcServer := cloudrunner.NewGRPCServer(ctx)
		healthServer := health.NewServer()
		grpc_health_v1.RegisterHealthServer(grpcServer, healthServer)
		return cloudrunner.ListenGRPC(ctx, grpcServer)
	}); err != nil {


The service is configured with environment variables.

When the service is running on GCE, all built-in integrations
are turned on by default.

Service-specific config is supported out of the box.

Invoke your service with -help to show available configuration.

 $ go run -help

Usage of grpc-server:

  -config string
        load environment from a YAML service specification
        show help then exit
        validate config then exit

Runtime configuration of grpc-server:

CONFIG         ENV                                  TYPE                            DEFAULT        ON GCE
cloudrunner    PORT                                 int                             8080
cloudrunner    K_SERVICE                            string
cloudrunner    K_REVISION                           string
cloudrunner    K_CONFIGURATION                      string
cloudrunner    GOOGLE_CLOUD_PROJECT                 string
cloudrunner    SERVICE_ACCOUNT                      string
cloudrunner    SERVICE_VERSION                      string
cloudrunner    LOGGER_DEVELOPMENT                   bool                            true           false
cloudrunner    LOGGER_LEVEL                         zapcore.Level                   debug          info
cloudrunner    LOGGER_REPORTERRORS                  bool                                           true
cloudrunner    PROFILER_ENABLED                     bool                                           true
cloudrunner    PROFILER_MUTEXPROFILING              bool
cloudrunner    PROFILER_ALLOCFORCEGC                bool                            true
cloudrunner    TRACEEXPORTER_ENABLED                bool                                           true
cloudrunner    SERVER_TIMEOUT                       time.Duration                   290s
cloudrunner    SERVER_RECOVERPANICS                 bool                                           true
cloudrunner    CLIENT_TIMEOUT                       time.Duration                   10s
cloudrunner    CLIENT_RETRY_ENABLED                 bool                            true
cloudrunner    CLIENT_RETRY_INITIALBACKOFF          time.Duration                   200ms
cloudrunner    CLIENT_RETRY_MAXBACKOFF              time.Duration                   60s
cloudrunner    CLIENT_RETRY_MAXATTEMPTS             int                             5
cloudrunner    CLIENT_RETRY_BACKOFFMULTIPLIER       float64                         1.3
cloudrunner    CLIENT_RETRY_RETRYABLESTATUSCODES    []codes.Code                    Unavailable
cloudrunner    REQUESTLOGGER_MESSAGESIZELIMIT       int                                            1024
cloudrunner    REQUESTLOGGER_CODETOLEVEL            map[codes.Code]zapcore.Level
cloudrunner    REQUESTLOGGER_STATUSTOLEVEL          map[int]zapcore.Level

Build-time configuration of grpc-server:

LDFLAG                                                     TYPE      VALUE    string