Rate limit service

Rate limiting is a powerful technique to improve the availability and resilience of your services. In Emissary-ingress, each request can have one or more labels. These labels are exposed to a third-party service via a gRPC API. The third-party service can then rate limit requests based on the request labels.

Note that RateLimitService is only applicable to Emissary-ingress, and not Ambassador Edge Stack, as Ambassador Edge Stack includes a built-in rate limit service.

Request labels

See Attaching labels to requests for how to configure the labels that are attached to a request.

Domains

In Emissary-ingress, each engineer (or team) can be assigned its own domain. A domain is a separate namespace for labels. By creating individual domains, each team can assign their own labels to a given request, and independently set the rate limits based on their own labels.

See Attaching labels to requests for how to labels under different domains.

External rate limit service

In order for Emissary-ingress to rate limit, you need to implement a gRPC RateLimitService, as defined in Envoy's v3/rls.proto interface. If you do not have the time or resources to implement your own rate limit service, Ambassador Edge Stack integrates a high-performance rate limiting service.

Emissary-ingress generates a gRPC request to the external rate limit service and provides a list of labels on which the rate limit service can base its decision to accept or reject the request:

If Emissary-ingress cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration.

It is the external rate limit service's responsibility to determine whether rate limiting should take place, depending on custom business logic. The rate limit service must simply respond to the request with an OK or OVER_LIMIT code:

If Envoy receives an OK response from the rate limit service, then Emissary-ingress allows the client request to resume being processed by the normal flow.
If Envoy receives an OVER_LIMIT response, then Emissary-ingress will return an HTTP 429 response to the client and will end the transaction flow, preventing the request from reaching the backing service.

The headers injected by the AuthService can also be passed to the rate limit service since the AuthService is invoked before the RateLimitService.

Configuring the rate limit service

A RateLimitService manifest configures Emissary-ingress to use an external service to check and enforce rate limits for incoming requests:

service gives the URL of the rate limit service. If using a Kubernetes service, this should be the namespace-qualified DNS name of that service.
protocol_version Allowed values are v3 and v2(default). protocol_version was used in previous versions of Emissary-ingress to control the protocol used by the gRPC service to communicate with the RateLimitService. Emissary-ingress 3.x is running an updated version of Envoy that has dropped support for the v2 protocol, so starting in 3.x, if protocol_version is not specified, the default value of v2 will cause an error to be posted and a static response will be returned. Therefore, you must set it to protocol_version: v3. If upgrading from a previous version, you will want to set it to v3 and ensure it is working before upgrading to Emissary-ingress 3.Y. The default value for protocol_version remains v2 in the getambassador.io/v3alpha1 CRD specifications to avoid making breaking changes outside of a CRD version change. Future versions of CRD's will deprecate it.
failure_mode_deny By default, Envoy will fail open when unable to communicate with the service due to it becoming unvailable or due to timeouts. When this happens the upstream service that is being protected by a rate limit may be overloaded due to this behavior. When set to true Envoy will be configured to return a 500 status code when it is unable to communicate with the RateLimit service and will fail closed by rejecting request to the upstream service.
grpc contains settings for grpc connections
- use_resource_exhausted_code By default, Emissary-ingress will return an UNAVAILABLE gRPC code when a request is rate limited. When set to true, this field will cause Emissary-ingress will return a RESOURCE_EXHAUSTED gRPC code instead.

You may only use a single RateLimitService manifest.