• 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
• Request Fields
  • Negative hits
• GRPC Client
  • Commandline flags
• Global ShadowMode
  • Configuration
  • Statistics
• Statistics
  • Service statistics
  • Redis 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
    • Request Deadlines
    • TCP Settings
    • Pool On-Empty Behavior
    • Pipelining
  • One Redis Instance
  • Two Redis Instances
  • Health Checking for Redis Active Connection
  • Recovering from a failover (READONLY errors)
  • Redis failover and unresponsive Redis
  • Credentials that expire or rotate
    • AWS ElastiCache IAM authentication
  • Calendar-aligned MONTH rate limits
  • Configurable WEEK rate limit reset day
• Memcache
• Custom headers
  • RequestHeadersToAdd
• Tracing
• TLS
• mTLS
• Contact

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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗