Merge pull request #54 from bprashanth/devel_docs
Expand developer docs
This commit is contained in:
commit
0af8cccc7f
10 changed files with 362 additions and 5 deletions
|
@ -2,8 +2,8 @@ all: push
|
|||
|
||||
BUILDTAGS=
|
||||
|
||||
# 0.0 shouldn't clobber any release builds
|
||||
RELEASE?=0.0
|
||||
# Use the 0.0 tag for testing, it shouldn't clobber any release builds
|
||||
RELEASE?=0.8.4
|
||||
PREFIX?=gcr.io/google_containers/nginx-ingress-controller
|
||||
GOOS?=linux
|
||||
|
||||
|
|
12
docs/dev/README.md
Normal file
12
docs/dev/README.md
Normal file
|
@ -0,0 +1,12 @@
|
|||
# Ingress development guide
|
||||
|
||||
This directory is intended to be the canonical source of truth for things like writing and hacking on Ingress controllers. If you find a requirement that this doc does not capture, please submit an issue on github. If you find other docs with references to requirements that are not simply links to this doc, please submit an issue.
|
||||
|
||||
This document is intended to be relative to the branch in which it is found. It is guaranteed that requirements will change over time for the development branch, but release branches of Kubernetes should not change.
|
||||
|
||||
## Navigation
|
||||
|
||||
* [Build, test or release](build.md) an existing controller
|
||||
* [Setup a cluster](setup.md) to hack at an existing controller
|
||||
* [Write your own](devel.md) controller
|
||||
|
3
docs/dev/devel.md
Normal file
3
docs/dev/devel.md
Normal file
|
@ -0,0 +1,3 @@
|
|||
# Writing Ingress controllers
|
||||
|
||||
This doc outlines the basic steps needed to write an Ingress controller.
|
106
docs/dev/releases.md
Normal file
106
docs/dev/releases.md
Normal file
|
@ -0,0 +1,106 @@
|
|||
# Releases
|
||||
|
||||
This doc explains how to build, test and release ingress controllers.
|
||||
|
||||
## Building
|
||||
|
||||
All ingress controllers are build through a Makefile. Depending on your
|
||||
requirements you can build a raw server binary, a local container image,
|
||||
or push an image to a remote repository.
|
||||
|
||||
Build a raw server binary
|
||||
```console
|
||||
$ make controller
|
||||
```
|
||||
|
||||
Build a local container image
|
||||
```console
|
||||
$ make container TAG=0.0 PREFIX=$USER/ingress-controller
|
||||
```
|
||||
|
||||
Push the container image to a remote repository
|
||||
```console
|
||||
$ make push TAG=0.0 PREFIX=$USER/ingress-controller
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
The build should use dependencies in the `ingress/vendor` directory.
|
||||
Occasionally, you might need to update the dependencies.
|
||||
|
||||
```console
|
||||
$ godep version
|
||||
godep v74 (linux/amd64/go1.6.1)
|
||||
$ go version
|
||||
go version go1.6.1 linux/amd64
|
||||
```
|
||||
|
||||
This will automatically save godeps to `vendor/`
|
||||
```console
|
||||
$ godep save ./...
|
||||
```
|
||||
|
||||
If you have an older version of `godep`
|
||||
```console
|
||||
$ go get github.com/tools/godep
|
||||
$ cd $GOPATH/src/github.com/tools/godep
|
||||
$ go build -o godep *.go
|
||||
```
|
||||
|
||||
In general, you can follow [this guide](https://github.com/kubernetes/kubernetes/blob/release-1.5/docs/devel/godep.md#using-godep-to-manage-dependencies)
|
||||
to update godeps. To update a particular dependency, eg: Kubernetes:
|
||||
```console
|
||||
cd $GOPATH/src/github.com/kubernetes/ingress
|
||||
godep restore
|
||||
go get -u github.com/kubernetes/kubernetes
|
||||
cd $GOPATH/src/github.com/kubernetes/kubernetes
|
||||
godep restore
|
||||
cd $GOPATH/src/github/kubernetes/ingress
|
||||
rm -rf Godeps
|
||||
godep save ./...
|
||||
git [add/remove] as needed
|
||||
git commit
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
To run unittets, enter each directory in `controllers/`
|
||||
```console
|
||||
$ cd $GOPATH/src/k8s.io/ingress/controllers/gce
|
||||
$ go test ./...
|
||||
```
|
||||
|
||||
If you have access to a Kubernetes cluster, you can also run e2e tests
|
||||
```console
|
||||
$ cd $GOPATH/src/k8s.io/kubernetes
|
||||
$ ./hack/ginkgo-e2e.sh --ginkgo.focus=Ingress.* --delete-namespace-on-failure=false
|
||||
```
|
||||
|
||||
TODO: add instructions on running integration tests, or e2e against
|
||||
local-up/minikube.
|
||||
|
||||
## Releasing
|
||||
|
||||
All Makefiles will produce a release binary, as shown above. To publish this
|
||||
to a wider Kubernetes user base, push the image to a container registry, like
|
||||
[gcr.io](https://cloud.google.com/container-registry/). All release images are hosted under `gcr.io/google_containers` and
|
||||
tagged according to a [semver](http://semver.org/) scheme.
|
||||
|
||||
An example release might look like:
|
||||
```
|
||||
$ make push TAG=0.8.0 PREFIX=gcr.io/google_containers/glbc
|
||||
```
|
||||
|
||||
Please follow these guidelines to cut a release:
|
||||
|
||||
* Update the [release](https://help.github.com/articles/creating-releases/)
|
||||
page with a short description of the major changes that correspond to a given
|
||||
image tag.
|
||||
* Cut a release branch, if appropriate. Release branches follow the format of
|
||||
`controller-release-version`. Typically, pre-releases are cut from HEAD.
|
||||
All major feature work is done in HEAD. Specific bug fixes are
|
||||
cherrypicked into a release branch.
|
||||
* If you're not confident about the stability of the code, tag it as
|
||||
alpha or beta. Typically, a release branch should have stable code.
|
||||
|
||||
|
102
docs/dev/setup.md
Normal file
102
docs/dev/setup.md
Normal file
|
@ -0,0 +1,102 @@
|
|||
# Developer setup
|
||||
|
||||
This doc outlines the steps needed to setup a local dev cluster within which you
|
||||
can deploy/test an ingress controller.
|
||||
|
||||
## Deploy a dev cluster
|
||||
|
||||
### Single node local cluster
|
||||
|
||||
You can run the nginx ingress controller locally on any node with access to the
|
||||
internet, and the following dependencies: [docker](https://docs.docker.com/engine/getstarted/step_one/), [etcd](https://github.com/coreos/etcd/releases), [golang](https://golang.org/doc/install), [cfssl](https://github.com/cloudflare/cfssl#installation), [openssl](https://www.openssl.org/), [make](https://www.gnu.org/software/make/), [gcc](https://gcc.gnu.org/), [git](https://git-scm.com/download/linux).
|
||||
|
||||
|
||||
Clone the kubernetes repo:
|
||||
```console
|
||||
$ cd $GOPATH/src/k8s.io
|
||||
$ git clone https://github.com/kubernetes/kubernetes.git
|
||||
```
|
||||
|
||||
Add yourself to the docker group, if you haven't done so already (or give
|
||||
local-up-cluster sudo)
|
||||
```
|
||||
$ sudo usermod -aG docker $USER
|
||||
$ sudo reboot
|
||||
..
|
||||
$ docker ps
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
```
|
||||
|
||||
**NB: the next step will bring up Kubernetes daemons directly on your dev
|
||||
machine, no sandbox, iptables rules, routes, loadbalancers, network bridges
|
||||
etc are created on the host.**
|
||||
|
||||
```console
|
||||
$ cd $GOPATH/src/k8s.io/kubernetes
|
||||
$ hack/local-up-cluster.sh
|
||||
```
|
||||
|
||||
Check for Ready nodes
|
||||
```console
|
||||
$ kubectl get no --context=local
|
||||
NAME STATUS AGE VERSION
|
||||
127.0.0.1 Ready 5s v1.6.0-alpha.0.1914+8ccecf93aa6db5-dirty
|
||||
```
|
||||
|
||||
### Minikube cluster
|
||||
|
||||
[Minikube](https://github.com/kubernetes/minikube) is a popular way to bring up
|
||||
a sandboxed local cluster. You will first need to [install](https://github.com/kubernetes/minikube/releases)
|
||||
the minikube binary, then bring up a cluster
|
||||
```console
|
||||
$ minikube up
|
||||
```
|
||||
|
||||
Check for Ready nodes
|
||||
```console
|
||||
$ kubectl get no
|
||||
NAME STATUS AGE VERSION
|
||||
minikube Ready 42m v1.4.6
|
||||
```
|
||||
|
||||
List the existing addons
|
||||
```console
|
||||
$ minikube addons list
|
||||
- addon-manager: enabled
|
||||
- dashboard: enabled
|
||||
- kube-dns: enabled
|
||||
- heapster: disabled
|
||||
```
|
||||
|
||||
If this list already contains the ingress controller, you don't need to
|
||||
redeploy it. If the addon controller is disabled, you can enable it with
|
||||
```console
|
||||
$ minikube enable addons ingress
|
||||
```
|
||||
|
||||
If the list *does not* contain the ingress controller, you can either update
|
||||
minikube, or deploy it yourself as shown in the next section.
|
||||
|
||||
## Deploy the ingress controller
|
||||
|
||||
You can deploy an ingress controller on the cluster setup in the previous step
|
||||
[like this](../../examples/deployment).
|
||||
|
||||
## Run against a remote cluster
|
||||
|
||||
If the controller you're interested in using supports a "dry-run" flag, you can
|
||||
run it on any machine that has `kubectl` access to a remote cluster. Eg:
|
||||
```console
|
||||
$ cd $GOPATH/k8s.io/ingress/controllers/gce
|
||||
$ glbc --help
|
||||
--running-in-cluster Optional, if this controller is running in a kubernetes cluster, use the
|
||||
pod secrets for creating a Kubernetes client. (default true)
|
||||
|
||||
$ ./glbc --running-in-cluster=false
|
||||
I1210 17:49:53.202149 27767 main.go:179] Starting GLBC image: glbc:0.8.0, cluster name
|
||||
```
|
||||
|
||||
Note that this is equivalent to running the ingress controller on your local
|
||||
machine, so if you already have an ingress controller running in the remote
|
||||
cluster, they will fight for the same ingress.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Ingress developer guide
|
||||
|
||||
|
|
@ -6,6 +6,7 @@ A catalog of examples on how to run, configure and scale Ingress.
|
|||
|
||||
Name | Description | Platform | Complexity Level
|
||||
-----| ----------- | ---------- | ----------------
|
||||
Deployment | basic deployment of controllers | * | Beginner
|
||||
TLS termination | terminate TLS at the ingress controller | * | Beginner
|
||||
Name based virtual hosting | `Host` header routing | * | Beginner
|
||||
Path routing | URL regex routing | * | Beginner
|
49
examples/deployment/nginx/README.md
Normal file
49
examples/deployment/nginx/README.md
Normal file
|
@ -0,0 +1,49 @@
|
|||
# Deploying an Nginx Ingress controller
|
||||
|
||||
This example aims to demonstrate the deployment of an nginx ingress controller.
|
||||
|
||||
## Default Backend
|
||||
|
||||
The default backend is a Service capable of handling all url paths and hosts the
|
||||
nginx controller doesn't understand. This most basic implementation just returns
|
||||
a 404 page:
|
||||
```console
|
||||
$ kubectl create -f default-backend.yaml
|
||||
replicationcontroller "default-http-backend" created
|
||||
|
||||
$ kubectl expose rc default-http-backend --port=80 --target-port=8080 --name=default-http-backend
|
||||
service "default-http-backend" exposed
|
||||
|
||||
$ kubectl get po
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
default-http-backend-ppqdj 1/1 Running 0 1m
|
||||
```
|
||||
|
||||
## Controller
|
||||
|
||||
You can deploy the controller as follows:
|
||||
|
||||
```console
|
||||
$ kubectl create -f rc.yaml
|
||||
replicationcontroller "nginx-ingress-controller" created
|
||||
|
||||
$ kubectl get po
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
default-http-backend-ppqdj 1/1 Running 0 1m
|
||||
nginx-ingress-controller-vbgf9 0/1 ContainerCreating 0 2s
|
||||
```
|
||||
|
||||
Note the default settings of this controller:
|
||||
* serves a `/healthz` url on port 10254, as both a liveness and readiness probe
|
||||
* takes a `--default-backend-service` arg pointing to a Service, created above
|
||||
|
||||
## Running on a cloud provider
|
||||
|
||||
If you're running this ingress controller on a cloudprovider, you should assume
|
||||
the provider also has a native Ingress controller and set the annotation
|
||||
`kubernetes.io/ingress.class: nginx` in all Ingresses meant for this controller.
|
||||
You might also need to open a firewall-rule for ports 80/443 of the nodes the
|
||||
controller is running on.
|
||||
|
||||
|
||||
|
36
examples/deployment/nginx/default-backend.yaml
Normal file
36
examples/deployment/nginx/default-backend.yaml
Normal file
|
@ -0,0 +1,36 @@
|
|||
apiVersion: v1
|
||||
kind: ReplicationController
|
||||
metadata:
|
||||
name: default-http-backend
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
app: default-http-backend
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: default-http-backend
|
||||
spec:
|
||||
terminationGracePeriodSeconds: 60
|
||||
containers:
|
||||
- name: default-http-backend
|
||||
# Any image is permissable as long as:
|
||||
# 1. It serves a 404 page at /
|
||||
# 2. It serves 200 on a /healthz endpoint
|
||||
image: gcr.io/google_containers/defaultbackend:1.0
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /healthz
|
||||
port: 8080
|
||||
scheme: HTTP
|
||||
initialDelaySeconds: 30
|
||||
timeoutSeconds: 5
|
||||
ports:
|
||||
- containerPort: 8080
|
||||
resources:
|
||||
limits:
|
||||
cpu: 10m
|
||||
memory: 20Mi
|
||||
requests:
|
||||
cpu: 10m
|
||||
memory: 20Mi
|
51
examples/deployment/nginx/rc.yaml
Normal file
51
examples/deployment/nginx/rc.yaml
Normal file
|
@ -0,0 +1,51 @@
|
|||
apiVersion: v1
|
||||
kind: ReplicationController
|
||||
metadata:
|
||||
name: nginx-ingress-controller
|
||||
labels:
|
||||
k8s-app: nginx-ingress-lb
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
k8s-app: nginx-ingress-lb
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
k8s-app: nginx-ingress-lb
|
||||
name: nginx-ingress-lb
|
||||
spec:
|
||||
terminationGracePeriodSeconds: 60
|
||||
containers:
|
||||
- image: gcr.io/google_containers/nginx-ingress-controller:0.8.3
|
||||
name: nginx-ingress-lb
|
||||
imagePullPolicy: Always
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /healthz
|
||||
port: 10254
|
||||
scheme: HTTP
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /healthz
|
||||
port: 10254
|
||||
scheme: HTTP
|
||||
initialDelaySeconds: 10
|
||||
timeoutSeconds: 1
|
||||
# use downward API
|
||||
env:
|
||||
- name: POD_NAME
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: metadata.name
|
||||
- name: POD_NAMESPACE
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: metadata.namespace
|
||||
ports:
|
||||
- containerPort: 80
|
||||
hostPort: 80
|
||||
- containerPort: 443
|
||||
hostPort: 443
|
||||
args:
|
||||
- /nginx-ingress-controller
|
||||
- --default-backend-service=$(POD_NAMESPACE)/default-http-backend
|
Loading…
Reference in a new issue