Quais anotações são compatíveis com o MSE Ingress - Microservices Engine: Central de Documentação do Alibaba Cloud

Os gateways MSE Ingress oferecem suporte às anotações principais e comuns dos gateways NGINX Ingress, facilitando a migração. Eles também disponibilizam 40 anotações adicionais para gerenciamento avançado de tráfego.

Os recursos padrão do Kubernetes Ingress lidam apenas com criptografia Transport Layer Security (TLS) e roteamento HTTP básico da camada 7. Somente os controladores NGINX Ingress definem mais de 100 anotações personalizadas para atender aos requisitos reais de gerenciamento de tráfego e segurança. Os gateways MSE Ingress são compatíveis com as anotações mais comuns do NGINX Ingress, permitindo migrar cargas de trabalho existentes sem reescrever configurações de Ingress.

Visão geral

A tabela a seguir resume a cobertura de anotações.

Cobertura de anotações do NGINX Ingress

Categoria	Quantidade	Observações
Compatíveis	51	Cobre 90% dos casos de uso
Sem necessidade de configuração	15	Funcionalidade disponível sem configuração explícita
Planejadas	48	Aplica-se a poucos casos de uso
Não compatíveis	5	Vinculadas a trechos de código específicos do NGINX

O MSE implementa recursos de forma diferente do NGINX. Variáveis do NGINX usadas em anotações e trechos de código do NGINX Ingress não são compatíveis com seus equivalentes no NGINX.

Corpos de requisição grandes: A anotação nginx.ingress.kubernetes.io/proxy-body-size define um tamanho máximo de corpo de requisição no NGINX e rejeita qualquer conteúdo maior. O MSE usa codificação de transferência fragmentada (chunked), que lida automaticamente com corpos grandes, sem limite de tamanho. Para definir limites de buffer de conexão upstream, configure o parâmetro DownstreamConnectionBufferLimits no painel Parameter Settings do gateway MSE.

Redirecionamentos e variáveis do NGINX: Variáveis do NGINX (como $host ou $request_uri) em anotações de redirecionamento podem funcionar em algumas versões do NGINX Ingress, mas não possuem documentação oficial. Evite usar variáveis do NGINX para redirecionamentos no NGINX Ingress, pois elas não são compatíveis com o MSE.

Anotações exclusivas do MSE

Categoria	Quantidade	Observações
Anotações estendidas	40	Adiciona capacidades de governança de tráfego e proteção de segurança além do NGINX Ingress

Escopo das anotações

Cada anotação se aplica a um dos três escopos:

Ingress — aplica-se às regras de roteamento definidas no recurso Ingress.
Domínio — aplica-se aos hostnames definidos no recurso Ingress e também entra em vigor nos mesmos hostnames de outros recursos Ingress.
Service — aplica-se aos services de backend referenciados pelo recurso Ingress e também entra em vigor nos mesmos services referenciados por outros recursos Ingress.

Prefixos de anotações

As anotações compatíveis com MSE aceitam o prefixo nginx ou mse. Por exemplo, nginx.ingress.kubernetes.io/ssl-redirect e mse.ingress.kubernetes.io/ssl-redirect são equivalentes.

As anotações exclusivas do MSE usam apenas o prefixo mse. Substituir mse por nginx nessas anotações não produz efeito.

Índice de referência rápida

A tabela a seguir lista todas as anotações compatíveis, com seu status de compatibilidade e categoria. Use esta tabela para verificar rapidamente se uma anotação específica é compatível antes de ler os detalhes completos abaixo.

Anotação	Status	Categoria
`nginx.ingress.kubernetes.io/canary`	Compatível	Canary release
`nginx.ingress.kubernetes.io/canary-by-header`	Compatível	Canary release
`nginx.ingress.kubernetes.io/canary-by-header-value`	Compatível	Canary release
`nginx.ingress.kubernetes.io/canary-by-header-pattern`	Compatível	Canary release
`mse.ingress.kubernetes.io/canary-by-query`	Exclusivo do MSE	Canary release
`mse.ingress.kubernetes.io/canary-by-query-value`	Exclusivo do MSE	Canary release
`mse.ingress.kubernetes.io/canary-by-query-pattern`	Exclusivo do MSE	Canary release
`nginx.ingress.kubernetes.io/canary-by-cookie`	Compatível	Canary release
`mse.ingress.kubernetes.io/canary-by-cookie-value`	Exclusivo do MSE (V1.2.30+)	Canary release
`nginx.ingress.kubernetes.io/canary-weight`	Compatível	Canary release
`nginx.ingress.kubernetes.io/canary-weight-total`	Compatível	Canary release
`mse.ingress.kubernetes.io/destination`	Exclusivo do MSE	Roteamento multi-service
`mse.ingress.kubernetes.io/service-subset`	Exclusivo do MSE (V1.2.25+)	Subconjunto de service
`mse.ingress.kubernetes.io/subset-labels`	Exclusivo do MSE (V1.2.25+)	Subconjunto de service
`nginx.ingress.kubernetes.io/default-backend`	Compatível	Service de fallback
`nginx.ingress.kubernetes.io/custom-http-errors`	Compatível	Service de fallback
`nginx.ingress.kubernetes.io/use-regex`	Compatível	Correspondência de caminho regex
`nginx.ingress.kubernetes.io/rewrite-target`	Compatível	Reescrita de caminho
`nginx.ingress.kubernetes.io/upstream-vhost`	Compatível	Reescrita de caminho
`nginx.ingress.kubernetes.io/ssl-redirect`	Compatível	Redirecionamento
`nginx.ingress.kubernetes.io/force-ssl-redirect`	Compatível	Redirecionamento
`nginx.ingress.kubernetes.io/permanent-redirect`	Compatível	Redirecionamento
`nginx.ingress.kubernetes.io/permanent-redirect-code`	Compatível	Redirecionamento
`nginx.ingress.kubernetes.io/temporal-redirect`	Compatível	Redirecionamento
`nginx.ingress.kubernetes.io/app-root`	Compatível	Redirecionamento
`nginx.ingress.kubernetes.io/enable-cors`	Compatível	CORS
`nginx.ingress.kubernetes.io/cors-allow-origin`	Compatível	CORS
`nginx.ingress.kubernetes.io/cors-allow-methods`	Compatível	CORS
`nginx.ingress.kubernetes.io/cors-allow-headers`	Compatível	CORS
`nginx.ingress.kubernetes.io/cors-expose-headers`	Compatível	CORS
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Compatível	CORS
`nginx.ingress.kubernetes.io/cors-max-age`	Compatível	CORS
`mse.ingress.kubernetes.io/request-header-control-add`	Exclusivo do MSE	Controle de cabeçalho
`mse.ingress.kubernetes.io/request-header-control-update`	Exclusivo do MSE	Controle de cabeçalho
`mse.ingress.kubernetes.io/request-header-control-remove`	Exclusivo do MSE	Controle de cabeçalho
`mse.ingress.kubernetes.io/response-header-control-add`	Exclusivo do MSE	Controle de cabeçalho
`mse.ingress.kubernetes.io/response-header-control-update`	Exclusivo do MSE	Controle de cabeçalho
`mse.ingress.kubernetes.io/response-header-control-remove`	Exclusivo do MSE	Controle de cabeçalho
`mse.ingress.kubernetes.io/timeout`	Exclusivo do MSE	Timeout
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	Compatível	Nova tentativa
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	Compatível	Nova tentativa
`nginx.ingress.kubernetes.io/proxy-next-upstream`	Compatível	Nova tentativa
`mse.ingress.kubernetes.io/mirror-target-service`	Exclusivo do MSE	Espelhamento de tráfego
`mse.ingress.kubernetes.io/mirror-percentage`	Exclusivo do MSE (V1.2.32+)	Espelhamento de tráfego
`nginx.ingress.kubernetes.io/server-alias`	Parcialmente compatível (V1.2.30+)	Alias de domínio
`mse.ingress.kubernetes.io/route-limit-rpm`	Exclusivo do MSE	Limitação de taxa (gateway único, a ser descontinuado)
`mse.ingress.kubernetes.io/route-limit-rps`	Exclusivo do MSE	Limitação de taxa (gateway único, a ser descontinuado)
`mse.ingress.kubernetes.io/route-limit-burst-multiplier`	Exclusivo do MSE	Limitação de taxa (gateway único, a ser descontinuado)
`mse.ingress.kubernetes.io/rate-limit`	Exclusivo do MSE (V1.2.25+)	Limitação de taxa (global)
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code`	Exclusivo do MSE (V1.2.25+)	Limitação de taxa (global)
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type`	Exclusivo do MSE (V1.2.25+)	Limitação de taxa (global)
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body`	Exclusivo do MSE (V1.2.25+)	Limitação de taxa (global)
`mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url`	Exclusivo do MSE (V1.2.25+)	Limitação de taxa (global)
`mse.ingress.kubernetes.io/concurrency-limit`	Exclusivo do MSE (V1.2.25+)	Controle de concorrência
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code`	Exclusivo do MSE (V1.2.25+)	Controle de concorrência
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type`	Exclusivo do MSE (V1.2.25+)	Controle de concorrência
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body`	Exclusivo do MSE (V1.2.25+)	Controle de concorrência
`mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url`	Exclusivo do MSE (V1.2.25+)	Controle de concorrência
`nginx.ingress.kubernetes.io/backend-protocol`	Parcialmente compatível	Protocolo de backend
`nginx.ingress.kubernetes.io/load-balance`	Parcialmente compatível	Balanceamento de carga
`nginx.ingress.kubernetes.io/upstream-hash-by`	Parcialmente compatível	Balanceamento de carga
`mse.ingress.kubernetes.io/warmup`	Exclusivo do MSE	Warm-up de service
`nginx.ingress.kubernetes.io/affinity`	Compatível	Afinidade de cookie
`nginx.ingress.kubernetes.io/affinity-mode`	Parcialmente compatível	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-name`	Compatível	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-path`	Compatível	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-max-age`	Compatível	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-expires`	Compatível	Afinidade de cookie
`nginx.ingress.kubernetes.io/whitelist-source-range`	Compatível	Controle de acesso por IP
`nginx.ingress.kubernetes.io/denylist-source-range`	Compatível (V1.2.31+)	Controle de acesso por IP
`mse.ingress.kubernetes.io/blacklist-source-range`	Exclusivo do MSE	Controle de acesso por IP
`mse.ingress.kubernetes.io/domain-whitelist-source-range`	Exclusivo do MSE	Controle de acesso por IP
`mse.ingress.kubernetes.io/domain-blacklist-source-range`	Exclusivo do MSE	Controle de acesso por IP
`mse.ingress.kubernetes.io/connection-policy-tcp-max-connection`	Exclusivo do MSE	Pool de conexões
`mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint`	Exclusivo do MSE	Pool de conexões
`mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection`	Exclusivo do MSE	Pool de conexões
`mse.ingress.kubernetes.io/tls-min-protocol-version`	Exclusivo do MSE	TLS (cliente para gateway)
`mse.ingress.kubernetes.io/tls-max-protocol-version`	Exclusivo do MSE	TLS (cliente para gateway)
`nginx.ingress.kubernetes.io/ssl-cipher`	Compatível	TLS (cliente para gateway)
`mse.ingress.kubernetes.io/auth-tls-secret`	Parcialmente compatível	TLS (cliente para gateway)
`nginx.ingress.kubernetes.io/proxy-ssl-secret`	Compatível	TLS (gateway para backend)
`nginx.ingress.kubernetes.io/proxy-ssl-name`	Compatível	TLS (gateway para backend)
`nginx.ingress.kubernetes.io/proxy-ssl-server-name`	Compatível	TLS (gateway para backend)
`nginx.ingress.kubernetes.io/auth-type`	Parcialmente compatível	Autenticação
`nginx.ingress.kubernetes.io/auth-secret`	Compatível	Autenticação
`nginx.ingress.kubernetes.io/auth-secret-type`	Compatível	Autenticação
`nginx.ingress.kubernetes.io/auth-realm`	Compatível	Autenticação

Anotações compatíveis

Governança de tráfego

Canary release

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/canary`	Ingress	Compatível	Ativa o canary release para o Ingress.
`nginx.ingress.kubernetes.io/canary-by-header`	Ingress	Compatível	Divide o tráfego pela chave do cabeçalho da requisição.
`nginx.ingress.kubernetes.io/canary-by-header-value`	Ingress	Compatível	Divide o tráfego pelo valor do cabeçalho da requisição. Oferece suporte a correspondência exata.
`nginx.ingress.kubernetes.io/canary-by-header-pattern`	Ingress	Compatível	Divide o tráfego pelo valor do cabeçalho da requisição. Oferece suporte a correspondência por expressão regular.
`mse.ingress.kubernetes.io/canary-by-query`	Ingress	Exclusivo do MSE	Divide o tráfego pela chave do parâmetro de consulta da URL.
`mse.ingress.kubernetes.io/canary-by-query-value`	Ingress	Exclusivo do MSE	Divide o tráfego pelo valor do parâmetro de consulta da URL. Oferece suporte a correspondência exata.
`mse.ingress.kubernetes.io/canary-by-query-pattern`	Ingress	Exclusivo do MSE	Divide o tráfego pelo valor do parâmetro de consulta da URL. Oferece suporte a correspondência por expressão regular.
`nginx.ingress.kubernetes.io/canary-by-cookie`	Ingress	Compatível	Divide o tráfego pela chave do cookie.
`mse.ingress.kubernetes.io/canary-by-cookie-value`	Ingress	Exclusivo do MSE (requer gateway V1.2.30 ou posterior)	Divide o tráfego pelo valor do cookie. Oferece suporte a correspondência exata.
`nginx.ingress.kubernetes.io/canary-weight`	Ingress	Compatível	Define o peso do tráfego para o service canary.
`nginx.ingress.kubernetes.io/canary-weight-total`	Ingress	Compatível	Define o peso total usado para cálculos de divisão de tráfego.

Roteamento multi-service

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/destination`	Ingress	Exclusivo do MSE	Distribui o tráfego entre vários services por peso.

Sintaxe: {weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}

Configurar esta anotação substitui os services de destino para todas as regras de roteamento no Ingress. Se a sintaxe for inválida, a anotação será ignorada e as regras de roteamento originais permanecerão em vigor.

Exemplo:

annotations:
  # Route 60% of traffic to foo and 40% to bar
  mse.ingress.kubernetes.io/destination: |
    60% foo.default.svc.cluster.local:8080
    40% bar.default.svc.cluster.local:9090

Subconjunto de service

Use subconjuntos de service quando um único Service do Kubernetes gerencia múltiplos deployments — por exemplo, uma versão estável e uma versão canary. Um subconjunto direciona requisições para um grupo específico de pods.

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/service-subset`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Roteia requisições para um subconjunto de pods do service alvo. Quando `mse.ingress.kubernetes.io/subset-labels` não está definido, o comportamento de roteamento depende do valor desta anotação: defina como `""` ou `base` para atingir pods com `opensergo.io/canary: ""` ou pods sem o prefixo de rótulo `opensergo.io/canary`; defina como qualquer outro valor (por exemplo, `gray`) para atingir pods com o rótulo `opensergo.io/canary-gray: gray`. Quando `mse.ingress.kubernetes.io/subset-labels` está definido, as requisições são encaminhadas apenas para pods cujos rótulos correspondem aos pares chave-valor definidos ali. Se nenhum pod corresponder ao rótulo, as requisições retornam para todos os pods do service.
`mse.ingress.kubernetes.io/subset-labels`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Opcional. Use com `mse.ingress.kubernetes.io/service-subset` para especificar os rótulos que definem o subconjunto de pods.

Service de fallback

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/default-backend`	Ingress	Compatível	Especifica um service de fallback. Se nenhum nó estiver disponível para o service definido em uma regra de Ingress, as requisições serão encaminhadas para este service.
`nginx.ingress.kubernetes.io/custom-http-errors`	Ingress	Compatível	Funciona com `nginx.ingress.kubernetes.io/default-backend`. Quando um backend retorna um dos códigos de status HTTP especificados, a requisição é encaminhada para o service de fallback com o caminho reescrito para `/`.

Correspondência de caminho regex

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/use-regex`	Ingress	Compatível	Ativa a correspondência por expressão regular para o caminho definido na regra do Ingress. Usa sintaxe RE2.

Reescrita de caminho

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/rewrite-target`	Ingress	Compatível	Reescreve o caminho da requisição antes de encaminhar para o backend. Oferece suporte a grupos de captura.
`nginx.ingress.kubernetes.io/upstream-vhost`	Ingress	Compatível	Reescreve o cabeçalho `Host` para o valor especificado ao encaminhar requisições para o backend.

Redirecionamento

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/ssl-redirect`	Ingress	Compatível	Redireciona requisições HTTP para HTTPS.
`nginx.ingress.kubernetes.io/force-ssl-redirect`	Ingress	Compatível	Força o redirecionamento de requisições HTTP para HTTPS.
`nginx.ingress.kubernetes.io/permanent-redirect`	Ingress	Compatível	Redireciona requisições para a URL especificada com um redirecionamento permanente.
`nginx.ingress.kubernetes.io/permanent-redirect-code`	Ingress	Compatível	Define o código de status HTTP para redirecionamentos permanentes.
`nginx.ingress.kubernetes.io/temporal-redirect`	Ingress	Compatível	Redireciona requisições para a URL especificada com um redirecionamento temporário.
`nginx.ingress.kubernetes.io/app-root`	Ingress	Compatível	Redireciona requisições de `/` para o caminho raiz da aplicação especificado.

Compartilhamento de recursos de origem cruzada (CORS)

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/enable-cors`	Ingress	Compatível	Ativa o compartilhamento de recursos de origem cruzada (CORS).
`nginx.ingress.kubernetes.io/cors-allow-origin`	Ingress	Compatível	Define as origens permitidas para requisições CORS.
`nginx.ingress.kubernetes.io/cors-allow-methods`	Ingress	Compatível	Define os métodos HTTP permitidos para requisições CORS, como GET, POST e PUT.
`nginx.ingress.kubernetes.io/cors-allow-headers`	Ingress	Compatível	Define os cabeçalhos de requisição permitidos para requisições CORS.
`nginx.ingress.kubernetes.io/cors-expose-headers`	Ingress	Compatível	Define os cabeçalhos de resposta expostos aos navegadores nas respostas CORS.
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Ingress	Compatível	Especifica se credenciais podem ser incluídas em requisições CORS.
`nginx.ingress.kubernetes.io/cors-max-age`	Ingress	Compatível	Define a duração do cache dos resultados de requisição preflight.

Controle de cabeçalho

As anotações de controle de cabeçalho em rotas base e rotas canary são independentes e validadas separadamente. Configure políticas de cabeçalho diferentes para o tráfego da rota base e para o tráfego da rota canary conforme necessário.

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/request-header-control-add`	Ingress	Exclusivo do MSE	Adiciona um cabeçalho às requisições antes de encaminhar para o backend. Se o cabeçalho já existir, o novo valor é anexado ao original. Para um único cabeçalho, use um par chave-valor. Para múltiplos cabeçalhos, use um bloco literal YAML (`	`) com um par chave-valor por linha.
`mse.ingress.kubernetes.io/request-header-control-update`	Ingress	Exclusivo do MSE	Modifica um cabeçalho nas requisições antes de encaminhar para o backend. Se o cabeçalho existir, o novo valor sobrescreve o original. Mesma sintaxe de `request-header-control-add`.
`mse.ingress.kubernetes.io/request-header-control-remove`	Ingress	Exclusivo do MSE	Remove cabeçalhos das requisições antes de encaminhar para o backend. Para um único cabeçalho, especifique a chave. Para múltiplos cabeçalhos, separe as chaves por vírgulas.
`mse.ingress.kubernetes.io/response-header-control-add`	Ingress	Exclusivo do MSE	Adiciona um cabeçalho às respostas antes de encaminhar para o cliente. Se o cabeçalho já existir, o novo valor é anexado ao original. Mesma sintaxe de `request-header-control-add`.
`mse.ingress.kubernetes.io/response-header-control-update`	Ingress	Exclusivo do MSE	Modifica um cabeçalho nas respostas antes de encaminhar para o cliente. Se o cabeçalho existir, o novo valor sobrescreve o original. Mesma sintaxe de `request-header-control-add`.
`mse.ingress.kubernetes.io/response-header-control-remove`	Ingress	Exclusivo do MSE	Remove cabeçalhos das respostas antes de encaminhar para o cliente. Para um único cabeçalho, especifique a chave. Para múltiplos cabeçalhos, separe as chaves por vírgulas.

Timeout

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/timeout`	Ingress	Exclusivo do MSE	Define o timeout da requisição em segundos. Nenhum timeout é aplicado por padrão. Aplica-se na camada de aplicação, não na camada de transporte TCP.

Nova tentativa

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	Ingress	Compatível	Define o número máximo de novas tentativas. Padrão: 3.
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	Ingress	Compatível	Define o timeout para novas tentativas em segundos. Nenhum timeout é aplicado por padrão.
`nginx.ingress.kubernetes.io/proxy-next-upstream`	Ingress	Compatível	Define as condições que acionam uma nova tentativa. Consulte o mecanismo de nova tentativa do NGINX para valores compatíveis.

Espelhamento de tráfego

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/mirror-target-service`	Ingress	Exclusivo do MSE	Encaminha uma cópia do tráfego recebido para o service especificado. Formato: `namespace/name:port`. O `namespace` assume como padrão o namespace do gateway Ingress. A `port` assume como padrão a primeira porta do service.
`mse.ingress.kubernetes.io/mirror-percentage`	Ingress	Exclusivo do MSE (requer gateway V1.2.32 ou posterior)	Define a porcentagem de tráfego a ser espelhada. Valores válidos: 0–100. Padrão: 100.

Alias de domínio

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/server-alias`	Domínio	Parcialmente compatível — apenas domínios de correspondência exata e domínios curinga (requer gateway V1.2.30 ou posterior)	Define um alias de domínio para o hostname na especificação do Ingress. O alias herda a configuração de TLS, roteamento e governança de tráfego do domínio de origem.

Limitação de taxa (gateway único, a ser descontinuado)

Quando a limitação é acionada, o corpo da resposta é local_rate_limited. O código de status da resposta depende da versão do gateway: gateways anteriores à V1.2.23 retornam 503; V1.2.23 e posteriores retornam 429.

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/route-limit-rpm`	Ingress	Exclusivo do MSE	Define o máximo de requisições por minuto (RPM) em uma rota. O limite de pico é igual a este valor multiplicado por `mse.ingress.kubernetes.io/route-limit-burst-multiplier`.
`mse.ingress.kubernetes.io/route-limit-rps`	Ingress	Exclusivo do MSE	Define o máximo de requisições por segundo (RPS) em uma rota. O limite de pico é igual a este valor multiplicado por `mse.ingress.kubernetes.io/route-limit-burst-multiplier`.
`mse.ingress.kubernetes.io/route-limit-burst-multiplier`	Ingress	Exclusivo do MSE	Define o multiplicador do limite de pico. Padrão: 5.

Limitação de taxa (global, recomendado)

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/rate-limit`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o RPS máximo para limitação de taxa global em uma rota.
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o código de resposta HTTP retornado quando a limitação de taxa é acionada. Padrão: 429. Mutuamente exclusivo com `mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url`.
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o formato do corpo da resposta de limitação de taxa. Padrão: `text`. Definir como `text` retorna `Content-Type: text/plain; charset=UTF-8`. Definir como `JSON` retorna `Content-Type: application/json; charset=UTF-8`.
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o conteúdo do corpo da resposta de limitação de taxa. Padrão: `sentinel rate limited`.
`mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Redireciona requisições para a URL especificada quando a limitação de taxa é acionada. Mutuamente exclusivo com `mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code`.

Controle de concorrência (global)

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/concurrency-limit`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o número máximo de requisições simultâneas em uma rota.
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o código de resposta HTTP quando o controle de concorrência é acionado. Padrão: 429. Mutuamente exclusivo com `mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url`.
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o formato do corpo da resposta de limite de concorrência. Padrão: `text`. Definir como `text` retorna `Content-Type: text/plain; charset=UTF-8`. Definir como `JSON` retorna `Content-Type: application/json; charset=UTF-8`.
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Define o conteúdo do corpo da resposta de limite de concorrência. Padrão: `sentinel rate limited`.
`mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url`	Ingress	Exclusivo do MSE (requer gateway V1.2.25 ou posterior)	Redireciona requisições para a URL especificada quando o controle de concorrência é acionado. Mutuamente exclusivo com `mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code`.

Protocolo de backend

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/backend-protocol`	Service	Parcialmente compatível — AJP e FCGI não são compatíveis	Define o protocolo usado para comunicação com services de backend. Padrão: `HTTP`. Valores compatíveis: `HTTP`, `HTTP2`, `HTTPS`, `gRPC`, `gRPCS`.

Balanceamento de carga

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/load-balance`	Service	Parcialmente compatível — o algoritmo Exponentially Weighted Moving Average (EWMA) não é compatível e reverte para round-robin	Define o algoritmo de balanceamento de carga. Padrão: `round_robin`. Valores compatíveis: `round_robin`, `least_conn`, `random`.
`nginx.ingress.kubernetes.io/upstream-hash-by`	Service	Parcialmente compatível — combinar variáveis do NGINX com constantes não é compatível	Ativa o hash consistente. Tipos de chave de hash compatíveis: `$request_uri` (caminho da requisição, incluindo parâmetros de caminho), `$host` (hostname da requisição), `$remote_addr` (endereço IP do cliente), `$http_<headerName>` (valor do cabeçalho da requisição), `$arg_<varName>` (valor do parâmetro de consulta da URL).

Warm-up de service (início gradual)

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/warmup`	Service	Exclusivo do MSE	Define a duração do warm-up em segundos. Desativado por padrão. Compatível apenas com os algoritmos de balanceamento de carga `round_robin` e `least_conn`.

Afinidade de cookie

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/affinity`	Service	Compatível	Define o tipo de afinidade. O único valor válido é `cookie`.
`nginx.ingress.kubernetes.io/affinity-mode`	Service	Parcialmente compatível — o modo `persistent` não é compatível	Define o modo de afinidade. O único valor válido é `balanced`.
`nginx.ingress.kubernetes.io/session-cookie-name`	Service	Compatível	Define o nome do cookie usado como chave de hash para afinidade de sessão.
`nginx.ingress.kubernetes.io/session-cookie-path`	Service	Compatível	Define o atributo de caminho do cookie de sessão gerado. Padrão: `/`.
`nginx.ingress.kubernetes.io/session-cookie-max-age`	Service	Compatível	Define o `Max-Age` do cookie de sessão gerado em segundos. O padrão é expiração no nível da sessão.
`nginx.ingress.kubernetes.io/session-cookie-expires`	Service	Compatível	Define o atributo `Expires` do cookie de sessão gerado em segundos. O padrão é expiração no nível da sessão.

Controle de acesso baseado em endereço IP

Listas de permissões no nível de rota têm precedência sobre listas de permissões no nível de domínio. Listas de bloqueios no nível de rota têm precedência sobre listas de bloqueios no nível de domínio.

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/whitelist-source-range`	Ingress	Compatível	Define uma lista de permissões de IP para a rota. Aceita endereços IP e blocos CIDR, separados por vírgulas.
`nginx.ingress.kubernetes.io/denylist-source-range`	Ingress	Compatível (requer gateway V1.2.31 ou posterior)	Define uma lista de bloqueios de IP para a rota. Aceita endereços IP e blocos CIDR, separados por vírgulas. Tem precedência sobre `mse.ingress.kubernetes.io/blacklist-source-range`.
`mse.ingress.kubernetes.io/blacklist-source-range`	Ingress	Exclusivo do MSE	Define uma lista de bloqueios de IP para a rota. Aceita endereços IP e blocos CIDR, separados por vírgulas.
`mse.ingress.kubernetes.io/domain-whitelist-source-range`	Ingress	Exclusivo do MSE	Define uma lista de permissões de IP no nível de domínio. Aceita endereços IP e blocos CIDR, separados por vírgulas.
`mse.ingress.kubernetes.io/domain-blacklist-source-range`	Ingress	Exclusivo do MSE	Define uma lista de bloqueios de IP no nível de domínio. Aceita endereços IP e blocos CIDR, separados por vírgulas.

Pool de conexões (gateway para backend)

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/connection-policy-tcp-max-connection`	Service	Exclusivo do MSE	Define o número máximo de conexões TCP entre o gateway e o service de backend.
`mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint`	Service	Exclusivo do MSE	Define o número máximo de conexões TCP entre o gateway e um único pod de backend.
`mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection`	Service	Exclusivo do MSE	Define o número máximo de requisições HTTP por conexão entre o gateway e o service de backend.

Proteção de segurança

TLS entre clientes e o gateway

Anotação	Escopo	Status de suporte	Descrição
`mse.ingress.kubernetes.io/tls-min-protocol-version`	Domínio	Exclusivo do MSE	Define a versão mínima do TLS. Padrão: `TLSv1.0`. Valores válidos: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`.
`mse.ingress.kubernetes.io/tls-max-protocol-version`	Domínio	Exclusivo do MSE	Define a versão máxima do TLS. Padrão: `TLSv1.3`. Valores válidos: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`.
`nginx.ingress.kubernetes.io/ssl-cipher`	Domínio	Compatível	Define as suítes de cifras TLS, separadas por vírgulas. Entra em vigor apenas para handshakes TLS 1.0–1.2. Suítes de cifras 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`.
`mse.ingress.kubernetes.io/auth-tls-secret`	Domínio	Parcialmente compatível — o nome do secret deve seguir o formato `<domain-certificate-secret-name>-cacert`	Especifica o certificado CA que o gateway usa para verificar certificados de cliente durante handshakes mutual TLS (mTLS).

TLS entre o gateway e services de backend

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/proxy-ssl-secret`	Service	Compatível	Especifica o certificado de cliente que o gateway apresenta aos services de backend durante handshakes TLS.
`nginx.ingress.kubernetes.io/proxy-ssl-name`	Service	Compatível	Define o valor de Server Name Indication (SNI) usado durante o handshake TLS com o backend.
`nginx.ingress.kubernetes.io/proxy-ssl-server-name`	Service	Compatível	Ativa ou desativa o SNI durante o handshake TLS com o backend.

Autenticação

Autenticação básica

Anotação	Escopo	Status de suporte	Descrição
`nginx.ingress.kubernetes.io/auth-type`	Ingress	Parcialmente compatível — apenas autenticação `basic` é compatível	Define o tipo de autenticação.
`nginx.ingress.kubernetes.io/auth-secret`	Ingress	Compatível	Especifica o secret que contém credenciais para a rota. Formato: `<namespace>/<name>`.
`nginx.ingress.kubernetes.io/auth-secret-type`	Ingress	Compatível	Define o formato dos dados do secret. `auth-file`: a chave `auth` contém pares `username:password` separados por nova linha. `auth-map`: cada chave é um nome de usuário e seu valor é a senha.
`nginx.ingress.kubernetes.io/auth-realm`	Ingress	Compatível	Define o realm de autenticação. As credenciais são compartilhadas dentro de um realm.

Para a lista completa de anotações do NGINX Ingress, consulte Anotações.