102 lines
3.4 KiB
Markdown
102 lines
3.4 KiB
Markdown
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](https://github.com/kubernetes/ingress-nginx/blob/main/NEW_CONTRIBUTOR.md).
|
|
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](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/) (v19.03.0 or later with experimental feature on)
|
|
|
|
Install [kubectl](https://kubernetes.io/docs/tasks/tools/) (1.24.0 or higher)
|
|
|
|
Install [Kind](https://kind.sigs.k8s.io/)
|
|
|
|
!!! 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](https://kind.sigs.k8s.io/), build and deploy the ingress controller
|
|
|
|
```console
|
|
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](https://kind.sigs.k8s.io/docs/user/configuration/#a-note-on-cli-parameters-and-configuration-files), 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**
|
|
|
|
```console
|
|
make test
|
|
```
|
|
|
|
**Run unit-tests for lua code**
|
|
|
|
```console
|
|
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**
|
|
|
|
```console
|
|
make kind-e2e-test
|
|
```
|
|
|
|
To limit the scope of the tests to execute, we can use the environment variable `FOCUS`
|
|
|
|
```console
|
|
FOCUS="no-auth-locations" make kind-e2e-test
|
|
```
|
|
|
|
!!! note
|
|
The variable `FOCUS` defines Ginkgo [Focused Specs](https://onsi.github.io/ginkgo/#focused-specs)
|
|
|
|
Valid values are defined in the describe definition of the e2e tests like [Default Backend](https://github.com/kubernetes/ingress-nginx/blob/main/test/e2e/defaultbackend/default_backend.go#L29)
|
|
|
|
The complete list of tests can be found [here](../e2e-tests.md)
|
|
|
|
### 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
|
|
export TAG="dev"
|
|
export REGISTRY="$USER"
|
|
|
|
make build image
|
|
```
|
|
|
|
and then publish such version with
|
|
|
|
```console
|
|
docker push $REGISTRY/controller:$TAG
|
|
```
|