Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Protect your apps from supply chain attacks


Package skipper provides an HTTP routing library with flexible configuration as well as a runtime update of the routing rules. Skipper works as an HTTP reverse proxy that is responsible for mapping incoming requests to multiple HTTP backend services, based on routes that are selected by the request attributes. At the same time, both the requests and the responses can be augmented by a filter chain that is specifically defined for each route. Optionally, it can provide circuit breaker mechanism individually for each backend host. Skipper can load and update the route definitions from multiple data sources without being restarted. It provides a default executable command with a few built-in filters, however, its primary use case is to be extended with custom filters, predicates or data sources. For further information read 'Extending Skipper'. Skipper took the core design and inspiration from Vulcand: Skipper is 'go get' compatible. If needed, create a 'go workspace' first: Get the Skipper packages: Create a file with a route: Optionally, verify the syntax of the file: Start Skipper and make an HTTP request: The core of Skipper's request processing is implemented by a reverse proxy in the 'proxy' package. The proxy receives the incoming request, forwards it to the routing engine in order to receive the most specific matching route. When a route matches, the request is forwarded to all filters defined by it. The filters can modify the request or execute any kind of program logic. Once the request has been processed by all the filters, it is forwarded to the backend endpoint of the route. The response from the backend goes once again through all the filters in reverse order. Finally, it is mapped as the response of the original incoming request. Besides the default proxying mechanism, it is possible to define routes without a real network backend endpoint. One of these cases is called a 'shunt' backend, in which case one of the filters needs to handle the request providing its own response (e.g. the 'static' filter). Actually, filters themselves can instruct the request flow to shunt by calling the Serve(*http.Response) method of the filter context. Another case of a route without a network backend is the 'loopback'. A loopback route can be used to match a request, modified by filters, against the lookup tree with different conditions and then execute a different route. One example scenario can be to use a single route as an entry point to execute some calculation to get an A/B testing decision and then matching the updated request metadata for the actual destination route. This way the calculation can be executed for only those requests that don't contain information about a previously calculated decision. For further details, see the 'proxy' and 'filters' package documentation. Finding a request's route happens by matching the request attributes to the conditions in the route's definitions. Such definitions may have the following conditions: - method - path (optionally with wildcards) - path regular expressions - host regular expressions - headers - header regular expressions It is also possible to create custom predicates with any other matching criteria. The relation between the conditions in a route definition is 'and', meaning, that a request must fulfill each condition to match a route. For further details, see the 'routing' package documentation. Filters are applied in order of definition to the request and in reverse order to the response. They are used to modify request and response attributes, such as headers, or execute background tasks, like logging. Some filters may handle the requests without proxying them to service backends. Filters, depending on their implementation, may accept/require parameters, that are set specifically to the route. For further details, see the 'filters' package documentation. Each route has one of the following backends: HTTP endpoint, shunt, loopback or dynamic. Backend endpoints can be any HTTP service. They are specified by their network address, including the protocol scheme, the domain name or the IP address, and optionally the port number: e.g. "". (The path and query are sent from the original request, or set by filters.) A shunt route means that Skipper handles the request alone and doesn't make requests to a backend service. In this case, it is the responsibility of one of the filters to generate the response. A loopback route executes the routing mechanism on current state of the request from the start, including the route lookup. This way it serves as a form of an internal redirect. A dynamic route means that the final target will be defined in a filter. One of the filters in the chain must set the target backend url explicitly. Route definitions consist of the following: - request matching conditions (predicates) - filter chain (optional) - backend The eskip package implements the in-memory and text representations of route definitions, including a parser. (Note to contributors: in order to stay compatible with 'go get', the generated part of the parser is stored in the repository. When changing the grammar, 'go generate' needs to be executed explicitly to update the parser.) For further details, see the 'eskip' package documentation Skipper has filter implementations of basic auth and OAuth2. It can be integrated with tokeninfo based OAuth2 providers. For details, see: Skipper's route definitions of Skipper are loaded from one or more data sources. It can receive incremental updates from those data sources at runtime. It provides three different data clients: - Kubernetes: Skipper can be used as part of a Kubernetes Ingress Controller implementation together with . In this scenario, Skipper uses the Kubernetes API's Ingress extensions as a source for routing. For a complete deployment example, see more details in: . - Innkeeper: the Innkeeper service implements a storage for large sets of Skipper routes, with an HTTP+JSON API, OAuth2 authentication and role management. See the 'innkeeper' package and - etcd: Skipper can load routes and receive updates from etcd clusters ( See the 'etcd' package. - static file: package eskipfile implements a simple data client, which can load route definitions from a static file in eskip format. Currently, it loads the routes on startup. It doesn't support runtime updates. Skipper can use additional data sources, provided by extensions. Sources must implement the DataClient interface in the routing package. Skipper provides circuit breakers, configured either globally, based on backend hosts or based on individual routes. It supports two types of circuit breaker behavior: open on N consecutive failures, or open on N failures out of M requests. For details, see: Skipper can be started with the default executable command 'skipper', or as a library built into an application. The easiest way to start Skipper as a library is to execute the 'Run' function of the current, root package. Each option accepted by the 'Run' function is wired in the default executable as well, as a command line flag. E.g. EtcdUrls becomes -etcd-urls as a comma separated list. For command line help, enter: An additional utility, eskip, can be used to verify, print, update and delete routes from/to files or etcd (Innkeeper on the roadmap). See the cmd/eskip command package, and/or enter in the command line: Skipper doesn't use dynamically loaded plugins, however, it can be used as a library, and it can be extended with custom predicates, filters and/or custom data sources. To create a custom predicate, one needs to implement the PredicateSpec interface in the routing package. Instances of the PredicateSpec are used internally by the routing package to create the actual Predicate objects as referenced in eskip routes, with concrete arguments. Example, randompredicate.go: In the above example, a custom predicate is created, that can be referenced in eskip definitions with the name 'Random': To create a custom filter we need to implement the Spec interface of the filters package. 'Spec' is the specification of a filter, and it is used to create concrete filter instances, while the raw route definitions are processed. Example, hellofilter.go: The above example creates a filter specification, and in the routes where they are included, the filter instances will set the 'X-Hello' header for each and every response. The name of the filter is 'hello', and in a route definition it is referenced as: The easiest way to create a custom Skipper variant is to implement the required filters (as in the example above) by importing the Skipper package, and starting it with the 'Run' command. Example, hello.go: A file containing the routes, routes.eskip: Start the custom router: The 'Run' function in the root Skipper package starts its own listener but it doesn't provide the best composability. The proxy package, however, provides a standard http.Handler, so it is possible to use it in a more complex solution as a building block for routing. Skipper provides detailed logging of failures, and access logs in Apache log format. Skipper also collects detailed performance metrics, and exposes them on a separate listener endpoint for pulling snapshots. For details, see the 'logging' and 'metrics' packages documentation. The router's performance depends on the environment and on the used filters. Under ideal circumstances, and without filters, the biggest time factor is the route lookup. Skipper is able to scale to thousands of routes with logarithmic performance degradation. However, this comes at the cost of increased memory consumption, due to storing the whole lookup tree in a single structure. Benchmarks for the tree lookup can be run by: In case more aggressive scale is needed, it is possible to setup Skipper in a cascade model, with multiple Skipper instances for specific route segments.


Version published


[![Build Status](](
[![Go Reference](](
[![Go Report Card](](
[![Coverage Status](](
[![GitHub release](](
[![OpenSSF Best Practices](](
[![OpenSSF Scorecard](](

<p><img height="180" alt="Skipper" src=""></p>

# Skipper

Skipper is an HTTP router and reverse proxy for service composition. It's designed to handle >300k HTTP route
definitions with detailed lookup conditions, and flexible augmentation of the request flow with filters. It can be
used out of the box or extended with custom lookup, filter logic and configuration sources.

## Main features:

An overview of [deployments and data-clients](
shows some use cases to run skipper.


- identifies routes based on the requests' properties, such as path, method, host and headers
- allows modification of the requests and responses with filters that are independently configured for each route
- simultaneously streams incoming requests and backend responses
- optionally acts as a final endpoint (shunt), e.g. as a static file server or a mock backend for diagnostics
- updates routing rules without downtime, while supporting multiple types of data sources — including
  [etcd](, [Kubernetes Ingress](, [static files](, [route string]( and
  [custom configuration sources](
- can serve as a
  [Kubernetes Ingress controller](
  without reloads. You can use it in combination with a controller that will route public traffic to
  your skipper fleet; [see AWS example](
- shipped with
   - eskip: a descriptive configuration language designed for routing
   - routesrv: proxy to omit kube-apiserver overload leveraging Etag
     header to reduce amount of CPU used in your skipper data plane
   - webhook: Kubernetes validation webhook to make sure your
     manifests are deployed safely

Skipper provides a default executable command with a few built-in filters. However, its primary use case is to
be extended with custom filters, predicates or data sources. [Go here for additional documentation](

A few examples for extending Skipper:

- Example proxy with custom filter
- Image server
- Plugins repository, [plugin docs](

### Getting Started

#### Prerequisites/Requirements

In order to build and run Skipper, only the latest version of Go needs to be installed. Skipper can use
Innkeeper or Etcd as data sources for routes, or for the simplest cases, a local configuration file. See more
details in the documentation:

#### Installation

##### From Binary

Download binary tgz from

Example, assumes that you have $GOBIN set to a directory that exists
and is in your $PATH:

% curl -LO
% tar xzf skipper-v0.14.8-linux-amd64.tar.gz
% mv skipper-v0.14.8-linux-amd64/* $GOBIN/
% skipper -version
Skipper version v0.14.8 (commit: 95057948, runtime: go1.19.1)

##### From Source

% git clone
% make
% ./bin/skipper -version
Skipper version v0.14.8 (commit: 95057948, runtime: go1.19.3)

#### Running

Create a file with a route:

    echo 'hello: Path("/hello") -> ""' > example.eskip

Optionally, verify the file's syntax:

    eskip check example.eskip

If no errors are detected nothing is logged, else a descriptive error is logged.

Start Skipper and make an HTTP request:

    skipper -routes-file example.eskip &
    curl localhost:9090/hello

##### Docker

To run the latest Docker container:

    docker run

To run `eskip` you first mount the `.eskip` file, into the container, and run the command

    docker run \
      -v $(PWD)/doc-docker-intro.eskip:/doc-docker-intro.eskip \ eskip print doc-docker-intro.eskip

To run `skipper` you first mount the `.eskip` file, into the container, expose the ports and run the command

    docker run -it \
        -v $(PWD)/doc-docker-intro.eskip:/doc-docker-intro.eskip \
        -p 9090:9090 \
        -p 9911:9911 \ skipper -routes-file doc-docker-intro.eskip

Skipper will then be available on http://localhost:9090

#### Authentication Proxy

Skipper can be used as an authentication proxy, to check incoming
requests with Basic auth or an OAuth2 provider or an OpenID Connect
provider including audit logging. See the documentation at:

#### Working with the code

Getting the code with the test dependencies (`-t` switch):

    git clone
    cd skipper

Build and test all packages:

    make deps
    make install
    make lint
    make shortcheck

> On Mac the tests may fail because of low max open file limit. Please make sure you have correct limits setup
by following [these instructions](

##### Working from IntelliJ / GoLand

To run or debug skipper from _IntelliJ IDEA_ or _GoLand_, you need to create this configuration:

| Parameter         | Value                                    |
| Template          | Go Build                                 |
| Run kind          | Directory                                |
| Directory         | skipper source dir + `/cmd/skipper`      |
| Working directory | skipper source dir (usually the default) |

#### Kubernetes Ingress

Skipper can be used to run as an Kubernetes Ingress controller.
[Details with examples](
of [Skipper's capabilities]( and an
you will can be found in our [ingress-controller deployment docs](

For AWS integration, we provide an ingress controller, that
manage ALBs or NLBs in front of your skipper deployment.
A [production example for skipper](
and a [production example for kube-ingress-aws-controller](,
can be found in our Kubernetes configuration

- [Comparison with other Ingress controllers](
- [Comparison with service-mesh](

### Documentation

[Skipper's Documentation]( and
[Godoc developer documentation](,
includes information about [deployment use cases](
and detailed information on these topics:

- The [Routing]( Mechanism
- [Matching Requests](
- [Filters]( - Augmenting Requests and Responses
- [Predicates]( - additional predicates to match a route
- Service [Backends](
- Route Definitions fetched by dataclients:
   - [route string](
   - [eskip file](
   - [remote eskip](
   - [etcd](
   - [kubernetes](
- [Circuit Breakers](
- Extending It with Custom [Predicates](, [Filters](, can be done by [building your own proxy](, [Plugins]( or [Lua Scripts](
- [Proxy Package](
- [Logging]( and [Metrics](
- [Operations guide](
- [Authentication and Authorization](
- [Load Shedders](
- [Rate Limiters](
- [Opentracing tracers]( or extend [create your own](

#### 1 Minute Skipper introduction

The following example shows a skipper routes file in eskip format, that has 3 named routes: baidu, google and yandex.

    % cat doc-1min-intro.eskip
            -> setRequestHeader("Host", "")
            -> setPath("/s")
            -> setQuery("wd", "godoc skipper")
            -> "";
            -> setPath("/search")
            -> setQuery("q", "godoc skipper")
            -> "";
            * && Cookie("yandex", "true")
            -> setPath("/search/")
            -> setQuery("text", "godoc skipper")
            -> tee("")
            -> "";

Matching the route:

- baidu is using `Path()` matching to differentiate the HTTP requests to select the route.
- google is the default matching with wildcard `*`
- yandex is the default matching with wildcard `*` if you have a cookie `yandex=true`

Request Filters:

- If baidu is selected, skipper sets the Host header, changes the path and sets a query string to the http request to the backend "".
- If google is selected, skipper changes the path and sets a query string to the http request to the backend "".
- If yandex is selected, skipper changes the path and sets a query string to the http request to the backend "". The modified request will be copied to ""

Run skipper with the routes file doc-1min-intro.eskip shown above

    % skipper -routes-file doc-1min-intro.eskip

To test each route you can use curl:

    % curl -v localhost:9090/baidu
    % curl -v localhost:9090/
    % curl -v --cookie "yandex=true" localhost:9090/

To see the shadow traffic request that is made by the `tee()` filter you can use nc:

    [terminal1]% nc -l 12345
    [terminal2]% curl -v --cookie "yandex=true" localhost:9090/

#### 3 Minutes Skipper in Kubernetes introduction

This introduction was [moved to ingress controller documentation](

For More details, please check out our [Kubernetes ingress controller docs](, our [ingress usage]( and how to handle [common backend problems in Kubernetes](

### Packaging support


In case you want to implement and link your own modules into your
skipper, there is organization to
enable you to do so. In order to explain you the build process with
custom Go modules there is, that was
used to build skipper's [opentracing package](
We moved the opentracing plugin source into the `tracing` package, so
there is no need to use plugins for this case.

Because Go plugins are not very well supported by Go itself we do not
recommend to use plugins, but you can extend skipper and
[build your own proxy](

## Community

User or developer questions can be asked in our [public Google Group](!forum/skipper-router)

We have a slack channel #skipper in Get an [invite](
If for some reason this link doesn't work, you can find more information about
the gophers communities [here](

The preferred communication channel is the slack channel, because the google group is a manual process to add members.
Feel also free to [create an issue](, if you dislike chat and post your questions there.

### Proposals

We do our proposals open in [Skipper's Google drive](
If you want to make a proposal feel free to create an
[issue]( and if it is a
bigger change we will invite you to a document, such that we can work together.

### Users

Zalando used this project as shop frontend http router with 350000 routes.
We use it as Kubernetes ingress controller in more than 100 production clusters. With every day traffic between 500k and 7M RPS serving 15000 ingress and 3750 RouteGroups at less than ¢5/1M requests.
We also run several custom skipper instances that use skipper as library.

Sergio Ballesteros from [spotahome]( said 2018:
> We also ran tests with several ingress controllers and skipper gave us the more reliable results. Currently we are running skipper since almost 2 years with like 20K Ingress rules.
> The fact that skipper is written in go let us understand the code, add features and fix bugs since all of our infra stack is golang.

#### In the media

Blog posts:

- [ - Try this Kubernetes HTTP router and reverse proxy](
- [ - An open source HTTP router to increase your network visibility](
- [Building our own open source http routing
  Giving some context about why Skipper was created in the first place.
- [Kubernetes in production @ ShopGun](
- Hacker News [Skipper – An HTTP router and reverse proxy for service composition](

Conference/Meetups talks

- [LISA 2018 - modern HTTP routing](


Last updated on 22 Nov 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc