Skip to content

# Developing for NGINX Ingress Controller

This document explains how to get started with developing for NGINX Ingress controller.

## Prerequisites

Install Go 1.14 or later.

Note

The project uses Go Modules

Install Docker (v19.03.0 or later with experimental feature on)

Important

The majority of make tasks run as docker containers

## Quick Start

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

### Local build

Start a local Kubernetes cluster using kind, build and deploy the ingress controller

    make dev-env

- If you are working on the v1.x.x version of this controller, and you want to create a cluster with kubernetes version 1.22, then please visit the documentation for kind, and look for how to set a custom image for the kind node (image: kindest/node...), in the kind config file.

### Testing

Run go unit tests

    make test

Run unit-tests for lua code

    make lua-test

Lua tests are located in the directory `rootfs/etc/nginx/lua/test`

Important

Test files must follow the naming convention `<mytest>_test.lua` or it will be ignored

Run e2e test suite

    make kind-e2e-test

To limit the scope of the tests to execute, we can use the environment variable `FOCUS`

    FOCUS="no-auth-locations" make kind-e2e-test

Note

The variable `FOCUS` defines Ginkgo Focused Specs

Valid values are defined in the describe definition of the e2e tests like Default Backend

The complete list of tests can be found here

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

    export TAG="dev"
    export REGISTRY="$USER"

    make build image

and then publish such version with

    docker push $REGISTRY/controller:$TAG