<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• Overview
• Docker Image
  • Distroless Base Image
    • Benefits of Distroless:
    • Debugging with Distroless:
• Supported Envoy APIs
  • API Deprecation History
• Building and Testing
  • Docker-compose setup
  • Full test environment - Configure rate limits through files
  • Full test environment - Configure rate limits through an xDS Management Server
  • Self-contained end-to-end integration test
• Configuration
  • The configuration format
    • Definitions
    • Descriptor list definition
    • Rate limit definition
    • Replaces
    • ShadowMode
    • Including detailed metrics for unspecified values
    • Including descriptor values in metrics
    • Sharing thresholds for wildcard matches
    • Examples
      • Example 1
      • Example 2
      • Example 3
      • Example 4
      • Example 5
      • Example 6
      • Example 7
      • Example 8
      • Example 9
      • Example 10
      • Example 11
  • Loading Configuration
    • File Based Configuration Loading
    • xDS Management Server Based Configuration Loading
  • Log Format
  • GRPC Keepalive
  • Health-check
    • Health-check configurations
  • GRPC server
• Request Fields
• GRPC Client
  • Commandline flags
• Global ShadowMode
  • Configuration
  • Statistics
• Statistics
  • Statistics options
  • DogStatsD
    • Example
    • Continued example:
  • Prometheus
• HTTP Port
  • /json endpoint
• Debug Port
• Local Cache
• Redis
  • Redis type
  • Connection Pool Settings
    • Pool Size
    • Connection Timeout
    • Pool On-Empty Behavior
    • Pipelining
  • One Redis Instance
  • Two Redis Instances
  • Health Checking for Redis Active Connection
• Memcache
• Custom headers
• Tracing
• TLS
• mTLS
• Contact

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Overview

The rate limit service is a Go/gRPC service designed to enable generic rate limit scenarios from different types of applications. Applications request a rate limit decision based on a domain and a set of descriptors. The service reads the configuration from disk via runtime, composes a cache key, and talks to the Redis cache. A decision is then returned to the caller.

Docker Image

For every main commit, an image is pushed to Dockerhub. There is currently no versioning (post v1.4.0) and tags are based on commit sha.

Distroless Base Image

The Docker image uses Google's distroless base image (gcr.io/distroless/static-debian12:nonroot) for enhanced security and minimal attack surface. Distroless images contain only the application and its runtime dependencies, omitting unnecessary OS components like package managers, shells, and other utilities.

The image is pinned to a specific SHA digest for deterministic builds and uses the nonroot variant to run as a non-privileged user, following security best practices.

Benefits of Distroless:

• Enhanced Security: Minimal attack surface with no unnecessary components
• Smaller Image Size: Significantly smaller than traditional base images
• Reduced Vulnerabilities: Fewer components means fewer potential security issues
• Better Compliance: Meets security requirements for minimal base images
• Non-root Execution: Runs as a non-privileged user (UID 65532) for enhanced security
• Deterministic Builds: Pinned to specific SHA digest ensures reproducible builds

Debugging with Distroless:

For debugging purposes, you can use the debug variant of the distroless image:

FROM gcr.io/distroless/static-debian12:debug
COPY --from=build /go/bin/ratelimit /bin/ratelimit

This provides shell access and debugging tools while maintaining the security benefits of distroless.

Supported Envoy APIs

v3 rls.proto is currently supported. Support for v2 rls proto is now deprecated.

API Deprecation History

1. v1.0.0 tagged on commit 0ded92a2af8261d43096eba4132e45b99a3b8b14. Ratelimit has been in production use at Lyft for over 2 years.
2. v1.1.0 introduces the data-plane-api proto and initiates the deprecation of the legacy ratelimit.proto.
3. e91321b commit deleted support for the legacy ratelimit.proto. The current version of ratelimit protocol is changed to v3 rls.proto while v2 rls.proto is still supported as a legacy protocol.
4. 4bb32826 deleted support for legacy v2 rls.proto

Building and Testing

• Install Redis-server.

• Make sure go is setup correctly and checkout rate limit service into your go path. More information about installing go here.

• In order to run the integration tests using a local Redis server please run two Redis-server instances: one on port 6379 and another on port 6380

  redis-server --port 6379 &
  redis-server --port 6380 &
  

• To setup for the first time (only done once):

  make bootstrap
  

• To compile:

  make compile
  

  Ensure you set the correct platform if running OSX host with a linux container e.g.

  GOOS=linux make compile
  

• To compile and run tests:

  make tests
  

• To run the server locally using some sensible default settings you can do this (this will setup the server to read the configuration files from the path you specify):

  USE_STATSD=false LOG_LEVEL=debug REDIS_SOCKET_TYPE=tcp REDIS_URL=localhost:6379 RUNTIME_ROOT=/home/user/src/runtime/data RUNTIME_SUBDIRECTORY=ratelimit RUNTIME_APPDIRECTORY=config
  

Docker-compose setup

The docker-compose setup uses a distroless-based container for the ratelimit service. In order to run the docker-compose setup from the root of the repo, run

docker-compose up

The ratelimit service is built using the main Dockerfile which uses Google's distroless base image for enhanced security and minimal attack surface. The distroless image contains only the application and its runtime dependencies, omitting unnecessary OS components like package managers and shells.

If you want to run with two redis instances, you will need to modify the docker-compose.yml file to run a second redis container, and change the environment variables as explained in the two redis instances section.

Full test environment - Configure rate limits through files

To run a fully configured environment to demo Envoy based rate limiting, run:

export CONFIG_TYPE=FILE
docker-compose -f docker-compose-example.yml up --build --remove-orphans

This will run ratelimit, redis, prom-statsd-exporter and two Envoy containers such that you can demo rate limiting by hitting the below endpoints.

curl localhost:8888/test
curl localhost:8888/header -H "foo: foo" # Header based
curl localhost:8888/twoheader -H "foo: foo" -H "bar: bar" # Two headers
curl localhost:8888/twoheader -H "foo: foo" -H "baz: baz"  # This will be rate limited
curl localhost:8888/twoheader -H "foo: foo" -H "bar: banned" # Ban a particular header value
curl localhost:8888/twoheader -H "foo: