Configurações avançadas de entrada e controlador de entrada NGINX com o complemento de roteamento de aplicativos

O complemento de roteamento de aplicativos dá suporte a duas maneiras de configurar controladores de entrada e objetos de entrada:

• Configuração do controlador de entrada NGINX, como criar vários controladores, configurar balanceadores de carga privados e definir endereços IP estáticos.
• Configuração por recurso de entrada por meio de anotações.

Pré-requisitos

Um cluster do AKS com o complemento de roteamento de aplicativos.

Conectar-se ao cluster do AKS

Para se conectar ao cluster do Kubernetes no computador local, use o kubectl, o cliente de linha de comando do Kubernetes. Instale-o localmente usando o comando az aks install-cli. Se você usa o Azure Cloud Shell, o kubectl já estará instalado.

Configure o kubectl para se conectar ao seu cluster do Kubernetes usando o comando az aks get-credentials.

az aks get-credentials -resource-group <ResourceGroupName> --name <ClusterName>

Configuração do controlador de entrada NGINX

O complemento de roteamento de aplicativos usa uma definição de recurso personalizado (CRD) do Kubernetes chamada NginxIngressController para configurar controladores de entrada NGINX. Você pode criar mais controladores de entrada ou modificar a configuração existente.

Aqui está uma referência às propriedades que você pode definir para configurar um NginxIngressController.

Propriedade	Descrição
ingressClassName	O nome do IngressClass que será usado para o controlador de entrada NGINX. O padrão é o nome do NginxIngressController se não for especificado.
controllerNamePrefix	Um nome usado para prefixar os recursos gerenciados do controlador de entrada NGINX. Assume o padrão de nginx.
loadBalancerAnnotations	Um conjunto de anotações para controlar o comportamento do serviço do controlador de entrada NGINX, definindo anotações do balanceador de carga
escala	Opções de configuração de como o controlador de entrada NGINX é dimensionado.
scaling.minReplicas	O limite inferior para o número de réplicas do entrada Controller. O padrão é 2 pods.
scaling.maxReplicas	O limite superior para o número de réplicas do entrada Controller. O padrão é 100 pods.
scaling.threshold	Define a rapidez com que os pods do controlador de entrada NGINX devem ser dimensionados com base na carga de trabalho. Rapid significa que o entrada Controller será dimensionado de forma rápida e agressiva para lidar com picos de tráfego repentinos e significativos. Steady prioriza a economia com menos réplicas e mais trabalho. Balanced é uma boa combinação entre os dois que funciona para a maioria dos casos de uso. Se não for especificado, esse campo será padronizado como Balanced.
defaultBackendService	O serviço Kubernetes que o controlador de ingresso NGINX deve usar como padrão, que lida com todos os caminhos de URL e hospeda o controlador entrada-NGINX não entende (ou seja, todas as solicitações que não são mapeadas com um Ingress). O controlador direciona o tráfego para a primeira porta do serviço. Se não for especificado, isso usará o backend padrão que está integrado.
defaultBackendService.namespace	Namespace do serviço.
defaultBackendService.name	Nome do serviço.
defaultSSLCertificate	O segredo referido por essa propriedade contém o certificado padrão a ser usado ao acessar o serviço de backend padrão. Se essa propriedade não for fornecida, o NGINX usará um certificado autoassinado. Se a seção tls: não estiver definida em um entrada, o NGINX fornecerá o certificado padrão, mas não forçará o redirecionamento HTTPS.
defaultSSLCertificate.forceSSLRedirect	Força um redirecionamento para entrada que não especificam uma seção tls:.
defaultSSLCertificate.keyVaultURI	O URI do Azure Key Vault onde o certificado SSL padrão pode ser encontrado. O complemento precisa ser configurado para usar o cofre de chaves.
defaultSSLCertificate.secret	Configura o nome e o namespace onde o segredo SSL padrão está no cluster.
defaultSSLCertificate.secret.name	Nome do segredo.
defaultSSLCertificate.secret.namespace	Namespace do segredo.

Configurações comuns

Controlar a configuração padrão do controlador de entrada NGINX (versão prévia)

Observação

O controle da configuração do controlador de entrada NGINX ao habilitar o complemento está disponível em API 2024-06-02-preview, no Kubernetes versão 1.30 ou posterior e na versão prévia do AKS, extensão da CLI do Azure, versão 7.0.0b5 ou posterior. Para verificar a versão do cluster do AKS, consulte Verificar se há atualizações de cluster do AKS disponíveis.

Quando você habilita o complemento de roteamento de aplicativos com o NGINX, ele cria um controlador de entrada chamado default no app-routing-namespace configurado com um balanceador de carga do Azure voltado para o público. 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 obtém um IP público ou interno ou se ele é criado ao habilitar o complemento.

Aqui estão as opções de configuração possíveis:

• None: o controlador de entrada Nginx padrão não é criado e não será excluído se ele já existir. Os usuários devem excluir o recurso personalizado padrão NginxIngressController manualmente, se desejado.
• Internal: o controlador de entrada Nginx padrão é criado com um balanceador de carga interno. Qualquer alteração de anotações no recurso personalizado NginxIngressController para torná-lo externo será substituída.
• External: o controlador de entrada Nginx padrão criado com um balanceador de carga externo. Qualquer alteração de anotações no recurso personalizado NginxIngressController para torná-lo interno será substituída.
• AnnotationControlled (padrão): o controlador de entrada Nginx padrão é criado com um balanceador de carga externo. Os usuários podem editar o recurso personalizado padrão NginxIngressController para configurar anotações do balanceador de carga.

CLI do Azure

Controlar a configuração padrão do controlador de entrada ao criar o cluster

Para habilitar o roteamento de aplicativos em um novo cluster, use o comando az aks create, especificando os sinalizadores --enable-app-routing e --app-routing-default-nginx-controller. Você precisa definir <DefaultIngressControllerType> como uma das opções de configuração descritas anteriormente.

az aks create \
--resource-group <ResourceGroupName> \
--name <ClusterName> \
--location <Location> \
--enable-app-routing \
--app-routing-default-nginx-controller <DefaultIngressControllerType>

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

Para atualizar a configuração do controlador de entrada padrão de roteamento de aplicativos em um cluster existente, use o comando az aks approuting update, especificando o sinalizador --nginx. Você precisa definir <DefaultIngressControllerType> como uma das opções de configuração descritas anteriormente.

az aks approuting update --resource-group <ResourceGroupName> --name <ClusterName> --nginx <DefaultIngressControllerType>

Bicep

O perfil webAppRouting tem uma configuração opcional nginx com uma propriedade defaultIngressControllerType. Você precisa definir a propriedade defaultIngressControllerType como uma das opções de configuração descritas anteriormente.

"ingressProfile": {
  "webAppRouting": {
    "nginx": {
        "defaultIngressControllerType": "None|Internal|External|AnnotationControlled"
    }
}

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

Para criar outro controlador de entrada NGINX com um Azure Load Balancer voltado para o público:

1. Copie o manifesto YAML a seguir 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 entrada NGINX usando o comando kubectl apply.

   kubectl apply -f nginx-public-controller.yaml
   

   O seguinte exemplo de saída 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

Para criar um controlador de entrada NGINX com um Azure Load Balancer voltado para dentro com um endereço IP privado:

1. Copie o manifesto YAML a seguir 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 entrada NGINX usando o comando kubectl apply.

   kubectl apply -f nginx-internal-controller.yaml
   

   O seguinte exemplo de saída 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

Para criar um controlador de entrada NGINX com um endereço IP estático no Azure Load Balancer:

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

   az group create --name myNetworkResourceGroup --location eastus
   

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

   az network public-ip create \
       --resource-group myNetworkResourceGroup \
       --name myIngressPublicIP \
       --sku Standard \
       --allocation-method static
   

   Observação

   Se você estiver usando um balanceador de carga de SKU Básico no seu cluster do AKS, use Básico no parâmetro --sku ao definir um IP público. Somente os IPs de SKU Básico funcionam com o balanceador de carga de SKU Básico e somente os IPs de SKU Standard funcionam com os balanceadores de carga de SKU Standard.

3. Certifique-se de que a identidade do cluster utilizada pelo cluster do AKS tenha permissões delegadas para o grupo de recursos do IP público usando o comando az role assignment create.

   Observação

   Atualize <ClusterName> e <ClusterResourceGroup> com o nome do cluster do AKS e o nome do grupo de recursos.

   CLIENT_ID=$(az aks show --name <ClusterName> --resource-group <ClusterResourceGroup> --query identity.principalId -o tsv)
   RG_SCOPE=$(az group show --name myNetworkResourceGroup --query id -o tsv)
   az role assignment create \
       --assignee ${CLIENT_ID} \
       --role "Network Contributor" \
       --scope ${RG_SCOPE}
   

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

   Observação

   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 LoadBalancer e é altamente recomendável para evitar possíveis limitações.

   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: "myIngressPublicIP"
       service.beta.kubernetes.io/azure-load-balancer-resource-group: "myNetworkResourceGroup"
   

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

   kubectl apply -f nginx-staticip-controller.yaml
   

   O seguinte exemplo de saída mostra o recurso criado:

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

Verificar se o controlador de entrada foi criado

Você pode verificar o status do controlador de entrada NGINX usando o comando kubectl get nginxingresscontroller.

Observação

Atualize <IngressControllerName> com o nome que você usou ao criar o `NginxIngressController``.

kubectl get nginxingresscontroller -n <IngressControllerName>

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

Você também pode exibir as condições para solucionar problemas:

kubectl get nginxingresscontroller -n <IngressControllerName> -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

Usar o controlador de entrada em uma entrada

1. Copie o manifesto YAML a seguir em um novo arquivo chamado ingress.yaml e salve o arquivo no computador local.

   Observação

   Atualize <Hostname> com o nome do 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 comando kubectl apply.

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

   O seguinte exemplo de saída mostra o recurso criado:

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

Verificar se a entrada gerenciada foi criada

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

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

A saída de exemplo a seguir mostra a entrada gerenciada criada. A classe de entrada, o host e o endereço IP podem ser diferentes:

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

Limpar controladores de entrada

Você pode remover o controlador de entrada NGINX usando o comando kubectl delete nginxingresscontroller.

Observação

Atualize <IngressControllerName> com o nome que você usou ao criar o NginxIngressController.

kubectl delete nginxingresscontroller -n <IngressControllerName>

Configuração por recurso de entrada por meio de anotações

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

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

Observação

Chaves e valores de anotação só podem ser cadeias de caracteres. Outros tipos, como valores boolianos ou numéricos, devem ser citados, ou seja "true", "false", "100".

Aqui estão algumas anotações de exemplos para configurações comuns. Examine a documentação de anotações de entrada do NGINX para obter uma lista completa.

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

Veja um exemplo de configuração de entrada usando esta anotação:

Observação

Atualize <Hostname> com o nome do 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
  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 pelo qual o controlador de entrada NGINX aguarda para fechar uma conexão com sua carga de trabalho. Todos os valores de tempo limite são sem unidade 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"

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

Veja um exemplo de configuração de entrada usando esta anotação:

Observação

Atualize <Hostname> com o nome do 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
  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

Por padrão, o controlador de entrada NGINX usa HTTP para alcançar os serviços. Para configurar protocolos de back-end alternativos, como HTTPS ou GRPC, use a anotação:

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

or

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

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

Veja um exemplo de configuração de entrada usando esta anotação:

Observação

Atualize <Hostname> com o nome do 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
  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

Compartilhamento de Recursos entre Origens (CORS)

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

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

Examine habilitar o CORS para outras opções de configuração.

Veja um exemplo de configuração de entrada usando esta anotação:

Observação

Atualize <Hostname> com o nome do 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
  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

Desabilitar o redirecionamento do SSL

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

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

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

Veja um exemplo de configuração de entrada usando esta anotação:

Observação

Atualize <Hostname> com o nome do 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
  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 é particularmente útil com o roteamento baseado em caminho, em que você pode atender a dois aplicativos Web diferentes no mesmo domínio. Você pode definir o caminho esperado pelo serviço usando a anotação:

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

Veja um exemplo de configuração de entrada usando esta anotação:

Observação

Atualize <Hostname> com o nome do 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
  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

Próximas etapas

Saiba mais sobre como monitorar as métricas do controlador ingress-nginx incluídas com o complemento de roteamento de aplicativos com o Prometheus no Grafana como parte da análise do desempenho e do uso do aplicativo.