Getting Started
Developing for Ingress-Nginx Controller
This document explains how to get started with developing for Ingress-Nginx Controller.
For the really new contributors, who want to contribute to the INGRESS-NGINX project, but need help with understanding some basic concepts, that are needed to work with the Kubernetes ingress resource, here is a link to the New Contributors Guide. This guide contains tips on how a http/https request travels, from a browser or a curl command, to the webserver process running inside a container, in a pod, in a Kubernetes cluster, but enters the cluster via a ingress resource. For those who are familiar with those basic networking concepts like routing of a packet with regards to a http request, termination of connection, reverseproxy etc. etc., you can skip this and move on to the sections below. (or read it anyways just for context and also provide feedbacks if any)
Prerequisites ¶
Install Go 1.14 or later.
Note
The project uses Go Modules
Install Docker (v19.03.0 or later with experimental feature on)
Install kubectl (1.24.0 or higher)
Install Kind
Important
The majority of make tasks run as docker containers
Quick Start ¶
- Fork the repository
- Clone the repository to any location in your work station
- Add a
GO111MODULE
environment variable withexport GO111MODULE=on
- 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
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