• Stars
    star
    3,088
  • Rank 14,570 (Top 0.3 %)
  • Language
    Go
  • License
    Other
  • Created over 9 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An HTTP router and reverse proxy for service composition, including use cases like Kubernetes Ingress

Build Status Doc Go Reference License Go Report Card codecov GitHub release OpenSSF Best Practices OpenSSF Scorecard Slack CodeQL

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://pkg.go.dev/github.com/zalando/skipper

Installation

From Binary

Download binary tgz from https://github.com/zalando/skipper/releases/latest

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

% curl -LO https://github.com/zalando/skipper/releases/download/v0.14.8/skipper-v0.14.8-linux-amd64.tar.gz
% 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 https://github.com/zalando/skipper.git
% 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") -> "https://www.example.org"' > 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 registry.opensource.zalan.do/teapot/skipper:latest

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 \
  registry.opensource.zalan.do/teapot/skipper:latest 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 \
    registry.opensource.zalan.do/teapot/skipper:latest 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: https://pkg.go.dev/github.com/zalando/skipper/filters/auth.

Working with the code

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

git clone https://github.com/zalando/skipper.git
cd skipper

Build and test all packages:

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 https://github.com/zalando-incubator/kube-ingress-aws-controller, that manage ALBs in front of your skipper deployment. A production example, 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

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 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 was used to build skipper's opentracing package. We moved the opentracing plugin source into the tracing 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. If for some reason this link doesn't work, you can find more information about the gophers communities here.

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

More Repositories

1

patroni

A template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes
Python
6,267
star
2

postgres-operator

Postgres operator creates and manages PostgreSQL clusters running in Kubernetes
Go
3,686
star
3

restful-api-guidelines

A model set of guidelines for RESTful APIs and Events, created by Zalando
CSS
2,605
star
4

zalenium

A flexible and scalable container based Selenium Grid with video recording, live preview, basic auth & dashboard.
Java
2,385
star
5

SwiftMonkey

A framework for doing randomised UI testing of iOS apps
Swift
1,947
star
6

logbook

An extensible Java library for HTTP request and response logging
Java
1,788
star
7

tailor

A streaming layout service for front-end microservices
JavaScript
1,728
star
8

tech-radar

Visualizing our technology choices
1,581
star
9

spilo

Highly available elephant herd: HA PostgreSQL cluster using Docker
Python
1,225
star
10

intellij-swagger

A plugin to help you easily edit Swagger and OpenAPI specification files inside IntelliJ IDEA
Java
1,172
star
11

problem-spring-web

A library for handling Problems in Spring Web MVC
Java
1,031
star
12

nakadi

A distributed event bus that implements a RESTful API abstraction on top of Kafka-like queues
Java
928
star
13

zally

A minimalistic, simple-to-use API linter
Kotlin
903
star
14

problem

A Java library that implements application/problem+json
Java
869
star
15

zalando-howto-open-source

Open Source guidance from Zalando, Europe's largest online fashion platform
799
star
16

go-keyring

Cross-platform keyring interface for Go
Go
689
star
17

gin-oauth2

Middleware for Gin Framework users who also want to use OAuth2
Go
579
star
18

zappr

An agent that enforces guidelines for your GitHub repositories
JavaScript
542
star
19

pg_view

Get a detailed, real-time view of your PostgreSQL database and system metrics
Python
494
star
20

engineering-principles

Our guidelines for building new applications and managing legacy systems
376
star
21

gulp-check-unused-css

A build tool for checking your HTML templates for unused CSS classes
CSS
359
star
22

zmon

Real-time monitoring of critical metrics & KPIs via elegant dashboards, Grafana3 visualizations & more
Shell
355
star
23

expan

Open-source Python library for statistical analysis of randomised control trials (A/B tests)
Python
325
star
24

PGObserver

A battle-tested, flexible & comprehensive monitoring solution for your PostgreSQL databases
Python
316
star
25

riptide

Client-side response routing for Spring
Java
292
star
26

jackson-datatype-money

Extension module to properly support datatypes of javax.money
Java
240
star
27

grafter

Grafter is a library to configure and wire Scala applications
Scala
240
star
28

opentracing-toolbox

Best-of-breed OpenTracing utilities, instrumentations and extensions
Java
180
star
29

elm-street-404

A fun WebGL game built with Elm
Elm
176
star
30

tokens

Java library for conveniently verifying and storing OAuth 2.0 service access tokens
Java
169
star
31

innkeeper

Simple route management API for Skipper
Scala
166
star
32

public-presentations

List of public talks by Zalando Tech: meetup presentations, recorded conference talks, slides
165
star
33

python-nsenter

Enter kernel namespaces from Python
Python
139
star
34

faux-pas

A library that simplifies error handling for Functional Programming in Java
Java
132
star
35

dress-code

The official style guide and framework for all Zalando Brand Solutions products
CSS
129
star
36

beard

A lightweight, logicless templating engine, written in Scala and inspired by Mustache
Scala
121
star
37

friboo

Utility library for writing microservices in Clojure, with support for Swagger and OAuth
Clojure
117
star
38

spring-cloud-config-aws-kms

Spring Cloud Config add-on that provides encryption via AWS KMS
Java
99
star
39

zalando.github.io

Open Source Documentation and guidelines for Zalando developers
HTML
86
star
40

failsafe-actuator

Endpoint library for the failsafe framework
Java
52
star
41

package-build

A toolset for building system packages using Docker and fpm-cookery
Ruby
35
star
42

ghe-backup

Github Enterprise backup at ZalandoTech (Kubernetes, AWS, Docker)
Shell
30
star
43

rds-health

discover anomalies, performance issues and optimization within AWS RDS
Go
26
star
44

backstage-plugin-api-linter

API Linter is a quality assurance tool that checks the compliance of API's specifications to Zalando's API rules.
TypeScript
12
star
45

.github

Standard github health files
1
star