From d89f23f2f8b065d332c00bfcc6097812ccb650d9 Mon Sep 17 00:00:00 2001 From: Manuel Alejandro de Brito Fontes Date: Tue, 21 Jul 2020 21:31:51 -0400 Subject: [PATCH] Simplify development doc --- docs/development.md | 171 +++++++++++++------------------------------- 1 file changed, 49 insertions(+), 122 deletions(-) diff --git a/docs/development.md b/docs/development.md index 3cba6c0eb..4da173b39 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,162 +1,89 @@ # Developing for NGINX Ingress Controller This document explains how to get started with developing for NGINX Ingress controller. -It includes how to build, test, and release ingress controllers. + +## Prerequisites + +Install [Go 1.14](https://golang.org/dl/) or later. + +!!! note + The project uses [Go Modules](https://github.com/golang/go/wiki/Modules) + +Install [Docker](https://docs.docker.com/engine/install/) + +!!! important + The majority of make tasks run as docker containers ## Quick Start -### Getting the code -The code must be checked out as a subdirectory of k8s.io, and not github.com. +1. Fork the repository +2. Clone the repository to any location in your work station +3. Add a `GO111MODULE` environment variable with `export GO111MODULE=on` +4. Run `go mod download` to install dependencies -``` -mkdir -p $GOPATH/src/k8s.io -cd $GOPATH/src/k8s.io -# Replace "$YOUR_GITHUB_USERNAME" below with your github username -git clone https://github.com/$YOUR_GITHUB_USERNAME/ingress-nginx.git -cd ingress-nginx -``` +### Local build -### Initial developer environment build - -``` -$ make dev-env -``` - -### Updating the deployment - -The nginx controller container image can be rebuilt using: -``` -$ ARCH=amd64 TAG=dev REGISTRY=$USER/ingress-controller make build image -``` - -The image will only be used by pods created after the rebuild. To delete old pods which will cause new ones to spin up: -``` -$ kubectl get pods -n ingress-nginx -$ kubectl delete pod -n ingress-nginx ingress-nginx-controller- -``` - -## Dependencies - -The build uses dependencies in the `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 go 1.13 or newer. - -This will automatically save the dependencies to the `vendor/` directory. +Start a local Kubernetes cluster using [kind](https://kind.sigs.k8s.io/), build and deploy the ingress controller ```console -$ go get -$ make dep-ensure +make dev-env ``` -## Building +### Testing -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: +**Run go unit tests** ```console -# "gcloud docker" (default) or "docker" -$ export DOCKER= - -# "quay.io/kubernetes-ingress-controller" (default), "index.docker.io", or your own registry -$ export REGISTRY= +make test ``` -To find the registry simply run: `docker system info | grep Registry` - -### Building the e2e test image - -The e2e test image can also be built through the Makefile. +**Run unit-tests for lua code** ```console -$ make -C test/e2e-image build +make lua-test ``` -Then you can load the docker image using kind: +Lua tests are located in the directory `rootfs/etc/nginx/lua/test` + +!!! important + Test files must follow the naming convention `_test.lua` or it will be ignored + + +**Run e2e test suite** ```console -$ kind load docker-image --name="ingress-nginx-dev" nginx-ingress-controller:e2e +make kind-e2e-test ``` -### Nginx Controller - -Build a raw server binary -```console -$ make build -``` - -[TODO](https://github.com/kubernetes/ingress-nginx/issues/387): add more specific instructions needed for raw server binary. - -Build a local container image +To limit the scope of the tests to execute, we can use the environment variable `FOCUS` ```console -$ TAG= REGISTRY=$USER/ingress-controller make image +FOCUS="no-auth-locations" make kind-e2e-test ``` -## Deploying +!!! note + The variable `FOCUS` defines Ginkgo [Focused Specs](https://onsi.github.io/ginkgo/#focused-specs) -There are several ways to deploy the ingress controller onto a cluster. -Please check the [deployment guide](./deploy/index.md) +Valid values are defined in the describe definition of the e2e tests like [Default Backend](https://github.com/kubernetes/ingress-nginx/blob/master/test/e2e/defaultbackend/default_backend.go#L29) -## Testing +The compleete list of tests can be found [here](e2e-tests.md) -To run unit-tests, just run +### Custom docker image + +In some cases, it can be useful to build a docker image and publish such an image to a private or custom registry location. + +This can be done setting two environment variables, `REGISTRY` and `TAG` ```console -$ cd $GOPATH/src/k8s.io/ingress-nginx -$ make test +export TAG="dev" +export REGISTRY="$USER" + +make build image ``` -If you have access to a Kubernetes cluster, you can also run e2e tests using ginkgo. +and then publish such version with ```console -$ cd $GOPATH/src/k8s.io/ingress-nginx -$ KIND_CLUSTER_NAME="ingress-nginx-test" make kind-e2e-test +docker push $REGISTRY/controller:$TAG ``` -To set focus to a particular set of tests, a FOCUS flag can be set. - -```console -KIND_CLUSTER_NAME="ingress-nginx-test" FOCUS="no-auth-locations" make kind-e2e-test -``` - -NOTE: if your e2e pod keeps hanging in an ImagePullBackoff, make sure you've made your e2e nginx-ingress-controller image available to minikube as explained in the **Building the e2e test image** section - -To run unit-tests for lua code locally, run: - -```console -$ cd $GOPATH/src/k8s.io/ingress-nginx -$ ./rootfs/etc/nginx/lua/test/up.sh -$ make lua-test -``` - -Lua tests are located in `$GOPATH/src/k8s.io/ingress-nginx/rootfs/etc/nginx/lua/test`. When creating a new test file it must follow the naming convention `_test.lua` or it will be ignored. - -## 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 release -``` - -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 -cherry-picked into a release branch. -* If you're not confident about the stability of the code, -[tag](https://help.github.com/articles/working-with-tags/) it as alpha or beta. -Typically, a release branch should have stable code.