Core Concepts
Understanding Zentinel’s architecture and design principles.
Overview
Zentinel is a high-performance reverse proxy built on Cloudflare’s Pingora framework. It provides a flexible agent-based architecture for implementing security controls, traffic management, and custom request processing.
Key Concepts
| Concept | Description |
|---|---|
| Proxy | The core Zentinel process that handles incoming requests |
| Listener | A network endpoint (IP:port) that accepts connections |
| Route | Rules that match requests and direct them to upstreams |
| Upstream | A group of backend servers that handle requests |
| Agent | An external process that inspects/modifies requests |
Architecture Principles
- Performance First - Built on Pingora for minimal latency overhead
- Agent Isolation - Security logic runs in separate processes
- Fail-Safe Defaults - Configurable fail-open behavior for resilience
- Observable - Built-in metrics, logging, and tracing
In This Section
| Page | Description |
|---|---|
| Architecture | System design and component interaction |
| Components | Detailed breakdown of each component |
| Pingora Foundation | Understanding the Pingora framework |
| Request Flow | How requests traverse the proxy |
| Agent Pipeline | Agent chaining, execution strategies, and pipeline architecture |
| Routing | Request matching and forwarding rules |
| Comparison | How Zentinel compares to Envoy, HAProxy, and Nginx |
Recommended Reading Order
- Start with Architecture for the big picture
- Read Components to understand each part
- Review Request Flow to see how they work together
- Explore Agent Pipeline for agent chaining and execution strategies
- Dive into Routing for traffic management details
- See Comparison to understand trade-offs with alternatives