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

Artigo
01/30/2024

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.

NginxIngressController O CRD tem um loadBalancerAnnotations campo para controlar o comportamento do serviço do controlador de ingresso NGINX definindo anotações do balanceador de carga.

O controlador de entrada NGINX padrã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.

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:

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

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:

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"

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:

Crie um grupo de recursos do Azure usando o az group create comando.
```
az group create --name myNetworkResourceGroup --location eastus
```
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 .

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

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}

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"
```
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.

Nota

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

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

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, host e 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.

Nota

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

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.

Nota

As chaves e valores de anotação só podem ser strings. Outros tipos, como valores booleanos ou numéricos devem ser citados, ou seja "true", , "false", "100".

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:

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

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

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:

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

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:

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

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
  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. Isso é particularmente ú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:

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

Share via

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

Pré-requisitos

Conecte-se ao cluster AKS

Configuração do controlador de ingresso NGINX

O controlador de entrada NGINX padrão

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

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

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

Verifique se o controlador de entrada foi criado

Use o controlador de entrada em uma entrada

Verifique se o Ingress gerenciado foi criado

Limpeza de controladores de entrada

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

Tamanho máximo do corpo personalizado

Tempo limite de conexão personalizado

Protocolo de back-end

Desativar redirecionamento SSL

Reconfiguração de URL

Próximos passos

Recursos adicionais

Share via

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

Pré-requisitos

Conecte-se ao cluster AKS

Configuração do controlador de ingresso NGINX

O controlador de entrada NGINX padrão

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

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

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

Verifique se o controlador de entrada foi criado

Use o controlador de entrada em uma entrada

Verifique se o Ingress gerenciado foi criado

Limpeza de controladores de entrada

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

Tamanho máximo do corpo personalizado

Tempo limite de conexão personalizado

Protocolo de back-end

Partilha de Recursos Transversais à Origem (CORS)

Desativar redirecionamento SSL

Reconfiguração de URL

Próximos passos

Recursos adicionais