APIG Ingress annotation reference - API Gateway: Central de Documentação do Alibaba Cloud

O APIG Ingress oferece suporte a 51 annotations do NGINX Ingress para migração sem interrupções e 40 annotations estendidas para governança de tráfego e segurança.

Resumo do suporte a annotations

Categoria	Quantidade	Descrição
Annotations compatíveis com NGINX Ingress	51	Cobrem 90% dos casos de uso
Annotations sem efeito funcional	15	Nenhuma configuração necessária
Annotations a serem suportadas	48	Planejadas; usadas em cenários limitados
Annotations não suportadas	5	Específicas para trechos de código interno do NGINX Ingress
Annotations 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 annotation para visualizar sua descrição completa.

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

Escopo

Cada annotation se aplica a um escopo específico:

Ingress — Aplica-se às regras de roteamento no recurso Ingress onde a annotation 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 services.

Prefixos de annotation

Para annotations compartilhadas entre NGINX Ingress e APIG Ingress, os seguintes prefixos são intercambiáveis:

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

As annotations marcadas como Higress extension exigem o prefixo higress e não podem utilizar o prefixo nginx.

Notas de compatibilidade

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

Variáveis do NGINX: as variáveis do NGINX em annotations e trechos de código não são compatíveis com o APIG Ingress. Revise as annotations que dependem de variáveis antes de realizar a migração.
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 esse limite é excedido. O APIG Ingress utiliza streaming baseado em blocos, sem limite predefinido para o tamanho do corpo. Para transferências de arquivos muito grandes, ajuste o parâmetro DownstreamConnectionBufferLimits na configuração da instância do gateway.

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

Canary release

Annotation	Scope	Status	Descrição
`nginx.ingress.kubernetes.io/canary`	Ingress	Compatible	Ativa ou desativa o canary release para uma rota.
`nginx.ingress.kubernetes.io/canary-by-header`	Ingress	Compatible	Chave do cabeçalho de requisição usada para divisão de tráfego.
`nginx.ingress.kubernetes.io/canary-by-header-value`	Ingress	Compatible	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	Compatible	Valor do cabeçalho de requisição para divisão de tráfego. Suporta correspondência por regex.
`higress.ingress.kubernetes.io/canary-by-query`	Ingress	Higress extension	Chave do parâmetro de consulta URL usada para divisão de tráfego.
`higress.ingress.kubernetes.io/canary-by-query-value`	Ingress	Higress extension	Valor do parâmetro de consulta URL para divisão de tráfego. Suporta correspondência exata.
`higress.ingress.kubernetes.io/canary-by-query-pattern`	Ingress	Higress extension	Valor do parâmetro de consulta URL para divisão de tráfego. Suporta correspondência por regex.
`nginx.ingress.kubernetes.io/canary-by-cookie`	Ingress	Compatible	Chave do cookie usada para divisão de tráfego.
`higress.ingress.kubernetes.io/canary-by-cookie-value`	Ingress	Higress extension (V1.2.30+)	Valor do cookie para divisão de tráfego. Suporta correspondência exata.
`nginx.ingress.kubernetes.io/canary-weight`	Ingress	Compatible	Peso do service usado para divisão de tráfego.
`nginx.ingress.kubernetes.io/canary-weight-total`	Ingress	Compatible	Peso total para divisão de tráfego.

Roteamento para múltiplos services

Annotation	Scope	Status	Descrição
`higress.ingress.kubernetes.io/destination`	Ingress	Higress extension	Distribui o tráfego entre múltiplos services por peso. Sintaxe: `{weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}`

Definir esta annotation altera o destino de todas as regras de roteamento no Ingress. Se a sintaxe for inválida, a annotation é ignorada e o roteamento permanece 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 service

Encaminhe requisições para um subconjunto específico de Pods quando um service gerencia múltiplos Deployments.

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

Comportamento de roteamento para service-subset:

Quando subset-labels não está definido:
- Definido como "" ou base — roteia para Pods com o rótulo opensergo.io/canary: "" ou para Pods sem nenhuma chave de rótulo opensergo.io/canary.
- Definido com qualquer outro valor (por exemplo, gray) — roteia para Pods com o rótulo opensergo.io/canary-gray: gray.
Quando subset-labels está 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 automaticamente encaminhadas para todos os Pods do service.

Exemplo:

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

Fallback

Annotation	Scope	Status	Descrição
`nginx.ingress.kubernetes.io/default-backend`	Ingress	Compatible	Service de fallback acionado quando não há nós primários saudáveis disponíveis.
`nginx.ingress.kubernetes.io/custom-http-errors`	Ingress	Compatible	Códigos de status HTTP que disparam o encaminhamento para o service de fallback.

Importante

Quando uma requisição é encaminhada para o service de fallback, o caminho da requisição é reescrito para /. Esse comportamento é compatível com o NGINX Ingress.

Correspondência por expressão regular

Annotation	Scope	Status	Descrição
`nginx.ingress.kubernetes.io/use-regex`	Ingress	Compatible	Ativa a correspondência de caminho por regex no Ingress, utilizando a sintaxe RE2.

Rewrite

Annotation	Scope	Status	Descrição
`nginx.ingress.kubernetes.io/rewrite-target`	Ingress	Compatible	Caminho de destino para reescrita de URL. Grupos de captura são suportados.
`nginx.ingress.kubernetes.io/upstream-vhost`	Ingress	Compatible	Reescreve o cabeçalho `Host` nas requisições encaminhadas ao service de backend.

Redirection

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

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

CORS

Annotation	Scope	Status	Descrição
`nginx.ingress.kubernetes.io/enable-cors`	Ingress	Compatible	Ativa o compartilhamento de recursos entre origens (CORS).
`nginx.ingress.kubernetes.io/cors-allow-origin`	Ingress	Compatible	Origens permitidas para requisições CORS.
`nginx.ingress.kubernetes.io/cors-allow-methods`	Ingress	Compatible	Métodos HTTP permitidos para CORS. Inclui GET, POST e PUT.
`nginx.ingress.kubernetes.io/cors-allow-headers`	Ingress	Compatible	Cabeçalhos de requisição permitidos para CORS.
`nginx.ingress.kubernetes.io/cors-expose-headers`	Ingress	Compatible	Cabeçalhos de resposta expostos aos navegadores.
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Ingress	Compatible	Indica se credenciais podem ser incluídas em requisições CORS.
`nginx.ingress.kubernetes.io/cors-max-age`	Ingress	Compatible	Tempo (em segundos) pelo qual os resultados de preflight ficam em cache.

Controle de cabeçalhos

As annotations de controle de cabeçalhos nas rotas base e canary são independentes e validadas separadamente. Use-as para configurar políticas de cabeçalho distintas para cada tipo de tráfego.

Annotation	Scope	Status	Descrição
`higress.ingress.kubernetes.io/request-header-control-add`	Ingress	Higress extension	Acrescenta um cabeçalho às requisições encaminhadas. Se o cabeçalho já existir, o valor é adicionado ao existente.
`higress.ingress.kubernetes.io/request-header-control-update`	Ingress	Higress extension	Sobrescreve um cabeçalho nas requisições encaminhadas.
`higress.ingress.kubernetes.io/request-header-control-remove`	Ingress	Higress extension	Remove um cabeçalho das requisições encaminhadas.
`higress.ingress.kubernetes.io/response-header-control-add`	Ingress	Higress extension	Acrescenta um cabeçalho às respostas enviadas ao cliente. Se o cabeçalho já existir, o valor é adicionado ao existente.
`higress.ingress.kubernetes.io/response-header-control-update`	Ingress	Higress extension	Sobrescreve um cabeçalho nas respostas enviadas ao cliente.
`higress.ingress.kubernetes.io/response-header-control-remove`	Ingress	Higress extension	Remove um cabeçalho das respostas enviadas ao cliente.

Sintaxe:

Cabeçalho único (add/update): Use um par chave-valor. Exemplo: X-Custom-Header: value
Múltiplos cabeçalhos (add/update): Use um bloco escalar YAML (|). Cada par chave-valor em uma linha separada.
Cabeçalho único (remove): Informe apenas a chave do cabeçalho.
Múltiplos cabeçalhos (remove): 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

Annotation	Scope	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/timeout`	Ingress	Higress extension	None	Timeout da requisição, em segundos.

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

Retry

Annotation	Scope	Status	Padrão	Descrição
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	Ingress	Compatible	`3`	Número máximo de tentativas de retry.
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	Ingress	Compatible	None	Timeout para as tentativas de retry, em segundos.
`nginx.ingress.kubernetes.io/proxy-next-upstream`	Ingress	Compatible	—	Condições de retry. Consulte o mecanismo de retry do NGINX para os valores válidos.

Espelhamento de tráfego

Annotation	Scope	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/mirror-target-service`	Ingress	Higress extension	—	Service 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	Higress extension (V1.2.32+)	`100`	Percentual de tráfego a ser espelhado. 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

Annotation	Scope	Status	Descrição
`nginx.ingress.kubernetes.io/server-alias`	Nome de domínio	Partially compatible (V1.2.30+)	Domínio alias que compartilha as configurações de TLS, roteamento e governança de tráfego do domínio primário. Suporta apenas domínios com correspondência exata e wildcard.

Limitação de taxa (descontinuado)

Essas annotations estão descontinuadas. Utilize o controle global de throttling no lugar delas.

Annotation	Scope	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/route-limit-rpm`	Ingress	Higress extension	—	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` a partir da V1.2.23.
`higress.ingress.kubernetes.io/route-limit-rps`	Ingress	Higress extension	—	Máximo de requisições por segundo (RPS) por gateway. Comportamento de burst e resposta idêntico ao de `route-limit-rpm`.
`higress.ingress.kubernetes.io/route-limit-burst-multiplier`	Ingress	Higress extension	`5`	Multiplicador do limite de burst.

Controle global de throttling (recomendado)

Todas as annotations desta seção exigem a versão de gateway V1.2.25 ou superior.

Annotation	Scope	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/rate-limit`	Ingress	Higress extension	—	RPS máximo para a rota. Usado para limitação de taxa global.
`higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code`	Ingress	Higress extension	`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	Higress extension	`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	Higress extension	`sentinel rate limited`	Corpo da resposta quando a limitação de taxa é acionada.
`higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url`	Ingress	Higress extension	—	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 deles.

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 global de concorrência

Todas as annotations desta seção exigem a versão de gateway V1.2.25 ou superior.

Annotation	Scope	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/concurrency-limit`	Ingress	Higress extension	—	Número máximo de requisições simultâneas na rota.
`higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code`	Ingress	Higress extension	`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	Higress extension	`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	Higress extension	`sentinel rate limited`	Corpo da resposta quando o controle de concorrência é acionado.
`higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url`	Ingress	Higress extension	—	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 deles.

Protocolo de backend

Annotation	Scope	Status	Padrão	Descrição
`nginx.ingress.kubernetes.io/backend-protocol`	Service	Partially compatible	`HTTP`	Protocolo usado pelo service de backend. AJP e FCGI não são suportados. Valores válidos: `HTTP`, `HTTP2`, `HTTPS`, `gRPC`, `gRPCS`.

Balanceamento de carga

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

Warmup (inicialização gradual)

Annotation	Scope	Status	Padrão	Descrição
`higress.ingress.kubernetes.io/warmup`	Service	Higress extension	Disabled	Duração do período de warmup, em segundos.

Importante

O warmup requer o algoritmo de balanceamento de carga round_robin ou least_conn. Não é compatível com outros algoritmos.

Afinidade por cookie

Annotation	Scope	Status	Padrão	Descrição
`nginx.ingress.kubernetes.io/affinity`	Service	Compatible	`cookie`	Tipo de afinidade. Valor padrão e único válido: `cookie`.
`nginx.ingress.kubernetes.io/affinity-mode`	Service	Partially compatible	`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	Compatible	—	Nome do cookie usado como chave de hash.
`nginx.ingress.kubernetes.io/session-cookie-path`	Service	Compatible	`/`	Caminho do cookie gerado quando o cookie especificado não existe.
`nginx.ingress.kubernetes.io/session-cookie-max-age`	Service	Compatible	Session level	Tempo de expiração do cookie gerado, em segundos.
`nginx.ingress.kubernetes.io/session-cookie-expires`	Service	Compatible	Session level	Tempo de expiração do cookie gerado, em segundos.

Controle de acesso por endereço IP

Annotation	Scope	Status	Descrição
`nginx.ingress.kubernetes.io/whitelist-source-range`	Ingress	Compatible	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	Compatible (V1.2.31+)	Lista de bloqueios de endereços IP e blocos CIDR no nível de rota. Separados por vírgula. Tem precedência sobre `higress.ingress.kubernetes.io/blacklist-source-range`.
`higress.ingress.kubernetes.io/blacklist-source-range`	Ingress	Higress extension	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	Higress extension	Lista de permissões de endereços IP e blocos CIDR no nível de domínio. Separados por vírgula. Listas de permissões no nível de rota têm precedência.
`higress.ingress.kubernetes.io/domain-blacklist-source-range`	Ingress	Higress extension	Lista de bloqueios de endereços IP e blocos CIDR no nível de domínio. Separados por vírgula. Listas de bloqueios no nível de rota têm precedência.

Pool de conexões (gateway para backend)

Annotation	Scope	Status	Descrição
`higress.ingress.kubernetes.io/connection-policy-tcp-max-connection`	Service	Higress extension	Número máximo total de conexões TCP com o service de backend.
`higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint`	Service	Higress extension	Número máximo de conexões TCP por endpoint de backend.
`higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection`	Service	Higress extension	Número máximo de requisições HTTP por conexão de backend.

Anotações de segurança

TLS do cliente ao gateway

Annotation	Scope	Status	Default	Description
`higress.ingress.kubernetes.io/tls-min-protocol-version`	Domain name	Higress extension	`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`	Domain name	Higress extension	`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`	Domain name	Compatible	Veja abaixo	Conjuntos de cifras TLS, separados por vírgula. Aplica-se apenas ao TLS v1.0–v1.2 (não ao v1.3).
`higress.ingress.kubernetes.io/auth-tls-secret`	Domain name	Partially compatible	—	Certificado CA para verificação de cliente mTLS. Formato do nome do Secret: `{domain-certificate-secret-name}-cacert`.

Conjuntos de cifras 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 do gateway ao backend

Annotation	Scope	Status	Description
`nginx.ingress.kubernetes.io/proxy-ssl-secret`	Service	Compatible	Certificado de cliente utilizado pelo gateway para autenticação no backend.
`nginx.ingress.kubernetes.io/proxy-ssl-name`	Service	Compatible	Server Name Indication (SNI) enviado durante o handshake TLS com o backend.
`nginx.ingress.kubernetes.io/proxy-ssl-server-name`	Service	Compatible	Ativa ou desativa o SNI durante o handshake TLS com o backend.

Autenticação básica

Annotation	Scope	Status	Description
`nginx.ingress.kubernetes.io/auth-type`	Ingress	Partially compatible	Tipo de autenticação. Apenas `basic` é compatível.
`nginx.ingress.kubernetes.io/auth-secret`	Ingress	Compatible	Secret contendo as credenciais da rota. Formato: `<namespace>/<name>`.
`nginx.ingress.kubernetes.io/auth-secret-type`	Ingress	Compatible	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 e o valor é a senha.
`nginx.ingress.kubernetes.io/auth-realm`	Ingress	Compatible	Realm de autenticação. As credenciais são compartilhadas dentro de um mesmo realm.

Referência completa de annotations do NGINX Ingress: Annotations.