Como configuro e soluciono problemas do Ingress NGINX Controller no Amazon EKS?

Breve descrição

O Ingress NGINX Controller implanta, configura e gerencia pods que contêm instâncias do NGINX, um servidor HTTP e proxy reverso de código aberto. Esses pods são expostos por meio do recurso de serviço do controlador. O recurso de serviço recebe o tráfego das aplicações relevantes que os recursos de entrada e serviço do Kubernetes representam. Para obter mais informações, consulte Ingress NGINX Controller no site do GitHub e NGINX no site do NGINX.

Resolução

Opcional: Instale o Helm. Para obter mais informações, consulte Installing Helm (Instalando o Helm) no site do Helm. O Helm não é necessário quando você usa um manifesto YAML para instalar o Ingress NGINX Controller.

Opcional: Instale o AWS Load Balancer Controller. Esse controlador é necessário para que você configure o tipo de destino do grupo de destino do Network Load Balancer para o tipo de destino IP. O tipo de destino IP registra os IPs do pod do Ingress NGINX Controller no grupo de destino. O tipo de destino da instância usa o serviço Ingress NGINX Controller no NodePort para registrar a instância.

Instale o Ingress INGINX Controller

Use um dos métodos a seguir para instalar o Ingress NGINX Controller em um cluster do Kubernetes:

Use o arquivo de manifesto YAML que define todos os diferentes componentes. Use kubectl para criar os recursos no manifesto.

-ou-

Use o Helm para implantar o Ingress NGINX Controller por meio do gráfico do repositório do projeto.

É possível expor o Ingress NGINX Controller externamente por meio de um AWS Classic Load Balancer ou do AWS Network Load Balancer. Por padrão, os dois métodos expõem o controlador por meio de um Classic Load Balancer voltado para a Internet.

Use o Helm para implantar o Ingress NGINX Controller

Use o comando apropriado para configurar e expor o controlador:

Classic Load Balancer voltado para a internet

helm upgrade --install ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
ingress-nginx

Classic Load Balancer interno

Você deve adicionar a seguinte anotação no serviço Kubernetes que expõe o Ingress NGINX Controller:

service.beta.kubernetes.io/aws-load-balancer-internal: true

Exemplo:

Network Load Balancer voltado para a internet

Para alterar o balanceador de carga de Classic para Network, adicione a seguinte anotação:

service.beta.kubernetes.io/aws-load-balancer-type: nlb

Exemplo:

helm upgrade --install ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
--set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-type"="nlb" \
ingress-nginx

Network Load Balancer interno

Para provisionar um Network Load Balancer interno, adicione as seguintes anotações:

service.beta.kubernetes.io/aws-load-balancer-type: nlb

service.beta.kubernetes.io/aws-load-balancer-internal: true

Exemplo:

helm upgrade --install ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
--set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-type"="nlb" \
--set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-internal"="true" \
ingress-nginx

Network Load Balancer no modo IP por meio do AWS Load Balancer Controller

O cluster deve ter o AWS Load Balancer Controller instalado. Para obter mais informações, consulte AWS Load Balancer Controller no site do GitHub.

Use a anotação a seguir para garantir que o AWS Load Balancer Controller assuma o provisionamento do Network Load Balancer:

service.beta.kubernetes.io/aws-load-balancer-type: external

Por padrão, o sistema cria um Network Load Balancer interno. No entanto, é possível adicionar a seguinte anotação para criar um Network Load Balancer voltado para a internet com o tipo de destino do grupo de destino IP:

service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing

Exemplo:

helm upgrade --install ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
--set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-type"="external" \
--set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-scheme"="internet-facing" \
ingress-nginx

Use arquivos de manifesto kubectl e YAML

Baixe o arquivo de manifesto YAML. O comando a seguir baixa o Ingress NGINX Controller versão 1.11.2:

curl -Lo ingress-nginx.yaml https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.11.2/deploy/static/provider/cloud/deploy.yaml

Observação: é possível substituir o valor por outras versões do controlador. Para obter mais informações, consulte Tags no site do GitHub. Em alguns casos, você deve anotar o serviço de balanceador de carga do Kubernetes ingress-nginx-controller para alterar o tipo e as propriedades do balanceador de carga provisionado pelo sistema.

Exemplo:

curl -Lo ingress-nginx.yaml https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.11.2/deploy/static/provider/cloud/deploy.yaml

Classic Load Balancer voltado para a internet

É possível aplicar o manifesto ao cluster sem nenhuma modificação. Execute o seguinte comando:

kubectl apply -f ingress-nginx.yaml

Classic Load Balancer interno

Conclua as etapas a seguir:

1. Modifique o manifesto YAML para adicionar uma seção de anotações que especifique a seguinte anotação:
   service.beta.kubernetes.io/aws-load-balancer-internal: true
   Exemplo:

   ...
   apiVersion: v1
   kind: Service
   metadata:
     ...
     name: ingress-nginx-controller
     namespace: ingress-nginx
     annotations:
       service.beta.kubernetes.io/aws-load-balancer-internal: true
     ...
   type: LoadBalancer
   ...

2. Execute o comando a seguir para aplicar o manifesto ao seu cluster:

   kubectl apply -f ingress-nginx.yaml

Network Load Balancer voltado para a internet

1. Use a anotação a seguir para criar um Network Load Balancer:
   service.beta.kubernetes.io/aws-load-balancer-type: nlb
   Exemplo:

   ...
   apiVersion: v1
   kind: Service
   metadata:
     ...
     name: ingress-nginx-controller
     namespace: ingress-nginx
     annotations:
       service.beta.kubernetes.io/aws-load-balancer-type: nlb
     ...
   type: LoadBalancer
   ...

2. Execute o comando a seguir para aplicar o manifesto ao seu cluster:
   service.beta.kubernetes.io/aws-load-balancer-type: nlb
   Exemplo:

   kubectl apply -f ingress-nginx.yaml

Network Load Balancer interno:

1. Use as seguintes anotações em conjunto para criar um Network Load Balancer interno:
   service.beta.kubernetes.io/aws-load-balancer-type: nlb
   service.beta.kubernetes.io/aws-load-balancer-internal: true
   Exemplo:

   ...
   apiVersion: v1
   kind: Service
   metadata:
     ...
     name: ingress-nginx-controller
     namespace: ingress-nginx
     annotations:
       service.beta.kubernetes.io/aws-load-balancer-type: nlb
       service.beta.kubernetes.io/aws-load-balancer-internal: true
     ...
   type: LoadBalancer
   ...

2. Execute o comando a seguir para aplicar o manifesto ao seu cluster:

   kubectl apply -f ingress-nginx.yaml

Network Load Balancer no modo IP por meio do AWS Load Balancer Controller

1. Instale o AWS Load Balancer Controller no cluster. Para obter mais informações, consulte AWS Load Balancer Controller no site do GitHub. Use a seguinte anotação para fazer com que o AWS Load Balancer Controller provisione um Network Load Balancer:

   service.beta.kubernetes.io/aws-load-balancer-type: external

2. Por padrão, o sistema cria um Network Load Balancer interno. Para criar um Network Load Balancer voltado para a internet com o tipo de destino do grupo de destino como IP, adicione a seguinte anotação:
   service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
   Exemplo:

   apiVersion: v1
   kind: Service
   metadata:
     ...
     name: ingress-nginx-controller
     namespace: ingress-nginx
     annotations:
       service.beta.kubernetes.io/aws-load-balancer-type: external
       service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
     ...
   type: LoadBalancer

3. Execute o comando a seguir para aplicar o manifesto ao seu cluster:

   kubectl apply -f ingress-nginx.yaml

Solucionar problemas

Para obter mais informações, consulte Troubleshooting (Solução de problemas) no site do GitHub.

Erro de sub-rede

Se o Network Load Balancer não conseguir descobrir a sub-rede automaticamente, você poderá receber a seguinte mensagem de erro:

"Reconciler error","controller":"ingress",...,"error":"couldn't auto-discover subnets: unable to resolve at least one subnet"

O AWS Load Balancer Controller usa tags de sub-rede para encontrar automaticamente sub-redes para usar em balanceadores de carga. Para os AWS Load Balancers, o controlador precisa de pelo menos duas sub-redes em diferentes Zonas de disponibilidade. Para Network Load Balancers, o controlador precisa de pelo menos uma sub-rede. Para a descoberta automática, você deve marcar as sub-redes:

• Marque sub-redes públicas com a chave kubernetes.io/role/elb. Defina o valor como 1.
• Marque sub-redes privadas com a chave kubernetes.io/role/internal-elb. Defina o valor como 1.
• Se você usa o AWS Load Balancer Controller versão 2.1.1 e versões anteriores, marque sub-redes públicas e privadas com a chave kubernetes.io/cluster/your-cluster-name. Defina o valor como próprio ou compartilhado.

O campo de endereço não mostra kubectl get nem kubectl describe ingress

Quando você executa o comando kubectl get ingress your-ingress-name, o campo de endereço pode estar vazio. Ou kubectl describe ingress pode não mostrar um endereço atribuído. Em qualquer um desses cenários, realize as seguintes ações:

• Descreva o recurso Ingress para verificar se ele usa a anotação ingressClassName ou kubernetes.io/ingress.class correta. O nome IngressClass do Ingress NGINX Controller deve corresponder ao valor do campo ingressClassName ou da anotação kubernetes.io/ingress.class. Se não corresponder, configure o recurso IngressClass do Ingress NGINX Controller como o único IngressClass padrão para o cluster. Para obter mais informações, consulte Default IngressClass (IngressClass padrão) no site do Kubernetes.
• Descreva o recurso Ingress para ver se há erros adicionados aos eventos pelo Ingress NGINX Controller. Se não houver eventos, então os eventos atingiram o limite de tempo de vida. Ou o Ingress NGINX Controller não consegue detectar as entradas nas quais ele deve agir.
• Execute o comando a seguir para verificar os logs dos pods do Ingress NGINX Controller para controle de acesso baseado em perfis (RBAC) ou outros erros relacionados:

  kubectl logs ingress-nginx-controller-pod-name -n ingress-nginx-namespace

  Observação: substitua ingress-nginx-controller-pod-name pelo nome do seu pod do Ingress NGINX Controller. Substitua ingress-nginx-namespace pelo nome do seu namespace do Ingress NGINX.

Logs de acesso e solicitação

Analise o formato de log padrão do Ingress NGINX Controller para encontrar informações sobre solicitações e respostas específicas. Para fazer isso, consulte Log format (Formato de log) no site do GitHub. No exemplo a seguir, o formato de log padrão corresponde ao seguinte exemplo de log. Isso mostra que o endereço IP e a porta do destino do backend é 192.168.114.102.80 e a resposta HTTP do destino do backend é 200.

192.168.116.133 - - \[24/Sep/2024:22:14:59 +0000\] "GET / HTTP/1.1" 200 45 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10\_15\_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36" 524 0.003 \[default-apache-service-80\] \[\] 192.168.114.102:80 45 0.003 200 ffe584bdeb28959241e8d8408cfc06e5

Informações relacionadas

Exposing Kubernetes Applications, Part 3: Ingress-Nginx Controller (Expondo aplicativos Kubernetes, parte 3: Ingress-Nginx Controller)