Deploy a gRPC Service on Knative with h2c Protocol - Container Compute Service

ACS Knative supports HTTP and HTTP/2, including gRPC. To expose a gRPC service through Knative, set the container port name to h2c — the standard identifier for HTTP/2 cleartext. Knative Ingress reads this port name and automatically routes gRPC traffic over HTTP/2.

Prerequisites

Before you begin, ensure that you have:

Knative deployed in your ACS cluster. See Deploy Knative

How it works

Deploy a Knative Service with a container port named h2c. Knative Ingress detects this and enables HTTP/2 routing for gRPC traffic.
Map the service's default domain name to the gateway IP in your local hosts file.
Send a gRPC request to the domain name over port 80. Knative routes it to the correct container.

The gRPC path follows the format {package}.{ServiceName}/{MethodName}. For example, grpcbin.GRPCBin/Index routes to the Index method of the GRPCBin service in the grpcbin package.

Deploy a gRPC service

Log on to the ACS console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster you want to manage and click its ID. In the left-side navigation pane of the cluster details page, choose Applications > Knative.
On the Knative page, click the Services tab. Set Namespace to default, click Create from Template, and select Custom from the Sample Template drop-down list.

Copy the following YAML to the template editor and click Create. The critical gRPC configuration is name: h2c in the ports section. This tells Knative Ingress to route traffic using HTTP/2.

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: tells Knative to use HTTP/2 for gRPC routing
          protocol: TCP

After the service is created, add a hosts file entry to map the service's default domain name to the gateway IP. On the Services tab, find the Default Domain and Gateway columns for the helloworld-grpc service. Add an entry to your local hosts file in the following format:
```
<gateway-ip> <default-domain>
```
For example:
```
121.xx.xxx.xx helloworld-grpc.default.example.com
```

Verify the gRPC service

Use BloomRPC to send a test request and confirm the service is responding.

Visit grpcbin and install the BloomRPC version for your operating system.

Save the following proto definition to a file named gRPC.proto on your local machine:

syntax = "proto3";

package grpcbin;

service GRPCBin {
  rpc Index(EmptyMessage) returns (IndexReply) {}
  // Unary: takes an empty message, returns an empty message
  rpc Empty(EmptyMessage) returns (EmptyMessage) {}
  // Unary: takes a DummyMessage, returns a DummyMessage
  rpc DummyUnary(DummyMessage) returns (DummyMessage) {}
  // Server streaming: takes a DummyMessage, streams 10 DummyMessages
  rpc DummyServerStream(DummyMessage) returns (stream DummyMessage) {}
  // Client streaming: streams DummyMessages, returns a DummyMessage
  rpc DummyClientStream(stream DummyMessage) returns (DummyMessage) {}
  // Bidirectional streaming: streams DummyMessages in both directions
  rpc DummyBidirectionalStreamStream(stream DummyMessage) returns (stream DummyMessage) {}
  // Returns a specific gRPC error
  rpc SpecificError(SpecificErrorRequest) returns (EmptyMessage) {}
  // Returns a random gRPC error
  rpc RandomError(EmptyMessage) returns (EmptyMessage) {}
  // Unary: returns response headers
  rpc HeadersUnary(EmptyMessage) returns (HeadersMessage) {}
  // Unary: sends a message but 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-side navigation pane of BloomRPC, click DummyUnary. In the address bar at the top, enter helloworld-grpc.default.example.com:80.
Click the green run button. If the server returns a response, the gRPC service is working correctly.

What's next

Configure a TLS certificate to expose your Knative service over HTTPS with a custom domain name. See Configure a certificate to access Knative Services over HTTPS.