Set Up gRPC Services

Deploy gRPC services with HTTP/2 and automatic TLS

Prerequisites

• A deployed CVM on Phala Cloud
• Docker image with gRPC service
• gRPC client tools for testing

This guide shows you how to deploy gRPC services with native HTTP/2 support and automatic TLS encryption.

How gRPC Works Through the Gateway

gRPC services get special HTTP/2 treatment:

1. Add a g suffix to your port: <app-id>-<port>g.<cluster>.phala.network
2. Gateway detects the g suffix and enables HTTP/2 via ALPN negotiation
3. gRPC traffic flows over HTTP/2 with automatic TLS termination
4. Your service handles standard gRPC calls without TLS configuration

Note: The g suffix enables HTTP/2 for any service, not just gRPC. You can use it for any HTTP/2-compatible application that benefits from multiplexing, server push, or header compression.

Deploy Your gRPC Service

services:
  grpc-server:
    image: your-grpc-service:latest
    ports:
      - "50051:50051"  # Standard gRPC port
    environment:
      GRPC_PORT: 50051
      # No TLS config needed - gateway handles it

Access your gRPC service at: <app-id>-50051g.dstack-prod5.phala.network:443

Note the g suffix - this tells the gateway to enable HTTP/2.

Connect from Clients

Go

// Go client
conn, err := grpc.Dial(
    "<app-id>-50051g.dstack-prod5.phala.network:443",
    grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{
        ServerName: "<app-id>-50051g.dstack-prod5.phala.network",
    })),
)

# Python client
channel = grpc.secure_channel(
    '<app-id>-50051g.dstack-prod5.phala.network:443',
    grpc.ssl_channel_credentials()
)

// Node.js client
const credentials = grpc.credentials.createSsl();
const client = new YourService(
    '<app-id>-50051g.dstack-prod5.phala.network:443',
    credentials
);

gRPC with Custom Domains

Use dstack-ingress for custom domains:

services:
  dstack-ingress:
    image: dstacktee/dstack-ingress:2.2@sha256:d05a7b343c37c1cca1bba8dbf7e8f3c6d2118158af2d41c455103796db4f67f0
    ports:
      - "443:443"
    environment:
      - DOMAIN=api.mycompany.com
      - TARGET_ENDPOINT=grpc-server:50051
      - ALPN=h2  # Allow gRPC clients to negotiate HTTP/2
      - CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN}
      - GATEWAY_DOMAIN=_.${DSTACK_GATEWAY_DOMAIN}
      - CERTBOT_EMAIL=${CERTBOT_EMAIL}
    volumes:
      - /var/run/dstack.sock:/var/run/dstack.sock
      - /var/run/tappd.sock:/var/run/tappd.sock
      - cert-data:/etc/letsencrypt
      - evidences:/evidences

  grpc-server:
    image: your-grpc-service:latest

volumes:
  cert-data:
  evidences:

Then connect to: api.mycompany.com. Learn more details at Set up custom domains.

dstack-ingress terminates TLS and forwards raw TCP to the backend. For gRPC custom domains, set ALPN=h2 so clients can negotiate HTTP/2 over TLS; your backend should accept cleartext HTTP/2 on TARGET_ENDPOINT.

Testing with grpcurl

# List services
grpcurl <app-id>-50051g.dstack-prod5.phala.network:443 list

# Call a method
grpcurl -d '{"name": "world"}' \
    <app-id>-50051g.dstack-prod5.phala.network:443 \
    your.service.v1.YourService/SayHello

Key Differences

gRPC (with g suffix):

• Native HTTP/2 with ALPN negotiation
• Optimal performance for gRPC protocols
• Proper streaming support

Regular HTTP:

• Standard HTTP/1.1 or HTTP/2
• Best for REST APIs and web applications
• No gRPC-specific optimizations

Internal vs External

services:
  grpc-client:
    environment:
      GRPC_SERVER: grpc-server:50051  # Internal: direct connection
      
  grpc-server:
    ports:
      - "50051:50051"  # External: HTTP/2 via gateway

Troubleshooting

No HTTP/2 negotiation? Use the g suffix and verify ALPN support.

Connection refused? Check port mapping and service status.

TLS errors? Connect to port 443 with correct hostname.

Next Steps

• Expose TCP services
• Set up custom domains
• Learn about security