Skip to content
An HTTP router and reverse proxy for service composition, including use cases like Kubernetes Ingress
Go Shell Makefile Yacc PHP Lua
Branch: master
Clone or download

Latest commit

szuecs fix lua() should have access to host header (#1431)
* fix lua() should have access to host header

Signed-off-by: Sandor Szücs <>

* add docs that we have the host as field in the request and remove the write possibility, because people schould modify outgoing_host instead

Signed-off-by: Sandor Szücs <>
Latest commit cc0a495 May 28, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Fix GitHub actions (#1408) Apr 6, 2020
_test_plugins Multi plugins, plugin .conf filles (#598) Apr 18, 2018
_test_plugins_fail Multi plugins, plugin .conf filles (#598) Apr 18, 2018
circuit Using YAML configuration file to pass args for skipper binary (#1205) Oct 14, 2019
cmd fix build for github actions (#1402) Apr 5, 2020
config feature: add optional startup checks (#1292) Jan 30, 2020
dataclients Fix: Align CRD backend algorithms to those allowed by skipper (#1389) Mar 31, 2020
docs fix lua() should have access to host header (#1431) May 28, 2020
eskip Add FastCGI backend (#1325) Mar 16, 2020
eskipfile delete routes only on ENOEXIST when using file watching (#1193) Sep 22, 2019
etcd fix build for github actions (#1402) Apr 5, 2020
fastcgiserver Add FastCGI backend (#1325) Mar 16, 2020
filters cleanup unused rand data which does not provide value as discussed in… May 27, 2020
fixtures Implemented TLS support May 18, 2016
img add scaled images Jan 19, 2018
innkeeper gosec integration (#946) May 9, 2019
loadbalancer Feature/routegroup crd (#1180) Jan 28, 2020
logging - feature: implement http.Client similar interface (has no interface) ( Feb 11, 2020
metrics Experiment/queue listener (#1241) Nov 5, 2019
net reduce the flaky test (#1356) Mar 18, 2020
oauth close test servers Jun 5, 2016
packaging fix cross compile build command (#1413) Apr 8, 2020
pathmux Allow wildcard name collision (#1227) Oct 30, 2019
predicates Traffic(): allow weight of 1.0 (#1425) May 6, 2020
proxy Read and discard request body on shunt (#1314) May 27, 2020
queuelistener fix measuring the connection count in TCP-LIFO (#1424) May 4, 2020
ratelimit - upstream issue was fixed in go-redis v7, so we switch to TxPipeline… Jan 6, 2020
rfc Fix/rfc patch path (#1088) Jun 11, 2019
routing Always close Body (#1358) Mar 19, 2020
scheduler fix the build and the checks for go1.14 (#1319) Feb 28, 2020
script fix lua() should have access to host header (#1431) May 28, 2020
secrets add tests for secret readers (#1318) Feb 28, 2020
skptesting test the full roundtrip of an OpenIDConnect request (#1265) Jan 20, 2020
swarm Feature/redis based cluster ratelimit (#981) Mar 13, 2019
tracing Remove unnecessary dependency (#1274) Jan 17, 2020
.catwatch.yaml added .catwatch.yaml Feb 11, 2016
.gitignore Docs/egress features (#1146) Jul 31, 2019
.zappr.yaml make Zappr compliant Jun 19, 2017 we have to define key roles in the project to achieve silver in CII b… Apr 7, 2019 add some stuff to achieve silver badge (#940) Feb 4, 2019
LICENSE Move pathmux (#361) Jun 30, 2017
MAINTAINERS we have to define key roles in the project to achieve silver in CII b… Apr 7, 2019
Makefile Fix GitHub actions (#1408) Apr 6, 2020 update security reporting mechanism (#1213) Oct 7, 2019
VERSION add major and minor from a fixed file that needs a manual modificatio… Oct 24, 2019
delivery.yaml cross compile arm7 32bit and arm8 64bit containers (#1409) Apr 7, 2020
doc.go feature: support dynamic backends (#908) (#918) Jan 28, 2019
go.mod Add FastCGI backend (#1325) Mar 16, 2020
go.sum Add FastCGI backend (#1325) Mar 16, 2020
metricsinit_test.go move metrics initialization before packages depending on metrics.Defa… Jun 6, 2019
mkdocs.yml Feature/routegroup crd (#1180) Jan 28, 2020
plugins.go Multi plugins, plugin .conf filles (#598) Apr 18, 2018
plugins_test.go shortcheck: run with -race (#970) Mar 11, 2019 Fix GitHub actions (#1408) Apr 6, 2020
skipper.go Always close Body (#1358) Mar 19, 2020
skipper_test.go Fix/graceful shutdown (#988) Mar 13, 2019

Build Status Doc GoDoc License Go Report Card codecov GitHub release CII Best Practices



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, Innkeeper (deprecated), 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 rules

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:

Getting Started


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:


Skipper is 'go get' compatible. If needed, create a Go workspace first:

mkdir ws
cd ws
export GOPATH=$(pwd)
export PATH=$PATH:$GOPATH/bin

Get the Skipper packages:

GO111MODULE=on go get


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

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 including audit logging. See the documentation at:

Working with the code

Working with the code requires Go1.11 or a higher version. Getting the code with the test dependencies (-t switch):

GO111MODULE=on go get -t

Build and test all packages:

cd src/
make deps
make install
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 overview you will can be found in our ingress-controller deployment docs.

For AWS integration, we provide an ingress controller, that manage ALBs in front of your skipper deployment. A production example, can be found in our Kubernetes configuration


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

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 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.

You should have a base understanding of Kubernetes and Ingress.

Packaging support


Skipper uses Go modules, so you might need to add GO111MODULE=on in your custom build process.

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.


User or developer questions can be asked in our public Google Group

We also have a slack channel #skipper in Get an invite at gophers official invite page.


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.


Zalando uses this project as shop frontend http router with 350000 routes, as Kubernetes ingress controller and runs several custom skipper instances that use skipper as library.

Sergio Ballesteros from spotahome

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:

Conference/Meetups talks

You can’t perform that action at this time.