DocsEdge StackRate limit service
Rate limit service
Rate limiting is a powerful technique to improve the availability and resilience of your services. In Ambassador Edge Stack, 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 Ambassador Edge Stack, 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 Ambassador Edge Stack 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.
Ambassador Edge Stack 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 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.
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 Ambassador Edge Stack allows the client request to resume being processed by the normal flow. - If Envoy receives an
OVER_LIMIT
response, then Ambassador Edge Stack 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 Ambassador Edge Stack 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 arev3
andv2
(default).protocol_version
was used in previous versions of Ambassador Edge Stack to control the protocol used by the gRPC service to communicate with theRateLimitService
. Ambassador Edge Stack 3.x is running an updated version of Envoy that has dropped support for thev2
protocol, so starting in 3.x, ifprotocol_version
is not specified, the default value ofv2
will cause an error to be posted and a static response will be returned. Therefore, you must set it toprotocol_version: v3
. If upgrading from a previous version, you will want to set it tov3
and ensure it is working before upgrading to Emissary-ingress 3.Y. The default value forprotocol_version
remainsv2
in thegetambassador.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 totrue
Envoy will be configured to return a500
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 connectionsuse_resource_exhausted_code
By default, Ambassador Edge Stack will return anUNAVAILABLE
gRPC code when a request is rate limited. When set totrue
, this field will cause Ambassador Edge Stack will return aRESOURCE_EXHAUSTED
gRPC code instead.
You may only use a single RateLimitService
manifest.
Rate limit service and TLS
You can tell Ambassador Edge Stack to use TLS to talk to your service by
using a RateLimitService
with an https://
prefix. However, you may also
provide a tls
attribute: if tls
is present and true
, Ambassador Edge Stack will originate TLS even if the service
does not have the https://
prefix.
If tls
is present with a value that is not true
, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service.
Example
The Emissary-ingress Rate Limiting Tutorial has a simple rate limiting example.