Basic rate limiting

Rate limiting in Ambassador Edge Stack is composed of two parts:

• The [RateLimitService] resource tells Ambassador Edge Stack what external service to use for rate limiting.

  If Ambassador Edge Stack cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration.

• Labels that get attached to requests. A label is basic metadata that is used by the RateLimitService to decide which limits to apply to the request.

  These labels require Mapping resources with apiVersiongetambassador.io/v2 or newer — if you're updating an old installation, check theapiVersion!

Labels are grouped according to domain and group:

Attaching labels to requests

There are two ways of setting labels on a request:

1. You can set labels on an individual Mapping. These labels will only apply to requests that use that Mapping.

2. You can set global labels in the ambassador Module. These labels will apply to every request that goes through Ambassador Edge Stack.

   If a Mapping and the defaults both give label groups for the same domain, the default labels are prepended to each label group from the Mapping. If the Mapping does not give any labels for that domain, the global labels are placed into a new label group named "default" for that domain.

Each label group is a list of labels; each label is a key/value pair. Since the label group is a list rather than a map:

• it is possible to have multiple labels with the same key, and
• the order of labels matters.

Note: The terminology used by the Envoy documentation differs from the terminology used by Ambassador Edge Stack:

Ambassador Edge Stack	Envoy
label group	descriptor
label	descriptor entry
label specifier	rate limit action

The Mappings' listing of the groups of specifiers have names for the groups; the group names are useful for humans dealing with the YAML, but are ignored by Ambassador Edge Stack, all Ambassador Edge Stack cares about are the contents of the groupings of label specifiers.

There are 5 types of label specifiers in Ambassador Edge Stack:

1. source_cluster

   Sets the label source_cluster=«Envoy source cluster name»". The Envoy source cluster name is the name of the Envoy cluster that the request came in on.

   The syntax of this label currently requires source_cluster: {}.

2. destination_cluster

   Sets the label destination_cluster=«Envoy destination cluster name»". The Envoy destination cluster name is the name of the Envoy cluster to which the Mapping routes the request. You can get the name for a cluster from the diagnostics service.

   The syntax of this label currently requires destination_cluster: {}.

3. remote_address

   Sets the label remote_address=«IP address of the client»". The IP address of the client will be taken from the X-Forwarded-For header, to correctly manage situations with L7 proxies. This requires that Ambassador Edge Stack be correctly configured to communicate.

   The syntax of this label currently requires remote_address: {}.

4. request_headers

   If a header named header-name is present, set the label mykey=«value of the header». If no header named header-name is present, the entire label group is dropped.

5. generic_key

   Sets the label «mykey»=«myval». Note that supplying a key is supported only with the Envoy V3 API: if you are using Envoy V2, the key will always be the constant generic_key.

Rate limiting requests based on their labels

This is determined by your RateLimitService implementation.

Ambassador Edge Stack provides a RateLimitService implementation that is configured by a RateLimit custom resource.

See the Ambassador Edge Stack RateLimit Reference for information on how to configure RateLimits in Ambassador Edge Stack.

See the Basic Rate Limiting tutorial for an example RateLimitService implementation for Emissary-ingress.