Expose a service with Gateway API and ALB - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Modelo de recursos

A Gateway API define três tipos de recursos, cada um sob responsabilidade de uma função diferente:

Recurso	Responsável	Finalidade
GatewayClass	Provedor de infraestrutura (Alibaba Cloud)	Define uma classe de gateway suportada por um controller — neste caso, o ALB Ingress Controller
Gateway	Operador do cluster	Provisiona uma instância de ALB e configura listeners (portas, protocolos, hostnames)
HTTPRoute	Desenvolvedor de aplicações	Define regras de roteamento que mapeiam requisições recebidas para Services de backend

As equipes de plataforma controlam a infraestrutura, enquanto as equipes de aplicações gerenciam as regras de roteamento de forma independente.

O ALB Ingress Controller oferece suporte à Gateway API desde a versão 2.17.0.

Pré-requisitos

Verifique os seguintes itens:

Um cluster gerenciado ACK executando Kubernetes 1.24 ou superior
O ALB Ingress Controller versão 2.17.0 ou superior instalado no cluster
O Gateway API versão 1.1.0 ou superior instalado no cluster
Dois vSwitches compatíveis com ALB na VPC onde seu cluster está implantado

Verificar o ambiente

O ALB Ingress Controller cria automaticamente um recurso GatewayClass chamado alb. Confirme sua existência antes de continuar.

Console

Faça login no console do ACK. 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, escolha Workloads > Custom Resources.
Clique em gateway.networking.k8s.io e visualize o recurso GatewayClass em v1.

kubectl

Verifique o GatewayClass:

kubectl get gatewayclass

Exemplo de saída:

NAME   CONTROLLER                         ACCEPTED   AGE
alb    gateways.alibabacloud.com/alb/v1   True       1m

O valor ACCEPTED: True confirma que o GatewayClass está pronto.

Implantar uma aplicação de exemplo

Crie um arquivo httpbin.yaml:

O Service usa ClusterIP por padrão. Se o seu cluster utilizar o plug-in de rede Flannel, altere spec.type para NodePort .

apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
        version: v1
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/mse/go-httpbin
          args:
            - "--port=8090"
            - "--version=v1"
          imagePullPolicy: Always
          name: go-httpbin
          ports:
            - containerPort: 8090
---
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: 8090
      protocol: TCP
  selector:
    app: go-httpbin

Aplique o manifesto:

kubectl apply -f httpbin.yaml

Implantar o Gateway e a regra de roteamento

Importante

A criação de um Gateway provisiona uma instância de ALB e gera custos. As instâncias de ALB criadas por um Gateway não são excluídas automaticamente quando você exclui o cluster. Exclua o recurso Gateway antes de excluir o cluster para evitar cobranças inesperadas.

Etapa 1: Criar o Gateway e o HTTPRoute

Crie um arquivo gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: alb
  namespace: default
spec:
  gatewayClassName: alb
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: "*.ingress.top"
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: demo-route
spec:
  parentRefs:            # Attach this route to the Gateway above
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: alb
  hostnames:
    - demo.ingress.top
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:       # Forward matched traffic to go-httpbin on port 80
        - kind: Service
          name: go-httpbin
          port: 80

O Gateway provisiona uma instância de ALB com um listener HTTP na porta 80 para *.ingress.top. O HTTPRoute encaminha o tráfego de demo.ingress.top para o Service go-httpbin.

Aplique o manifesto:

kubectl apply -f gateway.yaml

Etapa 2: Aguardar o Gateway ficar pronto

kubectl wait --for=condition=programmed gateway/alb --timeout=120s

Verifique o endereço do Gateway:

kubectl get gateway alb

Exemplo de saída:

NAME   CLASS   ADDRESS                                                  PROGRAMMED   AGE
alb    alb     alb-0mwhq4ck6xxxxxxxxx.cn-hangzhou.alb.aliyuncsslb.com   True         2m12s

Etapa 3: Verificar o status do HTTPRoute

kubectl describe httproute demo-route | grep Status -A 20

Exemplo de saída:

Status:
  Parents:
    Conditions:
      Last Transition Time:  2025-05-23T08:21:25Z
      Message:               Route is accepted.
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-05-23T08:21:25Z
      Message:               Route is resolved.
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
    Controller Name:         gateways.alibabacloud.com/alb/v1
    Parent Ref:
      Group:  gateway.networking.k8s.io
      Kind:   Gateway
      Name:   alb

Os valores Accepted: True e ResolvedRefs: True confirmam que a rota está ativa.

Etapa 4: Testar o acesso

Obtenha o endereço do Gateway e envie uma requisição de teste:

export ALB_DOMAIN=$(kubectl get gateway alb -n default -o jsonpath='{.status.addresses[?(@.type=="Hostname")].value}')
curl -H "Host: demo.ingress.top" http://${ALB_DOMAIN}/version

Exemplo de saída:

version: v1
hostname: go-httpbin-547xxxxxf6-xxxxx

Casos de uso

Modificar cabeçalhos de requisição com um filtro

Os filtros do HTTPRoute permitem reescrever requisições ou respostas em trânsito. Este exemplo adiciona um cabeçalho de requisição personalizado.

Crie um arquivo httproute-filter.yaml:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: demo-filter
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: alb
  hostnames:
    - filter.ingress.top
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: my-header
                value: foo
      backendRefs:
        - kind: Service
          name: go-httpbin
          port: 80

O filtro RequestHeaderModifier modifica as requisições antes que elas cheguem ao backend:

Adiciona my-header: foo às requisições correspondentes.
Utiliza a ação add, que acrescenta o cabeçalho em vez de substituir cabeçalhos existentes com o mesmo nome.

Aplique a regra de roteamento:

kubectl apply -f httproute-filter.yaml

Teste com o endpoint /header, que ecoa os cabeçalhos da requisição:

curl -H "Host: filter.ingress.top" http://${ALB_DOMAIN}/header

Exemplo de saída:

headers: {
    "Accept": [
      "*/*"
    ],
    "Connection": [
      "close"
    ],
    "Host": [
      "filter.ingress.top"
    ],
    "My-Header": [
      "foo"
    ],
    "Path": [
      "/header"
    ],
    "Protocol": [
      "HTTP/1.1"
    ],
    "Remoteip": [
      "118.xx.xx.91"
    ],
    "URL": [
      "/header"
    ],
    "User-Agent": [
      "curl/8.9.1"
    ]
  }
 query param:
, hostname: go-httpbin-547xxxxxf6-xxxxx

A presença de My-Header: foo na saída confirma que o filtro funciona corretamente.

Dividir tráfego por peso

Atribua pesos a múltiplos Services de backend para distribuir o tráfego proporcionalmente, como em implantações canário.

Crie um arquivo nginx.yaml com dois deployments NGINX:

Expandir para visualizar o conteúdo YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: old-nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      run: old-nginx
  template:
    metadata:
      labels:
        run: old-nginx
    spec:
      containers:
      - image: registry.cn-hangzhou.aliyuncs.com/acs-sample/old-nginx
        imagePullPolicy: Always
        name: old-nginx
        ports:
        - containerPort: 80
          protocol: TCP
      restartPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: old-nginx
spec:
  type: ClusterIP
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: old-nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: new-nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      run: new-nginx
  template:
    metadata:
      labels:
        run: new-nginx
    spec:
      containers:
      - image: registry.cn-hangzhou.aliyuncs.com/acs-sample/new-nginx
        imagePullPolicy: Always
        name: new-nginx
        ports:
        - containerPort: 80
          protocol: TCP
      restartPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: new-nginx
spec:
  type: ClusterIP
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: new-nginx

O old-nginx retorna old; o new-nginx retorna new. Ambos são implantados no namespace default.

Crie um arquivo httproute-weight.yaml:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: demo-weight
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: alb
  hostnames:
    - weight.ingress.top
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        # Weights are relative, not percentages — they do not need to add up to 100.
        - kind: Service
          name: old-nginx
          port: 80
          weight: 100
        - kind: Service
          name: new-nginx
          port: 80
          weight: 100

Ambos os backends têm pesos iguais (100:100), portanto o tráfego é dividido na proporção 1:1.

Aplique os manifestos:

kubectl apply -f nginx.yaml
kubectl apply -f httproute-weight.yaml

Envie 10 requisições para observar a distribuição:

for i in {1..10}; do curl -H "Host: weight.ingress.top" http://${ALB_DOMAIN}/; done

Exemplo de saída:

old
new
new
old
new
old
old
new
new
old

O tráfego é dividido aproximadamente na proporção 1:1 entre os dois backends.

Configurar um certificado TLS

Adicione terminação HTTPS ao Gateway referenciando um Secret do Kubernetes com seu certificado TLS.

Etapa 1: Criar um certificado autoassinado

openssl req -subj '/CN=ingress.top' -new -newkey rsa:2048 -sha256 \
  -days 365 -nodes -x509 -keyout server.key -out server.crt \
  -addext "subjectAltName = DNS:ingress.top" \
  -addext "keyUsage = digitalSignature" \
  -addext "extendedKeyUsage = serverAuth" 2> /dev/null; \
  openssl x509 -in server.crt -subject -noout

Etapa 2: Criar um Secret TLS

kubectl create secret tls ingress.top --key server.key --cert server.crt

Etapa 3: Atualizar o Gateway para adicionar um listener HTTPS

Crie um arquivo gateway-tls.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: alb
  namespace: default
spec:
  gatewayClassName: alb
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: "*.ingress.top"
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.ingress.top"
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate          # ALB terminates TLS and forwards plain HTTP to backends
        certificateRefs:
          - kind: Secret
            name: ingress.top   # The Secret created in the previous step

No modo Terminate, o ALB descriptografa o tráfego HTTPS e encaminha HTTP simples para os backends. O campo certificateRefs referencia o Secret que contém o certificado e a chave privada.

Aplique a atualização:

kubectl apply -f gateway-tls.yaml

Etapa 4: Verificar o certificado

Aguarde até que o status PROGRAMMED do Gateway retorne para True:

kubectl wait --for=condition=programmed gateway/alb --timeout=120s

Verifique o certificado:

openssl s_client -servername ingress.top -connect ${ALB_DOMAIN}:443

Exemplo de saída:

CONNECTED(00000003)
depth=0 CN = ingress.top
verify error:num=18:self-signed certificate
verify return:1
depth=0 CN = ingress.top
verify return:1
---
Certificate chain
 0 s:CN = ingress.top
   i:CN = ingress.top
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Jun 24 10:49:39 2025 GMT; NotAfter: Jun 24 10:49:39 2026 GMT
---
Server certificate
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
subject=CN = ingress.top
issuer=CN = ingress.top
---
...
New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256
Server public key is 2048 bit
...
Verify return code: 18 (self-signed certificate)

O valor CN = ingress.top e a cifra TLSv1.2 confirmam que a terminação TLS está funcionando. O erro de self-signed certificate é esperado — utilize um certificado assinado por CA em produção.

Teste o acesso HTTPS com a flag -k para ignorar a verificação de certificado autoassinado:

curl -H "Host: demo.ingress.top" -k https://${ALB_DOMAIN}/version

Exemplo de saída:

version: v1
hostname: go-httpbin-547xxxxxf6-xxxxx

Próximos passos

Gateway API — Especificação completa, incluindo roteamento avançado como correspondência baseada em cabeçalhos e espelhamento de tráfego.
ALB Ingress Controller — Anotações específicas do ALB e configurações para cargas de trabalho em produção.