Explorando a Gateway API em Ambientes Locais com kind

Este guia prático tem como objetivo orientar a configuração de um ambiente experimental local para a Gateway API utilizando o kind (Kubernetes in Docker).

Para empresas que buscam modernizar o gerenciamento de conexões e tráfego, a Gateway API representa a evolução do padrão Ingress, oferecendo uma interface mais expressiva, orientada a papéis e extensível. Este setup é ideal para times de engenharia que desejam validar conceitos antes de avançar para implementações complexas em provedores de cloud ou ambientes produtivos.

Atenção: Este é um ambiente estritamente focado em aprendizado e experimentação. Os componentes descritos aqui não possuem os requisitos de resiliência e segurança necessários para ambientes de produção. Para deployments reais, escolha uma implementação compatível com os SLAs do seu negócio.

Visão Geral

Neste guia, você irá:

1. Configurar um cluster Kubernetes local via kind.
2. Implantar o cloud-provider-kind, que simula funcionalidades de nuvem, fornecendo tanto Services do tipo LoadBalancer quanto um controlador de Gateway API.
3. Criar recursos de Gateway e HTTPRoute para gerenciar o tráfego de uma aplicação demo.
4. Validar as configurações de roteamento localmente.

Pré-requisitos

Certifique-se de ter as seguintes ferramentas instaladas:

• Docker: Necessário para rodar o kind e o cloud-provider-kind.
• kubectl: CLI oficial do Kubernetes.
• kind: Para orquestração do cluster local.
• curl: Para testar as rotas configuradas.

Passo 1: Criar o cluster kind

Inicie um novo cluster executando:

Copiarkind create cluster

Isso criará um nó único de Kubernetes rodando dentro de um container Docker.

Passo 2: Instalar o cloud-provider-kind

O cloud-provider-kind é fundamental neste cenário por prover dois componentes chave:

• Um LoadBalancer controller que atribui endereços IP aos Services.
• Um Gateway API controller que interpreta as especificações da API e instala automaticamente as CRDs (Custom Resource Definitions) necessárias.

Execute o componente como um container Docker na mesma rede do host:

CopiarVERSION="$(basename $(curl -s -L -o /dev/null -w '%{url_effective}' https://github.com/kubernetes-sigs/cloud-provider-kind/releases/latest))"
docker run -d --name cloud-provider-kind --rm --network host -v /var/run/docker.sock:/var/run/docker.sock registry.k8s.io/cloud-provider-kind/cloud-controller-manager:${VERSION}

Nota: Dependendo do seu sistema operacional, pode ser necessário rodar o comando com privilégios de administrador para acessar o socket do Docker.

Verifique se o container está ativo:

Copiardocker ps --filter name=cloud-provider-kind

Experimentando a Gateway API

O cloud-provider-kind provisiona automaticamente uma GatewayClass chamada cloud-provider-kind. Este recurso serve como o "template" para a criação dos seus Gateways.

Deploy de um Gateway

O manifesto abaixo cria um Gateway que escuta na porta 80 e aceita rotas de qualquer namespace que sigam o padrão de host *.exampledomain.example.

Copiar---
apiVersion: v1
kind: Namespace
metadata:
  name: gateway-infra
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
  namespace: gateway-infra
spec:
  gatewayClassName: cloud-provider-kind
  listeners:
  - name: default
    hostname: "*.exampledomain.example"
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All

Após aplicar, verifique se o status está como PROGRAMMED e se há um endereço IP atribuído:

Copiarkubectl get gateway -n gateway-infra gateway

Deploy da Aplicação Demo

Usaremos uma aplicação echo para validar o roteamento. Ela responde detalhes da requisição, como headers e variáveis de ambiente na porta 3000.

CopiarapiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: echo
  name: echo
  namespace: demo
spec:
  ports: 
  - name: http
    port: 3000
    protocol: TCP
    targetPort: 3000
  selector:
    app.kubernetes.io/name: echo
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:    app.kubernetes.io/name: echo
  name: echo
  namespace: demo
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: echo
  template:
    metadata:
      labels:
        app.kubernetes.io/name: echo
    spec:
      containers:
      - env:
        - name: POD_NAME
          valueFrom:            fieldRef:
              apiVersion: v1
              fieldPath: metadata.name
        - name: NAMESPACE
          valueFrom:            fieldRef:
              apiVersion: v1
              fieldPath: metadata.namespace
        image: registry.k8s.io/gateway-api/echo-basic:v20251204-v1.4.1
        name: echo-basic

Criando uma HTTPRoute

A HTTPRoute define as regras de roteamento do Gateway para o Service. No exemplo, direcionamos o tráfego do hostname some.exampledomain.example para a aplicação anterior.

CopiarapiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo
  namespace: demo
spec:
  parentRefs:
  - name: gateway
    namespace: gateway-infra
  hostnames: ["some.exampledomain.example"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: echo
      port: 3000

Testando a Rota

Capture o endereço do Gateway e valide com um curl utilizando a flag --resolve para simular o DNS:

CopiarGW_ADDR=$(kubectl get gateway -n gateway-infra gateway -o jsonpath='{.status.addresses[0].value}')
curl --resolve some.exampledomain.example:80:${GW_ADDR} http://some.exampledomain.example

Se o retorno for um JSON com informações do pod e do namespace, sua Gateway API está operacional.

Troubleshooting: O que observar

Se os testes falharem, a análise sob a ótica de observability deve focar nos recursos:

1. Status do Gateway: Utilize kubectl get gateway -n gateway-infra gateway -o yaml. Verifique se Accepted e Programmed estão como True.
2. Status da HTTPRoute: Utilize kubectl get httproute -n demo echo -o yaml. O erro comum BackendNotFound em ResolvedRefs indica divergência entre a rota e o Service.
3. Logs do Controller: Em casos de falhas silenciosas, inspecione os logs do container do cloud-provider-kind: docker logs -f cloud-provider-kind.

Próximos Passos e Governança

Validada a tecnologia localmente, os times de Infraestrutura e SRE devem considerar:

• Implementações de Produção: Para workloads reais, explore controladores como Cilium, Istio ou Envoy Gateway.
• Separação de Preocupações: A Gateway API permite que o time de infraestrutura gerencie o Gateway enquanto times de desenvolvimento gerenciam suas próprias HTTPRoutes, garantindo maior autonomia e agilidade no delivery.

---

Artigo originalmente publicado por Ricardo Katz (Red Hat) em Kubernetes Blog.