Controlador de entrada NGINX avançado e configurações de entrada com o complemento de roteamento de aplicativo para o Serviço Kubernetes do Azure (AKS)

Propriedades de configuração para controladores de entrada NGINX

O complemento de roteamento de aplicativo usa uma definição de recurso personalizada (CRD) do Kubernetes chamada NginxIngressController para configurar controladores de entrada NGINX. Você pode criar mais controladores de entrada ou modificar configurações existentes.

A tabela a seguir lista as propriedades que você pode definir para configurar um NginxIngressController:

Controle a configuração padrão do controlador de entrada NGINX

Quando é ativado o complemento de roteamento de aplicação com NGINX, é criado um controlador de entrada chamado default no app-routing-namespace configurado com um balanceador de carga público do Azure. Esse controlador de entrada usa um nome de classe de entrada de webapprouting.kubernetes.azure.com.

Você também pode controlar se o padrão recebe um IP público ou interno, ou se ele é criado ao ativar o complemento.

As opções de configuração possíveis incluem:

• None: O controlador de entrada NGINX padrão não é criado e não é excluído se já existir. Você deve excluir manualmente o recurso personalizado padrão NginxIngressController , se desejar.
• Internal: O controlador de entrada NGINX padrão é criado com um balanceador de carga interno. Todas as alterações de anotações do NginxIngressController recurso personalizado para torná-lo externo são substituídas.
• External: O controlador de entrada NGINX padrão criado com um balanceador de carga externo. Todas as alterações de anotação no NginxIngressController recurso personalizado para torná-lo interno são substituídas.
• AnnotationControlled (padrão): O controlador de entrada NGINX padrão é criado com um balanceador de carga externo. Você pode editar o recurso personalizado padrão NginxIngressController para configurar anotações do balanceador de carga.)

Controlar a configuração padrão do controlador de entrada em um novo cluster

Atualizar a configuração padrão do controlador de entrada em um cluster existente

Crie outro controlador de entrada NGINX voltado para o público

1. Copie o seguinte manifesto YAML em um novo arquivo chamado nginx-public-controller.yaml e salve o arquivo em seu computador local.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-public
   spec:
     ingressClassName: nginx-public
     controllerNamePrefix: nginx-public
   

2. Crie os recursos do controlador de ingresso NGINX usando o kubectl apply comando.

   kubectl apply -f nginx-public-controller.yaml
   

   O exemplo de saída a seguir mostra o recurso criado:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
   

Criar um controlador de entrada NGINX interno com um endereço IP privado

1. Copie o seguinte manifesto YAML em um novo arquivo chamado nginx-internal-controller.yaml e salve o arquivo em seu computador local.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-internal
   spec:
     ingressClassName: nginx-internal
     controllerNamePrefix: nginx-internal
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-load-balancer-internal: "true"
   

2. Crie os recursos do controlador de ingresso NGINX usando o kubectl apply comando.

   kubectl apply -f nginx-internal-controller.yaml
   

   O exemplo de saída a seguir mostra o recurso criado:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created
   

Criar um controlador de entrada NGINX com um endereço IP estático

1. Crie um grupo de recursos do Azure usando o az group create comando.

   az group create --name $NETWORK_RESOURCE_GROUP --location $LOCATION
   

2. Crie um endereço IP público estático usando o az network public ip create comando.

   az network public-ip create \
     --resource-group $NETWORK_RESOURCE_GROUP \
     --name $PUBLIC_IP_NAME \
     --sku Standard \
     --allocation-method static
   

   Nota

   Se estiver a usar um balanceador de carga SKU Básico no seu cluster AKS, use Basic para definir um IP público para o parâmetro --sku. Apenas Basic IPs SKU funcionam com o balanceador de carga SKU Básico e apenas Standard IPs SKU funcionam com os balanceadores de carga SKU Padrão .

3. Verifique se a identidade do cluster usada pelo cluster AKS delegou permissões ao grupo de recursos do IP público usando o az role assignment create comando.

   CLIENT_ID=$(az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query identity.principalId -o tsv)
   RG_SCOPE=$(az group show --name $NETWORK_RESOURCE_GROUP --query id -o tsv)
   az role assignment create \
     --assignee ${CLIENT_ID} \
     --role "Network Contributor" \
     --scope ${RG_SCOPE}
   

4. Copie o seguinte manifesto YAML em um novo arquivo chamado nginx-staticip-controller.yaml e salve o arquivo em seu computador local.

   Nota

   Você pode usar service.beta.kubernetes.io/azure-pip-name para nome IP público ou usar service.beta.kubernetes.io/azure-load-balancer-ipv4 para um endereço IPv4 e service.beta.kubernetes.io/azure-load-balancer-ipv6 para um endereço IPv6, conforme mostrado no exemplo YAML. Adicionar a anotação service.beta.kubernetes.io/azure-pip-name garante a criação mais eficiente do Load Balancer e é altamente recomendado para evitar possíveis estrangulamentos.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-static
   spec:
     ingressClassName: nginx-static
     controllerNamePrefix: nginx-static
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-pip-name: "$PUBLIC_IP_NAME"
       service.beta.kubernetes.io/azure-load-balancer-resource-group: "$NETWORK_RESOURCE_GROUP"
   

5. Crie os recursos do controlador de ingresso NGINX usando o kubectl apply comando.

   kubectl apply -f nginx-staticip-controller.yaml
   

   O exemplo de saída a seguir mostra o recurso criado:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created
   

Verifique se o controlador de entrada foi criado

• Verifique o status do controlador de entrada NGINX usando o kubectl get nginxingresscontroller comando.

  kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

  A saída de exemplo a seguir mostra o recurso criado. Pode levar alguns minutos para que o controlador esteja disponível:

  NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
  nginx-public   nginx-public   nginx                  True
  

Ver as condições do controlador de entrada

• Exiba as condições do controlador de entrada para solucionar problemas usando o kubectl get nginxingresscontroller comando.

  kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'
  

  A saída de exemplo a seguir mostra as condições de um controlador de entrada íntegro:

  2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
  2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
  2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
  2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed
  

Use o controlador de entrada em uma entrada

1. Copie o seguinte manifesto YAML em um novo arquivo chamado ingress.yaml e salve o arquivo em seu computador local.

   Nota

   Atualize <HostName> com seu nome de host DNS. O <IngressClassName> é o que você definiu ao criar o NginxIngressController.

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: aks-helloworld
     namespace: hello-web-app-routing
   spec:
     ingressClassName: <IngressClassName>
     rules:
     - host: <HostName>
       http:
         paths:
         - backend:
             service:
               name: aks-helloworld
               port:
                 number: 80
           path: /
           pathType: Prefix
   

2. Crie os recursos de cluster usando o kubectl apply comando.

   kubectl apply -f ingress.yaml --namespace hello-web-app-routing
   

   O exemplo de saída a seguir mostra o recurso criado:

   ingress.networking.k8s.io/aks-helloworld created
   

Verifique se a entrada gerenciada foi criada

• Verifique se a entrada gerenciada foi criada usando o kubectl get ingress comando.

  kubectl get ingress --namespace hello-web-app-routing
  

  Sua saída deve ser semelhante à saída de exemplo a seguir:

  NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
  aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m
  

Remover controladores de entrada

• Remova o controlador de entrada NGINX usando o kubectl delete nginxingresscontroller comando.

  kubectl delete nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

Configuração por recurso de entrada através de anotações

O controlador de entrada NGINX suporta a adição de anotações a objetos de entrada específicos para personalizar seu comportamento.

Você pode anotar o objeto de entrada adicionando a respetiva anotação no metadata.annotations campo.

As seções a seguir fornecem exemplos de configurações comuns. Para obter uma lista completa, consulte a documentação de anotações de ingresso NGINX.

Tamanho máximo do corpo personalizado

Para NGINX, um erro 413 é retornado ao cliente quando o tamanho em uma solicitação excede o tamanho máximo permitido do corpo da solicitação do cliente. Para substituir o valor padrão, use a anotação:

nginx.ingress.kubernetes.io/proxy-body-size: 4m

Aqui está um exemplo de configuração de entrada usando esta anotação:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Tempo limite de conexão personalizado

Você pode alterar o tempo limite que o controlador de entrada NGINX aguarda para fechar uma conexão com sua carga de trabalho. Todos os valores de tempo de espera são sem unidades e em segundos. Para substituir o tempo limite padrão, use a seguinte anotação para definir um tempo limite de leitura de proxy válido de 120 segundos:

nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

Revise os tempos limite personalizados para outras opções de configuração.

Aqui está um exemplo de configuração de entrada usando esta anotação:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Protocolo de back-end

O controlador de entrada NGINX usa HTTP para alcançar os serviços por padrão. Para configurar protocolos de back-end alternativos, como HTTPS ou GRPC, use uma das seguintes anotações:

# HTTPS annotation
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

# GRPC annotation
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

Analise os protocolos de back-end para obter outras opções de configuração.

Aqui está um exemplo de configuração de entrada usando esta anotação:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Partilha de Recursos Transversais à Origem (CORS)

Para habilitar o CORS (Compartilhamento de Recursos entre Origens) em uma regra de Ingress, use a seguinte anotação:

nginx.ingress.kubernetes.io/enable-cors: "true"

Reveja ativar CORS para outras opções de configuração.

Aqui está um exemplo de configuração de entrada usando esta anotação:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Desativar redirecionamento SSL

O controlador redireciona (308) para HTTPS se o TLS estiver habilitado para uma entrada por padrão. Para desabilitar esse recurso para recursos de entrada específicos, use a seguinte anotação:

nginx.ingress.kubernetes.io/ssl-redirect: "false"

Analise a imposição de HTTPS do lado do servidor por meio de redirecionamento para outras opções de configuração.

Aqui está um exemplo de configuração de entrada usando esta anotação:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Reescrita de URL

Em alguns cenários, a URL exposta no serviço de back-end difere do caminho especificado na regra de entrada. Sem uma reescrita, qualquer solicitação retorna 404. Essa configuração é útil com o roteamento baseado em caminho, onde você pode servir dois aplicativos Web diferentes sob o mesmo domínio. Você pode definir o caminho esperado pelo serviço usando a seguinte anotação:

nginx.ingress.kubernetes.io/rewrite-target: /$2

Aqui está um exemplo de configuração de entrada usando esta anotação:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

Atualização do percurso de verificação de integridade do NGINX

O caminho da sonda de integridade padrão para o Balanceador de Carga do Azure associado ao controlador de entrada NGINX deve ser definido como "/healthz". Para garantir verificações de integridade corretas, verifique se o serviço do controlador de ingresso tem a seguinte anotação:

metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Se você estiver usando o Helm para gerenciar seu controlador de entrada NGINX, poderá definir a anotação de teste de integridade do Balanceador de Carga do Azure em um arquivo de valores e aplicá-la durante uma atualização:

controller:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Essa configuração ajuda a manter a disponibilidade do serviço e evita interrupções inesperadas do tráfego durante as atualizações.