Descrição dos campos do RateLimitingPolicy - Alibaba Cloud Service Mesh: Central de Documentação do Alibaba Cloud

Funcionamento

O RateLimitingPolicy usa um token bucket para controlar as taxas de requisição:

O bucket armazena uma quantidade fixa de tokens, definida por bucket_capacity.
Os tokens são adicionados a uma taxa constante: fill_amount tokens a cada interval.
Cada requisição recebida consome um token. Se o bucket estiver vazio, as requisições serão rejeitadas com o código HTTP 429.
Definir bucket_capacity igual a fill_amount impede picos de tráfego. Configurar bucket_capacity com valor superior a fill_amount permite breves rajadas acima da taxa de estado estacionário.

Para aplicar limites de taxa separados por cliente ou usuário, agrupe as requisições por um rótulo (como um cabeçalho de ID de usuário). Assim, cada grupo obtém seu próprio token bucket independente.

Estrutura da CRD

apiVersion: istio.alibabacloud.com/v1
kind: RateLimitingPolicy
metadata:
  name: ...
  namespace: ...
spec:
  rate_limiter:                        # RateLimiter (required)
    fill_amount: ...                   # double  - tokens added per interval
    bucket_capacity: ...               # double  - max tokens in bucket
    parameters:                        # RateLimiterParameters (required)
      interval: ...                    # Duration - refill interval
      limit_by_label_key: ...          # string  - group requests by label
      continuous_fill: ...             # bool    - smooth refill (default: true)
      delay_initial_fill: ...          # bool    - delay first fill (default: false)
      max_idle_time: ...               # Duration - idle bucket TTL (default: 7200s)
      lazy_sync:                       # RateLimiterParametersLazySync
        enabled: ...                   # bool    - enable lazy sync (default: false)
        num_sync: ...                  # int     - syncs per interval (default: 4)
    request_parameters:                # RateLimiterRequestParameters
      denied_response_status_code: ... # int     - override HTTP 429
      tokens_label_key: ...            # string  - override token cost per request
    selectors:                         # []Selector (required)
    - agent_group: ...
      control_point: ...
      service: ...

Exemplos

Limitação de taxa básica

A configuração abaixo limita a taxa do serviço httpbin a 2 requisições a cada 30 segundos. Como bucket_capacity é igual a fill_amount, não há permissão para picos de tráfego. O agrupamento das requisições ocorre pelo cabeçalho user_id, garantindo que cada user_id único tenha seu próprio token bucket.

apiVersion: istio.alibabacloud.com/v1
kind: RateLimitingPolicy
metadata:
  name: ratelimit
  namespace: istio-system
spec:
  rate_limiter:
    bucket_capacity: 2                                    # Max 2 tokens in the bucket
    fill_amount: 2                                        # Add 2 tokens per interval
    parameters:
      interval: 30s                                       # Refill every 30 seconds
      limit_by_label_key: http.request.header.user_id     # One bucket per user_id header
    selectors:
    - agent_group: default
      control_point: ingress
      service: httpbin.default.svc.cluster.local

Limitação de taxa por usuário com margem para picos

Esta configuração permite 100 requisições por minuto, com capacidade de pico de 150. A sincronização lazy está ativada para reduzir a latência, embora isso resulte em uma aplicação ligeiramente menos precisa das regras.

apiVersion: istio.alibabacloud.com/v1
kind: RateLimitingPolicy
metadata:
  name: per-user-ratelimit
  namespace: istio-system
spec:
  rate_limiter:
    bucket_capacity: 150                                  # Allow bursts up to 150 requests
    fill_amount: 100                                      # Steady-state: 100 requests per minute
    parameters:
      interval: 60s
      limit_by_label_key: http.request.header.user_id
      continuous_fill: true                               # Smooth token distribution
      lazy_sync:
        enabled: true                                     # Local decisions, periodic sync
        num_sync: 4                                       # Sync 4 times per interval
    request_parameters:
      denied_response_status_code: 503                    # Return 503 instead of 429
    selectors:
    - agent_group: default
      control_point: ingress
      service: my-api.production.svc.cluster.local

Referência de campos

RateLimitingPolicySpec

Campo spec de nível superior de um recurso RateLimitingPolicy.

Campo	Tipo	Obrigatório	Descrição
`rate_limiter`	RateLimiter	Sim	Configuração do limitador de taxa.

RateLimiter

Define os parâmetros do token bucket, o tratamento de requisições e os seletores de destino.

Campo	Tipo	Obrigatório	Padrão	Descrição
`fill_amount`	double	Sim	--	Quantidade de tokens adicionados ao bucket em cada intervalo. Em conjunto com `interval`, define a taxa de requisição em estado estacionário.
`bucket_capacity`	double	Sim	--	Capacidade máxima de tokens do bucket. Defina como igual a `fill_amount` para evitar picos. Use valores maiores para permitir picos curtos de tráfego.
`parameters`	RateLimiterParameters	Sim	--	Parâmetros de execução do limitador de taxa.
`request_parameters`	RateLimiterRequestParameters	Não	--	Configuração personalizada para tratamento de requisições.
`selectors`	[]Selector	Sim	--	Serviços e tráfego aos quais a limitação de taxa se aplica.

RateLimiterParameters

Controla como o limitador preenche o token bucket e agrupa as requisições.

Campo	Tipo	Obrigatório	Padrão	Descrição
`interval`	Duration	Sim	--	Intervalo de recarga do token bucket. Exemplo: `30s` adiciona `fill_amount` tokens a cada 30 segundos.
`limit_by_label_key`	string	Não	--	Agrupa requisições por um rótulo de requisição. Cada valor de rótulo exclusivo recebe seu próprio token bucket. Consulte Rótulos de requisição para ver as chaves de rótulo disponíveis.
`continuous_fill`	bool	Não	`true`	Quando definido como `true`, os tokens são adicionados gradualmente ao longo do intervalo, em vez de todos de uma vez ao final dele.
`delay_initial_fill`	bool	Não	`false`	Se for `false`, o bucket inicia com capacidade total na primeira requisição. Isso pode permitir mais requisições do que a taxa configurada durante o primeiro intervalo.
`lazy_sync`	RateLimiterParametersLazySync	Não	--	Configuração de sincronização lazy. Veja Sincronização lazy: precisão vs. latência.
`max_idle_time`	Duration	Não	`7200s`	Tempo de retenção de um token bucket por rótulo após sua última requisição. Aplica-se apenas quando `limit_by_label_key` está definido.

RateLimiterRequestParameters

Substitui o comportamento padrão de tratamento de requisições.

Campo	Tipo	Obrigatório	Padrão	Descrição
`denied_response_status_code`	int	Não	`429`	Código de status HTTP retornado quando uma requisição atinge o limite de taxa.
`tokens_label_key`	string	Não	--	Rótulo de requisição cujo valor determina o número de tokens consumidos por requisição, substituindo o padrão de 1.

RateLimiterParametersLazySync

Gerencia a sincronização lazy entre o Envoy e o agente remoto. Consulte Sincronização lazy: precisão vs. latência para obter orientações sobre quando ativar este recurso.

Campo	Tipo	Obrigatório	Padrão	Descrição
`enabled`	bool	Não	`false`	Ativa a sincronização lazy.
`num_sync`	int	Não	`4`	Número de vezes que o Envoy sincroniza com o agente remoto dentro de cada `interval`.

Sincronização lazy: precisão vs. latência

Por padrão, o Envoy consulta o agente remoto a cada requisição para tomar uma decisão precisa sobre a limitação de taxa. A sincronização lazy altera esse comportamento: o Envoy decide localmente e sincroniza com o agente remoto periodicamente.

Modo	Comportamento	Precisão	Latência
Padrão (sincronização lazy desativada)	O Envoy verifica o agente remoto por requisição	Alta — aplicação exata da contagem de tokens	Maior — chamada remota em todas as requisições
Sincronização lazy ativada	O Envoy decide localmente e sincroniza `num_sync` vezes por `interval`	Menor — possibilidade de contagem excessiva ou insuficiente temporária entre sincronizações	Menor — a maioria das requisições ignora a chamada remota

Ative a sincronização lazy para APIs de alto throughput nas quais uma aplicação aproximada da taxa seja aceitável e a baixa latência tenha mais importância do que a contagem exata.

Rótulos de requisição

O conjunto de agendamento de tráfego do ASM atribui rótulos a cada requisição como pares chave-valor. Use esses rótulos com limit_by_label_key para agrupar requisições e aplicar limitação de taxa por grupo, ou com tokens_label_key para variar o custo de tokens por requisição.

Metadados de requisição HTTP

Cada requisição HTTP recebe automaticamente os seguintes metadados como rótulos:

Chave do rótulo	Valor	Exemplo
`http.method`	Método HTTP	`POST`
`http.flavor`	Versão do protocolo HTTP	`1.1`
`http.host`	Host da requisição	`httpbin.default.svc.cluster.local`
`http.target`	Caminho da requisição	`/get`
`http.request_content_length`	Tamanho do corpo da requisição em bytes	`431`
`http.request.header.<header_name>`	Valor do cabeçalho de requisição especificado	`http.request.header.user_agent`

Cabeçalho Baggage

O Baggage é um padrão OpenTelemetry para propagação de contexto em sistemas distribuídos. Caso uma requisição inclua um cabeçalho HTTP baggage, cada par chave-valor será convertido em um rótulo de requisição.

Exemplo de cabeçalho:

baggage: userId=alice,isProduction=false

Isso gera dois rótulos: userId: alice e isProduction: false. Para limitar a taxa por usuário com base no Baggage, defina limit_by_label_key como userId.