From 86b52fa95739f61725df3df3aadbf49b1848d3d3 Mon Sep 17 00:00:00 2001 From: Fernando Diaz Date: Wed, 2 Aug 2017 23:02:02 -0500 Subject: [PATCH] Add more descriptive steps in Dev Documentation Adds more descriptive steps in the Development Documentation, like more information on obtaining dependencies, building, and deploying an image of the ingress controller. Also adds more descriptive information on deploying as well as some fixes on grammar and spelling. --- docs/dev/README.md | 18 ++- docs/dev/{devel.md => custom_controller.md} | 0 docs/dev/getting_started.md | 141 ++++++++++++++++++++ docs/dev/releases.md | 108 --------------- docs/dev/{setup.md => setup_cluster.md} | 7 +- examples/deployment/nginx/README.md | 24 +++- examples/deployment/nginx/kubeadm/README.md | 2 +- 7 files changed, 178 insertions(+), 122 deletions(-) rename docs/dev/{devel.md => custom_controller.md} (100%) create mode 100644 docs/dev/getting_started.md delete mode 100644 docs/dev/releases.md rename docs/dev/{setup.md => setup_cluster.md} (95%) diff --git a/docs/dev/README.md b/docs/dev/README.md index a8fa4c5121..134d813427 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -1,12 +1,18 @@ -# Ingress development guide +# 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 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. +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](releases.md) an existing controller -* [Setup a cluster](setup.md) to hack at an existing controller -* [Write your own](devel.md) controller +* [Build, test, release](getting_started.md) an existing controller +* [Setup a cluster](setup_cluster.md) to hack at an existing controller +* [Write your own](custom_controller.md) controller diff --git a/docs/dev/devel.md b/docs/dev/custom_controller.md similarity index 100% rename from docs/dev/devel.md rename to docs/dev/custom_controller.md diff --git a/docs/dev/getting_started.md b/docs/dev/getting_started.md new file mode 100644 index 0000000000..f0c5357d0d --- /dev/null +++ b/docs/dev/getting_started.md @@ -0,0 +1,141 @@ +# Getting Started + +This document explains how to get started with developing for Kubernetes Ingress. +It includes how to build, test, and release ingress controllers. + +## Dependencies + +The build uses dependencies in the `ingress/vendor` directory, which +must be installed before building a binary/image. Occasionally, you +might need to update the dependencies. + +This guide requires you to install the[godep](https://github.com/tools/godep)dependency +tool. + +Check the version of `godep` you are using and make sure it is up to date. +```console +$ godep version +godep v74 (linux/amd64/go1.6.1) +``` + +If you have an older version of `godep`, you can update it as follows: +```console +$ cd $GOPATH/src/ingress +$ go get github.com/tools/godep +$ cd $GOPATH/src/github.com/tools/godep +$ go build -o godep *.go +``` + +This will automatically save the dependencies to the `vendor/` directory. +```console +$ cd $GOPATH/src/ingress +$ godep save ./... +``` + +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 dependencies. +To update a particular dependency, eg: Kubernetes: +```console +$ cd $GOPATH/src/k8s.io/ingress +$ godep restore +$ go get -u k8s.io/kubernetes +$ cd $GOPATH/src/k8s.io/kubernetes +$ godep restore +$ cd $GOPATH/src/k8s.io/kubernetes/ingress +$ rm -rf Godeps +$ godep save ./... +$ git [add/remove] as needed +$ git commit +``` + +## Building + +All ingress controllers are built 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. + +In order to use your local Docker, you may need to set the following environment variables: +* export TAG=0.0 # or whatever you want the version to be named +* export DOCKER=docker +* export REGISTRY=index.docker.io + +To find the registry simply run: `docker system info | grep Registry` + +Otherwise by default you will be using the [Google Cloud Platform](https://cloud.google.com/sdk/gcloud/): +* REGISTRY=gcr.io/google_containers +* DOCKER=gcloud docker -- + +### Nginx Controller + +Build a raw server binary +```console +$ make controllers +``` + +[TODO](https://github.com/kubernetes/ingress/issues/387): add more specific instructions needed for raw server binary. + +Build a local container image +```console +$ make docker-build PREFIX=$USER/ingress-controller +``` + +Push the container image to a remote repository +```console +$ make docker-push PREFIX=$USER/ingress-controller +``` + +### GCE Controller + +[TODO](https://github.com/kubernetes/ingress/issues/387): add instructions on building gce controller. + +## Deploying + +There are several ways to deploy the ingress controller onto a cluster. If you don't have a cluster start by +creating one [here](setup_cluster.md). + +* [nginx controller](../../examples/deployment/nginx/README.md) +* [gce controller](../../examples/deployment/gce/README.md) + +## Testing + +To run unit-tests, enter each directory in `controllers/` +```console +$ cd $GOPATH/src/k8s.io/ingress/controllers/ +$ go test ./... +``` + +If you have access to a Kubernetes cluster, you can also run e2e tests using ginko. +```console +$ cd $GOPATH/src/k8s.io/kubernetes +$ ./hack/ginkgo-e2e.sh --ginkgo.focus=Ingress.* --delete-namespace-on-failure=false +``` + +See also [related FAQs](../faq#how-are-the-ingress-controllers-tested). + +[TODO](https://github.com/kubernetes/ingress/issues/5): 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/getting_started.md) +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 +cherry-picked 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. + + diff --git a/docs/dev/releases.md b/docs/dev/releases.md deleted file mode 100644 index cd3aee7c8e..0000000000 --- a/docs/dev/releases.md +++ /dev/null @@ -1,108 +0,0 @@ -# Releases - -This doc explains how to build, test and release ingress controllers. - -## Building - -All ingress controllers are built 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 controllers -``` - -Build a local container image -```console -$ make docker-build TAG=0.0 PREFIX=$USER/ingress-controller -``` - -Push the container image to a remote repository -```console -$ make docker-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/k8s.io/ingress -godep restore -go get -u k8s.io/kubernetes -cd $GOPATH/src/k8s.io/kubernetes -godep restore -cd $GOPATH/src/k8s.io/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 -``` - -See also [related FAQs](../faq#how-are-the-ingress-controllers-tested). - -[TODO](https://github.com/kubernetes/ingress/issues/5): 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. - - diff --git a/docs/dev/setup.md b/docs/dev/setup_cluster.md similarity index 95% rename from docs/dev/setup.md rename to docs/dev/setup_cluster.md index 76e0397eb2..cb82c0483c 100644 --- a/docs/dev/setup.md +++ b/docs/dev/setup_cluster.md @@ -1,9 +1,10 @@ -# Developer setup +# Cluster getting Started This doc outlines the steps needed to setup a local dev cluster within which you -can deploy/test an ingress controller. +can deploy/test an ingress controller. Note that you can also setup the ingress controller +locally. -## Deploy a dev cluster +## Deploy a Development cluster ### Single node local cluster diff --git a/examples/deployment/nginx/README.md b/examples/deployment/nginx/README.md index 7adf49811c..df30d39a8b 100644 --- a/examples/deployment/nginx/README.md +++ b/examples/deployment/nginx/README.md @@ -13,7 +13,7 @@ $ kubectl apply -f default-backend.yaml deployment "default-http-backend" created service "default-http-backend" created -$ kubectl -n kube-system get po +$ kubectl -n kube-system get pods NAME READY STATUS RESTARTS AGE default-http-backend-2657704409-qgwdd 1/1 Running 0 28s ``` @@ -22,23 +22,39 @@ default-http-backend-2657704409-qgwdd 1/1 Running 0 28s You can deploy the controller as follows: +1. Disable the ingress addon: +```console +$ minikube addons disable ingress +``` +2. Use the [docker daemon](https://github.com/kubernetes/minikube/blob/master/docs/reusing_the_docker_daemon.md) +3. [Build the image](../../../docs/dev/getting_started.md) +4. Create the [default-backend](default-backend.yaml): +```console +$ kubectl apply -f default-backend.yaml +``` +5. Change [nginx-ingress-controller.yaml](nginx-ingress-controller.yaml) to use the appropriate image. Local images can be +seen by performing `docker images`. +```yaml +image: : +``` +6. Create the nginx-ingress-controller deployment: ```console $ kubectl apply -f nginx-ingress-controller.yaml deployment "nginx-ingress-controller" created -$ kubectl -n kube-system get po +$ kubectl -n kube-system get pods NAME READY STATUS RESTARTS AGE default-http-backend-2657704409-qgwdd 1/1 Running 0 2m nginx-ingress-controller-873061567-4n3k2 1/1 Running 0 42s ``` Note the default settings of this controller: -* serves a `/healthz` url on port 10254, as both a liveness and readiness probe +* serves a `/healthz` url on port 10254, as a status probe * takes a `--default-backend-service` argument pointing to the Service created above ## Running on a cloud provider -If you're running this ingress controller on a cloudprovider, you should assume +If you're running this ingress controller on a cloud-provider, 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 diff --git a/examples/deployment/nginx/kubeadm/README.md b/examples/deployment/nginx/kubeadm/README.md index 3cb0f0b85c..49bdbf1a7c 100644 --- a/examples/deployment/nginx/kubeadm/README.md +++ b/examples/deployment/nginx/kubeadm/README.md @@ -13,7 +13,7 @@ a 404 page. ## Controller -The Nginx Ingress Controller uses nginx (surprisingly!) to loadbalance requests that are coming to +The Nginx Ingress Controller uses nginx (surprisingly!) to loadbalancer requests that are coming to ports 80 and 443 to Services in the cluster. ```console