Hephy Router v2

Deis (pronounced DAY-iss) Workflow is an open source Platform as a Service (PaaS) that adds a developer-friendly layer to any Kubernetes cluster, making it easy to deploy and manage applications on your own servers.

We welcome your input! If you have feedback, please submit an [issue][issues]. If you'd like to participate in development, please read the "Development" section below and submit a [pull request][prs].

About

The Deis router handles ingress and routing of HTTP/S traffic bound for the Deis Workflow controller (API) and for your own applications. This component is 100% Kubernetes native and, while it's intended for use with the Deis Workflow PaaS, it's flexible enough to be used standalone inside any Kubernetes cluster.

Development

The Deis project welcomes contributions from all developers. The high level process for development matches many other open source projects. See below for an outline.

• Fork this repository
• Make your changes
• Submit a [pull request][prs] (PR) to this repository with your changes, and unit tests whenever possible.
  • If your PR fixes any [issues][issues], make sure you write Fixes #1234 in your PR description (where #1234 is the number of the issue you're closing)
• The Deis core contributors will review your code. After each of them sign off on your code, they'll label your PR with LGTM1 and LGTM2 (respectively). Once that happens, they'll merge it.

Installation

This section documents simple procedures for installing the Deis Router for evaluation or use. Those wishing to contribute to Deis Router development might consider the more developer-oriented instructions in the Hacking Router section.

Deis Router can be installed with or without the rest of the Deis Workflow platform. In either case, begin with a healthy Kubernetes cluster. Kubernetes getting started documentation is available here.

Next, install the Helm package manager, then use the commands below to initialize that tool and install all of Deis Workflow or the Deis Router by itself.

$ helm init

To install all of Deis Workflow:

$ helm repo add workflow https://charts.deis.com/workflow
$ helm install workflow/workflow --namespace deis

Or to install the Deis Router by itself:

$ helm repo add router https://charts.deis.com/router
$ helm install router/router --namespace deis

For next steps, skip ahead to the How it Works and Configuration Guide sections.

<a name="hacking"></a>Hacking Router

The only dependencies for hacking on / contributing to this component are:

• git
• make
• docker
• kubectl, properly configured to manipulate a healthy Kubernetes cluster that you presumably use for development
• Your favorite text editor

Although the router is written in Go, you do not need Go or any other development tools installed. Any parts of the developer workflow requiring tools not listed above are delegated to a containerized Go development environment.

Registry

The following sections setup, build, deploy, and test the Deis Router. You'll need a configured Docker registry to push changed images to so that they can be deployed to your Kubernetes cluster. You can easily make use of a public registry such as hub.docker.com, provided you have an account. To do so:

$ export DEIS_REGISTRY=registry.hub.docker.com/
$ export IMAGE_PREFIX=your-username

If I can make it there, I'll make it anywhere...

The entire developer workflow for anyone hacking on the router is implemented as a set of make targets. They are simple and easy to use, and collectively provide a workflow that should feel familiar to anyone who has hacked on Deis v1.x in the past.

Setup:

To "vendor" the development environment:

$ make vendor

In router's case, this step carries out some extensive dependency management using go modules within the containerized development environment. Because the router leverages the Kubernetes API, which in turn has in excess of one hundred dependencies, this step can take quite some time. Be patient, and allow up to 20 minutes. You generally only ever have to do this once.

To build:

$ make build

Make sure to have defined the variable DEIS_REGISTRY previous to this step, as your image tags will be prefixed according to this.

To deploy:

$ make deploy

The deploy target will implicitly build first, then push the built image to your development registry (i.e. that specified by DEIS_REGISTRY). The router's existing Kubernetes Deployment (installed via Helm) will be updated to use the newly built image.

To see that the router is running, you can look for its pod(s):

$ kubectl get pods --namespace=deis

Trying it Out

To deploy some sample routable applications:

$ helm install charts/examples --namespace router-examples

This will deploy Nginx and Apache to your Kubernetes cluster as if they were user applications.

To test, first modify your /etc/hosts such that the following four hostnames are resolvable to the IP of the Kubernetes node that is hosting the router:

• nginx.example.com
• apache.example.com
• httpd.example.com
• unknown.example.com

By requesting the following three URLs from your browser, you should find that one is routed to a pod running Nginx, while the other two are routed to a pod running Apache:

• http://nginx.example.com
• http://apache.example.com
• http://httpd.example.com

Requesting http://unknown.example.com should result in a 404 from the router since no route exists for that domain name.

<a name="how-it-works"></a>How it Works

The router is implemented as a simple Go program that manages Nginx and Nginx configuration. It regularly queries the Kubernetes API for services labeled with router.deis.io/routable: "true". Such services are compared to known services resident in memory. If there are differences, new Nginx configuration is generated and Nginx is reloaded.

Routable services must expose port 80. The target port in underlying pods may be anything, but the service itself must expose port 80. For example:

apiVersion: v1
kind: Service
metadata:
  name: foo
  labels:
  	router.deis.io/routable: "true"
  namespace: router-examples
  annotations:
    router.deis.io/domains: www.foobar.com
  spec:
    selector:
      app: foo
    ports:
    - port: 80
      targetPort: 3000
# ...

When generating configuration, the program reads all annotations of each service prefixed with router.deis.io. These annotations describe all the configuration options that allow the program to dynamically construct Nginx configuration, including virtual hosts for all the domain names associated with each routable application.

Similarly, the router watches the annotations on its own deployment object to dynamically construct global Nginx configuration.

<a name="configuration"></a>Configuration Guide

Environment variables

Router configuration is driven almost entirely by annotations on the router's deployment object and the services of all routable applications-- those labeled with router.deis.io/routable: "true".

One exception to this, however, is that in order for the router to discover its own annotations, the router must be configured via environment variable with some awareness of its own namespace. (It cannot query the API for information about itself without knowing this.)

The POD_NAMESPACE environment variable is required by the router and it should be configured to match the Kubernetes namespace that the router is deployed into. If no value is provided, the router will assume a value of default.

For example, consider the following Kubernetes manifest. Given a manifest containing the following metadata:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: deis-router
  namespace: deis
# ...

The corresponding template must inject a POD_NAMESPACE=deis environment variable into router containers. The most elegant way to achieve this is by means of the Kubernetes "downward API," as in this snippet from the same manifest:

# ...
spec:
  # ...
  template:
    # ...
    spec:
      containers:
      - name: deis-router
        # ...
        env:
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
# ...

Altering the value of the POD_NAMESPACE environment variable requires the router to be restarted for changes to take effect.

Annotations

All remaining options are configured through annotations. Any of the following three Kubernetes resources can be configured:

| Resource | Notes | |----------|-------| | <ul><li>deis-router deployment object</li><li>deis-builder service (if in use)</li></ul> | All of these configuration options are specific to this implementation of the router (as indicated by the inclusion of the token nginx in the annotations' names). Customized and alternative router implementations are possible. Such routers are under no obligation to honor these annotations, as many or all of these may not be applicable in such scenarios. Customized and alternative implementations should document their own configuration options. | | <ul><li>routable app