Zalando Skipper Documentation

Pathmux is a package for effective tree lookup with wildcard matching. It is a fork of httptreemux that exposes the internal tree lookup interface and removes HTTP-specific wrappers.

Use pathmux instead of httptreemux if you need to:

• Store a large number of custom objects in a lookup tree keyed by path values.
• Use the backtracking feature to refine wildcard matching evaluation using custom logic (instructing the lookup to continue searching the tree if a matched object does not meet specific custom conditions).

Skipper is designed for high-throughput environments and scales linearly with the number of CPUs.

Performance Characteristics:

• Overhead: Can run with sub-millisecond overhead.
• Routing Efficiency: Uses a tree search algorithm to reduce the number of routes scanned for a match, followed by predicate matching to find the best route.
• Route Capacity: Capable of efficient routing for up to 500,000 routes (as a standalone proxy) and handles 15,000+ routes in Kubernetes Ingress controller configurations.
• Configuration Updates: Uses dataclients to feed rebuilt routing trees. The tree is rebuilt every 3 seconds, making Kubernetes Ingress configuration changes quasi-instant.

Skipper is distributed as both a library and a multi-binary project consisting of two main components:

• skipper: The HTTP proxy that handles request routing, filtering, and backend communication.
• eskip: A CLI application used to verify, print, update, or delete Skipper routes.

Internally, the skipper package connects to various dataclient sources (such as static files or Kubernetes ingress objects) to populate the proxy package's routing table.

Skipper is an HTTP proxy designed for high-performance routing. It consists of two main binaries:

• skipper: The HTTP proxy itself.
• eskip: A CLI application used to verify, print, update, or delete Skipper routes.

Internally, the skipper package uses dataclients to pull route information from sources like local files or Kubernetes ingress objects. The proxy package maintains a routing table that is replaced whenever routes change. Skipper supports Opentracing API (e.g., Jaeger) and exposes metrics in JSON and Prometheus formats.

Skipper acts as an Ingress Controller by serving HTTP requests into a Kubernetes cluster. It is designed for rapidly changing routing trees and provides advanced resiliency and deployment features such as ratelimiting, circuit breakers, blue-green deployments, and shadow traffic.

Deployment patterns:

• Cloud: Deploy Skipper behind a cloud load balancer (e.g., AWS ALB or NLB).
• Baremetal: Deploy Skipper behind a hardware/software load balancer, treating all Skipper instances as members of a single pool.

To manage DNS entries pointing to your load balancer, it is recommended to use tools like external-dns.

Filters modify requests (before backend) or responses (after backend) in a pipeline.

• Filter Chain: Request-phase filters run in definition order. Response-phase filters run in reverse order.
• Filter Context: A request-scoped state shared among filters. It provides access to the request, response, metrics, tracer, logger, state bag, path params, and loopback/serve controls.
• State Bag: A map[string]interface{} within the Filter Context used to share data between filters in the same request/response cycle.

Predicates are conditions used to decide which route handles an incoming request. A request matches a route only if all predicates within that route evaluate to true.

Example route with multiple predicates:

all: Host(/^my-host-header\.example\.org$/) && Method("GET") && Path("/hello") -> "http://127.0.0.1:1234/";

Security Warning: Routing is not a security feature. Use auth filters to secure routes. Some predicates like ForwardedHost, JWTPayload*, QueryParam, Source, ClientIP, and OTelBaggage have known security considerations (e.g., potential for forgery or bypass) if the upstream proxy layer is not correctly configured.

Skipper uses a specific domain language to define and execute routing. Key concepts include:

• Eskip: The domain-specific language used to define routing rules (predicates, filters, and backends).
• Route: A rule that matches HTTP requests and defines processing and forwarding.
• Route Definition: The static representation of a route in Eskip syntax.
• Route Instance: The compiled runtime representation of a route ready for matching.
• Route ID: A unique identifier for a route (e.g., "kube__healthz_down").
• Routing Tree: An immutable radix tree of route instances used for fast path-based lookups.
• Atomic Switching: The process of replacing the active routing tree with a new one without blocking in-flight requests.