DocsEdge Stack1.14Basic rate limiting
Basic rate limiting
Rate limiting in Ambassador Edge Stack is composed of two parts:
RateLimitService
that tells Ambassador Edge Stack what service to use for rate limiting. (The Ambassador Edge Stack provides aRateLimitService
implementation for you).- 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.
Attaching labels to requests
There are two ways of setting labels on a request:
On an individual Mapping. Labels set here will only apply to requests that use that Mapping.
Globally, in the
ambassador
Module. Labels set here are applied to every single request that goes through Ambassador Edge Stack. This includes requests go through a Mapping that sets more labels; for those requests, the global labels are prepended to each of the Mapping's label groups for the matching domain; otherwise the global labels are put in to a new label group named "default" for that domain.
Labels on a request are lists of key/value pairs, organized in to label groups. Because a label group is a list of key/value pairs (rather than a map),
- it is possible to have multiple labels with the same key
- the order of labels matters
Your Module
and Mappings
contain label specifiers that tell
Ambassador Edge Stack what labels to set on the request.
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:
# | Label Specifier | Action, in human terms | Action, in Envoy gRPC terms |
---|---|---|---|
1 | "source_cluster" | Sets the label "source_cluster =«Envoy source cluster name»" | { "source_cluster": {} } |
2 | "destination_cluster" | Sets the label "destination_cluster =«Envoy destination cluster name»" | { "destination_cluster": {} } |
3 | { "my_key": { "header": "my_hdr" } } | If the my_hdr header is set, then set the label "«my_key »=«Value of the my_hdr header»"; otherwise skip applying this label group | { "request_headers": { "header_name": "my_hdr", descriptor_key: "my_key" } } |
4 | "remote_address" | Sets the label "remote_address =«IP address of the client»" | { "remote_address": {} } |
5 | { "generic_key": "my_val" } | Sets the label "generic_key =«my_val »" | { "generic_key": { "descriptor_value": "my_val" } } |
5 (shorthand) | "my_val" | Shorthand for { "generic_key": "my_val" } |
- The Envoy source cluster name is the name of the Envoy listener cluster that the request name in on.
- The Envoy destination cluster is the name of the Envoy cluster that the Mapping routes the request to. Typically, there is a 1:1 correspondence between upstream services (pointed to by Mappings) and clusters. You can get the name for a cluster from the diagnostics service or Edge Policy Console.
- When setting a label from an HTTP request header, be aware that if that header is not set in the request, then the entire label group is skipped.
- The IP address of the HTTP client could be the actual IP of the
client talking directly to $productName, or it could be the IP
address from
X-Forwarded-For
if $productName is configured to trust theX-Fowarded-For
header. generic_key
allows you to apply a simple string label to requests flowing through that Mapping.
Rate limiting requests based on their labels
This is determined by your RateLimitService
implementation.
The Ambassador Edge Stack provides a RateLimitService
implementation that is
configured by a RateLimit
custom resource.
See the AES RateLimit Reference for information on how
to configure RateLimit
s in Ambassador Edge Stack.
See the Basic Rate Limiting with Emissary-ingress for an
example RateLimitService
implementation for Emissary-ingress.