gRPC Support

This guide explains how to configure and deploy gRPC services on Runway for Kubernetes (AWS EKS or GCP GKE).

Runway provides end-to-end gRPC support for services deployed on both GKE and EKS clusters. This includes support for:

• External load balancers with optional Runway managed Cloudflare zone
• Internal load balancers for private gRPC services

To enable gRPC for your service, set the spec.protocol field in your default-values.yaml:

apiVersion: runway/v1
kind: RunwayKubernetesService
metadata:
  name: example-service
spec:
  image: "registry.gitlab.com/gitlab-com/gl-infra/platform/runway/example-service:{{ .AppVersion }}"
  command: ["/bin/grpc-server"]
  container_port: 50051
  protocol: grpc  # Enable gRPC protocol

Runway supports gRPC health checks that conform to the standard gRPC Health Checking Protocol. Health checks verify the overall server health and are configured at two levels: Kubernetes probes and load balancer health checks.

Configure startup, liveness, and readiness probes for Kubernetes to monitor pod health:

spec:
  protocol: grpc
  container_port: 50051

  # Health check configuration
  startup_probe:
    timeout_seconds: 1
    period_seconds: 10
    failure_threshold: 10

  liveness_probe:
    timeout_seconds: 1
    period_seconds: 10
    failure_threshold: 3

  readiness_probe:
    timeout_seconds: 1
    period_seconds: 5
    failure_threshold: 1

Runway automatically configures load balancer health checks for gRPC services based on your target runtime.

For EKS, Runway configures the ALB Ingress health check path to /grpc.health.v1.Health/Check as part of the ALB ingress annotations. This tells the AWS Application Load Balancer to use the standard gRPC health check service for overall server health.

For GKE, Runway leverages the Gateway API’s first-class support for gRPC. The Gateway API implicitly handles gRPC health checks using the standard service name grpc.health.v1.Health.Check defined by the gRPC Health Checking Protocol for overall server health.

Here’s a complete example of a gRPC service configuration for both EKS and GKE:

apiVersion: runway/v1
kind: RunwayKubernetesService
metadata:
  name: grpc-example
spec:
  image: "registry.gitlab.com/gitlab-com/gl-infra/platform/runway/grpc-example:{{ .AppVersion }}"
  command: ["/bin/grpc-server"]
  container_port: 50051
  protocol: grpc

  # Autoscaling configuration
  scalability:
    min_instances: 2
    max_instances: 10
    cpu_utilization: 70

  # Resource requirements
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
      ephemeral-storage: "512Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"
      ephemeral-storage: "1Gi"

  # Health check configuration
  startup_probe:
    timeout_seconds: 1
    period_seconds: 10
    failure_threshold: 10

  liveness_probe:
    timeout_seconds: 1
    period_seconds: 10
    failure_threshold: 3

  readiness_probe:
    timeout_seconds: 1
    period_seconds: 5
    failure_threshold: 1

  # Prometheus metrics configuration
  observability:
    scrape_targets:
      - "localhost:8082"

Refer to the schema for more information on these settings.

grpc-example-eks:
  serviceMixins:
    - "runway-eks.service-mixin"

  metadata:
    labels:
      gitlab.com/department: eng-infra
      gitlab.com/department_group: eng-infra-scalability
      gitlab.com/owner_email_handle: your-handle
      gitlab.com/product_category: scalability

grpc-example-gke:
  serviceMixins:
    - "runway-gke.service-mixin"

  metadata:
    labels:
      gitlab.com/department: eng-infra
      gitlab.com/department_group: eng-infra-scalability
      gitlab.com/owner_email_handle: your-handle
      gitlab.com/product_category: scalability

If your gRPC health checks are failing:

1. Check the health check implementation: Confirm your service implements the gRPC Health Checking Protocol

2. Review logs: Check pod logs for health check errors: kubectl logs <pod-name>

3. Test locally: Use grpcurl to test health checks locally:

   grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

If clients cannot connect to your gRPC service:

1. Verify HTTPS: gRPC requires HTTP/2 over HTTPS. Ensure your client uses TLS
2. Check load balancer: Verify the load balancer is configured for gRPC (check annotations on EKS)

For questions or issues with gRPC support, contact the Runway team in #f_runway.