Dicionário de configuração do Nginx Ingress - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Configure o NGINX Ingress globalmente pelo ConfigMap nginx-configuration ou individualmente por Ingress usando anotações.

Consulte a documentação do ConfigMap do NGINX Ingress e a documentação de anotações do NGINX Ingress.

ConfigMap

O ConfigMap nginx-configuration define padrões globais para todos os Ingresses gerenciados pelo controlador NGINX Ingress.

Edite o ConfigMap

kubectl edit cm -n kube-system nginx-configuration

Configuração padrão

O ConfigMap a seguir apresenta os padrões do ACK. Campos não listados herdam os padrões upstream do ingress-nginx.

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
  namespace: <namespace>    # Default: kube-system
  labels:
    app: ingress-nginx
data:
  log-format-upstream: '$remote_addr - [$remote_addr] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id $host [$proxy_alternative_upstream_name]'
  proxy-body-size: 20m
  proxy-connect-timeout: "10"
  max-worker-connections: "65536"
  enable-underscores-in-headers: "true"
  reuse-port: "true"
  worker-cpu-affinity: "auto"
  server-tokens: "false"
  ssl-redirect: "false"
  allow-backend-server-header: "true"
  ignore-invalid-headers: "true"
  generate-request-id: "true"
  upstream-keepalive-timeout: "900"

Descrição dos campos

Campo	Padrão	Descrição
`log-format-upstream`	(veja acima)	Formato de log para requisições upstream. Ao alterar este campo, atualize também o AliyunLogConfig `kube-system/k8s-nginx-ingress` e o formato de coleta de logs no Simple Log Service (SLS). Consulte Diagnosticar logs de acesso do controlador NGINX Ingress no Simple Log Service.
`proxy-body-size`	`20m`	Tamanho máximo do corpo da requisição do cliente. Corresponde a client_max_body_size.
`proxy-connect-timeout`	`10`	Tempo limite (segundos) para estabelecer conexão com um servidor proxy. Máximo: 75. Para gRPC, defina também `grpc_connect_timeout`. Veja proxy_connect_timeout.
`max-worker-connections`	`65536`	Número máximo de conexões simultâneas por processo worker. Defina como `0` para usar o valor de `max-worker-open-files`.
`enable-underscores-in-headers`	`true`	Indica se underscores (`_`) são permitidos nos nomes dos cabeçalhos de requisição.
`reuse-port`	`true`	Crie um socket de escuta separado por worker usando `SO_REUSEPORT` e distribui as conexões recebidas entre os workers.
`worker-cpu-affinity`	`auto`	Associa cada processo worker a um núcleo de CPU disponível. Recomendado para cargas de trabalho de alto desempenho.
`server-tokens`	`false`	Quando definido como `true`, inclui a versão do NGINX no cabeçalho de resposta `Server` e nas páginas de erro. Use `false` para ocultar a versão.
`ssl-redirect`	`false`	Se `true`, redireciona globalmente HTTP para HTTPS (301) em todos os servidores com certificado TLS.
`allow-backend-server-header`	`true`	Com valor `true`, repassa o cabeçalho `Server` do backend em vez de uma string genérica do NGINX.
`ignore-invalid-headers`	`true`	Define se campos de cabeçalho inválidos nas requisições devem ser ignorados.
`generate-request-id`	`true`	Se `true`, gera um valor aleatório para `X-Request-ID` em requisições que ainda não possuem esse cabeçalho.
`upstream-keepalive-timeout`	`900` (ACK) / `60` (open source)	Tempo limite de ociosidade (segundos) para conexões keep-alive com servidores upstream. Mapeia para a diretiva NGINX `keepalive_timeout`.

Anotações

Adicione anotações a recursos Ingress individuais para substituir ou estender as configurações globais do ConfigMap.

Consulte a documentação de anotações do NGINX Ingress.

Balanceamento de carga

Anotação	Tipo	Descrição
`nginx.ingress.kubernetes.io/load-balance`	`round_robin`	`ewma`	Algoritmo de balanceamento de carga para serviços de backend. O padrão `round_robin` atende à maioria das cargas de trabalho. Já o `ewma` (Peak Exponential Weighted Moving Average) é mais indicado para aplicações sensíveis a latência.
`nginx.ingress.kubernetes.io/upstream-hash-by`	string	Ative hash consistente. O valor corresponde à variável usada como chave de hash. Exemplos: `$request_uri`, `$request_uri$host`, `${request_uri}-text-value`. A adição ou remoção de nós migra apenas um subconjunto das rotas.

Exemplo: hash consistente por URI de requisição

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: <your-service-name>
                port:
                  number: <your-service-port>

Para clusters Kubernetes anteriores à versão 1.22, use apiVersion: networking.k8s.io/v1beta1 e os campos serviceName / servicePort dentro de backend .

Afinidade por cookie

Anotação	Tipo	Padrão	Descrição
`nginx.ingress.kubernetes.io/affinity`	`cookie`	—	Tipo de afinidade. Apenas `cookie` é suportado.
`nginx.ingress.kubernetes.io/affinity-mode`	`balanced`	`persistent`	`balanced`	O modo `balanced` distribui requisições entre as instâncias. Já `persistent` sempre encaminha o mesmo cliente para a mesma instância de backend, garantindo consistência de sessão.
`nginx.ingress.kubernetes.io/session-cookie-name`	string	—	Nome do cookie usado como chave de hash para roteamento de sessão.
`nginx.ingress.kubernetes.io/session-cookie-path`	string	`/`	Atributo de caminho definido no cookie de sessão. Não suporta expressões regulares quando `nginx.ingress.kubernetes.io/use-regex` for `true`.
`nginx.ingress.kubernetes.io/session-cookie-max-age`	inteiro (segundos)	—	Atributo `Max-Age` do cookie de sessão (em segundos).
`nginx.ingress.kubernetes.io/session-cookie-expires`	inteiro (segundos)	—	Tempo de vida do cookie (segundos). Defina o atributo `Expires`.

Exemplo: afinidade de sessão baseada em cookie

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "route"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
spec:
  ingressClassName: nginx
  rules:
    - host: stickyingress.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: http-svc
                port:
                  number: 80

Redirecionamentos

Anotação	Tipo	Padrão	Descrição
`nginx.ingress.kubernetes.io/ssl-redirect`	`"true"`	`"false"`	—	Redireciona HTTP para HTTPS neste Ingress quando há um certificado TLS configurado. Veja Redirecionamento de HTTP para HTTPS.
`nginx.ingress.kubernetes.io/force-ssl-redirect`	`"true"`	`"false"`	`"false"`	Força o redirecionamento de HTTP para HTTPS mesmo sem certificado TLS.
`nginx.ingress.kubernetes.io/permanent-redirect`	URL	—	URL de destino para redirecionamento permanente. Deve incluir esquema (`http://` ou `https://`).
`nginx.ingress.kubernetes.io/permanent-redirect-code`	inteiro	`301`	Código de status HTTP para o redirecionamento permanente.
`nginx.ingress.kubernetes.io/temporal-redirect`	URL	—	URL de destino para redirecionamento temporário. Requer esquema (`http://` ou `https://`).
`nginx.ingress.kubernetes.io/app-root`	caminho	—	Redireciona requisições para `/` ao caminho raiz da aplicação especificado.

Exemplo: redirecionamento permanente de foo.com para bar.com

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/permanent-redirect: "https://bar.com"
spec:
  ingressClassName: nginx
  rules:
    - host: foo.com
      http:
        paths:
          - path: "/"
            pathType: ImplementationSpecific
            backend:
              service:
                name: httpbin
                port:
                  number: 8000

Reescritas

Anotação	Tipo	Descrição
`nginx.ingress.kubernetes.io/rewrite-target`	string	Caminho de destino da reescrita. Suporta grupos de captura. Consulte Configurar redirecionamento de URL.
`nginx.ingress.kubernetes.io/upstream-vhost`	string	Reescreve o cabeçalho `Host` enviado ao serviço upstream.

Exemplo: reescrever o cabeçalho Host para test.com em requisições a example.com/test

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  annotations:
    nginx.ingress.kubernetes.io/upstream-vhost: "test.com"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            pathType: ImplementationSpecific
            backend:
              service:
                name: demo-service
                port:
                  number: 80

Limitação de taxa

Limite as taxas de requisição e conexões simultâneas por IP de cliente para proteger os serviços de backend contra picos de tráfego.

Anotação	Tipo	Padrão	Descrição
`nginx.ingress.kubernetes.io/limit-connections`	inteiro	—	Máximo de conexões simultâneas por IP. Requisições excedentes recebem erro 503.
`nginx.ingress.kubernetes.io/limit-rate`	inteiro (KB)	—	Volume máximo de dados transmitidos por conexão por segundo (KB). Defina como `0` para desativar. Requer buffering de proxy ativado.
`nginx.ingress.kubernetes.io/limit-rps`	inteiro	—	Limite de requisições por segundo por endereço IP. Requisições acima do limite de burst (taxa × `limit-burst-multiplier`) retornam erro limit-req-status-code (503 por padrão).
`nginx.ingress.kubernetes.io/limit-rpm`	inteiro	—	Limite de requisições por minuto por endereço IP. Segue o mesmo comportamento de burst de `limit-rps`.
`nginx.ingress.kubernetes.io/limit-burst-multiplier`	inteiro	`5`	Multiplicador do limite de taxa de burst.
`nginx.ingress.kubernetes.io/limit-whitelist`	lista CIDR	—	Blocos CIDR separados por vírgula excluídos da limitação de taxa.

Exemplo: limitação de taxa com lista de permissões de IP

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/limit-rate: "100K"
    nginx.ingress.kubernetes.io/limit-rps: "1"
    nginx.ingress.kubernetes.io/limit-rpm: "30"
    nginx.ingress.kubernetes.io/limit-whitelist: "10.1.10.100"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: backend-svc
                port:
                  number: 80

Fallback

Encaminhe o tráfego para um serviço de backup quando o backend principal estiver indisponível.

Anotação	Tipo	Descrição
`nginx.ingress.kubernetes.io/default-backend`	string	Serviço de fallback usado quando nenhum nó de backend está disponível. Configure globalmente pela página Add-ons no console ACK.
`nginx.ingress.kubernetes.io/custom-http-errors`	códigos de status HTTP	Funciona em conjunto com `default-backend`. O NGINX encaminha requisições ao serviço de fallback quando o backend retorna um dos códigos listados. O caminho é reescrito para `/`. Substitui a configuração global `custom-http-errors` do ConfigMap.

Lançamentos canary

Implemente lançamentos canary e implantações blue-green. Consulte Usar o controlador NGINX Ingress para implementar lançamentos canary e implantações blue-green.

Anotação	Tipo	Descrição
`nginx.ingress.kubernetes.io/canary`	`"true"`	`"false"`	Defina se os lançamentos canary estão habilitados.
`nginx.ingress.kubernetes.io/canary-by-header`	string	Chave de cabeçalho para divisão de tráfego.
`nginx.ingress.kubernetes.io/canary-by-header-value`	string	Valor de correspondência exata para a chave de cabeçalho. Encaminha requisições correspondentes para o canary.
`nginx.ingress.kubernetes.io/canary-by-header-pattern`	regex	Expressão regular para correspondência do valor do cabeçalho.
`nginx.ingress.kubernetes.io/canary-by-cookie`	string	Chave de cookie usada para divisão de tráfego.
`nginx.ingress.kubernetes.io/canary-weight`	inteiro	Percentual de tráfego roteado para o canary (0–`canary-weight-total`).
`nginx.ingress.kubernetes.io/canary-weight-total`	inteiro	Denominador de peso para `canary-weight`.

Timeout

Configurações globais de timeout

Edite o ConfigMap nginx-configuration para definir timeouts globalmente:

kubectl edit cm -n kube-system nginx-configuration

Campo	Padrão	Descrição
`proxy-connect-timeout`	`5s`	Tempo limite de conexão do proxy. Máximo: 75s.
`proxy-read-timeout`	`60s`	Intervalo máximo entre leituras consecutivas do proxy (não é o tempo total de resposta).
`proxy-send-timeout`	`60s`	Intervalo máximo entre escritas consecutivas do proxy (não é o tempo total de transmissão).
`proxy-stream-next-upstream-timeout`	`600s`	Tempo máximo para passar uma conexão ao próximo servidor upstream. Defina como `0` para ilimitado.
`proxy-stream-timeout`	`600s`	Tempo limite de ociosidade em conexões de cliente ou proxy. Fecha a conexão se não houver transferência de dados.
`upstream-keepalive-timeout`	`900s` (ACK) / `60s` (open source)	Tempo limite de ociosidade para conexões keep-alive com servidores upstream.
`worker-shutdown-timeout`	`240s`	Tempo limite para desligamento gracioso.
`proxy-protocol-header-timeout`	`5s`	Tempo limite para recebimento do cabeçalho PROXY protocol. Evita que handlers de TLS passthrough bloqueiem em conexões quebradas.
`ssl-session-timeout`	`10m`	Tempo de vida do cache de sessão SSL. Cada entrada consome aproximadamente 0,25 MB.
`client-body-timeout`	`60s`	Tempo limite para leitura do corpo da requisição do cliente.
`client-header-timeout`	`60s`	Tempo limite para leitura dos cabeçalhos da requisição do cliente.

Configurações de timeout por Ingress

Substitua os timeouts globais para Ingresses específicos usando estas anotações:

Anotação	Descrição
`nginx.ingress.kubernetes.io/proxy-connect-timeout`	Tempo limite de conexão do proxy.
`nginx.ingress.kubernetes.io/proxy-send-timeout`	Tempo limite de envio do proxy.
`nginx.ingress.kubernetes.io/proxy-read-timeout`	Tempo limite de leitura do proxy.
`nginx.ingress.kubernetes.io/proxy-request-buffering`	Modo de buffering de requisição. `on`: armazena toda a requisição em buffer antes de encaminhar (requisições chunked HTTP/1.1 são sempre armazenadas). `off`: transmite dados diretamente; sem nova tentativa em caso de erros de transmissão.

CORS

Ative o compartilhamento de recursos de origem cruzada (CORS) para requisições de navegador. Consulte Configurar CORS em NGINX Ingresses.

Anotação	Descrição
`nginx.ingress.kubernetes.io/enable-cors`	Ative CORS para este Ingress.
`nginx.ingress.kubernetes.io/cors-allow-origin`	Origens permitidas para requisições CORS.
`nginx.ingress.kubernetes.io/cors-allow-methods`	Métodos de requisição permitidos, incluindo GET, POST e PUT.
`nginx.ingress.kubernetes.io/cors-allow-headers`	Cabeçalhos de requisição permitidos.
`nginx.ingress.kubernetes.io/cors-expose-headers`	Cabeçalhos de resposta expostos ao navegador.
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Defina se credenciais (cookies, cabeçalhos de autorização) são permitidas em requisições CORS.
`nginx.ingress.kubernetes.io/cors-max-age`	Duração do cache de preflight CORS (segundos).

Políticas de nova tentativa

Anotação	Padrão	Descrição
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	`3`	Número de novas tentativas quando as condições forem atendidas.
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	—	Tempo limite (segundos) para toda a sequência de novas tentativas. Sem padrão (ilimitado).
`nginx.ingress.kubernetes.io/proxy-next-upstream`	—	Condições para nova tentativa. Separe múltiplos valores com espaços. Valores válidos: `error` (falha de conexão), `timeout` (tempo esgotado), `invalid_response` (código de status inválido), `http_500`, `http_502`, `http_503`, `http_504`, `http_403`, `http_404`, `http_429`, `off` (desativa novas tentativas).

Controle de acesso baseado em endereço IP

Anotação	Tipo	Descrição
`nginx.ingress.kubernetes.io/whitelist-source-range`	lista CIDR	Lista de permissões de IP. Apenas endereços IP ou blocos CIDR listados são permitidos. Separe por vírgulas.
`nginx.ingress.kubernetes.io/denylist-source-range`	lista CIDR	Lista de bloqueios de IP. Endereços IP ou blocos CIDR listados são negados. Separe por vírgulas.

Exemplo: permitir apenas um endereço IP específico

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/whitelist-source-range: "10.1.10.2"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: backend-svc
                port:
                  number: 80

Para aplicar globalmente, defina whitelist-source-range no ConfigMap nginx-configuration.

Espelhamento de tráfego

Duplique requisições de produção para um ambiente sombra para testes, sem afetar o tráfego ativo. Consulte Usar um controlador Ingress para espelhar tráfego de rede.

Anotação	Tipo	Descrição
`nginx.ingress.kubernetes.io/mirror-target`	URL	Destino do espelhamento. Aceita endereço IP de Service ou URL externa. Use `$request_uri` para anexar a URI original da requisição. Exemplo: `https://test.env.com/$request_uri`.
`nginx.ingress.kubernetes.io/mirror-request-body`	`"true"`	`"false"`	Defina se o corpo da requisição deve ser espelhado.
`nginx.ingress.kubernetes.io/mirror-host`	string	Cabeçalho `Host` enviado com as requisições espelhadas.

Proteção de segurança

Configure criptografia TLS entre clientes e o controlador NGINX Ingress, e entre o controlador e os serviços de backend. Consulte Criptografia do controlador NGINX Ingress.

Criptografia cliente-gateway

Anotação	Escopo	Descrição
`nginx.ingress.kubernetes.io/ssl-cipher`	Domínio	Suítes de cifra TLS (separadas por vírgula). Aplica-se apenas a handshakes TLS 1.0–1.2. Suítes padrão: `ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-ECDSA-AES128-SHA`, `ECDHE-RSA-AES128-SHA`, `AES128-GCM-SHA256`, `AES128-SHA`, `ECDHE-ECDSA-AES256-GCM-SHA384`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-ECDSA-AES256-SHA`, `ECDHE-RSA-AES256-SHA`, `AES256-GCM-SHA384`, `AES256-SHA`.
`nginx.ingress.kubernetes.io/auth-tls-secret`	Domínio	Secret contendo certificado CA para verificação de certificados de cliente em mTLS. Deve incluir um arquivo `ca.crt` com a cadeia completa da CA.

Criptografia gateway-backend

Anotação	Escopo	Descrição
`nginx.ingress.kubernetes.io/proxy-ssl-secret`	Serviço	Secret com certificado de cliente apresentado aos backends. Deve estar no formato PEM com `tls.crt` (certificado de cliente), `tls.key` (chave privada) e `ca.crt` (certificado CA confiável). Especifique como `"namespace/secretName"`.
`nginx.ingress.kubernetes.io/proxy-ssl-name`	Serviço	Valor SNI (Server Name Indication) para handshake TLS com o backend.
`nginx.ingress.kubernetes.io/proxy-ssl-server-name`	Serviço	Ative ou desative SNI para handshake TLS com o backend.

Autenticação de segurança

Restrinja o acesso com Basic Authentication. Apenas requisições autenticadas chegam aos serviços de backend.

Anotação	Escopo	Descrição
`nginx.ingress.kubernetes.io/auth-type`	Ingress	Tipo de autenticação. Defina como `basic`.
`nginx.ingress.kubernetes.io/auth-secret`	Ingress	Nome do Secret de credenciais. Formato: `namespace/secretName`.
`nginx.ingress.kubernetes.io/auth-secret-type`	Ingress	Formato dos dados do Secret. `auth-file`: a chave `auth` contém entradas `username:password` separadas por nova linha. `auth-map`: chaves são nomes de usuário, valores são senhas.
`nginx.ingress.kubernetes.io/auth-realm`	Ingress	Realm de autenticação exibido ao cliente ao solicitar credenciais.

Configurar Basic Authentication

Gere um arquivo de senhas com htpasswd:

htpasswd -c auth joker

Verifique o arquivo:

cat auth
# Expected output: joker:$apr1$R.G4krs/$hh0mX8xe4A3lYKMjvlVs1/

Crie um Secret a partir do arquivo de senhas:

kubectl create secret generic basic-auth --from-file=auth

Adicione as anotações ao seu Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: basic-auth
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: backend-svc
                port:
                  number: 80

Container Service for Kubernetes:Dicionário de configuração do Nginx Ingress