NGINX Gateway Fabric

Última atualização em 8 de junho de 2026

O NGINX Gateway Fabric é um controlador Kubernetes Gateway API que usa o NGINX para lidar com o tráfego de entrada. Com ele, você pode publicar serviços HTTP, HTTPS, gRPC, TCP e UDP, configurar roteamento por domínio e caminho, gerenciar TLS e migrar gradualmente do Ingress para o Gateway API.

O Gateway API é a evolução do Ingress. Em vez de um único recurso Ingress, as responsabilidades são divididas entre vários objetos dedicados:

  • GatewayClass — define qual controlador vai gerenciar os gateways.
  • Gateway — descreve o ponto de entrada: portas, protocolos, domínios e configurações de TLS.
  • HTTPRoute — define as regras de roteamento do tráfego HTTP para os serviços de backend.
  • GRPCRoute, TCPRoute, UDPRoute, TLSRoute — tratam outros tipos de tráfego.

O NGINX Gateway Fabric monitora os recursos do Gateway API e os utiliza para criar um NGINX data plane: pods NGINX e um serviço pelo qual o tráfego externo entra no cluster e é direcionado para os serviços Kubernetes.

Instalação
Copiar link

Antes de instalar o NGINX Gateway Fabric pelo painel de controle, você precisa instalar manualmente os CRDs do Gateway API.

Especifique a versão do NGINX Gateway Fabric no parâmetro ref. Por exemplo, para a versão v2.6.3:

kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.6.3" | kubectl apply -f -

Após instalar os CRDs:

  1. Acesse a seção Kubernetes e clique no cluster.
  2. Navegue até a aba Complementos e selecione NGINX Gateway Fabric.
  3. (Opcional) Ative a Instalação avançada para editar o values.yaml. Na maioria dos casos, os valores padrão já são suficientes para começar.
  4. Clique em Instalar.
  5. Aguarde a conclusão e verifique se os pods do NGINX Gateway Fabric estão em execução:
kubectl get pods -n nginx-gateway

Todos os pods devem exibir o status Running.

Você também pode confirmar que os recursos do Gateway API estão disponíveis no cluster:

kubectl api-resources | grep gateway.networking.k8s.io

A instalação padrão do NGINX Gateway Fabric cria um GatewayClass com o nome nginx. Verifique o status:

kubectl get gatewayclass nginx

A coluna ACCEPTED deve exibir True.

Exemplo prático
Copiar link

Neste exemplo, vamos configurar o NGINX Gateway Fabric para receber tráfego HTTP em um único IP externo e roteá-lo para dois serviços diferentes:

  • http://app.example.com/service1 direciona para service1
  • http://app.example.com/service2 direciona para service2

Comece criando um namespace dedicado:

kubectl create namespace nginx-gateway-example

Criar um ConfigMap
Copiar link

Crie um arquivo chamado configmap.yaml com as páginas HTML dos dois serviços:

apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-pages
 namespace: nginx-gateway-example
data:
 service1.html: |
   <html>
     <head><title>Service 1</title></head>
     <body><h1>Service 1</h1></body>
   </html>
 service2.html: |
   <html>
     <head><title>Service 2</title></head>
     <body><h1>Service 2</h1></body>
   </html>

Aplique o manifesto:

kubectl apply -f configmap.yaml

Criar Deployments e Services
Copiar link

Crie o arquivo service1.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
 name: service1
 namespace: nginx-gateway-example
spec:
 replicas: 2
 selector:
   matchLabels:
     app: service1
 template:
   metadata:
     labels:
       app: service1
   spec:
     containers:
       - name: nginx
         image: nginx:latest
         ports:
           - containerPort: 80
         volumeMounts:
           - name: html
             mountPath: /usr/share/nginx/html
     volumes:
       - name: html
         configMap:
           name: nginx-pages
           items:
             - key: service1.html
               path: index.html
---
apiVersion: v1
kind: Service
metadata:
 name: service1
 namespace: nginx-gateway-example
spec:
 selector:
   app: service1
 ports:
   - name: http
     port: 80
     targetPort: 80
 type: ClusterIP

Crie o arquivo service2.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
 name: service2
 namespace: nginx-gateway-example
spec:
 replicas: 2
 selector:
   matchLabels:
     app: service2
 template:
   metadata:
     labels:
       app: service2
   spec:
     containers:
       - name: nginx
         image: nginx:latest
         ports:
           - containerPort: 80
         volumeMounts:
           - name: html
             mountPath: /usr/share/nginx/html
     volumes:
       - name: html
         configMap:
           name: nginx-pages
           items:
             - key: service2.html
               path: index.html
---
apiVersion: v1
kind: Service
metadata:
 name: service2
 namespace: nginx-gateway-example
spec:
 selector:
   app: service2
 ports:
   - name: http
     port: 80
     targetPort: 80
 type: ClusterIP

Aplique os dois manifestos:

kubectl apply -f service1.yaml
kubectl apply -f service2.yaml

Verifique se os pods estão em execução:

kubectl get pods -n nginx-gateway-example

Criar um Gateway
Copiar link

O recurso Gateway define o ponto de entrada externo da sua aplicação. Na instalação padrão, o NGINX Gateway Fabric gerencia Gateways que usam gatewayClassName: nginx.

Crie o arquivo gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: app-gateway
 namespace: nginx-gateway-example
spec:
 gatewayClassName: nginx
 listeners:
   - name: http
     hostname: app.example.com
     protocol: HTTP
     port: 80
     allowedRoutes:
       namespaces:
         from: Same

Aplique:

kubectl apply -f gateway.yaml

Após a criação, o NGINX Gateway Fabric vai provisionar um NGINX data plane e um load balancer no namespace nginx-gateway-example. Verifique o status com:

kubectl get gateway app-gateway -n nginx-gateway-example

Aguarde até que a coluna PROGRAMMED exiba True e a coluna ADDRESS mostre um IP externo.

Você também pode inspecionar os recursos criados:

kubectl get deployments -n nginx-gateway-example
kubectl get svc -n nginx-gateway-example

Criar um HTTPRoute
Copiar link

O HTTPRoute define as regras de roteamento. Crie o arquivo httproute.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: app-route
 namespace: nginx-gateway-example
spec:
 parentRefs:
   - name: app-gateway
 hostnames:
   - app.example.com
 rules:
   - matches:
       - path:
           type: PathPrefix
           value: /service1
     filters:
       - type: URLRewrite
         urlRewrite:
           path:
             type: ReplacePrefixMatch
             replacePrefixMatch: /
     backendRefs:
       - name: service1
         port: 80
   - matches:
       - path:
           type: PathPrefix
           value: /service2
     filters:
       - type: URLRewrite
         urlRewrite:
           path:
             type: ReplacePrefixMatch
             replacePrefixMatch: /
     backendRefs:
       - name: service2
         port: 80

Aplique:

kubectl apply -f httproute.yaml

Confirme que a rota foi aceita:

kubectl get httproute app-route -n nginx-gateway-example -o yaml

O status do recurso deve conter as duas condições:

status: "True"
type: Accepted

status: "True"
type: ResolvedRefs

Neste manifesto, o HTTPRoute aceita requisições para app.example.com e as direciona para diferentes serviços com base no prefixo do caminho. O filtro URLRewrite substitui os prefixos /service1 e /service2 por /, para que o NGINX dentro de cada serviço sirva corretamente sua página principal.

Verificar o funcionamento
Copiar link

Adicione o IP do load balancer como um registro A para app.example.com nas configurações de DNS. Após a propagação, teste os dois endpoints:

curl http://app.example.com/service1
curl http://app.example.com/service2

Se o DNS ainda não tiver propagado, você pode testar pelo IP usando o cabeçalho Host:

curl -H "Host: app.example.com" http://<EXTERNAL_IP>/service1
curl -H "Host: app.example.com" http://<EXTERNAL_IP>/service2

Ambas as requisições devem retornar as páginas do Service 1 e do Service 2.

Limpar os recursos
Copiar link

Para remover todos os recursos criados neste exemplo, execute:

kubectl delete namespace nginx-gateway-example

Isso não desinstala o add-on NGINX Gateway Fabric. Para removê-lo, acesse a aba Complementos no painel de controle do cluster.

Migrar do Nginx Ingress para o NGINX Gateway Fabric
Copiar link

Você pode rodar o NGINX Gateway Fabric junto com o Nginx Ingress e migrar as rotas aos poucos. Essa abordagem permite testar os recursos do Gateway API em um IP externo separado antes de atualizar os registros DNS ou redirecionar o tráfego para o novo Gateway.

Para automatizar a conversão dos recursos Ingress existentes, use o utilitário ingress2gateway. Ele lê os recursos Ingress do cluster ou de arquivos YAML e gera os recursos equivalentes do Gateway API: Gateway, HTTPRoute e outros objetos relacionados.

Pré-requisitos
Copiar link

Antes de migrar, certifique-se de que o cluster está preparado:

  • O Nginx Ingress e o NGINX Gateway Fabric estão instalados.
  • Os recursos Ingress existentes estão funcionando corretamente pelo Nginx Ingress.
  • Existe um GatewayClass chamado nginx no cluster.

Se o Nginx Ingress foi instalado pelo painel de controle da Hostman, ele usa um IngressClass chamado nginx. Você vai precisar desse nome ao rodar o ingress2gateway.

Verifique se as duas classes estão presentes:

kubectl get ingressclass
kubectl get gatewayclass

O resultado deve incluir um IngressClass chamado nginx e um GatewayClass chamado nginx.

Instalar o ingress2gateway
Copiar link

Se você tiver o Go instalado localmente, execute:

go install github.com/kubernetes-sigs/ingress2gateway@v1.1.0

O binário será colocado em $(go env GOPATH)/bin. Certifique-se de que esse diretório está no seu PATH.

Outra opção é instalar via Homebrew:

brew install ingress2gateway

Ou baixar um binário pré-compilado na página de releases do projeto.

Configuração de origem
Copiar link

Neste exemplo, a migração é feita para uma aplicação já publicada pelo Nginx Ingress.

O cluster tem um namespace chamado ingress-migration-demo com:

  • Um recurso Ingress chamado migration-source
  • Os serviços service1 e service2
  • Duas regras de roteamento para o domínio app.example.com:
    • /service1 direciona para service1
    • /service2 direciona para service2

Verifique o Ingress de origem:

kubectl get ingress -n ingress-migration-demo

A coluna CLASS deve exibir nginx.

Converter os recursos Ingress
Copiar link

Para converter o Ingress em recursos do Gateway API, execute:

ingress2gateway print \
  --providers=ingress-nginx \
  --ingress-nginx-ingress-class=nginx \
  --namespace=ingress-migration-demo > gateway-migration.yaml

O que cada flag faz:

  • print exibe os recursos gerados no stdout; o redirecionamento > salva o resultado em gateway-migration.yaml.
  • --providers=ingress-nginx especifica o tipo de Ingress controller de origem.
  • --ingress-nginx-ingress-class=nginx filtra apenas os recursos Ingress que usam a classe nginx.
  • --namespace=ingress-migration-demo limita a conversão ao namespace de origem.

Revisar e corrigir o arquivo gerado
Copiar link

Abra o arquivo gateway-migration.yaml e revise os recursos antes de aplicá-los.

Verifique o campo gatewayClassName no recurso Gateway. Na instalação padrão do NGINX Gateway Fabric, o valor deve ser nginx:

spec:
  gatewayClassName: nginx

Revise também as regras do HTTPRoute. Algumas anotações do Ingress podem ser convertidas em filtros ou tipos de correspondência que precisam de ajuste manual. Por exemplo, para roteamento padrão por prefixo de caminho, use PathPrefix:

rules:
 - matches:
     - path:
         type: PathPrefix
         value: /service1
   filters:
     - type: URLRewrite
       urlRewrite:
         path:
           type: ReplacePrefixMatch
           replacePrefixMatch: /
   backendRefs:
     - name: service1
       port: 80

Se o arquivo gerado contiver rotas com RegularExpression ou anotações não suportadas, verifique a compatibilidade com o NGINX Gateway Fabric e substitua por regras suportadas pelo Gateway API.

Aplicar os recursos do Gateway API
Copiar link

Quando estiver satisfeito com o arquivo, aplique:

kubectl apply -f gateway-migration.yaml

Verifique se o Gateway foi criado e recebeu um IP externo:

kubectl get gateway -A

Confirme que o HTTPRoute foi aceito pelo controlador:

kubectl get httproute -A
kubectl describe httproute <nome-da-rota> -n <namespace>

O status do HTTPRoute deve conter Accepted=True e ResolvedRefs=True.

Testar antes de mudar o tráfego
Copiar link

Enquanto os registros DNS ainda apontam para o Nginx Ingress antigo, verifique o novo Gateway enviando requisições diretamente para o IP externo com o cabeçalho Host:

curl -H "Host: app.example.com" http://<EXTERNAL_IP>/<path>

Onde:

  • app.example.com é o domínio do seu Ingress ou HTTPRoute.
  • <EXTERNAL_IP> é o IP do novo Gateway.
  • <path> é o caminho tratado pela rota.

Compare as respostas do Ingress antigo e do novo Gateway. Se tudo estiver correto, atualize os registros DNS para apontar para o IP do novo load balancer.