DevFW-CICD/ingress-nginx-helm
16
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #1065 from diazjf/master

Browse source 
Add more descriptive steps in Dev Documentation
This commit is contained in:
Manuel Alejandro de Brito Fontes 2017-08-03 20:43:42 -04:00 committed by GitHub
commit eccbe2e530
6 changed files with 172 additions and 121 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
docs/dev/README.md
View file

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

0
docs/dev/devel.md → docs/dev/custom-controller.md
View file

140
docs/dev/getting-started.md Normal file
View file

@ -0,0 +1,140 @@
# 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:
```console
# "gcloud docker" (default) or "docker"
$ export DOCKER=<docker>
# "gcr.io/google_containers" (default), "index.docker.io", or your own registry
$ export REGISTRY=<your-docker-registry>
```
To find the registry simply run: `docker system info | grep Registry`
### 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 TAG=<tag> PREFIX=$USER/ingress-controller
```
Push the container image to a remote repository
```console
$ make docker-push TAG=<tag> 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/<controller>
$ 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.

108
docs/dev/releases.md
View file

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

7
docs/dev/setup.md → docs/dev/setup-cluster.md
View file

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

20
examples/deployment/nginx/README.md
View file

@ -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,35 @@ 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. 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: <IMAGE-NAME>:<TAG>
```
5. 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