Skip to content

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

## Quick Start

### Getting the code

The code must be checked out as a subdirectory of k8s.io, and not github.com.

    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

### Initial developer environment build

Ensure docker experimental features option is enabled for buildx

    $ 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 container

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 nginx-ingress-controller-<unique-pod-id>

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

    $ go get
    $ make dep-ensure

## 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:

    # "gcloud docker" (default) or "docker"
    $ export DOCKER=<docker>

    # "quay.io/kubernetes-ingress-controller" (default), "index.docker.io", or your own registry
    $ export REGISTRY=<your-docker-registry>

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.

    $ make e2e-test-image

You can then make this image available on your minikube host by exporting the image and loading it with the minikube docker context:

    $ docker save nginx-ingress-controller:e2e |  (eval $(minikube docker-env) && docker load)

### Nginx Controller

Build a raw server binary

    $ make build

TODO: add more specific instructions needed for raw server binary.

Build a local container image

    $ TAG=<tag> REGISTRY=$USER/ingress-controller make container

Push the container image to a remote repository

    $ TAG=<tag> REGISTRY=$USER/ingress-controller make push

## Deploying

There are several ways to deploy the ingress controller onto a cluster. Please check the deployment guide

## Testing

To run unit-tests, just run

    $ cd $GOPATH/src/k8s.io/ingress-nginx
    $ make test

If you have access to a Kubernetes cluster, you can also run e2e tests using ginkgo.

    $ cd $GOPATH/src/k8s.io/ingress-nginx
    $ make 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:

    $ 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 `<mytest>_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. All release images are hosted under `gcr.io/google_containers` and tagged according to a semver scheme.

An example release might look like:

    $ make release

Please follow these guidelines to cut a release:

- Update the release 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.