Referência de anotações do APIG Ingress - API Gateway: Central de Documentação do Alibaba Cloud

O APIG Ingress oferece suporte a 51 anotações compatíveis com o NGINX Ingress para facilitar a migração e a 40 anotações estendidas para governança de tráfego e segurança.

Resumo do suporte a anotações

Categoria	Quantidade	Descrição
Anotações compatíveis com NGINX Ingress	51	Cobrem 90% dos casos de uso
Anotações sem efeito funcional	15	Nenhuma configuração necessária
Anotações com suporte planejado	48	Previstas; usadas em cenários limitados
Anotações não suportadas	5	Específicas de trechos de código interno do NGINX Ingress
Anotações estendidas do APIG	40	Controles adicionais de governança de tráfego e segurança além do NGINX Ingress

Referência rápida

Clique em uma anotação para visualizar sua descrição completa.

Anotação	Escopo	Status	Padrão	Categoria
`nginx.ingress.kubernetes.io/canary`	Ingress	Compatível	—	Canary release
`nginx.ingress.kubernetes.io/canary-by-header`	Ingress	Compatível	—	Canary release
`nginx.ingress.kubernetes.io/canary-by-header-value`	Ingress	Compatível	—	Canary release
`nginx.ingress.kubernetes.io/canary-by-header-pattern`	Ingress	Compatível	—	Canary release
`higress.ingress.kubernetes.io/canary-by-query`	Ingress	Extensão Higress	—	Canary release
`higress.ingress.kubernetes.io/canary-by-query-value`	Ingress	Extensão Higress	—	Canary release
`higress.ingress.kubernetes.io/canary-by-query-pattern`	Ingress	Extensão Higress	—	Canary release
`nginx.ingress.kubernetes.io/canary-by-cookie`	Ingress	Compatível	—	Canary release
`higress.ingress.kubernetes.io/canary-by-cookie-value`	Ingress	Extensão Higress (V1.2.30+)	—	Canary release
`nginx.ingress.kubernetes.io/canary-weight`	Ingress	Compatível	—	Canary release
`nginx.ingress.kubernetes.io/canary-weight-total`	Ingress	Compatível	—	Canary release
`higress.ingress.kubernetes.io/destination`	Ingress	Extensão Higress	—	Roteamento multiserviço
`higress.ingress.kubernetes.io/service-subset`	Ingress	Extensão Higress (V1.2.25+)	—	Subconjuntos de serviço
`higress.ingress.kubernetes.io/subset-labels`	Ingress	Extensão Higress (V1.2.25+)	—	Subconjuntos de serviço
`nginx.ingress.kubernetes.io/default-backend`	Ingress	Compatível	—	Fallback
`nginx.ingress.kubernetes.io/custom-http-errors`	Ingress	Compatível	—	Fallback
`nginx.ingress.kubernetes.io/use-regex`	Ingress	Compatível	—	Correspondência regex
`nginx.ingress.kubernetes.io/rewrite-target`	Ingress	Compatível	—	Reescrita
`nginx.ingress.kubernetes.io/upstream-vhost`	Ingress	Compatível	—	Reescrita
`nginx.ingress.kubernetes.io/ssl-redirect`	Ingress	Compatível	—	Redirecionamento
`nginx.ingress.kubernetes.io/force-ssl-redirect`	Ingress	Compatível	—	Redirecionamento
`nginx.ingress.kubernetes.io/permanent-redirect`	Ingress	Compatível	—	Redirecionamento
`nginx.ingress.kubernetes.io/permanent-redirect-code`	Ingress	Compatível	—	Redirecionamento
`nginx.ingress.kubernetes.io/temporal-redirect`	Ingress	Compatível	—	Redirecionamento
`nginx.ingress.kubernetes.io/app-root`	Ingress	Compatível	—	Redirecionamento
`nginx.ingress.kubernetes.io/enable-cors`	Ingress	Compatível	—	CORS
`nginx.ingress.kubernetes.io/cors-allow-origin`	Ingress	Compatível	—	CORS
`nginx.ingress.kubernetes.io/cors-allow-methods`	Ingress	Compatível	—	CORS
`nginx.ingress.kubernetes.io/cors-allow-headers`	Ingress	Compatível	—	CORS
`nginx.ingress.kubernetes.io/cors-expose-headers`	Ingress	Compatível	—	CORS
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Ingress	Compatível	—	CORS
`nginx.ingress.kubernetes.io/cors-max-age`	Ingress	Compatível	—	CORS
`higress.ingress.kubernetes.io/request-header-control-add`	Ingress	Extensão Higress	—	Controle de cabeçalho
`higress.ingress.kubernetes.io/request-header-control-update`	Ingress	Extensão Higress	—	Controle de cabeçalho
`higress.ingress.kubernetes.io/request-header-control-remove`	Ingress	Extensão Higress	—	Controle de cabeçalho
`higress.ingress.kubernetes.io/response-header-control-add`	Ingress	Extensão Higress	—	Controle de cabeçalho
`higress.ingress.kubernetes.io/response-header-control-update`	Ingress	Extensão Higress	—	Controle de cabeçalho
`higress.ingress.kubernetes.io/response-header-control-remove`	Ingress	Extensão Higress	—	Controle de cabeçalho
`higress.ingress.kubernetes.io/timeout`	Ingress	Extensão Higress	Nenhum	Timeout
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	Ingress	Compatível	`3`	Nova tentativa
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	Ingress	Compatível	Nenhum	Nova tentativa
`nginx.ingress.kubernetes.io/proxy-next-upstream`	Ingress	Compatível	—	Nova tentativa
`higress.ingress.kubernetes.io/mirror-target-service`	Ingress	Extensão Higress	—	Espelhamento de tráfego
`higress.ingress.kubernetes.io/mirror-percentage`	Ingress	Extensão Higress (V1.2.32+)	`100`	Espelhamento de tráfego
`nginx.ingress.kubernetes.io/server-alias`	Nome de domínio	Parcialmente compatível (V1.2.30+)	—	Alias de domínio
`higress.ingress.kubernetes.io/route-limit-rpm`	Ingress	Extensão Higress	—	Limitação de taxa (obsoleto)
`higress.ingress.kubernetes.io/route-limit-rps`	Ingress	Extensão Higress	—	Limitação de taxa (obsoleto)
`higress.ingress.kubernetes.io/route-limit-burst-multiplier`	Ingress	Extensão Higress	`5`	Limitação de taxa (obsoleto)
`higress.ingress.kubernetes.io/rate-limit`	Ingress	Extensão Higress (V1.2.25+)	—	Limitação global
`higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code`	Ingress	Extensão Higress (V1.2.25+)	`429`	Limitação global
`higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type`	Ingress	Extensão Higress (V1.2.25+)	`text`	Limitação global
`higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body`	Ingress	Extensão Higress (V1.2.25+)	`sentinel rate limited`	Limitação global
`higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url`	Ingress	Extensão Higress (V1.2.25+)	—	Limitação global
`higress.ingress.kubernetes.io/concurrency-limit`	Ingress	Extensão Higress (V1.2.25+)	—	Concorrência global
`higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code`	Ingress	Extensão Higress (V1.2.25+)	`429`	Concorrência global
`higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type`	Ingress	Extensão Higress (V1.2.25+)	`text`	Concorrência global
`higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body`	Ingress	Extensão Higress (V1.2.25+)	`sentinel rate limited`	Concorrência global
`higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url`	Ingress	Extensão Higress (V1.2.25+)	—	Concorrência global
`nginx.ingress.kubernetes.io/backend-protocol`	Service	Parcialmente compatível	`HTTP`	Protocolo de backend
`nginx.ingress.kubernetes.io/load-balance`	Service	Parcialmente compatível	`round_robin`	Balanceamento de carga
`nginx.ingress.kubernetes.io/upstream-hash-by`	Service	Parcialmente compatível	—	Balanceamento de carga
`higress.ingress.kubernetes.io/warmup`	Service	Extensão Higress	Desativado	Warmup
`nginx.ingress.kubernetes.io/affinity`	Service	Compatível	`cookie`	Afinidade de cookie
`nginx.ingress.kubernetes.io/affinity-mode`	Service	Parcialmente compatível	`balanced`	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-name`	Service	Compatível	—	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-path`	Service	Compatível	`/`	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-max-age`	Service	Compatível	Nível de sessão	Afinidade de cookie
`nginx.ingress.kubernetes.io/session-cookie-expires`	Service	Compatível	Nível de sessão	Afinidade de cookie
`nginx.ingress.kubernetes.io/whitelist-source-range`	Ingress	Compatível	—	Controle de acesso por ip
`nginx.ingress.kubernetes.io/denylist-source-range`	Ingress	Compatível (V1.2.31+)	—	Controle de acesso por ip
`higress.ingress.kubernetes.io/blacklist-source-range`	Ingress	Extensão Higress	—	Controle de acesso por ip
`higress.ingress.kubernetes.io/domain-whitelist-source-range`	Ingress	Extensão Higress	—	Controle de acesso por ip
`higress.ingress.kubernetes.io/domain-blacklist-source-range`	Ingress	Extensão Higress	—	Controle de acesso por ip
`higress.ingress.kubernetes.io/connection-policy-tcp-max-connection`	Service	Extensão Higress	—	Pool de conexões
`higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint`	Service	Extensão Higress	—	Pool de conexões
`higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection`	Service	Extensão Higress	—	Pool de conexões
`higress.ingress.kubernetes.io/tls-min-protocol-version`	Nome de domínio	Extensão Higress	`TLSv1.0`	tls cliente-gateway
`higress.ingress.kubernetes.io/tls-max-protocol-version`	Nome de domínio	Extensão Higress	`TLSv1.3`	tls cliente-gateway
`nginx.ingress.kubernetes.io/ssl-cipher`	Nome de domínio	Compatível	Ver descrição	tls cliente-gateway
`higress.ingress.kubernetes.io/auth-tls-secret`	Nome de domínio	Parcialmente compatível	—	tls cliente-gateway
`nginx.ingress.kubernetes.io/proxy-ssl-secret`	Service	Compatível	—	tls gateway-backend
`nginx.ingress.kubernetes.io/proxy-ssl-name`	Service	Compatível	—	tls gateway-backend
`nginx.ingress.kubernetes.io/proxy-ssl-server-name`	Service	Compatível	—	tls gateway-backend
`nginx.ingress.kubernetes.io/auth-type`	Ingress	Parcialmente compatível	—	Autenticação básica
`nginx.ingress.kubernetes.io/auth-secret`	Ingress	Compatível	—	Autenticação básica
`nginx.ingress.kubernetes.io/auth-secret-type`	Ingress	Compatível	—	Autenticação básica
`nginx.ingress.kubernetes.io/auth-realm`	Ingress	Compatível	—	Autenticação básica

Escopo

Cada anotação aplica-se a um escopo específico:

Ingress — Aplica-se às regras de roteamento no recurso Ingress onde a anotação está definida.
Nome de domínio — Aplica-se a todos os recursos Ingress que compartilham os mesmos hosts.
Service — Aplica-se a todos os recursos Ingress que compartilham os mesmos serviços.

Prefixos de anotação

Para anotações compartilhadas entre NGINX Ingress e APIG Ingress, os seguintes prefixos são intercambiáveis:

nginx.ingress.kubernetes.io/xxx
higress.ingress.kubernetes.io/xxx

Anotações marcadas como Extensão Higress exigem o prefixo higress e não aceitam o prefixo nginx.

Notas de compatibilidade

Principais diferenças em relação ao NGINX Ingress:

Variáveis do NGINX: Variáveis do NGINX em anotações e trechos de código não são compatíveis com o APIG Ingress. Revise as anotações dependentes de variáveis antes de migrar.
Tamanho do corpo da requisição: O NGINX Ingress usa nginx.ingress.kubernetes.io/proxy-body-size para impor um limite rígido e retorna um erro quando excedido. O APIG Ingress utiliza streaming baseado em blocos, sem limite predefinido de tamanho de corpo. Para transferências de arquivos extremamente grandes, ajuste DownstreamConnectionBufferLimits na configuração da instância do gateway.

Anotações de governança de tráfego

Canary release

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/canary`	Ingress	Compatível	Ativa ou desativa o canary release para uma rota.
`nginx.ingress.kubernetes.io/canary-by-header`	Ingress	Compatível	Chave do cabeçalho de requisição usada para divisão de tráfego.
`nginx.ingress.kubernetes.io/canary-by-header-value`	Ingress	Compatível	Valor do cabeçalho de requisição para divisão de tráfego. Suporta correspondência exata.
`nginx.ingress.kubernetes.io/canary-by-header-pattern`	Ingress	Compatível	Valor do cabeçalho de requisição para divisão de tráfego. Suporta correspondência regex.
`higress.ingress.kubernetes.io/canary-by-query`	Ingress	Extensão Higress	Chave do parâmetro de query da url usada para divisão de tráfego.
`higress.ingress.kubernetes.io/canary-by-query-value`	Ingress	Extensão Higress	Valor do parâmetro de query da url para divisão de tráfego. Suporta correspondência exata.
`higress.ingress.kubernetes.io/canary-by-query-pattern`	Ingress	Extensão Higress	Valor do parâmetro de query da url para divisão de tráfego. Suporta correspondência regex.
`nginx.ingress.kubernetes.io/canary-by-cookie`	Ingress	Compatível	Chave do cookie usado para divisão de tráfego.
`higress.ingress.kubernetes.io/canary-by-cookie-value`	Ingress	Extensão Higress (V1.2.30+)	Valor do cookie para divisão de tráfego. Suporta correspondência exata.
`nginx.ingress.kubernetes.io/canary-weight`	Ingress	Compatível	Peso do serviço usado para divisão de tráfego.
`nginx.ingress.kubernetes.io/canary-weight-total`	Ingress	Compatível	Peso total para divisão de tráfego.

Roteamento multiserviço

Anotação	Escopo	Status	Descrição
`higress.ingress.kubernetes.io/destination`	Ingress	Extensão Higress	Distribui o tráfego entre vários serviços por peso. Sintaxe: `{weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}`

Definir esta anotação altera o destino de todas as regras de roteamento no Ingress. Se a sintaxe for inválida, a anotação será ignorada e o roteamento permanecerá inalterado.

Exemplo:

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

Subconjuntos de serviço

Direcione requisições para um subconjunto específico de Pods quando um único serviço gerencia múltiplos Deployments.

Anotação	Escopo	Status	Descrição
`higress.ingress.kubernetes.io/service-subset`	Ingress	Extensão Higress (V1.2.25+)	Identifica o subconjunto de Pods para o qual as requisições serão roteadas.
`higress.ingress.kubernetes.io/subset-labels`	Ingress	Extensão Higress (V1.2.25+)	(Opcional) Seletor de rótulos usado com `service-subset` para classificar Pods em subconjuntos.

Comportamento de roteamento para service-subset:

Se subset-labels não estiver definido:
- Definido como "" ou base — roteia para Pods rotulados com opensergo.io/canary: "" ou Pods sem nenhuma chave de rótulo opensergo.io/canary.
- Definido com qualquer outro valor (por exemplo, gray) — roteia para Pods rotulados com opensergo.io/canary-gray: gray.
Se subset-labels estiver definido — roteia apenas para Pods cujos rótulos correspondam aos pares chave-valor definidos em subset-labels.

Se nenhum Pod corresponder ao rótulo especificado, as requisições serão encaminhadas automaticamente para todos os Pods do serviço.

Exemplo:

annotations:
  # Route to the "gray" subset of Pods
  higress.ingress.kubernetes.io/service-subset: "gray"

Fallback

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/default-backend`	Ingress	Compatível	Serviço de fallback quando não há nós primários íntegros disponíveis.
`nginx.ingress.kubernetes.io/custom-http-errors`	Ingress	Compatível	Códigos de status HTTP que acionam o encaminhamento para o serviço de fallback.

Importante

Quando uma requisição é encaminhada para o serviço de fallback, o caminho da requisição é reescrito para /. Este comportamento corresponde ao do NGINX Ingress.

Correspondência de expressão regular

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/use-regex`	Ingress	Compatível	Habilita a correspondência de caminho via regex no Ingress usando sintaxe RE2.

Reescrita

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/rewrite-target`	Ingress	Compatível	Caminho de destino para reescrita de url. Grupos de captura são suportados.
`nginx.ingress.kubernetes.io/upstream-vhost`	Ingress	Compatível	Reescreve o cabeçalho `Host` nas requisições encaminhadas para um serviço de backend.

Redirecionamento

O uso de variáveis do NGINX para redirecionamento não está documentado no NGINX Ingress e pode causar problemas de compatibilidade. Evite variáveis do NGINX em anotações de redirecionamento.

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

CORS

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/enable-cors`	Ingress	Compatível	Habilita o compartilhamento de recursos de origem cruzada (CORS).
`nginx.ingress.kubernetes.io/cors-allow-origin`	Ingress	Compatível	Origens permitidas para requisições CORS.
`nginx.ingress.kubernetes.io/cors-allow-methods`	Ingress	Compatível	Métodos HTTP permitidos para CORS. Inclui GET, POST e PUT.
`nginx.ingress.kubernetes.io/cors-allow-headers`	Ingress	Compatível	Cabeçalhos de requisição permitidos para CORS.
`nginx.ingress.kubernetes.io/cors-expose-headers`	Ingress	Compatível	Cabeçalhos de resposta expostos aos navegadores.
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Ingress	Compatível	Indica se credenciais podem ser incluídas em requisições CORS.
`nginx.ingress.kubernetes.io/cors-max-age`	Ingress	Compatível	Tempo (em segundos) de cache dos resultados de preflight.

Controle de cabeçalho

As anotações de controle de cabeçalho em rotas base e canary são independentes e validadas separadamente. Utilize-as para configurar políticas de cabeçalho distintas para cada tipo de tráfego.

Anotação	Escopo	Status	Descrição
`higress.ingress.kubernetes.io/request-header-control-add`	Ingress	Extensão Higress	Adiciona um cabeçalho às requisições encaminhadas. Se o cabeçalho já existir, o valor será anexado.
`higress.ingress.kubernetes.io/request-header-control-update`	Ingress	Extensão Higress	Sobrescreve um cabeçalho nas requisições encaminhadas.
`higress.ingress.kubernetes.io/request-header-control-remove`	Ingress	Extensão Higress	Remove um cabeçalho das requisições encaminhadas.
`higress.ingress.kubernetes.io/response-header-control-add`	Ingress	Extensão Higress	Adiciona um cabeçalho às respostas para o cliente. Se o cabeçalho já existir, o valor será anexado.
`higress.ingress.kubernetes.io/response-header-control-update`	Ingress	Extensão Higress	Sobrescreve um cabeçalho nas respostas para o cliente.
`higress.ingress.kubernetes.io/response-header-control-remove`	Ingress	Extensão Higress	Remove um cabeçalho das respostas para o cliente.

Sintaxe:

Cabeçalho único (adicionar/atualizar): Use um par chave-valor. Exemplo: X-Custom-Header: value
Múltiplos cabeçalhos (adicionar/atualizar): Use um bloco escalar YAML (|). Cada par chave-valor deve estar em uma linha separada.
Cabeçalho único (remover): Use apenas a chave do cabeçalho.
Múltiplos cabeçalhos (remover): Chaves de cabeçalho separadas por vírgula.

Exemplo — adicionar um cabeçalho de requisição:

annotations:
  higress.ingress.kubernetes.io/request-header-control-add: "X-Request-Id: abc123"

Exemplo — adicionar múltiplos cabeçalhos de resposta:

annotations:
  higress.ingress.kubernetes.io/response-header-control-add: |
    X-Custom-Header: value1
    X-Another-Header: value2

Exemplo — remover múltiplos cabeçalhos de requisição:

annotations:
  higress.ingress.kubernetes.io/request-header-control-remove: "X-Forwarded-For,X-Real-IP"

Timeout

Anotação	Escopo	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/timeout`	Ingress	Extensão Higress	Nenhum	Timeout da requisição em segundos.

Este timeout aplica-se na camada de aplicação (HTTP), não na camada de transporte tcp.

Nova tentativa

Anotação	Escopo	Status	Padrão	Descrição
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	Ingress	Compatível	`3`	Número máximo de novas tentativas.
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	Ingress	Compatível	Nenhum	Timeout para novas tentativas, em segundos.
`nginx.ingress.kubernetes.io/proxy-next-upstream`	Ingress	Compatível	—	Condições para nova tentativa. Consulte o mecanismo de nova tentativa do NGINX para valores válidos.

Espelhamento de tráfego

Anotação	Escopo	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/mirror-target-service`	Ingress	Extensão Higress	—	Serviço de destino para o tráfego espelhado. Formato: `namespace/name:port`. `namespace` assume como padrão o namespace do gateway Ingress; `port` assume como padrão a primeira porta. `name` é obrigatório.
`higress.ingress.kubernetes.io/mirror-percentage`	Ingress	Extensão Higress (V1.2.32+)	`100`	Porcentagem de tráfego a ser espelhada. Valores válidos: `0`–`100`.

Exemplo:

annotations:
  # Mirror 20% of traffic to the shadow service
  higress.ingress.kubernetes.io/mirror-target-service: "default/shadow-service:8080"
  higress.ingress.kubernetes.io/mirror-percentage: "20"

Alias de domínio

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/server-alias`	Nome de domínio	Parcialmente compatível (V1.2.30+)	Domínio de alias que compartilha a configuração de tls, roteamento e governança de tráfego do domínio principal. Suporta apenas domínios exatos e curingas.

Limitação de taxa (obsoleto)

Estas anotações estão obsoletas. Utilize o controle de limitação global em seu lugar.

Anotação	Escopo	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/route-limit-rpm`	Ingress	Extensão Higress	—	Máximo de requisições por minuto (RPM) por gateway. Limite de burst = valor × `route-limit-burst-multiplier`. Quando acionado, o corpo da resposta é `local_rate_limited`. Retorna `503` antes da V1.2.23 e `429` na V1.2.23+.
`higress.ingress.kubernetes.io/route-limit-rps`	Ingress	Extensão Higress	—	Máximo de requisições por segundo (RPS) por gateway. Mesmo comportamento de burst e resposta que `route-limit-rpm`.
`higress.ingress.kubernetes.io/route-limit-burst-multiplier`	Ingress	Extensão Higress	`5`	Multiplicador do limite de burst.

Controle de limitação global (recomendado)

Todas as anotações nesta seção exigem a versão V1.2.25 ou posterior do gateway.

Anotação	Escopo	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/rate-limit`	Ingress	Extensão Higress	—	RPS máximo para a rota. Usado para limitação de taxa global.
`higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code`	Ingress	Extensão Higress	`429`	Código de resposta HTTP quando a limitação de taxa é acionada.
`higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type`	Ingress	Extensão Higress	`text`	Tipo de conteúdo do corpo da resposta quando a limitação de taxa é acionada. Defina como `json` para retornar `application/json; charset=UTF-8`.
`higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body`	Ingress	Extensão Higress	`sentinel rate limited`	Corpo da resposta quando a limitação de taxa é acionada.
`higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url`	Ingress	Extensão Higress	—	url de redirecionamento quando a limitação de taxa é acionada.

rate-limit-fallback-custom-response-code e rate-limit-fallback-redirect-url são mutuamente exclusivos. Defina apenas um.

Exemplo — retornar uma resposta JSON personalizada quando a limitação de taxa for acionada:

annotations:
  higress.ingress.kubernetes.io/rate-limit: "100"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: "429"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type: "json"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: '{"error":"rate limit exceeded"}'

Controle de concorrência global

Todas as anotações nesta seção exigem a versão V1.2.25 ou posterior do gateway.

Anotação	Escopo	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/concurrency-limit`	Ingress	Extensão Higress	—	Número máximo de requisições simultâneas na rota.
`higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code`	Ingress	Extensão Higress	`429`	Código de resposta HTTP quando o controle de concorrência é acionado.
`higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type`	Ingress	Extensão Higress	`text`	Tipo de conteúdo do corpo da resposta quando o controle de concorrência é acionado. Defina como `json` para retornar `application/json; charset=UTF-8`.
`higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body`	Ingress	Extensão Higress	`sentinel rate limited`	Corpo da resposta quando o controle de concorrência é acionado.
`higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url`	Ingress	Extensão Higress	—	url de redirecionamento quando o controle de concorrência é acionado.

concurrency-limit-fallback-custom-response-code e concurrency-limit-fallback-redirect-url são mutuamente exclusivos. Defina apenas um.

Protocolo de backend

Anotação	Escopo	Status	Padrão	Descrição
`nginx.ingress.kubernetes.io/backend-protocol`	Service	Parcialmente compatível	`HTTP`	Protocolo usado pelo serviço de backend. AJP e FCGI não são suportados. Valores válidos: `HTTP`, `HTTP2`, `HTTPS`, `gRPC`, `gRPCS`.

Balanceamento de carga

Anotação	Escopo	Status	Padrão	Descrição
`nginx.ingress.kubernetes.io/load-balance`	Service	Parcialmente compatível	`round_robin`	Algoritmo de balanceamento de carga. Exponentially Weighted Moving Average (EWMA) não é suportado; reverte para `round_robin`. Valores válidos: `round_robin`, `least_conn`, `random`.
`nginx.ingress.kubernetes.io/upstream-hash-by`	Service	Parcialmente compatível	—	Algoritmo de hash consistente. A combinação de variáveis do NGINX com constantes não é suportada. Suporta hash por variável do NGINX (`$request_uri`, `$host`, `$remote_addr`), cabeçalho de requisição (`$http_headerName`) ou parâmetro de query (`$arg_varName`).

Warmup (inicialização gradual)

Anotação	Escopo	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/warmup`	Service	Extensão Higress	Desativado	Duração do período de warmup em segundos.

Importante

O warmup exige um algoritmo de balanceamento de carga round_robin ou least_conn. Não há suporte para outros algoritmos.

Afinidade de cookie

Anotação	Escopo	Status	Padrão	Descrição
`nginx.ingress.kubernetes.io/affinity`	Service	Compatível	`cookie`	Tipo de afinidade. Valor padrão e único válido: `cookie`.
`nginx.ingress.kubernetes.io/affinity-mode`	Service	Parcialmente compatível	`balanced`	Modo de afinidade. O modo `persistent` não é suportado. Valor padrão e único válido: `balanced`.
`nginx.ingress.kubernetes.io/session-cookie-name`	Service	Compatível	—	Nome do cookie usado como chave de hash.
`nginx.ingress.kubernetes.io/session-cookie-path`	Service	Compatível	`/`	Caminho do cookie gerado quando o cookie especificado não existe.
`nginx.ingress.kubernetes.io/session-cookie-max-age`	Service	Compatível	Nível de sessão	Tempo de expiração do cookie gerado, em segundos.
`nginx.ingress.kubernetes.io/session-cookie-expires`	Service	Compatível	Nível de sessão	Tempo de expiração do cookie gerado, em segundos.

Controle de acesso por endereço ip

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/whitelist-source-range`	Ingress	Compatível	Lista de permissões de endereços ip e blocos CIDR para a rota. Separados por vírgula.
`nginx.ingress.kubernetes.io/denylist-source-range`	Ingress	Compatível (V1.2.31+)	Lista de bloqueios de endereços ip e blocos CIDR no nível da rota. Separados por vírgula. Tem precedência sobre `higress.ingress.kubernetes.io/blacklist-source-range`.
`higress.ingress.kubernetes.io/blacklist-source-range`	Ingress	Extensão Higress	Lista de bloqueios de endereços ip e blocos CIDR para a rota. Separados por vírgula.
`higress.ingress.kubernetes.io/domain-whitelist-source-range`	Ingress	Extensão Higress	Lista de permissões de endereços ip e blocos CIDR no nível do domínio. Separados por vírgula. Listas de permissões no nível da rota têm precedência.
`higress.ingress.kubernetes.io/domain-blacklist-source-range`	Ingress	Extensão Higress	Lista de bloqueios de endereços ip e blocos CIDR no nível do domínio. Separados por vírgula. Listas de bloqueios no nível da rota têm precedência.

Pool de conexões (gateway para backend)

Anotação	Escopo	Status	Descrição
`higress.ingress.kubernetes.io/connection-policy-tcp-max-connection`	Service	Extensão Higress	Total máximo de conexões tcp para o serviço de backend.
`higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint`	Service	Extensão Higress	Máximo de conexões tcp por endpoint de backend.
`higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection`	Service	Extensão Higress	Máximo de requisições HTTP por conexão de backend.

Anotações de segurança

tls cliente-gateway

Anotação	Escopo	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/tls-min-protocol-version`	Nome de domínio	Extensão Higress	`TLSv1.0`	Versão mínima do tls. Valores válidos: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`.
`higress.ingress.kubernetes.io/tls-max-protocol-version`	Nome de domínio	Extensão Higress	`TLSv1.3`	Versão máxima do tls. Valores válidos: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`.
`nginx.ingress.kubernetes.io/ssl-cipher`	Nome de domínio	Compatível	Ver abaixo	Suítes de criptografia tls, separadas por vírgula. Aplica-se apenas ao tls v1.0–v1.2 (não v1.3).
`higress.ingress.kubernetes.io/auth-tls-secret`	Nome de domínio	Parcialmente compatível	—	Certificado CA para verificação de cliente mTLS. Formato do nome do Secret: `{domain-certificate-secret-name}-cacert`.

Suítes de criptografia padrão para ssl-cipher: 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.

tls gateway-backend

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/proxy-ssl-secret`	Service	Compatível	Certificado de cliente usado pelo gateway para autenticação no backend.
`nginx.ingress.kubernetes.io/proxy-ssl-name`	Service	Compatível	Server Name Indication (SNI) enviado 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 básica

Anotação	Escopo	Status	Descrição
`nginx.ingress.kubernetes.io/auth-type`	Ingress	Parcialmente compatível	Tipo de autenticação. Apenas `basic` é suportado.
`nginx.ingress.kubernetes.io/auth-secret`	Ingress	Compatível	Secret contendo as credenciais para a rota. Formato: `<namespace>/<name>`.
`nginx.ingress.kubernetes.io/auth-secret-type`	Ingress	Compatível	Formato dos dados do secret. `auth-file`: a chave é `auth`, o valor é `username:password` (uma entrada por linha). `auth-map`: a chave é o nome de usuário, o valor é a senha.
`nginx.ingress.kubernetes.io/auth-realm`	Ingress	Compatível	Realm de autenticação. As credenciais são compartilhadas dentro de um realm.

Referência completa de anotações do NGINX Ingress: Anotações.