Stay organized with collections
Save and categorize content based on your preferences.
This page shows Knative serving-specific details for developers who
want to use gRPC to connect a
Knative serving service with other services, for example, to provide
simple, high performance communication between internal
microservices. Knative serving supports both
unary
and
streaming
gRPC calls.
gRPC Unary
In a unary RPC call, the client sends a single request to the server and gets a
single response back, similar to a normal function call:
The following streaming options are available with gRPC.
Server streaming RPCs where the client sends a request to the server and gets a
stream to read containing a sequence of messages. The client reads the returned
stream until there are no more messages.
Client streaming RPCs where the client writes a sequence of messages and sends
them to the server in a stream. After the client finishes writing messages, it
waits for the server to return its response.
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.
To integrate your service with gRPC,
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.
Defining and compiling messages in a proto file
There are no extra or Knative serving 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 Knative serving 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.
Listening for gRPC requests in a Knative serving service
The only special requirement for a gRPC server running in
Knative serving is to listen at the port specified by the PORT
environment variable as shown in the code:
Go
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 need
to specify the host domain, which is the URL of the Knative serving 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
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, using
a gRPC connection configured as mentioned previously.
Go
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)}
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eKnative Serving supports both unary and streaming gRPC calls, enabling high-performance communication between microservices.\u003c/p\u003e\n"],["\u003cp\u003egRPC offers several streaming options, including server streaming, client streaming, and bidirectional streaming, for various communication patterns.\u003c/p\u003e\n"],["\u003cp\u003eIntegrating a service with gRPC involves defining messages in a proto file, creating a gRPC server and client, and handling requests and responses.\u003c/p\u003e\n"],["\u003cp\u003eKnative Serving requires gRPC servers to listen on the port specified by the \u003ccode\u003ePORT\u003c/code\u003e environment variable.\u003c/p\u003e\n"],["\u003cp\u003eTo connect to a gRPC service, you specify the service's URL, which can be the Knative serving URL or custom domain, and use port 443.\u003c/p\u003e\n"]]],[],null,["# Invoking with gRPC\n\nThis page shows Knative serving-specific details for developers who\nwant to use [gRPC](https://grpc.io/) to connect a\nKnative serving service with other services, for example, to provide\nsimple, high performance communication between internal\nmicroservices. Knative serving supports both\n[unary](#before-you-begin)\nand\n[streaming](#before-you-begin)\ngRPC calls. \n\n### gRPC Unary\n\nIn a unary RPC call, the client sends a single request to the server and gets a single response back, similar to a normal function call: \n\n```\nrpc SayHello(HelloRequest) returns (HelloResponse);\n``` \nOK \n\n### gRPC Streaming\n\n\u003cbr /\u003e\n\nThe following streaming options are available with gRPC.\nServer streaming RPCs where the client sends a request to the server and gets a\nstream to read containing a sequence of messages. The client reads the returned\nstream until there are no more messages. \n\n```\nrpc LotsOfReplies(HelloRequest) returns (stream HelloResponse);\n```\n\n\u003cbr /\u003e\n\nClient streaming RPCs where the client writes a sequence of messages and sends\nthem to the server in a stream. After the client finishes writing messages, it\nwaits for the server to return its response. \n\n```\nrpc LotsOfGreetings(stream HelloRequest) returns (HelloResponse);\n```\n\n\u003cbr /\u003e\n\nBidirectional streaming RPCs where client and server send messages in two\nread-write streams that operate independently. \n\n```\nrpc BidiHello(stream HelloRequest) returns (stream HelloResponse);\n``` \nOK\n\nPossible use cases include:\n\n- Communication between internal microservices.\n- High loads of data (gRPC uses [protocol buffers](https://developers.google.com/protocol-buffers), which are up to seven times faster than REST calls).\n- Only a simple service definition is needed, you don't want to write a full client library.\n\nTo integrate your service with gRPC,\n\n- Define the request messages and responses in a proto file and compile them.\n- Create a gRPC server to handle requests and return responses: it should listen to the `PORT` environment variable.\n- Create a client that sends requests and handles responses from the gRPC server.\n- Optionally, add authentication.\n- Build and deploy your service.\n\nDefining and compiling messages in a proto file\n-----------------------------------------------\n\nThere are no extra or Knative serving specific things to add to your proto\ndefinitions. Just as with any other use of gRPC, you use\n[gRPC protocol buffers](https://grpc.io/docs/guides/#working-with-protocol-buffers)\nfor service definitions and data serialization.\n\nCreating a gRPC client\n----------------------\n\nThere are no extra or Knative serving specific things to add to a client\nthat uses gRPC: follow the gRPC docs on using service definitions in\n[client code](https://grpc.io/docs/guides/concepts/#using-the-api), and the\nsample clients provided in the language-specific\n[gRPC tutorials](https://grpc.io/docs/languages).\n\nListening for gRPC requests in a Knative serving service\n--------------------------------------------------------\n\nThe only special requirement for a gRPC server running in\nKnative serving is to listen at the port specified by the `PORT`\nenvironment variable as shown in the code:\n\n\n### Go\n\n func main() {\n \tlog.Printf(\"grpc-ping: starting server...\")\n\n \tport := os.Getenv(\"PORT\")\n \tif port == \"\" {\n \t\tport = \"8080\"\n \t\tlog.Printf(\"Defaulting to port %s\", port)\n \t}\n\n \tlistener, err := net.Listen(\"tcp\", \":\"+port)\n \tif err != nil {\n \t\tlog.Fatalf(\"net.Listen: %v\", err)\n \t}\n\n \tgrpcServer := grpc.NewServer()\n \tpb.RegisterPingServiceServer(grpcServer, &pingService{})\n \tif err = grpcServer.Serve(listener); err != nil {\n \t\tlog.Fatal(err)\n \t}\n }\n\n\u003cbr /\u003e\n\nOpening a gRPC connection to a service\n--------------------------------------\n\nTo open a gRPC connection to a service so you can send gRPC messages, you need\nto specify the host domain, which is the URL of the Knative serving service\nor the custom domain [mapped](/anthos/run/archive/docs/mapping-custom-domains) to that service,\nalong with the port 443, which is the port expected to be used by gRPC.\n\n\n### Go\n\n\n import (\n \t\"crypto/tls\"\n \t\"crypto/x509\"\n\n \t\"google.golang.org/grpc\"\n \t\"google.golang.org/grpc/credentials\"\n )\n\n // NewConn creates a new gRPC connection.\n // host should be of the form domain:port, e.g., example.com:443\n func NewConn(host string, insecure bool) (*grpc.ClientConn, error) {\n \tvar opts []grpc.DialOption\n \tif host != \"\" {\n \t\topts = append(opts, grpc.WithAuthority(host))\n \t}\n\n \tif insecure {\n \t\topts = append(opts, grpc.WithInsecure())\n \t} else {\n \t\t// Note: On the Windows platform, use of x509.SystemCertPool() requires\n \t\t// Go version 1.18 or higher.\n \t\tsystemRoots, err := x509.SystemCertPool()\n \t\tif err != nil {\n \t\t\treturn nil, err\n \t\t}\n \t\tcred := credentials.NewTLS(&tls.Config{\n \t\t\tRootCAs: systemRoots,\n \t\t})\n \t\topts = append(opts, grpc.WithTransportCredentials(cred))\n \t}\n\n \treturn grpc.Dial(host, opts...)\n }\n\n\u003cbr /\u003e\n\nSending gRPC requests without authentication\n--------------------------------------------\n\nThe following sample shows how to send a request without authentication, using\na [gRPC connection](#connect) configured as mentioned previously.\n\n\n### Go\n\n\n import (\n \t\"context\"\n \t\"time\"\n\n \tpb \"github.com/GoogleCloudPlatform/golang-samples/run/grpc-ping/pkg/api/v1\"\n \t\"google.golang.org/grpc\"\n )\n\n // pingRequest sends a new gRPC ping request to the server configured in the connection.\n func pingRequest(conn *grpc.ClientConn, p *pb.Request) (*pb.Response, error) {\n \tctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\n \tdefer cancel()\n\n \tclient := pb.NewPingServiceClient(conn)\n \treturn client.Send(ctx, p)\n }\n\n\u003cbr /\u003e"]]