Merge pull request #54 from bprashanth/devel_docs

Expand developer docs

controllers/nginx/Makefile

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

docs/dev/README.md

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

docs/dev/devel.md

@@ -0,0 +1,3 @@
+# Writing Ingress controllers
+
+This doc outlines the basic steps needed to write an Ingress controller.

docs/dev/releases.md

@@ -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.
+
+

docs/dev/setup.md

@@ -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.
+

docs/examples/README.md → examples/README.md

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

examples/deployment/nginx/README.md

@@ -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.
+
+
+

examples/deployment/nginx/default-backend.yaml

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

examples/deployment/nginx/rc.yaml

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