How to configure a gRPC service for Nginx Ingress - Container Service for Kubernetes

For gRPC applications deployed in ACK clusters, configure Nginx Ingress and add the nginx.ingress.kubernetes.io/backend-protocol: "GRPC" annotation to route gRPC traffic and enable external client access.

Prerequisites

Ensure the following:

An ACK cluster with the NGINX Ingress Controller installed
kubectl connected to the cluster.
A domain name for gRPC traffic (e.g., grpc.example.com)
A TLS certificate for that domain (CA-signed or self-signed for testing)

How it works

When a client sends a gRPC request to the Ingress endpoint, NGINX:

Terminates TLS and decrypts the traffic.
Forwards the decrypted gRPC traffic (over HTTP/2) to the backend pod on port 50051.
Returns the gRPC response to the client.

The backend-protocol: "GRPC" annotation tells the Ingress controller to proxy traffic as gRPC instead of HTTP:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grpc-ingress
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"  # Proxy traffic as gRPC (HTTP/2)
spec:
  tls:
  - hosts:
    - grpc.example.com          # Replace with your domain
    secretName: nginx-ingress-tls
  rules:
  - host: grpc.example.com      # Replace with your domain
  # ...

Step 1: Deploy a sample gRPC application

Console

On the Clusters page, click the name of your cluster. In the left navigation pane, click Workloads > Deployments.

On the Deployments page, click Create from YAML. Paste the following YAML and click Create.

Sample application YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: grpc-service
spec:
  replicas: 1
  selector:
    matchLabels:
      run: grpc-service
  template:
    metadata:
      labels:
        run: grpc-service
    spec:
      containers:
      - image: registry.cn-hangzhou.aliyuncs.com/acs-sample/grpc-server:latest
        imagePullPolicy: Always
        name: grpc-service
        ports:
        - containerPort: 50051
          protocol: TCP
      restartPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: grpc-service
spec:
  ports:
  - port: 50051
    protocol: TCP
    targetPort: 50051
  selector:
    run: grpc-service
  sessionAffinity: None
  type: NodePort

In the dialog, click View and verify the Pod is Running.

kubectl

Create grpc.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: grpc-service
spec:
  replicas: 1
  selector:
    matchLabels:
      run: grpc-service
  template:
    metadata:
      labels:
        run: grpc-service
    spec:
      containers:
      - image: registry.cn-hangzhou.aliyuncs.com/acs-sample/grpc-server:latest
        imagePullPolicy: Always
        name: grpc-service
        ports:
        - containerPort: 50051
          protocol: TCP
      restartPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: grpc-service
spec:
  ports:
  - port: 50051
    protocol: TCP
    targetPort: 50051
  selector:
    run: grpc-service
  type: NodePort

Deploy the application:
```
kubectl apply -f grpc.yaml
```

The sample application exposes a Greeter service with a single unary RPC, SayHello:

gRPC sample application interface definition

package helloworld;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

See gRPC service examples.

Step 2: Store the TLS certificate as a Secret

Nginx Ingress requires TLS to enable HTTP/2, which gRPC depends on. Store your TLS certificate and private key in a Kubernetes Secret for the Ingress controller to use.

Get a TLS certificate for your domain:
- Production: Purchase a certificate from a trusted Certificate Authority (CA). For Alibaba Cloud certificates, download the certificate files.
- Testing: Generate a self-signed certificate.
Create a Secret named nginx-ingress-tls to store the certificate and private key.
Console
1. Log on to the ACK console. In the left navigation pane, click Clusters.
2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Configurations > Secrets.
3. On the Secrets page, select the default namespace and click Create. Configure the Secret and click OK.
  Name
  nginx-ingress-tls
  Type
  TLS Certificate
  Under + Add, enter the certificate and private key:
  - Certificates: Full content of the certificate file (.crt or .pem).
  - Key: Full content of the private key file (.key).
kubectl
Replace PUBLIC_CERT and PRIVATE_KEY with your certificate and key file paths:
```
# --cert: certificate file (.crt or .pem)
# --key:  private key file (.key)
kubectl create secret tls nginx-ingress-tls --cert PUBLIC_CERT --key PRIVATE_KEY
```

Step 3: Configure the Ingress to expose the service

Log on to the ACK console and click the cluster name. In the left navigation pane, choose Add-ons.
Search for NGINX Ingress Controller and click Install or Upgrade.
Note: Versions earlier than v1.2 are no longer maintained. Upgrade to the latest version.
Configure the Ingress to route gRPC traffic to the backend service.
Console
1. In the left navigation pane, choose Network > Ingresses. Select the default namespace and click Create Ingress.
2. Configure the Ingress as follows, then click OK:
  Gateway Type
  Nginx Ingress
  Name
  grpc-ingress
  Domain Name
  grpc.example.com
  Under Mappings, set:
  Mappings
  /
  Match Rule
  Prefix (Prefix-based match)
  Service
  grpc-service
  Port
  50051
  Under TLS settings, enable the option and set:
  Domain Name
  grpc.example.com
  Secrets
  nginx-ingress-tls
  Under Annotations, add:
  nginx.ingress.kubernetes.io/backend-protocol
  GRPC
3. On the Ingresses page, note the Endpoint of the new Ingress.
  The Ingress takes about 10 seconds to activate. If no endpoint appears after refreshing, check the Events tab to troubleshoot issues.
kubectl
1. Create grpc-ingress.yaml:
```
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grpc-ingress
  annotations:
    # Proxy traffic as gRPC (HTTP/2) to the backend
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - grpc.example.com             # Replace with your domain
    secretName: nginx-ingress-tls  # The Secret created in the previous step
  rules:
  - host: grpc.example.com         # Replace with your domain
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: grpc-service
            port:
              number: 50051
```
2. Apply the Ingress:
```
kubectl apply -f grpc-ingress.yaml
```
3. Get the Endpoint address. If no address is returned, wait 10 seconds and retry:
```
ADDRESS=$(kubectl get ingress grpc-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo $ADDRESS
```

Step 4: Verify the setup

Add the Ingress IP to your hosts file. Replace ADDRESS with the actual IP:
- macOS/Linux: Edit /etc/hosts with sudo vi /etc/hosts
- Windows: Open C:\Windows\System32\drivers\etc\hosts in Notepad (run as administrator)
```
ADDRESS grpc.example.com
```

Install grpcurl, then call the SayHello method:

grpcurl -d '{"name": "gRPC"}' grpc.example.com:443 helloworld.Greeter/SayHello

Expected response:

{
  "message": "Hello gRPC"
}

Limitations

Weight-based routing is not supported for gRPC. gRPC uses long-lived connections incompatible with the Nginx Ingress service-weight annotation.

FAQ

How do I generate a self-signed certificate for testing?

Use openssl to generate a self-signed certificate and private key valid for 365 days:

openssl req -x509 -newkey rsa:2048 -keyout grpc.key -out grpc.crt -days 365 -nodes \
  -subj "/CN=grpc.example.com" \
  -addext "subjectAltName=DNS:grpc.example.com"

Important

Self-signed certificates are not trusted by browsers or gRPC clients by default. Do not use them in production.

What is the difference between SSL and TLS?

Transport Layer Security (TLS) is the modern successor to the deprecated Secure Sockets Layer (SSL). In practice, "SSL certificate" colloquially refers to a TLS certificate.

Container Service for Kubernetes:Configure Nginx Ingress for gRPC

Prerequisites

How it works

Console

kubectl

Step 2: Store the TLS certificate as a Secret

Console

kubectl

Step 3: Configure the Ingress to expose the service

Console

kubectl

Step 4: Verify the setup

Limitations

FAQ

How do I generate a self-signed certificate for testing?

What is the difference between SSL and TLS?

Next steps

Gateway Type	`Nginx Ingress`
Name	`grpc-ingress`
Domain Name	`grpc.example.com`

Mappings	`/`
Match Rule	`Prefix (Prefix-based match)`
Service	`grpc-service`
Port	`50051`

Domain Name	`grpc.example.com`
Secrets	`nginx-ingress-tls`

Name	`nginx-ingress-tls`
Type	TLS Certificate