Basic rate limiting

Rate limiting in Emissary is composed of two parts:

• RateLimitService that tells Emissary what service to use for rate limiting. (Emissary provides a RateLimitService 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:

1. On an individual Mapping. Labels set here will only apply to requests that use that Mapping.

   ---
   apiVersion: getambassador.io/v2
   kind: Mapping
   metadata:
     name: foo-app
   spec:
     prefix: /foo/
     service: foo
     labels:
       "my_first_label_domain":
       - "my_first_label_group":
         - "my_label_specifier_1"
         - "my_label_specifier_2"
       - "my_second_label_group":
         - "my_label_specifier_3"
         - "my_label_specifier_4"
       "my_second_label_domain":
       - ...
   

2. Globally, in the ambassador Module. Labels set here are applied to every single request that goes through Emissary. 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.

   ---
   apiVersion: getambassador.io/v2
   kind: Module
   metadata:
     name: ambassador
   spec:
     config:
       default_labels:
         "my_first_label_domain":
           defaults:
           - "my_label_specifier_a"
           - "my_label_specifier_b"
         "my_second_label_domain":
           defaults:
           - "my_label_specifier_c"
           - "my_label_specifier_d"
   

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 Emissary what labels to set on the request.

Note: The terminology used by the Envoy documentation differs from the terminology used by Emissary:

Emissary	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 Emissary, all Emissary cares about are the contents of the groupings of label specifiers.

There are 5 types of label specifiers in Emissary:

1. The Envoy source cluster name is the name of the Envoy listener cluster that the request name in on.
2. 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.
3. 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.
4. The IP address of the HTTP client could be the actual IP of the client talking directly to Emissary, or it could be the IP address from X-Forwarded-For if Emissary is configured to trust the X-Fowarded-For header.
5. 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.

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 for an example RateLimitService implementation for Emissary.