DPTCloud
Back to articles
Technology Insight

Building a Distributed API Gateway with Caddy Server and Dynamic Redis Rate Limiting

June 1, 2026

Introduction to Modern API Gateways

In contemporary microservices architectures, the API Gateway serves as the critical entry point for all incoming client requests. It is responsible for routing traffic, ensuring security, and maintaining system stability. As organizations scale, traditional centralized gateways often become performance bottlenecks or single points of failure. This has driven the adoption of distributed API Gateways that can scale horizontally while maintaining a unified operational state.

While tools like Nginx, Kong, and Envoy are popular choices, Caddy Server has emerged as a formidable alternative. Written in Go, Caddy is a enterprise-ready, memory-safe web server known for its automatic TLS management, intuitive configuration, and extensible plugin ecosystem. By combining Caddy's lightweight architecture with Redis—a high-performance, in-memory data structure store—architects can build a resilient, distributed API Gateway capable of enforcing dynamic rate limiting across an entire cluster.

The Architecture: Distributed Caddy with Shared Redis Backend

Enforcing rate limits in a distributed environment presents a unique challenge. If each API Gateway instance tracks request counts independently in its local memory, traffic distribution imbalances can lead to inconsistent rate limiting. A client might hit their limit on Node A but continue to spam Node B.

To solve this, we decouple the rate-limiting state from the gateway nodes and centralize it within a shared Redis cluster. The architectural workflow operates as follows:

  • Client Request: A client sends an HTTP request to the global load balancer, which routes it to one of the distributed Caddy Server instances.
  • Rate Limit Evaluation: Caddy intercepts the request and extracts a unique identifier (such as an API key, JWT claim, or client IP address).
  • Redis Handshake: Caddy queries the shared Redis backend using an atomic sliding-window or token-bucket algorithm to check the current request counter against the allowed threshold.
  • Upstream Routing or Throttling: If the limit is not exceeded, Redis updates the counter, and Caddy proxies the request to the appropriate upstream microservice. If the limit is exceeded, Caddy immediately rejects the request with an HTTP 429 Too Many Requests status, bypassing the backend entirely to save computing resources.

Step-by-Step Configuration Guide

Implementing this architecture requires compiling Caddy with the necessary third-party modules and writing a production-ready Caddyfile. Because dynamic Redis-based rate limiting is not built into the Caddy core, we utilize trusted community plugins, such as caddy-ratelimit or custom Redis-integrated middleware.

1. Compiling Caddy with Custom Modules

To include Redis rate-limiting capabilities, compile Caddy using xcaddy, the official command-line tool for building Caddy with plugins. Execute the following command in your terminal:

xcaddy build --with [github.com/mholt/caddy-ratelimit](https://github.com/mholt/caddy-ratelimit)

Note: Ensure you verify the specific plugin documentation for exact import paths regarding Redis cluster support.

2. Writing the Production Caddyfile

Below is a comprehensive configuration example defining a distributed API Gateway with a centralized Redis backend. This setup dynamically extracts the client's IP address and evaluates it against a defined threshold.

{
    # Global configurations
    admin 0.0.0.0:2019
    
    # Configuring the distributed storage backend for TLS/State if needed
    storage redis {
        host "redis-cluster.internal.net"
        port 6379
        db 0
    }
}

# API Gateway Virtual Host
api.company.com {
    # Enable compression for optimal performance
    encode gzip zstd

    # Define the rate-limiting block with Redis integration
    @throttled {
        expression {header.Authorization} != ""
    }

    # Apply rate limiting using a shared Redis cluster
    rate_limit {
        zone api_tenant_zone {
            key {remote_host}
            events_per_period 100
            period 1m
            backend redis {
                address "redis-cluster.internal.net:6379"
                password "your_secure_password"
                key_prefix "caddy_rate_limit:"
            }
        }
    }

    # Reverse proxy routing to upstream microservices
    handle_path /v1/users* {
        reverse_proxy user-service.internal.net:8081 {
            lb_policy round_robin
            health_uri /health
            health_interval 10s
        }
    }

    handle_path /v1/orders* {
        reverse_proxy order-service.internal.net:8082 {
            lb_policy round_robin
            health_uri /health
            health_interval 10s
        }
    }

    # Fallback response for unhandled paths
    handle {
        respond "Resource Not Found" 404
    }
}

Advanced Optimization: Dynamic Limits and Security

In enterprise scenarios, a static rate limit for all users is rarely sufficient. Modern API Gateways must support dynamic rate limiting based on user tiers (e.g., Free, Premium, Enterprise). To achieve this with Caddy and Redis, consider the following advanced strategies:

JWT Claims and Dynamic Header Extraction

Instead of limiting solely by IP address—which can be unreliable due to NAT firewalls and shared corporate networks—configure Caddy to extract the sub (subject) or tier claim from an incoming JSON Web Token (JWT). Caddy can then pass this identifier as the Redis rate-limiting key, ensuring precise tracking per authenticated user account.

Handling Redis Downtime

What happens if the Redis cluster becomes unavailable? A resilient API Gateway must not completely crash if its rate-limiting backend drops. You should configure the rate-limit plugin to fail-open or fail-closed depending on your security posture. For most business operations, a fail-open strategy combined with real-time alerting via Prometheus/Grafana is preferred, ensuring business continuity while DevOps engineers remediate the Redis cluster.

Security Best Practice: Always deploy your Redis cluster within an isolated, private virtual network (VPC). Ensure communication between Caddy Server and Redis is encrypted using TLS (Redis TLS) to prevent malicious actors from intercepting internal system tokens or altering rate-limiting metrics.

Conclusion and Key Takeaways

Leveraging Caddy Server as a distributed API Gateway with a shared Redis infrastructure provides a modern, highly performant solution to API traffic management. It removes the operational complexity often associated with bulkier enterprise gateways while offering robust scalability. By centralizing the rate-limiting state in Redis, you guarantee uniform policy enforcement across all gateway nodes, protecting your backend microservices from intentional abuse and accidental traffic spikes alike.

As you plan your deployment, focus on fine-tuning your Redis eviction policies (such as volatile-lru) and setting appropriate key expirations to keep memory utilization optimized. With Caddy's active development cycle and growing enterprise adoption, this architecture stands as a future-proof foundation for high-scale application delivery.

Building a Distributed API Gateway with Caddy Server and Dynamic Redis Rate Limiting | DPTCloud