Run gRPC Microservices on Knative via HTTP/2 - Container Service for Kubernetes

ACK Knative supports both HTTP and HTTP/2 protocols, including gRPC. This guide shows you how to deploy a gRPC service by creating a Knative Service with the correct port configuration and verify it using a gRPC client.

Prerequisites

Before you begin, ensure that you have:

Deployed Knative in your cluster. For more information, see Deploy Knative.

How it works

gRPC runs on HTTP/2. Knative identifies gRPC traffic by the port name field in your Knative Service spec — this field must be set to h2c (HTTP/2 cleartext). If the port name is missing or incorrect, the Knative gateway cannot route gRPC traffic to your service. Once the port name is correctly configured, the Knative gateway handles all gRPC routing automatically.

Deploy the gRPC service

Log on to the Container Service Management Console. In the left navigation pane, click ACK consoleClusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, choose Applications > Knative.

On the Knative page, click the Services tab. Set Namespace to default, then click Create from Template. From the Sample Template drop-down list, select custom. Paste the following YAML into the template editor and click Create. This creates a Knative Service named helloworld-grpc using the grpcbin test image, which exposes multiple gRPC methods for testing.

The name: h2c field under ports is required. Knative uses this name to identify HTTP/2 (gRPC) traffic and route it correctly.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: helloworld-grpc
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/class: mpa.autoscaling.knative.dev
    spec:
      containers:
      - image: docker.io/moul/grpcbin
        env:
        - name: TARGET
          value: "Knative"
        ports:
        - containerPort: 9000
          name: h2c    # Required: identifies HTTP/2 (gRPC) traffic
          protocol: TCP

Bind the service's default domain to the gateway IP address by adding an entry to your local hosts file. On the Knative page, click the Services tab, click the helloworld-grpc service name, and note the Gateway IP on the service details page. Add the following line to your hosts file (/etc/hosts on Linux and macOS, C:\Windows\System32\drivers\etc\hosts on Windows), replacing the IP address with your actual gateway IP:
```
121.xx.xxx.xx helloworld-grpc.default.example.com
```

Verify the gRPC service

The gRPC request path format is {Package}.{Service}/{Method}. For example, to call the Index method of the GRPCBin service in the grpcbin package, the path is grpcbin.GRPCBin/Index.

Verify using BloomRPC

BloomRPC is a GUI client for testing gRPC services.

Download and install BloomRPC for your operating system.

Save the following Protocol Buffers definition to a local file named gRPC.proto.

syntax = "proto3";

package grpcbin;

service GRPCBin {
  rpc Index(EmptyMessage) returns (IndexReply) {}
  // Returns an empty response.
  rpc Empty(EmptyMessage) returns (EmptyMessage) {}
  // Returns the request parameters as-is.
  rpc DummyUnary(DummyMessage) returns (DummyMessage) {}
  // Server streaming: sends 10 response messages.
  rpc DummyServerStream(DummyMessage) returns (stream DummyMessage) {}
  // Client streaming: accepts 10 requests and returns the last request body.
  rpc DummyClientStream(stream DummyMessage) returns (DummyMessage) {}
  // Bidirectional streaming.
  rpc DummyBidirectionalStreamStream(stream DummyMessage) returns (stream DummyMessage) {}
  // Returns a specified gRPC error.
  rpc SpecificError(SpecificErrorRequest) returns (EmptyMessage) {}
  // Returns a random error.
  rpc RandomError(EmptyMessage) returns (EmptyMessage) {}
  // Returns request headers.
  rpc HeadersUnary(EmptyMessage) returns (HeadersMessage) {}
  // Returns no response.
  rpc NoResponseUnary(EmptyMessage) returns (EmptyMessage) {}
}

message HeadersMessage {
  message Values {
    repeated string values = 1;
  }
  map<string, Values> Metadata = 1;
}

message SpecificErrorRequest {
  uint32 code = 1;
  string reason = 2;
}

message EmptyMessage {}

message DummyMessage {
  message Sub {
    string f_string = 1;
  }
  enum Enum {
    ENUM_0 = 0;
    ENUM_1 = 1;
    ENUM_2 = 2;
  }
  string f_string = 1;
  repeated string f_strings = 2;
  int32 f_int32 = 3;
  repeated int32 f_int32s = 4;
  Enum f_enum = 5;
  repeated Enum f_enums = 6;
  Sub f_sub = 7;
  repeated Sub f_subs = 8;
  bool f_bool = 9;
  repeated bool f_bools = 10;
  int64 f_int64 = 11;
  repeated int64 f_int64s= 12;
  bytes f_bytes = 13;
  repeated bytes f_bytess = 14;
  float f_float = 15;
  repeated float f_floats = 16;
}

message IndexReply {
  message Endpoint {
    string path = 1;
    string description = 2;
  }
  string description = 1;
  repeated Endpoint endpoints = 2;
}

Import gRPC.proto into BloomRPC.
In the left navigation pane, click DummyUnary. At the top of the page, enter the server address in the format <domain>:<port>:
```
helloworld-grpc.default.example.com:80
```
Click the green execute button. If the server returns a response without errors, the service is running correctly.

What's next

Configure an HTTPS certificate for your custom domain. For more information, see Configure HTTPS Certificate Access.