An HTTP router and reverse proxy for service composition, including use cases like Kubernetes Ingress
Switch branches/tags
Clone or download
aryszka and szuecs Feature/configurable http redirect code in kubernetes (#799)
* configurable redirect code in kubernetes, package option

* configurable redirect code in kubernetes, command line options

* enable redirect from ingress annotation

* refactor: convert test routes into eskip

* disable global redirect from individual ingresses

* support redirect code from annotation

* refactor kubernetes redirect code

* refactor kubernetes redirect code

* docs: kubernetes HTTPS redirect
Latest commit 01e6736 Sep 20, 2018
Permalink
Failed to load latest commit information.
_test_plugins Multi plugins, plugin .conf filles (#598) Apr 18, 2018
_test_plugins_fail Multi plugins, plugin .conf filles (#598) Apr 18, 2018
circuit Properly log the state of the circuits breakers. Nov 18, 2017
cmd Feature/configurable http redirect code in kubernetes (#799) Sep 20, 2018
dataclients Feature/configurable http redirect code in kubernetes (#799) Sep 20, 2018
docs Feature/configurable http redirect code in kubernetes (#799) Sep 20, 2018
eskip Using regex delimiter fails in character list in eskip #134 (#578) Mar 15, 2018
eskipfile File watch (#588) Mar 26, 2018
etcd Speedup CI buildtime Sep 4, 2018
filters Deprecate accessLogDisabled in favor of disableAccessLog and enableAc… Sep 18, 2018
fixtures Implemented TLS support May 18, 2016
img add scaled images Jan 19, 2018
innkeeper all: gofmt -s (#515) Dec 22, 2017
loadbalancer review fixes: Jun 15, 2018
logging Feature/access log filter (#752) Sep 5, 2018
metrics Update prometheus library (#783) Sep 11, 2018
net Source predicate can be by passed in AWS (#533) Jan 17, 2018
oauth close test servers Jun 5, 2016
packaging Build opentracing tracers into main binary (#779) Sep 10, 2018
pathmux Add visualization Tree built from pathmux (#445) Oct 6, 2017
predicates add predicates to match based on jwt content (#710) Jul 22, 2018
proxy Deprecate accessLogDisabled in favor of disableAccessLog and enableAc… Sep 18, 2018
ratelimit Retry After Header (#786) Sep 12, 2018
routing sort routing table output on support endpoint (#681) Jun 15, 2018
script serve's body= parameter accepts a table (#529) Jan 4, 2018
skptesting LUA Scripting (#522) Dec 28, 2017
tracing Build opentracing tracers into main binary (#779) Sep 10, 2018
.catwatch.yaml added .catwatch.yaml Feb 11, 2016
.gitignore fix build to create non dirty containers (#771) Sep 5, 2018
.travis.yml Use Go 1.11 modules Sep 2, 2018
.zappr.yaml make Zappr compliant Jun 19, 2017
CONTRIBUTING.md Fix broken markdown links in CONTRIBUTING.md (#447) Oct 10, 2017
LICENSE Move pathmux (#361) Jun 30, 2017
MAINTAINERS remove Raffo from maintainers list (#289) Mar 3, 2017
Makefile fix: add go modules to all tasks Sep 11, 2018
SECURITY.md Create SECURITY.md (#347) Jun 20, 2017
delivery.yaml Build opentracing tracers into main binary (#779) Sep 10, 2018
doc.go raw migration of the skoap code to skipper (#367) Apr 27, 2018
go.mod Filter for fowarding tokeninfo and token introspection results. (#793) Sep 17, 2018
go.sum Filter for fowarding tokeninfo and token introspection results. (#793) Sep 17, 2018
mkdocs.yml Docs/restructure tree (#785) Sep 13, 2018
plugins.go Multi plugins, plugin .conf filles (#598) Apr 18, 2018
readme.md godoc link (#788) Sep 13, 2018
skipper.go Feature/configurable http redirect code in kubernetes (#799) Sep 20, 2018
skipper_test.go Multi plugins, plugin .conf filles (#598) Apr 18, 2018

readme.md

Build Status Doc GoDoc License Go Report Card codecov GitHub release

Skipper

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.

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

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: https://godoc.org/github.com/zalando/skipper.

Installation

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:

go get github.com/zalando/skipper/...

Running

Create a file with a route:

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

Optionally, verify the file's syntax:

eskip check example.eskip

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 registry.opensource.zalan.do/pathfinder/skipper:latest

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: https://godoc.org/github.com/zalando/skipper/filters/auth.

Working with the code

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

go get -t github.com/zalando/skipper/...

Build and test all packages:

cd src/github.com/zalando/skipper
make deps
make install
make shortcheck

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 https://github.com/zalando-incubator/kube-ingress-aws-controller, that manage ALBs in front of your skipper deployment. A production example, https://github.com/zalando-incubator/kubernetes-on-aws/blob/dev/cluster/manifests/skipper/daemonset.yaml, can be found in our Kubernetes configuration https://github.com/zalando-incubator/kubernetes-on-aws.

Documentation

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
baidu:
        Path("/baidu")
        -> setRequestHeader("Host", "www.baidu.com")
        -> setPath("/s")
        -> setQuery("wd", "godoc skipper")
        -> "http://www.baidu.com";
google:
        *
        -> setPath("/search")
        -> setQuery("q", "godoc skipper")
        -> "https://www.google.com";
yandex:
        * && Cookie("yandex", "true")
        -> setPath("/search/")
        -> setQuery("text", "godoc skipper")
        -> tee("http://127.0.0.1:12345/")
        -> "https://yandex.ru";

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 "http://www.baidu.com".
  • If google is selected, skipper changes the path and sets a query string to the http request to the backend "https://www.google.com".
  • If yandex is selected, skipper changes the path and sets a query string to the http request to the backend "https://yandex.ru". The modified request will be copied to "http://127.0.0.1:12345/"

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

See https://github.com/zalando/skipper/blob/master/packaging/readme.md

In case you want to implement and link your own modules into your skipper for more advanced features like opentracing API support there is https://github.com/skipper-plugins organization to enable you to do so. In order to explain you the build process with custom Go modules there is https://github.com/skipper-plugins/skipper-tracing-build, that is used to build skipper's opentracing package.

Community

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

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

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