Container Service for Kubernetes:Configurações avançadas de NGINX Ingress

Pré-requisitos

Antes de começar, certifique-se de ter:

• Instalado o controlador NGINX Ingress. Para mais informações, consulte Instalar o controlador NGINX Ingress.

• Um cliente kubectl conectado ao cluster. Para mais informações, consulte Obter o KubeConfig do cluster e usar o kubectl para conectar-se ao cluster.

• Um serviço exposto por um NGINX Ingress. Para mais informações, consulte Criar e usar um NGINX Ingress para expor um serviço.

Métodos de configuração

O controlador NGINX Ingress no Container Service for Kubernetes (ACK) é totalmente compatível com a comunidade open source. Para mais informações, consulte NGINX Configuration.

Há três métodos de configuração suportados:

Configurar redirecionamento de URL

Por padrão, o controlador NGINX Ingress encaminha solicitações com base no caminho completo da requisição. Por exemplo, uma solicitação para /service1/api é encaminhada diretamente para /service1/api no pod de backend. Se o caminho do serviço de backend for /api, o sistema retornará um erro 404 porque o caminho não corresponde. Use a annotation nginx.ingress.kubernetes.io/rewrite-target para reescrever o caminho da solicitação para o diretório correto.

Crie um NGINX Ingress com base na versão do seu cluster.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo.bar.com
  namespace: default
  annotations:
    # URL redirection.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
    # If the Ingress controller version is 0.22.0 or later, you must use a regular expression to define the path in the path field and use it with a capturing group in the rewrite-target annotation.
      - path: /svc(/|$)(.*)
        backend:
          service:
            name: web1-service
            port:
              number: 80
        pathType: ImplementationSpecific

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: foo.bar.com
  namespace: default
  annotations:
    # URL redirection.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      # If the Ingress controller version is 0.22.0 or later, you must use a regular expression to define the path in the path field and use it with a capturing group in the rewrite-target annotation.
      - path: /svc(/|$)(.*)
        backend:
          serviceName: web1-service
          servicePort: 80

Após implantar o Ingress, verifique a configuração:

1. Obtenha o endereço do Ingress.

   kubectl get ingress

   Saída esperada:

   NAME           CLASS   HOSTS                ADDRESS          PORTS   AGE
   foo.bar.com    nginx   foo.bar.com        172.16.XX.XX       80      46m

2. Teste a regra de rewrite. Substitua ADDRESS pelo endereço IP obtido na etapa anterior.

   curl -k -H "Host: foo.bar.com"  http://<ADDRESS>/svc/foo

   Saída esperada:

   web1: /foo

Configurar regras avançadas de rewrite

Para reescrita básica de URL, use a annotation nginx.ingress.kubernetes.io/rewrite-target conforme descrito em Configurar redirecionamento de URL.

Para requisitos complexos de reescrita, use as seguintes annotations para adicionar trechos personalizados à configuração do NGINX:

Exemplo:

annotations:
     nginx.ingress.kubernetes.io/server-snippet: |
         rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
     nginx.ingress.kubernetes.io/configuration-snippet: |
         rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;

Para visualizar a configuração gerada do NGINX, execute o comando abaixo. Substitua o nome do pod pelo nome real do pod do controlador NGINX Ingress no seu cluster.

kubectl exec nginx-ingress-controller-xxxxx --namespace kube-system -- cat /etc/nginx/nginx.conf

A configuração acima gera a seguinte saída no nginx.conf:

# start server foo.bar.com
    server {
        server_name foo.bar.com ;
        listen 80;
        listen [::]:80;
        set $proxy_upstream_name "-";
    # server-snippet configuration.
        rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
        ...
    # configuration-snippet configuration.
      rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;
      ...
    }
    # end server foo.bar.com

As annotations de snippet também suportam configurações globais. Para mais informações, consulte server-snippet. Para a referência completa da diretiva rewrite do NGINX, veja a documentação oficial do NGINX.

Configurar um certificado HTTPS

Use a semântica TLS nativa do Ingress para configurar um certificado HTTPS para o seu serviço.

1. Prepare seu certificado TLS.

   1. Gere um certificado autoassinado e uma chave privada. ``bash openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=foo.bar.com/O=foo.bar.com" ``

   2. Crie um Secret do Kubernetes a partir do certificado e da chave privada. Referencie este Secret no Ingress.

      kubectl create secret tls tls-test-ingress --key tls.key --cert tls.crt

   O CN (Common Name) do certificado deve corresponder ao host configurado no Ingress. Caso não correspondam, o controlador NGINX Ingress não conseguirá carregar o certificado.

2. Crie um recurso Ingress que referencie o Secret no campo tls. Kubernetes 1.19 ou posterior

   Clusters que executam Kubernetes 1.19 ou posterior

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: test-test-ingress
   spec:
     # Reference the TLS certificate.
     tls:
     - hosts:
       - foo.bar.com # The domain name that corresponds to the certificate.
       secretName: tls-test-ingress
     rules:
     - host: tls-test-ingress.com
       http:
         paths:
         - path: /foo
           backend:
             service:
               name: web1-svc
               port:
                 number: 80
           pathType: ImplementationSpecific

   Clusters que executam versões do Kubernetes anteriores à 1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: test-test-ingress
   spec:
     # Reference the TLS certificate.
     tls:
     - hosts:
       - foo.bar.com # The domain name that corresponds to the certificate.
       secretName: tls-test-ingress
     rules:
     - host: tls-test-ingress.com
       http:
         paths:
         - path: /foo
           backend:
             serviceName: web1-svc
             servicePort: 80

3. Atualize seu arquivo /etc/hosts ou use um nome de domínio real para acessar o serviço TLS em https://tls-test-ingress.com/foo.

Configurar autenticação mútua HTTPS

A autenticação mútua HTTPS (mTLS) exige que tanto o servidor quanto o cliente apresentem certificados, proporcionando uma segurança de conexão mais robusta do que o TLS unidirecional. O controlador NGINX Ingress suporta mTLS por meio de annotations.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
  name: nginx-test
  namespace: default
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
          service:
            name: http-svc
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-secret

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
  name: nginx-test
  namespace: default
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
          serviceName: http-svc
          servicePort: 80
        path: /
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-secret

ingress.networking.k8s.io/nginx-test configured

Encaminhar tráfego para um backend HTTPS

Por padrão, o controlador NGINX Ingress encaminha solicitações para contêineres de backend via HTTP. Se o seu contêiner de backend usar HTTPS, adicione a annotation nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" para encaminhar o tráfego via HTTPS.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: backend-https
  annotations:
    # Note: You must specify that the backend service is an HTTPS service.
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  tls:
  - hosts:
    - <YOUR-HOST-NAME>
    secretName: <YOUR-SECRET-CERT-NAME>
  rules:
  - host: <YOUR-HOST-NAME>
    http:
      paths:
      - path: /
        backend:
          service:
            name: <YOUR-SERVICE-NAME>
            port:
              number: <YOUR-SERVICE-PORT>
        pathType: ImplementationSpecific

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: backend-https
  annotations:
    # Note: You must specify that the backend service is an HTTPS service.
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  tls:
  - hosts:
    - <YOUR-HOST-NAME>
    secretName: <YOUR-SECRET-CERT-NAME>
  rules:
  - host: <YOUR-HOST-NAME>
    http:
      paths:
      - path: /
        backend:
          serviceName: <YOUR-SERVICE-NAME>
          servicePort: <YOUR-SERVICE-PORT>

Configurar nomes de domínio com expressões regulares

Os recursos Ingress do Kubernetes não suportam expressões regulares no campo host nativamente. Use a annotation nginx.ingress.kubernetes.io/server-alias para adicionar correspondência de nomes de domínio baseada em regex.

1. Implante o seguinte Ingress. Este exemplo usa a expressão regular ~^www\.\d+\.example\.com. Kubernetes 1.19 ou posterior

   Clusters que executam Kubernetes 1.19 ou posterior

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
     annotations:
       nginx.ingress.kubernetes.io/server-alias: '~^www\.\d+\.example\.com$, abc.example.com'
   spec:
     rules:
     - host: foo.bar.com
       http:
         paths:
         - path: /foo
           backend:
             service:
               name: http-svc1
               port:
                 number: 80
           pathType: ImplementationSpecific

   Clusters que executam versões do Kubernetes anteriores à 1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
     annotations:
       nginx.ingress.kubernetes.io/server-alias: '~^www\.\d+\.example\.com$, abc.example.com'
   spec:
     rules:
     - host: foo.bar.com
       http:
         paths:
         - path: /foo
           backend:
             serviceName: http-svc1
             servicePort: 80

2. Verifique a configuração no controlador NGINX Ingress.

   1. Liste os pods do controlador NGINX Ingress.

      kubectl get pods -n kube-system | grep nginx-ingress-controller

      Saída esperada:

      nginx-ingress-controller-77cd987c4c-c****         1/1     Running   0          1h
      nginx-ingress-controller-77cd987c4c-x****         1/1     Running   0          1h

   2. Inspecione o campo server_name na configuração gerada do NGINX.

      kubectl exec -n kube-system nginx-ingress-controller-77cd987c4c-c**** cat /etc/nginx/nginx.conf | grep -C3 "foo.bar.com"

      Saída esperada:

        # start server foo.bar.com
        server {
      --
        server {
          server_name foo.bar.com abc.example.com ~^www\.\d+\.example\.com$ ;
          listen 80  ;
          listen 443  ssl http2 ;
      --
      --
          }
        }
        # end server foo.bar.com

3. Obtenha o endereço IP do Ingress.

   kubectl get ing

   Saída esperada:

   NAME            HOSTS         ADDRESS          PORTS     AGE
   ingress-regex   foo.bar.com   101.37.XX.XX     80        11s

4. Teste o acesso ao serviço com diferentes cabeçalhos de host. Substitua IP_ADDRESS pelo endereço IP do Ingress obtido na etapa anterior.

   • Acesse usando foo.bar.com:

     curl -H "Host: foo.bar.com" <IP_ADDRESS>/foo

     Saída esperada:

     /foo

   • Acesse usando www.123.example.com (corresponde à regex):

     curl -H "Host: www.123.example.com" <IP_ADDRESS>/foo

     Saída esperada:

     /foo

   • Acesse usando www.321.example.com (também corresponde à regex):

     curl -H "Host: www.321.example.com" <IP_ADDRESS>/foo

     Saída esperada:

     /foo

Configurar nomes de domínio com wildcard

O NGINX Ingress suporta nomes de domínio com wildcard. O exemplo a seguir configura *.ingress-regex.com para corresponder a qualquer subdomínio.

1. Implante o seguinte Ingress.

   Clusters que executam Kubernetes 1.19 ou posterior

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
   spec:
     rules:
     - host: *.ingress-regex.com
       http:
         paths:
         - path: /foo
           backend:
             service:
               name: http-svc1
               port:
                 number: 80
           pathType: ImplementationSpecific

   Clusters que executam versões do Kubernetes anteriores à 1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
   spec:
     rules:
     - host: *.ingress-regex.com
       http:
         paths:
         - path: /foo
           backend:
             serviceName: http-svc1
             servicePort: 80

2. Verifique o campo server_name na configuração do NGINX. Substitua <nginx-ingress-pod-name> pelo nome real do pod do NGINX Ingress.

   kubectl exec -n kube-system <nginx-ingress-pod-name> cat /etc/nginx/nginx.conf | grep -C3 "*.ingress-regex.com"

   Saída esperada:

   # start server *.ingress-regex.com
     server {
       server_name *.ingress-regex.com ;
       listen 80;
       listen [::]:80;
   ...
     }
     # end server *.ingress-regex.com

   Em versões mais recentes do controlador NGINX Ingress, a saída é:

   ## start server *.ingress-regex.com
     server {
       server_name ~^(?<subdomain>[\w-]+)\.ingress-regex\.com$ ;
       listen 80;
       listen [::]:80;
   ...
     }
     ## end server *.ingress-regex.com

3. Obtenha o endereço IP do Ingress.

   kubectl get ing

   Saída esperada:

   NAME            HOSTS                 ADDRESS           PORTS     AGE
   ingress-regex   *.ingress-regex.com   101.37.XX.XX      80        11s

4. Teste o acesso com diferentes subdomínios. Substitua IP_ADDRESS pelo endereço IP do Ingress obtido na etapa anterior.

   • Acesse usando abc.ingress-regex.com:

     curl -H "Host: abc.ingress-regex.com" <IP_ADDRESS>/foo

     Saída esperada:

     /foo

   • Acesse usando 123.ingress-regex.com:

     curl -H "Host: 123.ingress-regex.com" <IP_ADDRESS>/foo

     Saída esperada:

     /foo

   • Acesse usando a1b1.ingress-regex.com:

     curl -H "Host: a1b1.ingress-regex.com" <IP_ADDRESS>/foo

     Saída esperada:

     /foo

Implementar canary releases

Use annotations de canary para rotear um subconjunto do tráfego para uma nova versão do serviço sem uma implantação completa. Ative o roteamento canary definindo nginx.ingress.kubernetes.io/canary: "true" no Ingress canary e combine-o com uma ou mais annotations de estratégia de roteamento.

Prioridade das regras da maior para a menor: baseada em cabeçalho → baseada em cookie → baseada em peso. O roteamento canary baseado em cookie suporta apenas os valores always e never.

Os exemplos a seguir mostram configurações comuns de canary. Para um guia completo, incluindo implantações blue-green, consulte Usar um NGINX Ingress para implementar canary releases e implantações blue-green.

Canary release baseado em peso — roteia 20% do tráfego para o serviço canary:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"

Canary release baseado em cabeçalho — quando o cabeçalho de solicitação ack for always, roteia para o serviço canary; quando for never, ignora o serviço canary; para outros valores de cabeçalho, roteia com base no peso:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "50"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"

Canary release baseado em cabeçalho com valor personalizado — roteia para o serviço canary apenas quando o cabeçalho ack for exatamente alibaba; caso contrário, aplica o roteamento baseado em peso:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"
    nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba"

Canary release baseado em cookie — quando nenhuma regra de cabeçalho corresponder e o cookie hangzhou_region for always, roteia para o serviço canary:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"
    nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba"
    nginx.ingress.kubernetes.io/canary-by-cookie: "hangzhou_region"

Solicitar um certificado HTTPS gratuito com cert-manager

O cert-manager é uma ferramenta de gerenciamento de certificados open source que provisiona e renova automaticamente certificados HTTPS em um cluster.

1. Implante o cert-manager.

   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

2. Verifique se os pods do cert-manager estão em execução.

   kubectl get pods -n cert-manager

   Saída esperada:

   NAME                     READY   STATUS    RESTARTS   AGE
   cert-manager-1           1/1     Running   0          2m11s
   cert-manager-cainjector  1/1     Running   0          2m11s
   cert-manager-webhook     1/1     Running   0          2m10s

3. Crie um ClusterIssuer usando o desafio HTTP01 do Let's Encrypt.

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: letsencrypt-prod-http01
   spec:
     acme:
       server: https://acme-v02.api.letsencrypt.org/directory
       email: <your_email@example.com>  # Replace this with your email address.
       privateKeySecretRef:
         name: letsencrypt-http01
       solvers:
       - http01:
           ingress:
             class: nginx

4. Verifique se o ClusterIssuer está pronto.

   kubectl get clusterissuer

   Saída esperada:

   NAME                         READY   AGE
   letsencrypt-prod-http01      True    17s

5. Crie um recurso Ingress que referencie o ClusterIssuer. Kubernetes 1.19 ou posterior

   O nome de domínio deve atender aos seguintes requisitos: no máximo 64 caracteres, sem nomes de domínio wildcard e acessível pela rede pública usando HTTP.

   Clusters que executam Kubernetes 1.19 ou posterior

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-tls
     annotations:
       kubernetes.io/ingress.class: "nginx"
       cert-manager.io/cluster-issuer: "letsencrypt-prod-http01"
   spec:
     tls:
     - hosts:
       - <YOUR_DOMAIN_NAME>        # Replace this with your domain name.
       secretName: ingress-tls
     rules:
     - host: <YOUR_DOMAIN_NAME>    # Replace this with your domain name.
       http:
         paths:
         - path: /
           backend:
             service:
               name: <YOUR_SERVICE_NAME>  # Replace this with your backend service name.
               port:
                 number: <YOUR_SERVICE_PORT>  # Replace this with your service port.
           pathType: ImplementationSpecific

   Clusters que executam versões do Kubernetes anteriores à 1.19

   apiVersion: extensions/v1beta1
   kind: Ingress
   metadata:
     name: ingress-tls
     annotations:
       kubernetes.io/ingress.class: "nginx"
       cert-manager.io/cluster-issuer: "letsencrypt-prod-http01"
   spec:
     tls:
     - hosts:
       - <YOUR_DOMAIN_NAME>        # Replace this with your domain name.
       secretName: ingress-tls
     rules:
     - host: <YOUR_DOMAIN_NAME>    # Replace this with your domain name.
       http:
         paths:
         - path: /
           backend:
             serviceName: <YOUR_SERVICE_NAME>  # Replace this with your backend service name.
             servicePort: <YOUR_SERVICE_PORT>  # Replace this with your service port.

6. Verifique se o certificado foi emitido.

   kubectl get cert

   Saída esperada:

   NAME          READY   SECRET        AGE
   ingress-tls   True    ingress-tls   52m

   Se READY não for True, execute kubectl describe cert ingress-tls para inspecionar o procedimento de processamento do certificado.

7. Verifique o Secret TLS.

   kubectl get secret ingress-tls

   Saída esperada:

   NAME          TYPE                DATA   AGE
   ingress-tls   kubernetes.io/tls   2      2m

8. Acesse o serviço em https://<YOUR_DOMAIN_NAME> no navegador.

Configurar redirecionamento de HTTP para HTTPS

Use a annotation nginx.ingress.kubernetes.io/ssl-redirect para forçar o redirecionamento do tráfego HTTP para HTTPS.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true" # Force the redirection of HTTP traffic to HTTPS.

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true" # Force the redirection of HTTP traffic to HTTPS.

Próximos passos

• Usar um NGINX Ingress para implementar canary releases e implantações blue-green

• Referência de annotations do controlador NGINX Ingress

• Documentação do cert-manager