Point a route at your gRPC upstream01

Declare the backend as an upstream and add a route whose path is the fully qualified service, /{package.Service}. gRPC calls are HTTP/2 POSTs to /{package.Service}/{Method}, so a path of /users.UserService matches every method on that service.

upstreams:
  - name: users-grpc
    instances:
      - id: users-grpc-1
        host: 127.0.0.1
        port: 50051

routes:
  - path: /users.UserService
    upstream: users-grpc

The router resolves the upstream from the request host and the gRPC path exactly like an HTTP route. To proxy several services, add one route per service.

(Optional) Acknowledge the gRPC config block02

A top-level grpc block exists. You can include it for documentation, but be aware of its current status.

grpc:
  enabled: true
  deadline_propagation: true

Validate and run03

octopus validate -c gateway.yaml
octopus serve -c gateway.yaml

The complete, validated configuration:

gateway:
  listen: "0.0.0.0:8080"

grpc:
  enabled: true
  deadline_propagation: true

upstreams:
  - name: users-grpc
    instances:
      - id: users-grpc-1
        host: 127.0.0.1
        port: 50051

routes:
  - path: /users.UserService
    upstream: users-grpc

Call it04

Use any gRPC client through the gateway. Deadlines propagate: a grpc-timeout header on the request becomes the upstream call timeout (default 30s when absent), and authorization/grpc-* metadata passes straight through.

# grpcurl, plaintext, through the gateway on :8080
grpcurl -plaintext \
  -d '{"id": "42"}' \
  localhost:8080 users.UserService/GetUser

If the upstream cannot be reached the gateway returns gRPC UNAVAILABLE; on timeout it returns DEADLINE_EXCEEDED (as HTTP 200 with the gRPC status in trailers, per the gRPC spec).