# zalando/skipper architecture

> Architecture diagram of the GitHub repository zalando/skipper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zalando/skipper
- Repository: https://github.com/zalando/skipper

## Overview

##### Project Type & Purpose
- Skipper is essentially a network-level proxy and router. It accepts incoming HTTP requests, applies route matching and filter modifications (such as header rewriting, query changes, and authentication), and then forwards the modified request to a backend service.
- It is designed for high-scale environments (handling hundreds of thousands of routes) and can be run as a stand-alone reverse proxy or used as a Kubernetes Ingress controller.
- The project is highly modular and extensible through custom filters, predicates, and data clients.

##### Main Architectural Components
a. Route Data Client Layer:
– This component is responsible for retrieving route definitions from various sources.
– Sub-modules include data clients for:
▪ etcd, Kubernetes Ingress, eskip files, route strings (see the “dataclients” directory).
▪ Custom configuration sources that may be integrated to update routes dynamically.
– The “eskip” language parser plays a central role in converting configuration into route rules.

b. Routing & Rule Engine:
– Once routes are acquired via data clients, this engine uses matching criteria (path, method, headers, host, cookies, etc.) to select the proper rule for each incoming request.
– It evaluates predicates (from the “predicates” directory) and then builds the filter chain.
– This component essentially composes the “lookup” logic, determining which set of filters will modify the request.

c. Filter & Predicate Layers:
– Skipper supports a large variety of filters that modify requests and responses (e.g., authentication, header modifications, circuit-breaking, rate limiting, etc.).
– The filters are organized by function (as seen in the “filters” directory) and include specialized modules (e.g., for JWT, authentication, traffic control, resizing, etc.).
– Predicate modules determine if a particular route should be matched. They check conditions like intervals, hostnames, and query parameters.
– Together, these layers form the decision-making and transformation pipeline before reaching the backend.

d. Core Proxy & Load Balancer:
– The proxy (referenced in the “proxy” directory) is the heart of the forwarder. It takes the filtered, processed requests from the routing engine and streams them to backend services.
– Load balancing is handled via a dedicated “loadbalancer” module that uses various algorithms to distribute traffic.
– Other lower-level modules (like “net” and “io”) assist with connection management, HTTP client handling, and efficient streaming.

e. Control and Management Components:
– Main executables are built in the “cmd” directory (notably cmd/skipper, cmd/routesrv, cmd/webhook). They include:
▪ Skipper’s main binary (which starts the HTTP router).
▪ A routesrv tool that helps reduce API server overload (leveraging Etag headers).
▪ A webhook for Kubernetes admission, ensuring manifest correctness.
– There is also support for circuit breakers (in the “circuit” directory) which provide fault tolerance.

f. Auxiliary Modules:
– Logging (“logging”), metrics (“metrics”), and tracing (“tracing”) components capture operational data, provide debug output, and enable performance monitoring.
– Packaging, documentation (“docs”), fuzz testing (“fuzz”), and plugin support (“plugins”, “eskipfile”) support deployment and external integration.

##### Relationships & Data Flow
- The request is initially processed by the Routing & Rule Engine which, based on request properties, selects a matching route.
- The engine uses the defined predicates to confirm if a route is valid and, once selected, builds a filter chain.
- Filters then modify the request (or response) – for example, by setting headers, performing authentication, applying rate limiting, or even “teeing” a copy to a shadow service.
- The processed request is then handled by the core Proxy, which uses the load balancer to direct traffic to a backend service.
- Throughout the flow, logging, metrics, and tracing components capture operational information that is fed back into monitoring systems.
- In parallel, dynamic route updates arrive from the Data Client Layer (by reading configuration files, contacting etcd, Kubernetes API, etc.), causing the routing engine to update its internal rule set without downtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Incoming Request
    HTTPReq["HTTP Request"]:::engine

    %% Data Client Layer
    subgraph "Data Client Layer"
        DC["Data Clients"]:::dataclients
    end

    %% Routing Engine Layer
    subgraph "Routing & Rule Engine Layer"
        ES["Eskip Parser"]:::engine
        RE["Routing Engine"]:::engine
        PE["Predicate Evaluation"]:::engine
        FC["Filter Chain"]:::engine
    end

    %% Core Proxy Layer
    subgraph "Core Proxy Layer"
        CP["Core Proxy"]:::proxy
        LB["Load Balancer"]:::proxy
    end

    %% Backend Services
    BE["Backend Services"]:::proxy

    %% Management and Observability Layer
    subgraph "Management & Observability"
        ME["Main Executable"]:::management
        CB["Circuit Breakers"]:::management
        LG["Logging"]:::observability
        MT["Metrics"]:::observability
        TR["Tracing"]:::observability
        PK["Packaging"]:::observability
    end

    %% Data Flow Arrows
    HTTPReq --> DC
    DC -->|"update_routes"| RE
    DC --> ES
    ES --> RE
    RE --> PE
    PE --> FC
    FC --> CP
    CP --> LB
    LB --> BE

    %% Observability and Management interactions
    RE -->|monitors| LG
    RE -->|monitors| MT
    RE -->|monitors| TR
    CP -->|monitors| LG
    CP -->|monitors| MT
    CP -->|monitors| TR

    RE --> ME
    CP --> ME
    ME --> CB
    FC --> PK

    %% Styles
    classDef dataclients fill:#a1d99b,stroke:#000,stroke-width:2px;
    classDef engine fill:#9ecae1,stroke:#000,stroke-width:2px;
    classDef proxy fill:#fdae6b,stroke:#000,stroke-width:2px;
    classDef management fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef observability fill:#d6616b,stroke:#000,stroke-width:2px;

    %% Click Events
    click DC "https://github.com/zalando/skipper/tree/master/dataclients/"
    click RE "https://github.com/zalando/skipper/tree/master/routing/"
    click PE "https://github.com/zalando/skipper/tree/master/predicates/"
    click FC "https://github.com/zalando/skipper/tree/master/filters/"
    click ES "https://github.com/zalando/skipper/tree/master/eskip/"
    click CP "https://github.com/zalando/skipper/tree/master/proxy/"
    click LB "https://github.com/zalando/skipper/tree/master/loadbalancer/"
    click ME "https://github.com/zalando/skipper/tree/master/cmd/"
    click CB "https://github.com/zalando/skipper/tree/master/circuit/"
    click LG "https://github.com/zalando/skipper/tree/master/logging/"
    click MT "https://github.com/zalando/skipper/tree/master/metrics/"
    click TR "https://github.com/zalando/skipper/tree/master/tracing/"
    click PK "https://github.com/zalando/skipper/tree/master/packaging/"
```
