How to configure a gRPC service for Nginx Ingress - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Para aplicações gRPC implantadas em clusters ACK, configure o Nginx Ingress e adicione a anotação nginx.ingress.kubernetes.io/backend-protocol: "GRPC" para rotear o tráfego gRPC e permitir o acesso de clientes externos.

Pré-requisitos

Certifique-se de que os seguintes requisitos sejam atendidos:

Um cluster ACK com o NGINX Ingress Controller instalado
kubectl connected to the cluster.
Um nome de domínio para o tráfego gRPC (por exemplo, grpc.example.com)
Um certificado TLS para esse domínio (assinado por CA ou autoassinado para testes)

Como funciona

Quando um cliente envia uma requisição gRPC ao endpoint do Ingress, o NGINX:

Encerra o TLS e descriptografa o tráfego.
Encaminha o tráfego gRPC descriptografado (via HTTP/2) para o pod de backend na porta 50051.
Retorna a resposta gRPC ao cliente.

A anotação backend-protocol: "GRPC" instrui o Ingress controller a fazer proxy do tráfego como gRPC em vez de 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
  # ...

Etapa 1: Implantar uma aplicação gRPC de exemplo

Console

Na página Clusters, clique no nome do seu cluster. No painel de navegação à esquerda, clique em Workloads > Deployments.

Na página Deployments, clique em Create from YAML. Cole o YAML a seguir e clique em Create.

YAML da aplicação de exemplo

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

Na caixa de diálogo, clique em View e verifique se o Pod está com status Running.

kubectl

Crie o arquivo 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

Implante a aplicação:
```
kubectl apply -f grpc.yaml
```

A aplicação de exemplo expõe um service Greeter com um único RPC unário, SayHello:

Definição de interface da aplicação gRPC de exemplo

package helloworld;

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

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Consulte exemplos de service gRPC.

Etapa 2: Armazenar o certificado TLS como um Secret

O Nginx Ingress exige TLS para habilitar o HTTP/2, do qual o gRPC depende. Armazene o certificado TLS e a chave privada em um Kubernetes Secret para que o Ingress controller possa utilizá-los.

Obtenha um certificado TLS para o seu domínio:
- Produção: Adquira um certificado de uma Certificate Authority (CA) confiável. Para certificados Alibaba Cloud, consulte baixe os arquivos de certificado.
- Testes: Generate a self-signed certificate.

Crie um Secret chamado nginx-ingress-tls para armazenar o certificado e a chave privada.

Console

Acesse o ACK console. No painel de navegação à esquerda, clique em Clusters.
Na página Clusters, clique no nome do seu cluster. No painel de navegação à esquerda, clique em Configurations > Secrets.

Na página Secrets, selecione o namespace default e clique em Create. Configure o Secret e clique em OK.

Name	`nginx-ingress-tls`
Type	Ingress TLS Certificate

Em + Add, insira o certificado e a chave privada:

Certificates: Conteúdo completo do arquivo de certificado (.crt ou .pem).
Key: Conteúdo completo do arquivo de chave privada (.key).

kubectl

Substitua PUBLIC_CERT e PRIVATE_KEY pelos caminhos do seu arquivo de certificado e de chave:

# --cert: certificate file (.crt or .pem)
# --key:  private key file (.key)
kubectl create secret tls nginx-ingress-tls --cert PUBLIC_CERT --key PRIVATE_KEY

Etapa 3: Configurar o Ingress para expor o service

Acesse o ACK console e clique no nome do cluster. No painel de navegação à esquerda, escolha Add-ons.
Pesquise pelo NGINX Ingress Controller e clique em Install ou Upgrade.

Nota: Versões anteriores à v1.2 não recebem mais manutenção. Atualize para a versão mais recente.

Configure o Ingress para rotear o tráfego gRPC ao service de backend.

Console

No painel de navegação à esquerda, escolha Network > Ingresses. Selecione o namespace default e clique em Create Ingress.

Configure o Ingress conforme indicado abaixo e clique em OK:

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

Em Mappings, defina:

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

Em TLS settings, ative a opção e defina:

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

Em Annotations, adicione:

nginx.ingress.kubernetes.io/backend-protocol

GRPC

Na página Ingresses, anote o Endpoint do novo Ingress.

O Ingress leva cerca de 10 segundos para ser ativado. Se nenhum endpoint aparecer após atualizar a página, verifique a aba Events para troubleshoot issues .

kubectl

Crie o arquivo 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

Aplique o Ingress:
```
kubectl apply -f grpc-ingress.yaml
```

Obtenha o endereço do Endpoint. Se nenhum endereço for retornado, aguarde 10 segundos e tente novamente:

ADDRESS=$(kubectl get ingress grpc-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo $ADDRESS

Etapa 4: Verificar a configuração

Adicione o ip do Ingress ao arquivo hosts. Substitua ADDRESS pelo ip real:
- macOS/Linux: Edite /etc/hosts com sudo vi /etc/hosts
- Windows: Abra C:\Windows\System32\drivers\etc\hosts no Bloco de Notas (execute como administrador)
```
ADDRESS grpc.example.com
```

Instale o grpcurl e chame o método SayHello:

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

Resposta esperada:

{
  "message": "Hello gRPC"
}

Limitações

O roteamento baseado em peso não é compatível com gRPC. O gRPC utiliza conexões de longa duração, incompatíveis com a anotação service-weight do Nginx Ingress.

FAQ

Como gerar um certificado autoassinado para testes?

Use o openssl para gerar um certificado autoassinado e uma chave privada com validade de 365 dias:

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"

Importante

Certificados autoassinados não são confiáveis por navegadores nem por clientes gRPC por padrão. Não os utilize em produção.

Qual é a diferença entre SSL e TLS?

O Transport Layer Security (TLS) é o sucessor moderno do protocolo Secure Sockets Layer (SSL), que está obsoleto. Na prática, o termo "certificado SSL" é comumente usado para se referir a um certificado TLS.

Container Service for Kubernetes:Configure Nginx Ingress for gRPC

Pré-requisitos

Como funciona

Console

kubectl

Etapa 2: Armazenar o certificado TLS como um Secret

Console

kubectl

Etapa 3: Configurar o Ingress para expor o service

Console

kubectl

Etapa 4: Verificar a configuração

Limitações

FAQ

Como gerar um certificado autoassinado para testes?

Qual é a diferença entre SSL e TLS?

Próximas etapas