Controlador de entrada NGINX avançado e configurações de entrada com o complemento de roteamento de aplicativo

O complemento de roteamento de aplicativo suporta duas maneiras de configurar controladores de entrada e objetos de entrada:

• Configuração do controlador de entrada NGINX, como a criação de vários controladores, a configuração de balanceadores de carga privados e a definição de endereços IP estáticos.
• Configuração por recurso de entrada através de anotações.

Pré-requisitos

Um cluster AKS com o complemento de roteamento de aplicativos.

Conecte-se ao cluster AKS

Para se conectar ao cluster do Kubernetes a partir do computador local, use kubectlo cliente de linha de comando do Kubernetes. Você pode instalá-lo localmente usando o comando az aks install-cli . Se utilizar o Azure Cloud Shell, o kubectl já está instalado.

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

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

Configuração do controlador de ingresso 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 a configuração existente.

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

Configurações comuns

Controle a configuração padrão do controlador de ingresso NGINX (visualização)

Quando você habilita o complemento de roteamento de aplicativo com NGINX, ele cria um controlador de entrada chamado default configurado com um balanceador de carga do Azure voltado para o app-routing-namespace 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 recebe um IP público ou interno, ou se ele é criado ao ativar 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 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. Quaisquer alterações de anotações no NginxIngressController recurso personalizado para torná-lo externo serão substituídas.
• External: O controlador de entrada Nginx padrão criado com um balanceador de carga externo. Quaisquer alterações de anotações no NginxIngressController recurso personalizado para torná-lo interno serão substituídas.
• 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.

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

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

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

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

Para criar outro controlador de entrada NGINX com um Balanceador de Carga do Azure 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

Para criar um controlador de entrada NGINX com um Balanceador de Carga do Azure 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

Para criar um controlador de entrada NGINX com um endereço IP estático no Balanceador de Carga do Azure:

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

   az group create --name myNetworkResourceGroup --location eastus
   

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 myNetworkResourceGroup \
       --name myIngressPublicIP \
       --sku Standard \
       --allocation-method static
   

   Nota

   Se você estiver usando um balanceador de carga Basic SKU em seu cluster AKS, use Basic para o --sku parâmetro ao definir um IP público. Apenas IPs de SKU Básicos funcionam com o balanceador de carga de SKU Básico e apenas IPs de SKU Padrão funcionam com balanceadores de carga de 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.

   Nota

   Atualize <ClusterName> e <ClusterResourceGroup> com o nome do seu cluster 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 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 service.beta.kubernetes.io/azure-pip-name anotação garante a criação mais eficiente do LoadBalancer e é altamente recomendado 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 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

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

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 quaisquer 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

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 -n hello-web-app-routing
   

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

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

Verifique se o Ingress gerenciado foi criado

Você pode verificar se o Ingress gerenciado foi criado usando o kubectl get ingress comando.

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

A saída de exemplo a seguir mostra o Ingress gerenciado criado. 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

Limpeza de controladores de entrada

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

kubectl delete nginxingresscontroller -n <IngressControllerName>

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 Ingress específicos para personalizar seu comportamento.

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

Aqui estão alguns exemplos de anotações para configurações comuns. Consulte a documentação de anotações de ingresso 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

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 limite são unitários 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

Por padrão, o controlador de entrada NGINX usa HTTP para acessar 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"

ou

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 Ingresso, use a anotação:

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

Analise a ativação do 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

Por padrão, o controlador redireciona (308) para HTTPS se o TLS estiver habilitado para uma entrada. Para desativar esse recurso para recursos de entrada específicos, use a 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

Reconfiguração 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 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

Próximos passos

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