Skip to content

Commit c812cde

Browse files
author
Kent Rancourt
committed
Initial commit.
0 parents  commit c812cde

File tree

21 files changed

+786
-0
lines changed

21 files changed

+786
-0
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
manifests/deis-router-rc.tmp.yaml
2+
rootfs/bin/router
3+
vendor/

‎CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Changlog for PROJECTNAME
2+
3+
This is a placeholder for a markdown-formatted changelog.

‎CONTRIBUTING.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# How to Contribute
2+
3+
This project is part of Deis. You can find the latest contribution
4+
guidelines [at the Deis project](https://github.com/deis/deis/blob/master/CONTRIBUTING.md).
5+

‎DCO

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
Developer Certificate of Origin
2+
Version 1.1
3+
4+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
5+
660 York Street, Suite 102,
6+
San Francisco, CA 94110 USA
7+
8+
Everyone is permitted to copy and distribute verbatim copies of this
9+
license document, but changing it is not allowed.
10+
11+
12+
Developer's Certificate of Origin 1.1
13+
14+
By making a contribution to this project, I certify that:
15+
16+
(a) The contribution was created in whole or in part by me and I
17+
have the right to submit it under the open source license
18+
indicated in the file; or
19+
20+
(b) The contribution is based upon previous work that, to the best
21+
of my knowledge, is covered under an appropriate open source
22+
license and I have the right under that license to submit that
23+
work with modifications, whether created in whole or in part
24+
by me, under the same open source license (unless I am
25+
permitted to submit under a different license), as indicated
26+
in the file; or
27+
28+
(c) The contribution was provided directly to me by some other
29+
person who certified (a), (b) or (c) and I have not modified
30+
it.
31+
32+
(d) I understand and agree that this project and the contribution
33+
are public and that a record of the contribution (including all
34+
personal information I submit with it, including my sign-off) is
35+
maintained indefinitely and may be redistributed consistent with
36+
this project or the open source license(s) involved.

‎LICENSE

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright 2015 Engine Yard, Inc.
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

‎MAINTAINERS.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Deis Maintainers
2+
3+
This project is part of Deis. The official maintainers documentation is
4+
located [in the main project](https://github.com/deis/deis/blob/master/MAINTAINERS.md).

‎Makefile

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
include includes.mk
2+
3+
SHORT_NAME := router
4+
VERSION := 2.0.0-$(shell date "+%Y%m%d%H%M%S")
5+
6+
GIT_SHA := $(shell git rev-parse --short HEAD)
7+
BUILD_TAG := git-${GIT_SHA}
8+
9+
# The following variables describe the containerized development environment
10+
# and other build options
11+
DEV_ENV_IMAGE := quay.io/deis/go-dev:0.1.0
12+
DEV_ENV_WORK_DIR := /go/src/github.com/deis/${SHORT_NAME}
13+
DEV_ENV_CMD := docker run --rm -v ${PWD}:${DEV_ENV_WORK_DIR} -w ${DEV_ENV_WORK_DIR} ${DEV_ENV_IMAGE}
14+
DEV_ENV_CMD_INT := docker run -it --rm -v ${PWD}:${DEV_ENV_WORK_DIR} -w ${DEV_ENV_WORK_DIR} ${DEV_ENV_IMAGE}
15+
LDFLAGS := "-s -X main.version=${VERSION}"
16+
BINDIR := ./rootfs/bin
17+
18+
# The following variables describe the Docker image we build and where it
19+
# is pushed to.
20+
# If DEIS_REGISTRY is not set, try to populate it from legacy DEV_REGISTRY.
21+
DEIS_REGISTRY ?= ${DEV_REGISTRY}
22+
IMAGE_PREFIX ?= deis/
23+
IMAGE := ${DEIS_REGISTRY}/${IMAGE_PREFIX}${SHORT_NAME}:${BUILD_TAG}
24+
25+
# The following variables describe k8s manifests we may wish to deploy
26+
# to a running k8s cluster in the course of development.
27+
RC := manifests/deis-${SHORT_NAME}-rc.yaml
28+
SVC := manifests/deis-${SHORT_NAME}-service.yaml
29+
30+
# Allow developers to step into the containerized development environment
31+
dev: check-docker
32+
${DEV_ENV_CMD_INT} bash
33+
34+
dev-registry: check-docker
35+
@docker inspect registry >/dev/null 2>&1 && docker start registry || docker run --restart="always" -d -p 5000:5000 --name registry registry:0.9.1
36+
@echo
37+
@echo "To use a local registry for Deis development:"
38+
@echo " export DEIS_REGISTRY=`docker-machine ip $$(docker-machine active 2>/dev/null) 2>/dev/null || echo $(HOST_IPADDR) `:5000"
39+
40+
# Containerized dependency resolution
41+
bootstrap: check-docker
42+
${DEV_ENV_CMD} glide up
43+
44+
# Containerized build of the binary
45+
build: check-docker
46+
mkdir -p ${BINDIR}
47+
${DEV_ENV_CMD} make binary-build
48+
docker build --rm -t ${IMAGE} rootfs
49+
50+
# Builds the binary-- this should only be executed within the
51+
# containerized development environment.
52+
binary-build:
53+
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o ${BINDIR}/${SHORT_NAME} -a -installsuffix cgo -ldflags ${LDFLAGS} ${SHORT_NAME}.go
54+
55+
clean: check-docker
56+
docker rmi ${IMAGE}
57+
58+
full-clean: check-docker
59+
docker images -q ${DEIS_REGISTRY}/${IMAGE_PREFIX}${SHORT_NAME} | xargs docker rmi -f
60+
61+
dev-release: push set-image
62+
63+
push: check-docker check-registry build
64+
docker push ${IMAGE}
65+
66+
set-image:
67+
sed "s#\(image:\) .*#\1 ${IMAGE}#" manifests/deis-${SHORT_NAME}-rc.yaml > manifests/deis-${SHORT_NAME}-rc.tmp.yaml
68+
69+
deploy: check-kubectl dev-release
70+
@kubectl describe rc deis-${SHORT_NAME} --namespace=deis >/dev/null 2>&1; \
71+
if [ $$? -eq 0 ]; then \
72+
kubectl delete rc deis-${SHORT_NAME} --namespace=deis; \
73+
kubectl create -f manifests/deis-${SHORT_NAME}-rc.tmp.yaml; \
74+
else \
75+
kubectl create -f manifests/deis-${SHORT_NAME}-rc.tmp.yaml; \
76+
fi
77+
78+
examples:
79+
kubectl create -f manifests/examples.yaml

‎README.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Deis Router v2
2+
3+
Deis (pronounced DAY-iss) is an open source PaaS that makes it easy to deploy and manage applications on your own servers. Deis builds on [Kubernetes](http://kubernetes.io/) to provide a lightweight, [Heroku-inspired](http://heroku.com) workflow.
4+
5+
The router component, specifically, handles ingress and routing of HTTP/S traffic bound for the Deis API and for your own applications. This component is 100% Kubernetes native and is useful even without the rest of Deis!
6+
7+
## Work in Progress
8+
9+
![Deis Graphic](https://s3-us-west-2.amazonaws.com/get-deis/deis-graphic-small.png)
10+
11+
Deis Router v2 is changing quickly. Your feedback and participation are more than welcome, but be aware that this project is considered a work in progress.
12+
13+
## Hacking Router
14+
15+
The only dependencies for hacking on / contributing to this component are:
16+
17+
* `git`
18+
* `make`
19+
* `docker`
20+
* `kubectl`, properly configured to manipulate a healthy Kubernetes cluster that you presumably use for development
21+
* Your favorite text editor
22+
23+
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.
24+
25+
### Registry
26+
27+
If your Kubernetes cluster is running locally on one or more virtual machines, it's advisable to also run your own local Docker registry. This provides a place where router images built from source-- possibly containing your own experimental hacks-- can be pushed relatively quickly and can be accessed readily by your Kubernetes cluster.
28+
29+
Fortunately, this is very easy to set up as long as you have Docker already functioning properly:
30+
31+
```
32+
$ make dev-registry
33+
```
34+
35+
This will produce output containing further instructions such as:
36+
37+
```
38+
59ba57a3628fe04016634760e039a3202036d5db984f6de96ea8876a7ba8a945
39+
40+
To use a local registry for Deis development:
41+
export DEIS_REGISTRY=192.168.99.102:5000
42+
```
43+
44+
Following those instructions will make your local registry usable by the various `make` targets mentioned in following sections.
45+
46+
If you do not want to run your own local registry or if the Kubernetes cluster you will be deploying to is remote, then you can easily make use of a public registry such as [hub.docker.com](http://hub.docker.com), provided you have an account. To do so:
47+
48+
```
49+
$ export DEIS_REGISTRY=registry.hub.docker.com
50+
$ export IMAGE_PREFIX=your-username/
51+
```
52+
53+
__Do not miss the trailing slash in the `IMAGE_PREFIX`!__
54+
55+
56+
### If I can `make` it there, I'll `make` it anywhere...
57+
58+
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.
59+
60+
#### Setup:
61+
62+
To "bootstrap" the development environment:
63+
64+
```
65+
$ make bootstrap
66+
```
67+
68+
In router's case, this step carries out some extensive dependency management using glide 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.__
69+
70+
71+
#### To build:
72+
73+
```
74+
$ make build
75+
```
76+
77+
Built images will be tagged with the sha of the latest git commit. __This means that for a new image to have its own unique tag, experimental changes should be committed _before_ building. Do this in a branch. Commits can be squashed later when you are done hacking.__
78+
79+
#### To deploy:
80+
81+
```
82+
$ make deploy
83+
```
84+
85+
The deploy target will implicitly build first, then push the built image (which has its own unique tags) to your development registry (i.e. that specified by `DEIS_REGISTRY`). A Kubernetes manifest is prepared, referencing the uniquely tagged image, and that manifest is submitted to your Kubernetes cluster. If a router component is already running in your Kubernetes cluster, it will be deleted and replaced with your build.
86+
87+
To see that the router is running, you can look for its pod(s):
88+
89+
```
90+
$ kubectl get pods --namespace=deis
91+
```
92+
93+
## Trying it Out
94+
95+
To deploy some sample routable applications:
96+
97+
```
98+
$ make examples
99+
```
100+
101+
This will deploy Nginx and Apache to your Kubernetes cluster as if they were user applications.
102+
103+
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:
104+
105+
* nginx.example.com
106+
* apache.example.com
107+
* httpd.example.com
108+
* unknown.example.com
109+
110+
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:
111+
112+
* http://nginx.example.com
113+
* http://apache.example.com
114+
* http://httpd.example.com
115+
116+
Requesting http://unknown.example.com should result in a 404 from the router since no route exists for that domain name.
117+
118+
## How it Works
119+
120+
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 `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.
121+
122+
When generating configuration, the program parses structured data (JSON) found in each service's `routerConfig` annotation. This data describes 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.
123+
124+
Similarly, the router watches its _own_ `routerConfig` annotations to dynamically construct global Nginx configuration.
125+
126+
## License
127+
128+
Copyright 2013, 2014, 2015 Engine Yard, Inc.
129+
130+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>
131+
132+
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

‎_tests/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Tests
2+
3+
This directory is used for functional tests.
4+
5+
The directory is prefixed with an underscore (`_tests`) to prevent Go
6+
tools from automatically running Go code found in this directory.

‎glide.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
package: github.com/deis/router
2+
flatten: true
3+
import:
4+
- package: k8s.io/kubernetes
5+
version: v1.1.1
6+
subpackage: pkg

0 commit comments

Comments
 (0)