DevFW-CICD/ingress-nginx-helm
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge remote-tracking branch 'base/master' into fix/collect-metrics-if-metrics-per-host-false

Browse source
This commit is contained in:
Christian Hoffmeister 2020-03-13 07:17:49 +01:00
commit 19770f5b41
2674 changed files with 371760 additions and 171868 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/deploy/baremetal.md
View file

@ -33,9 +33,7 @@ MetalLB can be deployed either with a simple Kubernetes manifest or with Helm. T
was deployed following the [Installation][metallb-install] instructions.
MetalLB requires a pool of IP addresses in order to be able to take ownership of the `ingress-nginx` Service. This pool
can be defined in a ConfigMap named `config` located in the same namespace as the MetalLB controller. In the simplest
possible scenario, the pool is composed of the IP addresses of Kubernetes nodes, but IP addresses can also be handed out
by a DHCP server.
can be defined in a ConfigMap named `config` located in the same namespace as the MetalLB controller. This pool of IPs **must** be dedicated to MetalLB's use, you can't reuse the Kubernetes node IPs or IPs handed out by a DHCP server.
!!! example
Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal
@ -64,14 +62,14 @@ by a DHCP server.
- name: default
protocol: layer2
addresses:
- 203.0.113.2-203.0.113.3
- 203.0.113.10-203.0.113.15
```
```console
$ kubectl -n ingress-nginx get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)
default-http-backend ClusterIP 10.0.64.249 <none> 80/TCP
ingress-nginx LoadBalancer 10.0.220.217 203.0.113.3 80:30100/TCP,443:30101/TCP
ingress-nginx LoadBalancer 10.0.220.217 203.0.113.10 80:30100/TCP,443:30101/TCP
```
As soon as MetalLB sets the external IP address of the `ingress-nginx` LoadBalancer Service, the corresponding entries
@ -367,7 +365,7 @@ address of all nodes running the NGINX Ingress controller.
[taints]: https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/
[daemonset]: https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/
[dnspolicy]: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy
[cli-args]: ../../user-guide/cli-arguments/
[cli-args]: ../user-guide/cli-arguments.md
## Using a self-provisioned edge

142
docs/deploy/index.md
View file

@ -16,37 +16,33 @@
## Prerequisite Generic Deployment Command
The following **Mandatory Command** is required for all deployments.
!!! attention
These commands depend on having kubectl version 1.14 or newer.
!!! attention
The default configuration watches Ingress object from all the namespaces.
The default configuration watches Ingress object from *all the namespaces*.
To change this behavior use the flag `--watch-namespace` to limit the scope to a particular namespace.
!!! warning
If multiple Ingresses define different paths for the same host, the ingress controller will merge the definitions.
!!! attention
If you're using GKE you need to initialize your user as a cluster-admin with the following command:
```console
kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole cluster-admin \
--user $(gcloud config get-value account)
```
The following **Mandatory Command** is required for all deployments.
```console
kubectl create namespace ingress-nginx
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/mandatory.yaml
```
```console
cat << EOF > kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: ingress-nginx
bases:
- github.com/kubernetes/ingress-nginx/deploy/cluster-wide
- # provider-specific, see below
EOF
```
!!! tip
If you are using a Kubernetes version previous to 1.14, you need to change `kubernetes.io/os` to `beta.kubernetes.io/os` at line 217 of [mandatory.yaml](https://github.com/kubernetes/ingress-nginx/blob/master/deploy/static/mandatory.yaml#L217), see [Labels details](https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/).
### Provider Specific Steps
There are cloud provider specific kustomize bases.
There are cloud provider specific yaml files.
#### Docker for Mac
@ -54,7 +50,11 @@ Kubernetes is available in Docker for Mac (from [version 18.06.0-ce](https://doc
[enable]: https://docs.docker.com/docker-for-mac/#kubernetes
Add `github.com/kubernetes/ingress-nginx/deploy/cloud-generic` to the `bases` list in `kustomization.yaml` and run `kubectl apply --kustomize .`.
Create a service
```console
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/cloud-generic.yaml
```
#### minikube
@ -69,16 +69,15 @@ For development:
1. Disable the ingress addon:
```console
$ minikube addons disable ingress
minikube addons disable ingress
```
2. Execute `make dev-env`
3. Confirm the `nginx-ingress-controller` deployment exists:
```console
$ kubectl get pods -n ingress-nginx
$ kubectl get pods -n ingress-nginx
NAME READY STATUS RESTARTS AGE
default-http-backend-66b447d9cf-rrlf9 1/1 Running 0 12s
nginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s
```
@ -95,57 +94,30 @@ This setup requires to choose in which layer (L4 or L7) we want to configure the
- [Layer 4](https://en.wikipedia.org/wiki/OSI_model#Layer_4:_Transport_Layer): use TCP as the listener protocol for ports 80 and 443.
- [Layer 7](https://en.wikipedia.org/wiki/OSI_model#Layer_7:_Application_Layer): use HTTP as the listener protocol for port 80 and terminate TLS in the ELB
Check that no change is necessary with regards to the ELB idle timeout. In some scenarios, users may want to modify the ELB idle timeout, so please check the [ELB Idle Timeouts section](#elb-idle-timeouts) for additional information. If a change is required, users will need to override the value of the annotation `service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout` on the service object.
To do this, create a patch file which will replace the annotation.
```
cat << EOF > elb-timeout.yaml
kind: Service
apiVersion: v1
metadata:
name: ingress-nginx
annotations:
service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "3600" # Recommended value for WebSockets
EOF
```
After creating the patch file, reference it in your `kustomization.yaml`:
```yaml
patchesStrategicMerge:
- elb-timeout.yaml
```
For L4:
To deploy the default example, add the base ` github.com/kubernetes/ingress-nginx/deploy/aws/l4` and then run `kubectl apply --kustomize .`
Check that no change is necessary with regards to the ELB idle timeout. In some scenarios, users may want to modify the ELB idle timeout, so please check the [ELB Idle Timeouts section](#elb-idle-timeouts) for additional information. If a change is required, users will need to update the value of `service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout` in `provider/aws/service-l4.yaml`
Then execute:
```console
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/aws/service-l4.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/aws/patch-configmap-l4.yaml
```
For L7:
Create a a patch that will annotate the ingress-controller's service with your ssl certificate id.
Change line of the file `provider/aws/service-l7.yaml` replacing the dummy id with a valid one `"arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"`
Check that no change is necessary with regards to the ELB idle timeout. In some scenarios, users may want to modify the ELB idle timeout, so please check the [ELB Idle Timeouts section](#elb-idle-timeouts) for additional information. If a change is required, users will need to update the value of `service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout` in `provider/aws/service-l7.yaml`
Then execute:
```console
cat << EOF > elb-ssl.yaml
kind: Service
apiVersion: v1
metadata:
name: ingress-nginx
annotations:
# replace with the correct value of the generated certificate in the AWS console
service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"
EOF
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/aws/service-l7.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/aws/patch-configmap-l7.yaml
```
Reference this patch in your `kustomization.yaml`:
```yaml
patchesStrategicMerge:
- elb-ssl.yaml
```
Then add the l7 base, `github.com/kubernetes/ingress-nginx/deploy/aws/l7` and execute `kubectl apply --kustomize .`
This example creates an ELB with just two listeners, one in port 80 and another in port 443
![Listeners](../images/elb-l7-listener.png)
@ -161,31 +133,33 @@ More information with regards to idle timeouts for your Load Balancer can be fou
##### Network Load Balancer (NLB)
This type of load balancer is supported since v1.10.0 as an ALPHA feature. Use the base `github.com/kubernetes/ingress-nginx/deploy/aws/nlb` and execute `kubectl apply --kustomize .`
This type of load balancer is supported since v1.10.0 as an ALPHA feature.
```console
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/aws/service-nlb.yaml
```
#### GCE-GKE
!!! attention
If you're using GKE you need to initialize your user as a cluster-admin with the following command:
```kubectl create clusterrolebinding cluster-admin-binding --clusterrole cluster-admin --user $(gcloud config get-value account)```
Use the base `github.com/kubernetes/ingress-nginx/deploy/cloud-generic` and execute `kubectl apply --kustomize .`
```console
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/cloud-generic.yaml
```
**Important Note:** proxy protocol is not supported in GCE/GKE
#### Azure
Use the base `github.com/kubernetes/ingress-nginx/deploy/cloud-generic` and execute `kubectl apply --kustomize .`
```console
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/cloud-generic.yaml
```
#### Bare-metal
Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport):
Use the base `github.com/kubernetes/ingress-nginx/deploy/baremetal` and execute `kubectl apply --kustomize .`
```console
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/provider/baremetal/service-nodeport.yaml
```
!!! tip
For extended notes regarding deployments on bare-metal, see [Bare-metal considerations](./baremetal.md).
@ -208,20 +182,31 @@ To detect which version of the ingress controller is running, exec into the pod
```console
POD_NAMESPACE=ingress-nginx
POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/name=ingress-nginx -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version
```
## Using Helm
NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [stable/nginx-ingress](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) from the official charts repository.
NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [stable/nginx-ingress](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) from the official charts repository.
To install the chart with the release name `my-nginx`:
```console
helm install stable/nginx-ingress --name my-nginx
helm install my-nginx stable/nginx-ingress
```
If the kubernetes cluster has RBAC enabled, then run:
```console
helm install my-nginx stable/nginx-ingress --set rbac.create=true
```
If you are using [Helm 2](https://v2.helm.sh/) then specify release name using `--name` flag
```console
helm install stable/nginx-ingress --name my-nginx
```
or
```console
helm install stable/nginx-ingress --name my-nginx --set rbac.create=true
```
@ -232,4 +217,3 @@ Detect installed version:
POD_NAME=$(kubectl get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it $POD_NAME -- /nginx-ingress-controller --version
```

2
docs/deploy/upgrade.md
View file

@ -33,7 +33,7 @@ The easiest way to do this is e.g. (do note you may need to change the name para
```
kubectl set image deployment/nginx-ingress-controller \
nginx-ingress-controller=nginx:quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.18.0
nginx-ingress-controller=quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.30.0
```
For interactive editing, use `kubectl edit deployment nginx-ingress-controller`.

4
docs/deploy/validating-webhook.md
View file

@ -148,7 +148,7 @@ webhooks:
- name: validate.nginx.ingress.kubernetes.io
rules:
- apiGroups:
- extensions
- networking.k8s.io/v1beta1
apiVersions:
- v1beta1
operations:
@ -161,7 +161,7 @@ webhooks:
service:
namespace: ingress-nginx
name: ingress-validation-webhook
path: /extensions/v1beta1/ingress
path: /networking.k8s.io/v1beta1/ingress
caBundle: <pem encoded ca cert that signs the server cert used by the webhook>
```

57
docs/development.md
View file

@ -19,10 +19,7 @@ cd ingress-nginx
### Initial developer environment build
>**Prequisites**: Minikube must be installed.
See [releases](https://github.com/kubernetes/minikube/releases) for installation instructions.
If you are using **MacOS** and deploying to **minikube**, the following command will build the local nginx controller container image and deploy the ingress controller onto a minikube cluster with RBAC enabled in the namespace `ingress-nginx`:
Ensure docker experimental features option is enabled for [buildx](https://docs.docker.com/buildx/working-with-buildx/)
```
$ make dev-env
@ -47,34 +44,13 @@ 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 the [dep](https://github.com/golang/dep) dependency tool.
Check the version of `dep` you are using and make sure it is up to date.
```console
$ dep version
dep:
version : devel
build date :
git hash :
go version : go1.9
go compiler : gc
platform : linux/amd64
```
If you have an older version of `dep`, you can update it as follows:
```console
$ go get -u github.com/golang/dep
```
This guide requires you to install go 1.13 or newer.
This will automatically save the dependencies to the `vendor/` directory.
```console
$ cd $GOPATH/src/k8s.io/ingress-nginx
$ dep ensure
$ dep ensure -update
$ dep prune
$ go get
$ make dep-ensure
```
## Building
@ -95,6 +71,21 @@ $ 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.
```console
$ 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:
```console
$ docker save nginx-ingress-controller:e2e | (eval $(minikube docker-env) && docker load)
```
### Nginx Controller
Build a raw server binary
@ -107,19 +98,19 @@ $ make build
Build a local container image
```console
$ TAG=<tag> REGISTRY=$USER/ingress-controller make docker-build
$ TAG=<tag> REGISTRY=$USER/ingress-controller make container
```
Push the container image to a remote repository
```console
$ TAG=<tag> REGISTRY=$USER/ingress-controller make docker-push
$ 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](./deploy)
Please check the [deployment guide](../deploy/)
## Testing
@ -137,6 +128,8 @@ $ 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:
```console
@ -145,7 +138,7 @@ $ ./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.
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

434
docs/e2e-tests.md Normal file
View file

@ -0,0 +1,434 @@
# e2e test suite for [NGINX Ingress Controller](https://github.com/kubernetes/ingress-nginx/tree/master/)
### [[Default Backend] change default settings](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/with_hosts.go#L31)
- [should apply the annotation to the default backend](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/with_hosts.go#L39)
### [[Default Backend]](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/default_backend.go#L29)
- [should return 404 sending requests when only a default backend is running](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/default_backend.go#L32)
- [enables access logging for default backend](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/default_backend.go#L87)
- [disables access logging for default backend](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/default_backend.go#L101)
### [[Default Backend] custom service](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/custom_default_backend.go#L32)
- [uses custom default backend that returns 200 as status code](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/custom_default_backend.go#L35)
### [[Default Backend] SSL](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/ssl.go#L26)
- [should return a self generated SSL certificate](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/defaultbackend/ssl.go#L29)
### [[TCP] tcp-services](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/tcpudp/tcp.go#L35)
- [should expose a TCP service](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/tcpudp/tcp.go#L38)
- [should expose an ExternalName TCP service](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/tcpudp/tcp.go#L92)
### [auth-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L36)
- [should return status code 200 when no authentication is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L43)
- [should return status code 503 when authentication is configured with an invalid secret](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L62)
- [should return status code 401 when authentication is configured but Authorization header is not configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L86)
- [should return status code 401 when authentication is configured and Authorization header is sent with invalid credentials](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L113)
- [should return status code 200 when authentication is configured and Authorization header is sent](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L141)
- [should return status code 200 when authentication is configured with a map and Authorization header is sent](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L168)
- [should return status code 401 when authentication is configured with invalid content and Authorization header is sent](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L196)
- [should set snippet 'proxy_set_header My-Custom-Header 42;' when external auth is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L235)
- [should not set snippet 'proxy_set_header My-Custom-Header 42;' when external auth is not configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L253)
- [should set 'proxy_set_header My-Custom-Header 42;' when auth-headers are set](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L270)
- [should set cache_key when external auth cache is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L291)
- [retains cookie set by external authentication server](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L313)
- [should return status code 200 when signed in](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L382)
- [should redirect to signin url when not signed in](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L391)
- [should return status code 200 when signed in after auth backend is deleted ](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L447)
- [should deny login for different location on same server](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L466)
- [should deny login for different servers](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L494)
- [should redirect to signin url when not signed in](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/auth.go#L522)
### [proxy-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L27)
- [should set proxy_redirect to off](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L35)
- [should set proxy_redirect to default](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L50)
- [should set proxy_redirect to hello.com goodbye.com](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L65)
- [should set proxy client-max-body-size to 8m](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L80)
- [should not set proxy client-max-body-size to incorrect value](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L94)
- [should set valid proxy timeouts](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L108)
- [should not set invalid proxy timeouts](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L126)
- [should turn on proxy-buffering](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L144)
- [should turn off proxy-request-buffering](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L163)
- [should build proxy next upstream](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L177)
- [should build proxy next upstream using configmap values](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L195)
- [should setup proxy cookies](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L214)
- [should change the default proxy HTTP version](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxy.go#L230)
### [affinity session-cookie-name](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L34)
- [should set sticky cookie SERVERID](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L41)
- [should change cookie name on ingress definition change](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L64)
- [should set the path to /something on the generated cookie](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L100)
- [does not set the path to / on the generated cookie if there's more than one rule referring to the same backend](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L123)
- [should set cookie with expires](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L185)
- [should work with use-regex annotation and session-cookie-path](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L217)
- [should warn user when use-regex is true and session-cookie-path is not set](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L242)
- [should not set affinity across all server locations when using separate ingresses](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L269)
- [should set sticky cookie without host](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/affinity.go#L301)
### [mirror-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/mirror.go#L28)
- [should set mirror-target to http://localhost/mirror](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/mirror.go#L36)
- [should set mirror-target to https://test.env.com/$request_uri](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/mirror.go#L51)
- [should disable mirror-request-body](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/mirror.go#L67)
### [canary-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L35)
- [should response with a 200 status from the mainline upstream when requests are made to the mainline ingress](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L47)
- [should return 404 status for requests to the canary if no matching ingress is found](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L79)
- [should return the correct status codes when endpoints are unavailable](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L106)
- [should route requests to the correct upstream if mainline ingress is created before the canary ingress](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L160)
- [should route requests to the correct upstream if mainline ingress is created after the canary ingress](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L205)
- [should route requests to the correct upstream if the mainline ingress is modified](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L249)
- [should route requests to the correct upstream if the canary ingress is modified](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L306)
- [should route requests to the correct upstream](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L361)
- [should route requests to the correct upstream](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L415)
- [should route requests to the correct upstream](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L479)
- [should route requests to the correct upstream](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L518)
- [should route requests to the correct upstream](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L573)
- [should not use canary as a catch-all server](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L629)
- [should not use canary with domain as a server](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L657)
- [does not crash when canary ingress has multiple paths to the same non-matching backend](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/canary.go#L681)
### [force-ssl-redirect](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/forcesslredirect.go#L27)
- [should redirect to https](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/forcesslredirect.go#L34)
### [http2-push-preload](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/http2pushpreload.go#L27)
- [enable the http2-push-preload directive](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/http2pushpreload.go#L34)
### [proxy-ssl-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxyssl.go#L29)
- [should set valid proxy-ssl-secret](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxyssl.go#L36)
- [should set valid proxy-ssl-secret, proxy-ssl-verify to on, and proxy-ssl-verify-depth to 2](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxyssl.go#L51)
- [should set valid proxy-ssl-secret, proxy-ssl-ciphers to HIGH:!AES](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxyssl.go#L68)
- [should set valid proxy-ssl-secret, proxy-ssl-protocols](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/proxyssl.go#L84)
### [modsecurity owasp](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/modsecurity.go#L26)
- [should enable modsecurity](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/modsecurity.go#L33)
- [should enable modsecurity with transaction ID and OWASP rules](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/modsecurity.go#L51)
- [should disable modsecurity](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/modsecurity.go#L72)
- [should enable modsecurity with snippet](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/modsecurity.go#L89)
### [backend-protocol - GRPC](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/grpc.go#L38)
- [should use grpc_pass in the configuration file](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/grpc.go#L41)
- [should return OK for service with backend protocol GRPC](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/grpc.go#L66)
- [should return OK for service with backend protocol GRPCS](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/grpc.go#L124)
### [cors-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/cors.go#L28)
- [should enable cors](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/cors.go#L35)
- [should set cors methods to only allow POST, GET](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/cors.go#L60)
- [should set cors max-age](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/cors.go#L76)
- [should disable cors allow credentials](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/cors.go#L92)
- [should allow origin for cors](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/cors.go#L108)
- [should allow headers for cors](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/cors.go#L124)
### [influxdb-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/influxdb.go#L38)
- [should send the request metric to the influxdb server](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/influxdb.go#L47)
### [client-body-buffer-size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/clientbodybuffersize.go#L27)
- [should set client_body_buffer_size to 1000](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/clientbodybuffersize.go#L34)
- [should set client_body_buffer_size to 1K](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/clientbodybuffersize.go#L49)
- [should set client_body_buffer_size to 1k](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/clientbodybuffersize.go#L64)
- [should set client_body_buffer_size to 1m](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/clientbodybuffersize.go#L79)
- [should set client_body_buffer_size to 1M](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/clientbodybuffersize.go#L94)
- [should not set client_body_buffer_size to invalid 1b](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/clientbodybuffersize.go#L109)
### [default-backend](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/default_backend.go#L29)
- [should use a custom default backend as upstream](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/default_backend.go#L37)
### [connection-proxy-header](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/connection.go#L29)
- [set connection header to keep-alive](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/connection.go#L36)
### [upstream-vhost](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/upstreamvhost.go#L27)
- [set host to upstreamvhost.bar.com](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/upstreamvhost.go#L34)
### [custom-http-errors](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/customhttperrors.go#L34)
- [configures Nginx correctly](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/customhttperrors.go#L41)
### [server-snippet](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/serversnippet.go#L27)
- [add valid directives to server via server snippet](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/serversnippet.go#L34)
### [rewrite-target use-regex enable-rewrite-log](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/rewrite.go#L30)
- [should write rewrite logs](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/rewrite.go#L37)
- [should use correct longest path match](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/rewrite.go#L66)
- [should use ~* location modifier if regex annotation is present](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/rewrite.go#L110)
- [should fail to use longest match for documented warning](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/rewrite.go#L156)
- [should allow for custom rewrite parameters](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/rewrite.go#L188)
### [app-root](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/approot.go#L28)
- [should redirect to /foo](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/approot.go#L35)
### [whitelist-source-range](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/ipwhitelist.go#L26)
- [should set valid ip whitelist range](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/ipwhitelist.go#L33)
### [enable-access-log enable-rewrite-log](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/log.go#L27)
- [set access_log off](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/log.go#L34)
- [set rewrite_log on](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/log.go#L49)
### [x-forwarded-prefix](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/xforwardedprefix.go#L28)
- [should set the X-Forwarded-Prefix to the annotation value](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/xforwardedprefix.go#L35)
- [should not add X-Forwarded-Prefix if the annotation value is empty](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/xforwardedprefix.go#L57)
### [configuration-snippet](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/snippet.go#L27)
- [ in all locations](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/snippet.go#L34)
### [backend-protocol - FastCGI](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fastcgi.go#L31)
- [should use fastcgi_pass in the configuration file](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fastcgi.go#L38)
- [should add fastcgi_index in the configuration file](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fastcgi.go#L55)
- [should add fastcgi_param in the configuration file](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fastcgi.go#L72)
- [should return OK for service with backend protocol FastCGI](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fastcgi.go#L105)
### [from-to-www-redirect](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fromtowwwredirect.go#L32)
- [should redirect from www HTTP to HTTP](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fromtowwwredirect.go#L39)
- [should redirect from www HTTPS to HTTPS](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/fromtowwwredirect.go#L65)
### [permanen-redirect permanen-redirect-code](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/redirect.go#L30)
- [should respond with a standard redirect code](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/redirect.go#L33)
- [should respond with a custom redirect code](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/redirect.go#L62)
### [upstream-hash-by-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/upstreamhashby.go#L76)
- [should connect to the same pod](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/upstreamhashby.go#L83)
- [should connect to the same subset of pods](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/upstreamhashby.go#L92)
### [backend-protocol](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/backendprotocol.go#L27)
- [should set backend protocol to https:// and use proxy_pass](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/backendprotocol.go#L34)
- [should set backend protocol to grpc:// and use grpc_pass](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/backendprotocol.go#L49)
- [should set backend protocol to grpcs:// and use grpc_pass](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/backendprotocol.go#L64)
- [should set backend protocol to '' and use fastcgi_pass](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/backendprotocol.go#L79)
- [should set backend protocol to '' and use ajp_pass](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/backendprotocol.go#L94)
### [satisfy](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/satisfy.go#L34)
- [should configure satisfy directive correctly](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/satisfy.go#L41)
- [should allow multiple auth with satisfy any](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/satisfy.go#L83)
### [server-alias](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/alias.go#L29)
- [should return status code 200 for host 'foo' and 404 for 'bar'](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/alias.go#L36)
- [should return status code 200 for host 'foo' and 'bar'](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/alias.go#L62)
### [ssl-ciphers](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/sslciphers.go#L27)
- [should change ssl ciphers](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/sslciphers.go#L34)
### [auth-tls-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/authtls.go#L30)
- [should set valid auth-tls-secret](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/authtls.go#L37)
- [should set valid auth-tls-secret, sslVerify to off, and sslVerifyDepth to 2](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/authtls.go#L73)
- [should set valid auth-tls-secret, pass certificate to upstream, and error page](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/annotations/authtls.go#L103)
### [[Status] status update](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/status/update.go#L37)
- [should update status field after client-go reconnection](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/status/update.go#L42)
### [Debug CLI](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/dbg/main.go#L29)
- [should list the backend servers](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/dbg/main.go#L37)
- [should get information for a specific backend server](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/dbg/main.go#L56)
- [should produce valid JSON for /dbg general](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/dbg/main.go#L85)
### [[Memory Leak] Dynamic Certificates](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/leaks/lua_ssl.go#L34)
- [should not leak memory from ingress SSL certificates or configuration updates](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/leaks/lua_ssl.go#L41)
### [[Security] request smuggling](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/security/request_smuggling.go#L32)
- [should not return body content from error_page](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/security/request_smuggling.go#L39)
### [[SSL] [Flag] default-ssl-certificate](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/default_ssl_certificate.go#L31)
- [uses default ssl certificate for catch-all ingress](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/default_ssl_certificate.go#L63)
- [uses default ssl certificate for host based ingress when configured certificate does not match host](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/default_ssl_certificate.go#L79)
### [[Lua] lua-shared-dicts](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/lua_shared_dicts.go#L26)
- [configures lua shared dicts](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/lua_shared_dicts.go#L29)
### [server-tokens](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/server_tokens.go#L30)
- [should not exists Server header in the response](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/server_tokens.go#L38)
- [should exists Server header in the response when is enabled](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/server_tokens.go#L50)
### [use-proxy-protocol](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/proxy_protocol.go#L31)
- [should respect port passed by the PROXY Protocol](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/proxy_protocol.go#L41)
- [should respect proto passed by the PROXY Protocol server port](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/proxy_protocol.go#L74)
### [[Flag] custom HTTP and HTTPS ports](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/listen_nondefault_ports.go#L31)
- [should set X-Forwarded-Port headers accordingly when listening on a non-default HTTP port](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/listen_nondefault_ports.go#L47)
- [should set X-Forwarded-Port header to 443](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/listen_nondefault_ports.go#L69)
- [should set the X-Forwarded-Port header to 443](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/listen_nondefault_ports.go#L99)
### [[Security] no-auth-locations](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/no_auth_locations.go#L34)
- [should return status code 401 when accessing '/' unauthentication](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/no_auth_locations.go#L55)
- [should return status code 200 when accessing '/' authentication](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/no_auth_locations.go#L69)
- [should return status code 200 when accessing '/noauth' unauthenticated](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/no_auth_locations.go#L83)
### [Dynamic $proxy_host](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/proxy_host.go#L28)
- [should exist a proxy_host](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/proxy_host.go#L36)
- [should exist a proxy_host using the upstream-vhost annotation value](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/proxy_host.go#L57)
### [[Security] Pod Security Policies](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/pod_security_policy.go#L39)
- [should be running with a Pod Security Policy](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/pod_security_policy.go#L78)
### [Geoip2](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/geoip2.go#L29)
- [should only allow requests from specific countries](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/geoip2.go#L38)
### [[Security] Pod Security Policies with volumes](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/pod_security_policy_volumes.go#L35)
- [should be running with a Pod Security Policy](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/pod_security_policy_volumes.go#L38)
### [enable-multi-accept](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/multi_accept.go#L27)
- [should be enabled by default](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/multi_accept.go#L31)
- [should be enabled when set to true](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/multi_accept.go#L39)
- [should be disabled when set to false](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/multi_accept.go#L49)
### [log-format-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/log-format.go#L28)
- [should disable the log-format-escape-json by default](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/log-format.go#L40)
- [should enable the log-format-escape-json](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/log-format.go#L47)
- [should disable the log-format-escape-json](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/log-format.go#L55)
- [log-format-escape-json enabled](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/log-format.go#L66)
- [log-format-escape-json disabled](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/log-format.go#L89)
### [[Flag] ingress-class](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/ingress_class.go#L32)
- [should ignore Ingress with class](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/ingress_class.go#L41)
- [should ignore Ingress with no class](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/ingress_class.go#L86)
- [should delete Ingress when class is removed](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/ingress_class.go#L120)
### [[Security] global-auth-url](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L32)
- [should return status code 401 when request any protected service](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L83)
- [should return status code 200 when request whitelisted (via no-auth-locations) service and 401 when request protected service](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L100)
- [should return status code 200 when request whitelisted (via ingress annotation) service and 401 when request protected service](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L120)
- [should still return status code 200 after auth backend is deleted using cache ](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L149)
- [should proxy_method method when global-auth-method is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L190)
- [should add custom error page when global-auth-signin url is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L203)
- [should add auth headers when global-auth-response-headers is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L216)
- [should set request-redirect when global-auth-request-redirect is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L230)
- [should set snippet when global external auth is configured](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_external_auth.go#L243)
### [[Security] block-*](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_access_block.go#L28)
- [should block CIDRs defined in the ConfigMap](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_access_block.go#L38)
- [should block User-Agents defined in the ConfigMap](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_access_block.go#L55)
- [should block Referers defined in the ConfigMap](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/global_access_block.go#L88)
### [use-forwarded-headers](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/forwarded_headers.go#L30)
- [should trust X-Forwarded headers when setting is true](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/forwarded_headers.go#L40)
- [should not trust X-Forwarded headers when setting is false](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/forwarded_headers.go#L89)
### [add-headers](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/custom_header.go#L30)
- [Add a custom header](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/custom_header.go#L40)
- [Add multiple custom headers](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/custom_header.go#L65)
### [hash size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L27)
- [should set server_names_hash_bucket_size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L40)
- [should set server_names_hash_max_size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L48)
- [should set proxy-headers-hash-bucket-size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L60)
- [should set proxy-headers-hash-max-size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L68)
- [should set variables-hash-bucket-size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L80)
- [should set variables-hash-max-size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L88)
- [should set vmap-hash-bucket-size](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/hash-size.go#L100)
### [keep-alive keep-alive-requests](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/keep-alive.go#L27)
- [should set keepalive_timeout](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/keep-alive.go#L38)
- [should set keepalive_requests](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/keep-alive.go#L46)
### [[Flag] disable-catch-all](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/disable_catch_all.go#L32)
- [should ignore catch all Ingress](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/disable_catch_all.go#L50)
- [should delete Ingress updated to catch-all](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/disable_catch_all.go#L69)
- [should allow Ingress with both a default backend and rules](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/disable_catch_all.go#L107)
### [main-snippet](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/main_snippet.go#L27)
- [should add value of main-snippet setting to nginx config](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/main_snippet.go#L31)
### [[SSL] TLS protocols, ciphers and headers)](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/tls.go#L31)
- [should configure TLS protocol](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/tls.go#L40)
- [should configure HSTS policy header](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/tls.go#L96)
- [should not use ports during the HTTP to HTTPS redirection](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/tls.go#L156)
- [should not use ports or X-Forwarded-Host during the HTTP to HTTPS redirection](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/tls.go#L174)
### [Configmap change](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/configmap_change.go#L29)
- [should reload after an update in the configuration](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/configmap_change.go#L36)
### [[Security] modsecurity-snippet](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/modsecurity_snippet.go#L27)
- [should add value of modsecurity-snippet setting to nginx config](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/modsecurity_snippet.go#L30)
### [reuse-port](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/reuse-port.go#L27)
- [reuse port should be enabled by default](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/reuse-port.go#L38)
- [reuse port should be disabled](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/reuse-port.go#L44)
- [reuse port should be enabled](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/settings/reuse-port.go#L52)
### [[Shutdown] Graceful shutdown with pending request](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/gracefulshutdown/slow_requests.go#L29)
- [should let slow requests finish before shutting down](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/gracefulshutdown/slow_requests.go#L37)
### [[Shutdown] ingress controller](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/gracefulshutdown/shutdown.go#L31)
- [should shutdown in less than 60 secons without pending connections](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/gracefulshutdown/shutdown.go#L42)
- [should shutdown after waiting 60 seconds for pending connections to be closed](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/gracefulshutdown/shutdown.go#L69)
- [should shutdown after waiting 150 seconds for pending connections to be closed](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/gracefulshutdown/shutdown.go#L133)
### [[Service] backend status code 503](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_backend.go#L32)
- [should return 503 when backend service does not exist](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_backend.go#L35)
- [should return 503 when all backend service endpoints are unavailable](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_backend.go#L53)
### [[Service] Type ExternalName](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_externalname.go#L32)
- [works with external name set to incomplete fdqn](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_externalname.go#L35)
- [should return 200 for service type=ExternalName without a port defined](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_externalname.go#L68)
- [should return 200 for service type=ExternalName with a port defined](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_externalname.go#L99)
- [should return status 502 for service type=ExternalName with an invalid host](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_externalname.go#L137)
- [should return 200 for service type=ExternalName using a port name](https://github.com/kubernetes/ingress-nginx/tree/master/test/e2e/servicebackend/service_externalname.go#L168)

63
docs/enhancements/20190724-only-dynamic-ssl.md Normal file
View file

@ -0,0 +1,63 @@
---
title: Remove static SSL configuration mode
authors:
- "@aledbf"
reviewers:
- "@ElvinEfendi"
approvers:
- "@ElvinEfendi"
editor: TBD
creation-date: 2019-07-24
last-updated: 2019-07-24
status: implementable
see-also:
replaces:
superseded-by:
---
# Remove static SSL configuration mode
## Table of Contents
<!-- toc -->
- [Summary](#summary)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Proposal](#proposal)
- [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
<!-- /toc -->
## Summary
Since release [0.19.0](https://github.com/kubernetes/ingress-nginx/releases/tag/nginx-0.19.0) is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release [0.24.0](https://github.com/kubernetes/ingress-nginx/releases/tag/nginx-0.19.0) the default enabled mode is dynamic.
## Motivation
The static configuration implies reloads, something that affects the majority of the users.
### Goals
- Deprecation of the flag `--enable-dynamic-certificates`.
- Cleanup of the codebase.
### Non-Goals
- Features related to certificate authentication are not changed in any way.
## Proposal
- Remove static SSL configuration
### Implementation Details/Notes/Constraints
- Deprecate the flag Move the directives `ssl_certificate` and `ssl_certificate_key` from each server block to the `http` section. These settings are required to avoid NGINX errors in the logs.
- Remove any action of the flag `--enable-dynamic-certificates`
## Drawbacks
## Alternatives
Keep both implementations

101
docs/enhancements/20190815-zone-aware-routing.md Normal file
View file

@ -0,0 +1,101 @@
---
title: Availability zone aware routing
authors:
- "@ElvinEfendi"
reviewers:
- "@aledbf"
approvers:
- "@aledbf"
editor: TBD
creation-date: 2019-08-15
last-updated: 2019-08-16
status: implementable
---
# Availability zone aware routing
## Table of Contents
<!-- toc -->
- [Summary](#summary)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Proposal](#proposal)
- [Implementation History](#implementation-history)
- [Drawbacks [optional]](#drawbacks-optional)
<!-- /toc -->
## Summary
Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint.
## Motivation
When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, Amazon EC charges money for that.
ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in different zone or the same one. That means it's at least equally likely
that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to ingress-nginx pod is considered as
inter zone traffic and costs money.
At the time of this writing GCP charges $0.01 per GB of inter zone egress traffic according to https://cloud.google.com/compute/network-pricing.
According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money sa GCP for cross zone, egress traffic.
This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost.
Arguably inter-zone network latency should also be better than cross zone.
### Goals
* Given a regional cluster running ingress-nginx, ingress-nginx should do best effort to pick zone-local endpoint when proxying
* This should not impact canary feature
* ingress-nginx should be able to operate successfully if there's no zonal endpoints
### Non-Goals
* This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone
* This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases
## Proposal
The idea here is to have controller part of ingress-nginx to (1) detect what zone its current pod is running in and (2) detect the zone for every endpoints it knows about.
After that it will post that data as part of endpoints to Lua land. Then Lua balancer when picking an endpoint will try to pick zone-local endpoint first and
if there is no zone-local endpoint then it will fallback to current behaviour.
This feature at least in the beginning should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that.
**How does controller know what zone it runs in?**
We can have the pod spec do pass node name using downward API as an environment variable.
Then on start controller can get node details from the API based on node name. Once the node details is obtained
we can extract the zone from `failure-domain.beta.kubernetes.io/zone` annotation. Then we can pass that value to Lua land through Nginx configuration
when loading `lua_ingress.lua` module in `init_by_lua` phase.
**How do we extract zones for endpoints?**
We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory.
And when we generate endpoints list, we can access node name using `.subsets.addresses[i].nodeName`
and based on that fetch zone from the map in memory and store it as a field on the endpoint.
__This solution assumes `failure-domain.beta.kubernetes.io/zone`__ annotation does not change until the end of node's life. Otherwise we have to
watch update events as well on the nodes and that'll add even more overhead.
Alternatively, we can get the list of nodes only when there's no node in the memory for given node name. This is probably a better solution
because then we would avoid watching for API changes on node resources. We can eagrly fetch all the nodes and build node name to zone mapping on start.
And from thereon sync it during endpoints building in the main event loop iff there's no entry exist for the node of an endpoint.
This means an extra API call in case cluster has expanded.
**How do we make sure we do our best to choose zone-local endpoint?**
This will be done on Lua side. For every backend we will initialize two balancer instances: (1) with all endpoints
(2) with all endpoints corresponding to current zone for the backend. Then given the request once we choose what backend
needs to serve the request, we will first try to use zonal balancer for that backend. If zonal balancer does not exist (i.e there's no zonal endpoint)
then we will use general balancer. In case of zonal outages we assume that readiness probe will fail and controller will
see no endpoints for the backend and therefore we will use general balancer.
We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem.
## Implementation History
- initial version of KEP is shipped
- proposal and implementation details is done
## Drawbacks [optional]
More load on the Kubernetes API server.

28
docs/enhancements/README.md Normal file
View file

@ -0,0 +1,28 @@
# Kubernetes Enhancement Proposals (KEPs)
A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the `ingress-nginx` project is adopting it.
## Quick start for the KEP process
Follow the process outlined in the [KEP template](YYYYMMDD-kep-template.md)
### Do I have to use the KEP process?
No... but we hope that you will.
Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record.
KEPs are only required when the changes are wide ranging and impact most of the project.
### Why would I want to use the KEP process?
Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community.
As such, we want to build a well curated set of clear proposals in a common format with useful metadata.
Benefits to KEP users (in the limit):
* Exposure on a kubernetes blessed web site that is findable via web search engines.
* Cross indexing of KEPs so that users can find connections and the current status of any KEP.
* A clear process with approvers and reviewers for making decisions.
This will lead to more structured decisions that stick as there is a discoverable record around the decisions.
We are inspired by IETF RFCs, Python PEPs, and Rust RFCs.

182
docs/enhancements/YYYYMMDD-kep-template.md Normal file
View file

@ -0,0 +1,182 @@
---
title: KEP Template
authors:
- "@janedoe"
reviewers:
- TBD
- "@alicedoe"
approvers:
- TBD
- "@oscardoe"
editor: TBD
creation-date: yyyy-mm-dd
last-updated: yyyy-mm-dd
status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
see-also:
- "/docs/enhancements/20190101-we-heard-you-like-keps.md"
- "/docs/enhancements/20190102-everyone-gets-a-kep.md"
replaces:
- "/docs/enhancements/20181231-replaced-kep.md"
superseded-by:
- "/docs/enhancements/20190104-superceding-kep.md"
---
# Title
This is the title of the KEP.
Keep it simple and descriptive.
A good title can help communicate what the KEP is and should be considered as part of any review.
The title should be lowercased and spaces/punctuation should be replaced with `-`.
To get started with this template:
1. **Make a copy of this template.**
Create a copy of this template and name it `YYYYMMDD-my-title.md`, where `YYYYMMDD` is the date the KEP was first drafted.
1. **Fill out the "overview" sections.**
This includes the Summary and Motivation sections.
These should be easy if you've preflighted the idea of the KEP in an issue.
1. **Create a PR.**
Assign it to folks that are sponsoring this process.
1. **Create an issue**
When filing an enhancement tracking issue, please ensure to complete all fields in the template.
1. **Merge early.**
Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly.
The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs.
View anything marked as a `provisional` as a working document and subject to change.
Aim for single topic PRs to keep discussions focused.
If you disagree with what is already in a document, open a new PR with suggested changes.
The canonical place for the latest set of instructions (and the likely source of this file) is [here](/keps/YYYYMMDD-kep-template.md).
The `Metadata` section above is intended to support the creation of tooling around the KEP process.
This will be a YAML section that is fenced as a code block.
See the KEP process for details on each of these items.
## Table of Contents
A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template.
Ensure the TOC is wrapped with <code>&lt;!-- toc --&rt;&lt;!-- /toc --&rt;</code> tags, and then generate with `hack/update-toc.sh`.
<!-- toc -->
- [Summary](#summary)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Proposal](#proposal)
- [User Stories [optional]](#user-stories-optional)
- [Story 1](#story-1)
- [Story 2](#story-2)
- [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional)
- [Risks and Mitigations](#risks-and-mitigations)
- [Design Details](#design-details)
- [Test Plan](#test-plan)
- [Removing a deprecated flag](#removing-a-deprecated-flag)
- [Implementation History](#implementation-history)
- [Drawbacks [optional]](#drawbacks-optional)
- [Alternatives [optional]](#alternatives-optional)
<!-- /toc -->
## Summary
The `Summary` section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap.
It should be possible to collect this information before implementation begins in order to avoid requiring implementors to split their attention between writing release notes and implementing the feature itself.
A good summary is probably at least a paragraph in length.
## Motivation
This section is for explicitly listing the motivation, goals and non-goals of this KEP.
Describe why the change is important and the benefits to users.
The motivation section can optionally provide links to [experience reports][] to demonstrate the interest in a KEP within the wider Kubernetes community.
[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
### Goals
List the specific goals of the KEP.
How will we know that this has succeeded?
### Non-Goals
What is out of scope for this KEP?
Listing non-goals helps to focus discussion and make progress.
## Proposal
This is where we get down to the nitty gritty of what the proposal actually is.
### User Stories [optional]
Detail the things that people will be able to do if this KEP is implemented.
Include as much detail as possible so that people can understand the "how" of the system.
The goal here is to make this feel real for users without getting bogged down.
#### Story 1
#### Story 2
### Implementation Details/Notes/Constraints [optional]
What are the caveats to the implementation?
What are some important details that didn't come across above.
Go in to as much detail as necessary here.
This might be a good place to talk about core concepts and how they releate.
### Risks and Mitigations
What are the risks of this proposal and how do we mitigate.
Think broadly.
For example, consider both security and how this will impact the larger kubernetes ecosystem.
How will security be reviewed and by whom?
How will UX be reviewed and by whom?
Consider including folks that also work outside project.
## Design Details
### Test Plan
**Note:** *Section not required until targeted at a release.*
Consider the following in developing a test plan for this enhancement:
- Will there be e2e and integration tests, in addition to unit tests?
- How will it be tested in isolation vs with other components?
No need to outline all of the test cases, just the general strategy.
Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out.
All code is expected to have adequate tests (eventually with coverage expectations).
Please adhere to the [Kubernetes testing guidelines][testing-guidelines] when drafting this test plan.
[testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md
#### Removing a deprecated flag
- Announce deprecation and support policy of the existing flag
- Two versions passed since introducing the functionality which deprecates the flag (to address version skew)
- Address feedback on usage/changed behavior, provided on GitHub issues
- Deprecate the flag
## Implementation History
Major milestones in the life cycle of a KEP should be tracked in `Implementation History`.
Major milestones might include
- the `Summary` and `Motivation` sections being merged signaling acceptance
- the `Proposal` section being merged signaling agreement on a proposed design
- the date implementation started
- the first Kubernetes release where an initial version of the KEP was available
- the version of Kubernetes where the KEP graduated to general availability
- when the KEP was retired or superseded
## Drawbacks [optional]
Why should this KEP _not_ be implemented.
## Alternatives [optional]
Similar to the `Drawbacks` section the `Alternatives` section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.

14
docs/examples/affinity/cookie/README.md
View file

@ -9,10 +9,14 @@ Session affinity can be configured using the following annotations:
|Name|Description|Value|
| --- | --- | --- |
|nginx.ingress.kubernetes.io/affinity|Type of the affinity, set this to `cookie` to enable session affinity|string (NGINX only supports `cookie`)|
|nginx.ingress.kubernetes.io/affinity-mode|The affinity mode defines how sticky a session is. Use `balanced` to redistribute some sessions when scaling pods or `persistent` for maximum stickyness.|`balanced` (default) or `persistent`|
|nginx.ingress.kubernetes.io/session-cookie-name|Name of the cookie that will be created|string (defaults to `INGRESSCOOKIE`)|
|nginx.ingress.kubernetes.io/session-cookie-path|Path that will be set on the cookie (required if your [Ingress paths][ingress-paths] use regular expressions)|string (defaults to the currently [matched path][ingress-paths])|
|nginx.ingress.kubernetes.io/session-cookie-samesite|SameSite attribute to apply to the cookie|Browser accepted values are `None`, `Lax`, and `Strict`|
|nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none|Will omit `SameSite=None` attribute for older browsers which reject the more-recently defined `SameSite=None` value|`"true"` or `"false"`
|nginx.ingress.kubernetes.io/session-cookie-max-age|Time until the cookie expires, corresponds to the `Max-Age` cookie directive|number of seconds|
|nginx.ingress.kubernetes.io/session-cookie-expires|Legacy version of the previous annotation for compatibility with older browsers, generates an `Expires` cookie directive by adding the seconds to the current date|number of seconds|
|nginx.ingress.kubernetes.io/session-cookie-change-on-failure|When set to `false` nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to `true` and previous attempt failed, sticky cookie will be changed to point to another upstream.|`true` or `false` (defaults to `false`)|
You can create the [example Ingress](ingress.yaml) to test this:
@ -28,12 +32,12 @@ You can confirm that the Ingress works:
$ kubectl describe ing nginx-test
Name: nginx-test
Namespace: default
Address:
Address:
Default backend: default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)
Rules:
Host Path Backends
---- ---- --------
stickyingress.example.com
stickyingress.example.com
/ nginx-service:80 (<none>)
Annotations:
affinity: cookie
@ -44,7 +48,7 @@ Events:
FirstSeen LastSeen Count From SubObjectPath Type Reason Message
--------- -------- ----- ---- ------------- -------- ------ -------
7s 7s 1 {nginx-ingress-controller } Normal CREATE default/nginx-test
$ curl -I http://stickyingress.example.com
HTTP/1.1 200 OK
@ -67,8 +71,8 @@ If the backend pool grows NGINX will keep sending the requests through the same
When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's [consistent hash][consistent-hashing] will change.
When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used.
When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used.
This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this.
[ingress-paths]: ../../../user-guide/ingress-path-matching
[ingress-paths]: ../../../user-guide/ingress-path-matching.md
[consistent-hashing]: https://en.wikipedia.org/wiki/Consistent_hashing

40
docs/examples/affinity/cookie/ingress-samesite.yaml Normal file
View file

@ -0,0 +1,40 @@
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: cookie-samesite-none
annotations:
nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "SSNONE"
nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
nginx.ingress.kubernetes.io/session-cookie-samesite: "None"
nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true" # omits SameSite=None for older browsers which reject cookies with SameSite=None
spec:
rules:
- host: stickyingress-samesite-none.example.com
http:
paths:
- backend:
serviceName: http-svc
servicePort: 80
path: /
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: cookie-samesite-strict
annotations:
nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "STRICTCOOKIENAME"
nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
nginx.ingress.kubernetes.io/session-cookie-samesite: "Strict"
spec:
rules:
- host: stickyingress-samesite-strict.example.com
http:
paths:
- backend:
serviceName: http-svc
servicePort: 80
path: /

2
docs/examples/affinity/cookie/ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: nginx-test

2
docs/examples/auth/basic/README.md
View file

@ -30,7 +30,7 @@ type: Opaque
```console
echo "
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: ingress-with-auth

6
docs/examples/auth/client-certs/README.md
View file

@ -44,6 +44,12 @@ Authentication to work properly.
kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
```
3. If you want to also enable Certificate Revocation List verification you can
create the secret also containing the CRL file in PEM format:
```bash
kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt --from-file=ca.crl=ca.crl
```
Note: The CA Certificate must contain the trusted certificate authority chain to verify client certificates.
## Setup Instructions

2
docs/examples/auth/client-certs/ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:

6
docs/examples/auth/external-auth/README.md
View file

@ -2,7 +2,7 @@
### Example 1:
Use an external service (Basic Auth) located in `https://httpbin.org`
Use an external service (Basic Auth) located in `https://httpbin.org`
```
$ kubectl create -f ingress.yaml
@ -13,7 +13,7 @@ NAME HOSTS ADDRESS PORTS AGE
external-auth external-auth-01.sample.com 172.17.4.99 80 13s
$ kubectl get ing external-auth -o yaml
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:
@ -23,7 +23,7 @@ metadata:
name: external-auth
namespace: default
resourceVersion: "2068378"
selfLink: /apis/extensions/v1beta1/namespaces/default/ingresses/external-auth
selfLink: /apis/networking/v1beta1/namespaces/default/ingresses/external-auth
uid: 5c388f1d-8970-11e6-9004-080027d2dc94
spec:
rules:

2
docs/examples/auth/external-auth/ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:

8
docs/examples/auth/oauth-external-auth/README.md
View file

@ -31,7 +31,7 @@ metadata:
### Example: OAuth2 Proxy + Kubernetes-Dashboard
This example will show you how to deploy [`oauth2_proxy`](https://github.com/bitly/oauth2_proxy)
This example will show you how to deploy [`oauth2_proxy`](https://github.com/pusher/oauth2_proxy)
into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider
#### Prepare
@ -51,13 +51,13 @@ kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addon
![Register OAuth2 Application](images/register-oauth-app-2.png)
3. Configure oauth2_proxy values in the file oauth2-proxy.yaml with the values:
3. Configure oauth2_proxy values in the file [`oauth2-proxy.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/auth/oauth-external-auth/oauth2-proxy.yaml) with the values:
- OAUTH2_PROXY_CLIENT_ID with the github `<Client ID>`
- OAUTH2_PROXY_CLIENT_SECRET with the github `<Client Secret>`
- OAUTH2_PROXY_COOKIE_SECRET with value of `python -c 'import os,base64; print base64.b64encode(os.urandom(16))'`
- OAUTH2_PROXY_COOKIE_SECRET with value of `python -c 'import os,base64; print(base64.b64encode(os.urandom(16)).decode("ascii"))'`
4. Customize the contents of the file dashboard-ingress.yaml:
4. Customize the contents of the file [`dashboard-ingress.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml):
Replace `__INGRESS_HOST__` with a valid FQDN and `__INGRESS_SECRET__` with a Secret with a valid SSL certificate.

4
docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:
@ -18,7 +18,7 @@ spec:
---
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: oauth2-proxy

4
docs/examples/auth/oauth-external-auth/oauth2-proxy.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
@ -31,7 +31,7 @@ spec:
# docker run -ti --rm python:3-alpine python -c 'import secrets,base64; print(base64.b64encode(base64.b64encode(secrets.token_bytes(16))));'
- name: OAUTH2_PROXY_COOKIE_SECRET
value: SECRET
image: docker.io/colemickens/oauth2_proxy:latest
image: quay.io/pusher/oauth2_proxy:latest
imagePullPolicy: Always
name: oauth2-proxy
ports:

2
docs/examples/chashsubset/deployment.yaml
View file

@ -54,7 +54,7 @@ spec:
targetPort: 8080
---
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:

2
docs/examples/customization/configuration-snippets/ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: nginx-configuration-snippet

4
docs/examples/customization/custom-errors/README.md
View file

@ -28,7 +28,7 @@ service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s
If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the
[deployment guide][deploy], then follow these steps:
1. Edit the `nginx-ingress-controller` Deployment and set the value of the `--default-backend` flag to the name of the
1. Edit the `nginx-ingress-controller` Deployment and set the value of the `--default-backend-service` flag to the name of the
newly created error backend.
2. Edit the `nginx-configuration` ConfigMap and create the key `custom-http-errors` with a value of `404,503`.
@ -40,7 +40,7 @@ If you do not already have an instance of the NGINX Ingress controller running,
ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m
```
!!! Note
!!! note
The `ingress-nginx` Service is of type `ClusterIP` in this example. This may vary depending on your environment.
Make sure you can use the Service to reach NGINX before proceeding with the rest of this example.

1
docs/examples/customization/external-auth-headers/README.md
View file

@ -28,7 +28,6 @@ ingress "secure-demo-echo-service" created
$ kubectl get po
NAME READY STATUS RESTARTS AGE
NAME READY STATUS RESTARTS AGE
demo-auth-service-2769076528-7g9mh 1/1 Running 0 30s
demo-echo-service-3636052215-3vw8c 1/1 Running 0 29s

2
docs/examples/customization/external-auth-headers/authsvc/Dockerfile
View file

@ -1,4 +1,4 @@
FROM alpine:3.5
FROM alpine:3.10
MAINTAINER Roman Safronov <electroma@gmail.com>
COPY authsvc /
EXPOSE 8080

2
docs/examples/customization/external-auth-headers/deploy/auth-service.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: apps/v1
kind: Deployment
metadata:
name: demo-auth-service

6
docs/examples/customization/external-auth-headers/deploy/echo-service.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: apps/v1
kind: Deployment
metadata:
name: demo-echo-service
@ -43,7 +43,7 @@ spec:
selector:
k8s-app: demo-echo-service
---
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: public-demo-echo-service
@ -61,7 +61,7 @@ spec:
servicePort: 80
path: /
---
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: secure-demo-echo-service

2
docs/examples/customization/external-auth-headers/echosvc/Dockerfile
View file

@ -1,4 +1,4 @@
FROM alpine:3.5
FROM alpine:3.10
MAINTAINER Roman Safronov <electroma@gmail.com>
COPY echosvc /
EXPOSE 8080

2
docs/examples/customization/ssl-dh-param/README.md
View file

@ -36,7 +36,7 @@ $ cat ssl-dh-param.yaml
apiVersion: v1
data:
dhparam.pem: "LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ..."
kind: ConfigMap
kind: Secret
metadata:
name: nginx-configuration
namespace: ingress-nginx

12
docs/examples/customization/sysctl/README.md
View file

@ -1,9 +1,15 @@
# Sysctl tuning
This example aims to demonstrate the use of an Init Container to adjust sysctl default values
using `kubectl patch`
This example aims to demonstrate the use of an Init Container to adjust sysctl default values using `kubectl patch`
```console
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --patch="$(cat patch.json)"
kubectl patch deployment -n ingress-nginx nginx-ingress-controller \
--patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/sysctl/patch.json)"
```
**Changes:**
- Backlog Queue setting `net.core.somaxconn` from `128` to `32768`
- Ephemeral Ports setting `net.ipv4.ip_local_port_range` from `32768 60999` to `1024 65000`
In a [post from the NGINX blog](https://www.nginx.com/blog/tuning-nginx/), it is possible to see an explanation for the changes.

4
docs/examples/customization/sysctl/patch.json
View file

@ -4,11 +4,11 @@
"spec": {
"initContainers": [{
"name": "sysctl",
"image": "alpine:3.6",
"image": "alpine:3.10",
"securityContext": {
"privileged": true
},
"command": ["sh", "-c", "sysctl -w net.core.somaxconn=32768; sysctl -w net.ipv4.ip_local_port_range=1024 65535"]
"command": ["sh", "-c", "sysctl -w net.core.somaxconn=32768; sysctl -w net.ipv4.ip_local_port_range='1024 65000'"]
}]
}
}

4
docs/examples/docker-registry/README.md
View file

@ -26,9 +26,9 @@ wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/exam
```
!!! Important
Running a docker registry without TLS requires we configure our local docker daemon with the insecure registry flag.
Running a docker registry without TLS requires we configure our local docker daemon with the insecure registry flag.
Please check [deploy a plain http registry](https://docs.docker.com/registry/insecure/#deploy-a-plain-http-registry)
Please check [deploy a plain http registry](https://docs.docker.com/registry/insecure/#deploy-a-plain-http-registry)
### With TLS

2
docs/examples/docker-registry/deployment.yaml
View file

@ -5,7 +5,7 @@ metadata:
---
apiVersion: extensions/v1beta1
apiVersion: apps/v1
kind: Deployment
metadata:
name: docker-registry

2
docs/examples/docker-registry/ingress-with-tls.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:

2
docs/examples/docker-registry/ingress-without-tls.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:

17
docs/examples/grpc/README.md
View file

@ -13,12 +13,12 @@ nginx controller.
for the ingress).
3. You have the nginx-ingress controller installed in typical fashion (must be
at least
[quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.13.0](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller)
[quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.30.0](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller)
for grpc support.
4. You have a backend application running a gRPC server and listening for TCP
traffic. If you prefer, you can use the
[fortune-teller](https://github.com/kubernetes/ingress-nginx/tree/master/images/grpc-fortune-teller)
application provided here as an example.
application provided here as an example.
### Step 1: kubernetes `Deployment`
@ -102,3 +102,16 @@ $ grpcurl fortune-teller.stack.build:443 build.stack.fortune.FortuneTeller/Predi
> If you are developing public gRPC endpoints, check out
> https://proto.stack.build, a protocol buffer / gRPC build service that can use
> to help make it easier for your users to consume your API.
> See also the specific GRPC settings of NGINX: https://nginx.org/en/docs/http/ngx_http_grpc_module.html
### Notes on using response/request streams
1. If your server does only response streaming and you expect a stream to be open longer than 60 seconds, you will have to change the `grpc_read_timeout` to acommodate for this.
2. If your service does only request streaming and you expect a stream to be open longer than 60 seconds, you have to change the
`grpc_send_timeout` and the `client_body_timeout`.
3. If you do both response and request streaming with an open stream longer than 60 seconds, you have to change all three timeouts: `grpc_read_timeout`, `grpc_send_timeout` and `client_body_timeout`.
Values for the timeouts must be specified as e.g. `"1200s"`.
> On the most recent versions of nginx-ingress, changing these timeouts requires using the `nginx.ingress.kubernetes.io/server-snippet` annotation. There are plans for future releases to allow using the Kubernetes annotations to define each timeout seperately.

5
docs/examples/grpc/app.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: apps/v1
kind: Deployment
metadata:
name: fortune-teller-app
@ -7,6 +7,9 @@ metadata:
namespace: default
spec:
replicas: 1
selector:
matchLabels:
k8s-app: fortune-teller-app
template:
metadata:
labels:

2
docs/examples/grpc/ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:

2
docs/examples/http-svc.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: apps/v1
kind: Deployment
metadata:
name: http-svc

4
docs/examples/multi-tls/multi-tls.yaml
View file

@ -90,9 +90,9 @@ spec:
valueFrom:
fieldRef:
fieldPath: status.podIP
---
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: foo-tls

23
docs/examples/psp/README.md Normal file
View file

@ -0,0 +1,23 @@
# Pod Security Policy (PSP)
In most clusters today, by default, all resources (e.g. Deployments and ReplicatSets)
have permissions to create pods.
Kubernetes however provides a more fine-grained authorization policy called
[Pod Security Policy (PSP)](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).
PSP allows the cluster owner to define the permission of each object, for example creating a pod.
If you have PSP enabled on the cluster, and you deploy ingress-nginx,
you will need to provide the Deployment with the permissions to create pods.
Before applying any objects, first apply the PSP permissions by running:
```console
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/psp/psp.yaml
```
Now that the pod security policy is applied, we can continue as usual by applying the
[mandatory.yaml](https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-0.30.0/deploy/static/mandatory.yaml)
according to the [Installation Guide](../../deploy/index.md).
Note: PSP permissions must be granted before to the creation of the Deployment and the ReplicaSet.
If the Deployment or ReplicaSet already exist, they will receive the PSP permissions
only after deleting them and reapplying mandatory.yaml.

87
docs/examples/psp/psp.yaml Normal file
View file

@ -0,0 +1,87 @@
apiVersion: v1
kind: Namespace
metadata:
name: ingress-nginx
---
apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
annotations:
# Assumes apparmor available
apparmor.security.beta.kubernetes.io/allowedProfileNames: 'runtime/default'
apparmor.security.beta.kubernetes.io/defaultProfileName: 'runtime/default'
seccomp.security.alpha.kubernetes.io/allowedProfileNames: 'docker/default'
seccomp.security.alpha.kubernetes.io/defaultProfileName: 'docker/default'
name: ingress-nginx
spec:
allowedCapabilities:
- NET_BIND_SERVICE
allowPrivilegeEscalation: true
fsGroup:
rule: 'MustRunAs'
ranges:
- min: 1
max: 65535
hostIPC: false
hostNetwork: false
hostPID: false
hostPorts:
- min: 80
max: 65535
privileged: false
readOnlyRootFilesystem: false
runAsUser:
rule: 'MustRunAsNonRoot'
ranges:
- min: 101
max: 65535
seLinux:
rule: 'RunAsAny'
supplementalGroups:
rule: 'MustRunAs'
ranges:
# Forbid adding the root group.
- min: 1
max: 65535
volumes:
- 'configMap'
- 'downwardAPI'
- 'emptyDir'
- 'projected'
- 'secret'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: ingress-nginx-psp
namespace: ingress-nginx
rules:
- apiGroups:
- policy
resourceNames:
- ingress-nginx
resources:
- podsecuritypolicies
verbs:
- use
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: ingress-nginx-psp
namespace: ingress-nginx
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: ingress-nginx-psp
subjects:
- kind: ServiceAccount
name: default
- kind: ServiceAccount
name: nginx-ingress-serviceaccount

13
docs/examples/rewrite/README.md
View file

@ -6,7 +6,7 @@ This example demonstrates how to use the Rewrite annotations
You will need to make sure your Ingress targets exactly one Ingress
controller by specifying the [ingress.class annotation](../../user-guide/multiple-ingress.md),
and that you have an ingress controller [running](../../deploy) in your cluster.
and that you have an ingress controller [running](../../deploy/) in your cluster.
## Deployment
@ -26,15 +26,15 @@ Rewriting can be controlled using the following annotations:
!!! attention
Starting in Version 0.22.0, ingress definitions using the annotation `nginx.ingress.kubernetes.io/rewrite-target` are not backwards compatible with previous versions. In Version 0.22.0 and beyond, any substrings within the request URI that need to be passed to the rewritten path must explicitly be defined in a [capture group](https://www.regular-expressions.info/refcapture.html).
!!! note
[Captured groups](https://www.regular-expressions.info/refcapture.html) are saved in numbered placeholders, chronologically, in the form `$1`, `$2` ... `$n`. These placeholders can be used as parameters in the `rewrite-target` annotation.
[Captured groups](https://www.regular-expressions.info/refcapture.html) are saved in numbered placeholders, chronologically, in the form `$1`, `$2` ... `$n`. These placeholders can be used as parameters in the `rewrite-target` annotation.
Create an Ingress rule with a rewrite annotation:
```console
$ echo '
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:
@ -53,9 +53,10 @@ spec:
' | kubectl create -f -
```
In this ingress definition, any characters captured by `(.*)` will be assigned to the placeholder `$2`, which is then used as a parameter in the `rewrite-target` annotation.
In this ingress definition, any characters captured by `(.*)` will be assigned to the placeholder `$2`, which is then used as a parameter in the `rewrite-target` annotation.
For example, the ingress definition above will result in the following rewrites:
- `rewrite.bar.com/something` rewrites to `rewrite.bar.com/`
- `rewrite.bar.com/something/` rewrites to `rewrite.bar.com/`
- `rewrite.bar.com/something/new` rewrites to `rewrite.bar.com/new`
@ -65,7 +66,7 @@ For example, the ingress definition above will result in the following rewrites:
Create an Ingress rule with a app-root annotation:
```
$ echo "
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:

4
docs/examples/static-ip/README.md
View file

@ -7,7 +7,7 @@ This example demonstrates how to assign a static-ip to an Ingress on through the
You need a [TLS cert](../PREREQUISITES.md#tls-certificates) and a [test HTTP service](../PREREQUISITES.md#test-http-service) for this example.
You will also need to make sure your Ingress targets exactly one Ingress
controller by specifying the [ingress.class annotation](../../user-guide/multiple-ingress.md),
and that you have an ingress controller [running](../../deploy) in your cluster.
and that you have an ingress controller [running](../../deploy/) in your cluster.
## Acquiring an IP
@ -48,7 +48,7 @@ From here on every Ingress created with the `ingress.class` annotation set to
$ kubectl create -f nginx-ingress.yaml
ingress "nginx-ingress" created
$ kubectl get ing nginx-ingress
$ kubectl get ing ingress-nginx
NAME HOSTS ADDRESS PORTS AGE
nginx-ingress * 104.154.109.191 80, 443 13m

4
docs/examples/static-ip/nginx-ingress-controller.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-ingress-controller
@ -24,7 +24,7 @@ spec:
# hostNetwork: true
terminationGracePeriodSeconds: 60
containers:
- image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.18.0
- image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.30.0
name: nginx-ingress-controller
readinessProbe:
httpGet:

2
docs/examples/static-ip/nginx-ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: ingress-nginx

6
docs/examples/tls-termination/README.md
View file

@ -11,7 +11,7 @@ You need a [TLS cert](../PREREQUISITES.md#tls-certificates) and a [test HTTP ser
Create a `values.yaml` file.
```yaml
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: nginx-test
@ -19,7 +19,7 @@ spec:
tls:
- hosts:
- foo.bar.com
# This assumes tls-secret exists and the SSL
# This assumes tls-secret exists and the SSL
# certificate contains a CN for foo.bar.com
secretName: tls-secret
rules:
@ -33,7 +33,7 @@ spec:
servicePort: 80
```
The following command instructs the controller to terminate traffic using the provided
The following command instructs the controller to terminate traffic using the provided
TLS cert, and forward un-encrypted HTTP traffic to the test HTTP service.
```console

4
docs/examples/tls-termination/ingress.yaml
View file

@ -1,4 +1,4 @@
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: nginx-test
@ -6,7 +6,7 @@ spec:
tls:
- hosts:
- foo.bar.com
# This assumes tls-secret exists and the SSL
# This assumes tls-secret exists and the SSL
# certificate contains a CN for foo.bar.com
secretName: tls-secret
rules:

4
docs/how-it-works.md
View file

@ -4,7 +4,7 @@ The objective of this document is to explain how the NGINX Ingress controller wo
## NGINX configuration
The goal of this Ingress controller is the assembly of a configuration file (nginx.conf). The main implication of this requirement is the need to reload NGINX after any change in the configuration file. _Though it is important to note that we don't reload Nginx on changes that impact only an `upstream` configuration (i.e Endpoints change when you deploy your app)_. We use https://github.com/openresty/lua-nginx-module to achieve this. Check [below](#avoiding-reloads-on-endpoints-changes) to learn more about how it's done.
The goal of this Ingress controller is the assembly of a configuration file (nginx.conf). The main implication of this requirement is the need to reload NGINX after any change in the configuration file. _Though it is important to note that we don't reload Nginx on changes that impact only an `upstream` configuration (i.e Endpoints change when you deploy your app)_. We use [lua-nginx-module](https://github.com/openresty/lua-nginx-module) to achieve this. Check [below](#avoiding-reloads-on-endpoints-changes) to learn more about how it's done.
## NGINX model
@ -60,7 +60,7 @@ In a relatively big clusters with frequently deploying apps this feature saves s
Because the ingress controller works using the [synchronization loop pattern](https://coreos.com/kubernetes/docs/latest/replication-controller.html#the-reconciliation-loop-in-detail), it is applying the configuration for all matching objects. In case some Ingress objects have a broken configuration, for example a syntax error in the `nginx.ingress.kubernetes.io/configuration-snippet` annotation, the generated configuration becomes invalid, does not reload and hence no more ingresses will be taken into account.
To prevent this situation to happen, the nginx ingress controller exposes optionnally a [validating admission webhook server][8] to ensure the validity of incoming ingress objects.
To prevent this situation to happen, the nginx ingress controller optionally exposes a [validating admission webhook server][8] to ensure the validity of incoming ingress objects.
This webhook appends the incoming ingress objects to the list of ingresses, generates the configuration and calls nginx to ensure the configuration has no syntax errors.
[0]: https://github.com/openresty/lua-nginx-module/pull/1259

BIN
docs/images/baremetal/baremetal_overview.jpg
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 30 KiB

Before After
Before After

BIN
docs/images/baremetal/cloud_overview.jpg
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 38 KiB

Before After
Before After

BIN
docs/images/baremetal/hostnetwork.jpg
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 34 KiB

Before After
Before After

BIN
docs/images/baremetal/metallb.jpg
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 49 KiB

After

Width:  |  Height:  |  Size: 41 KiB

Before After
Before After

BIN
docs/images/baremetal/nodeport.jpg
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 40 KiB

Before After
Before After

BIN
docs/images/baremetal/user_edge.jpg
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 62 KiB

After

Width:  |  Height:  |  Size: 52 KiB

Before After
Before After

BIN
docs/images/elb-l7-listener.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 28 KiB

Before After
Before After

BIN
docs/images/grafana.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 84 KiB

After

Width:  |  Height:  |  Size: 70 KiB

Before After
Before After

BIN
docs/images/jaeger-demo.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 141 KiB

After

Width:  |  Height:  |  Size: 70 KiB

Before After
Before After

BIN
docs/images/prometheus-dashboard.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 112 KiB

After

Width:  |  Height:  |  Size: 81 KiB

Before After
Before After

BIN
docs/images/zipkin-demo.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 120 KiB

After

Width:  |  Height:  |  Size: 60 KiB

Before After
Before After

2
docs/index.md
View file

@ -8,4 +8,4 @@ Learn more about using Ingress on [k8s.io](http://kubernetes.io/docs/user-guide/
## Getting Started
See [Deployment](./deploy) for a whirlwind tour that will get you started.
See [Deployment](./deploy/) for a whirlwind tour that will get you started.

43
docs/kubectl-plugin.md
View file

@ -11,17 +11,21 @@ Do not move it without providing redirects.
## Installation
Install [krew](https://github.com/GoogleContainerTools/krew), then run
```console
$ kubectl krew install ingress-nginx
kubectl krew install ingress-nginx
```
to install the plugin. Then run
```console
$ kubectl ingress-nginx --help
kubectl ingress-nginx --help
```
to make sure the plugin is properly installed and to get a list of commands:
```console
$ kubectl ingress-nginx --help
kubectl ingress-nginx --help
A kubectl plugin for inspecting your ingress-nginx deployments
Usage:
@ -76,9 +80,9 @@ Replacing `0.24.0` with the recently released version.
## Common Flags
- Every subcommand supports the basic `kubectl` configuration flags like `--namespace`, `--context`, `--client-key` and so on.
- Subcommands that act on a particular `ingress-nginx` pod (`backends`, `certs`, `conf`, `exec`, `general`, `logs`, `ssh`), support the `--deployment <deployment>` and `--pod <pod>` flags to select either a pod from a deployment with the given name, or a pod with the given name. The `--deployment` flag defaults to `nginx-ingress-controller`.
- Subcommands that inspect resources (`ingresses`, `lint`) support the `--all-namespaces` flag, which causes them to inspect resources in every namespace.
- Every subcommand supports the basic `kubectl` configuration flags like `--namespace`, `--context`, `--client-key` and so on.
- Subcommands that act on a particular `ingress-nginx` pod (`backends`, `certs`, `conf`, `exec`, `general`, `logs`, `ssh`), support the `--deployment <deployment>` and `--pod <pod>` flags to select either a pod from a deployment with the given name, or a pod with the given name. The `--deployment` flag defaults to `nginx-ingress-controller`.
- Subcommands that inspect resources (`ingresses`, `lint`) support the `--all-namespaces` flag, which causes them to inspect resources in every namespace.
## Subcommands
@ -117,11 +121,6 @@ $ kubectl ingress-nginx backends -n ingress-nginx
}
},
"port": 0,
"secureCACert": {
"secret": "",
"caFilename": "",
"pemSha": ""
},
"sslPassthrough": false,
"endpoints": [
{
@ -161,10 +160,12 @@ Add the `--list` option to show only the backend names. Add the `--backend <back
### certs
Use `kubectl ingress-nginx certs --host <hostname>` to dump the SSL cert/key information for a given host. Requires that `--enable-dynamic-certificates` is `true` (this is the default as of version `0.24.0`). WARNING: This command will dump sensitive private key information. Don't blindly share the output, and certainly don't log it anywhere.
Use `kubectl ingress-nginx certs --host <hostname>` to dump the SSL cert/key information for a given host. Requires that `--enable-dynamic-certificates` is `true` (this is the default as of version `0.24.0`).
**WARNING:** This command will dump sensitive private key information. Don't blindly share the output, and certainly don't log it anywhere.
```console
$ kubectl ingress-nginx certs --host testaddr.local -n ingress-nginx
$ kubectl ingress-nginx certs -n ingress-nginx --host testaddr.local
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
@ -182,7 +183,7 @@ $ kubectl ingress-nginx certs --host testaddr.local -n ingress-nginx
Use `kubectl ingress-nginx conf` to dump the generated `nginx.conf` file. Add the `--host <hostname>` option to view only the server block for that host:
```console
$ kubectl ingress-nginx conf -n ingress-nginx --host testaddr.local
kubectl ingress-nginx conf -n ingress-nginx --host testaddr.local
server {
server_name testaddr.local ;
@ -212,28 +213,16 @@ $ kubectl ingress-nginx conf -n ingress-nginx --host testaddr.local
```console
$ kubectl ingress-nginx exec -i -n ingress-nginx -- ls /etc/nginx
fastcgi.conf
fastcgi.conf.default
fastcgi_params
fastcgi_params.default
geoip
koi-utf
koi-win
lua
mime.types
mime.types.default
modsecurity
modules
nginx.conf
nginx.conf.default
opentracing.json
owasp-modsecurity-crs
scgi_params
scgi_params.default
template
uwsgi_params
uwsgi_params.default
win-utf
```
### general
@ -241,7 +230,7 @@ win-utf
`kubectl ingress-nginx general` dumps miscellaneous controller state as a JSON object. Currently it just shows the number of controller pods known to a particular controller pod.
```console
$ kubectl ingress-nginx general
$ kubectl ingress-nginx general -n ingress-nginx
{
"controllerPodsCount": 1
}

8
docs/troubleshooting.md
View file

@ -32,7 +32,7 @@ Rules:
/tea tea-svc:80 (<none>)
/coffee coffee-svc:80 (<none>)
Annotations:
kubectl.kubernetes.io/last-applied-configuration: {"apiVersion":"extensions/v1beta1","kind":"Ingress","metadata":{"annotations":{},"name":"cafe-ingress","namespace":"default","selfLink":"/apis/extensions/v1beta1/namespaces/default/ingresses/cafe-ingress"},"spec":{"rules":[{"host":"cafe.com","http":{"paths":[{"backend":{"serviceName":"tea-svc","servicePort":80},"path":"/tea"},{"backend":{"serviceName":"coffee-svc","servicePort":80},"path":"/coffee"}]}}]},"status":{"loadBalancer":{"ingress":[{"ip":"169.48.142.110"}]}}}
kubectl.kubernetes.io/last-applied-configuration: {"apiVersion":"networking.k8s.io/v1beta1","kind":"Ingress","metadata":{"annotations":{},"name":"cafe-ingress","namespace":"default","selfLink":"/apis/networking/v1beta1/namespaces/default/ingresses/cafe-ingress"},"spec":{"rules":[{"host":"cafe.com","http":{"paths":[{"backend":{"serviceName":"tea-svc","servicePort":80},"path":"/tea"},{"backend":{"serviceName":"coffee-svc","servicePort":80},"path":"/coffee"}]}}]},"status":{"loadBalancer":{"ingress":[{"ip":"169.48.142.110"}]}}}
Events:
Type Reason Age From Message
@ -70,7 +70,7 @@ daemon off;
worker_processes 2;
pid /run/nginx.pid;
worker_rlimit_nofile 523264;
worker_shutdown_timeout 10s;
worker_shutdown_timeout 240s;
events {
multi_accept on;
worker_connections 16384;
@ -218,8 +218,8 @@ $ kubectl exec test-701078429-s5kca -- curl --cacert /var/run/secrets/kubernetes
"/apis/batch/v2alpha1",
"/apis/certificates.k8s.io",
"/apis/certificates.k8s.io/v1alpha1",
"/apis/extensions",
"/apis/extensions/v1beta1",
"/apis/networking",
"/apis/networking/v1beta1",
"/apis/policy",
"/apis/policy/v1alpha1",
"/apis/rbac.authorization.k8s.io",

6
docs/user-guide/basic-usage.md
View file

@ -1,11 +1,11 @@
# Basic usage - host based routing
ingress-nginx can be used for many use cases, inside various cloud provider and supports a lot of configurations. In this section you can find a common usage scenario where a single load balancer powerd by ingress-nginx will route traffic to 2 different HTTP backend services based on the host name.
ingress-nginx can be used for many use cases, inside various cloud provider and supports a lot of configurations. In this section you can find a common usage scenario where a single load balancer powered by ingress-nginx will route traffic to 2 different HTTP backend services based on the host name.
First of all follow the instructions to install ingress-nginx. Then imagine that you need to expose 2 HTTP services already installed: `myServiceA`, `myServiceB`. Let's say that you want to expose the first at `myServiceA.foo.org` and the second at `myServiceB.foo.org`. One possible solution is to create two **ingress** resources:
```
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: ingress-myServiceA
@ -22,7 +22,7 @@ spec:
serviceName: myServiceA
servicePort: 80
---
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: ingress-myServiceB

8
docs/user-guide/cli-arguments.md
View file

@ -15,7 +15,8 @@ They are set in the container spec of the `nginx-ingress-controller` Deployment
| `--default-ssl-certificate string` | Secret containing a SSL certificate to be used by the default HTTPS server (catch-all). Takes the form "namespace/name". |
| `--disable-catch-all` | Disable support for catch-all Ingresses. |
| `--election-id string` | Election id to use for Ingress status updates. (default "ingress-controller-leader") |
| `--enable-dynamic-certificates` | Dynamically serves certificates instead of reloading NGINX when certificates are created, updated, or deleted. Currently does not support OCSP stapling, so --enable-ssl-chain-completion must be turned off (default behaviour). Assuming the certificate is generated with a 2048 bit RSA key/cert pair, this feature can store roughly 5000 certificates. (enabled by default) |
| `--enable-dynamic-certificates` | Dynamically serves certificates instead of reloading NGINX when certificates are created, updated, or deleted. Currently does not support OCSP stapling, so --enable-ssl-chain-completion must be turned off (default behaviour). Assuming the certificate is generated with a 2048 bit RSA key/cert pair, this feature can store roughly 5000 certificates. Once the backing Lua shared dictionary `certificate_data` is full, the least recently used certificate will be removed to store new ones. (enabled by default) |
| `--enable-metrics` | Enable the collection of metrics for scraping by Prometheus (default true) |
| `--enable-ssl-chain-completion` | Autocomplete SSL certificate chains with missing intermediate CA certificates. A valid certificate chain is required to enable OCSP stapling. Certificates uploaded to Kubernetes must have the "Authority Information Access" X.509 v3 extension for this to succeed. (default true) |
| `--enable-ssl-passthrough` | Enable SSL Passthrough. |
| `--health-check-path string` | URL path of the health check endpoint. Configured inside the NGINX status server. All requests received on the port defined by the healthz-port parameter are forwarded internally to this path. (default "/healthz") |
@ -23,11 +24,14 @@ They are set in the container spec of the `nginx-ingress-controller` Deployment
| `--healthz-port int` | Port to use for the healthz endpoint. (default 10254) |
| `--http-port int` | Port to use for servicing HTTP traffic. (default 80) |
| `--https-port int` | Port to use for servicing HTTPS traffic. (default 443) |
| `--status-port int` | Port to use for the lua HTTP endpoint configuration. (default 10246) |
| `--stream-port int` | Port to use for the lua TCP/UDP endpoint configuration. (default 10247) |
| `--ingress-class string` | Name of the ingress class this controller satisfies. The class of an Ingress object is set using the annotation "kubernetes.io/ingress.class". All ingress classes are satisfied if this parameter is left empty. |
| `--kubeconfig string` | Path to a kubeconfig file containing authorization and API server information. |
| `--log_backtrace_at traceLocation` | when logging hits line file:N, emit a stack trace (default :0) |
| `--log_dir string` | If non-empty, write log files in this directory |
| `--logtostderr` | log to standard error instead of files (default true) |
| `--metrics-per-host` | enable host labels for prometheus metrics. You may want to disable this to reduce the number of time-series created. (default true) |
| `--profiling` | Enable profiling via web interface host:port/debug/pprof/ (default true) |
| `--publish-service string` | Service fronting the Ingress controller. Takes the form "namespace/name". When used together with update-status, the controller mirrors the address of this service's endpoints to the load-balancer status of all Ingress objects it satisfies. |
| `--publish-status-address string` | Customized address to set as the load-balancer status of Ingress objects this controller satisfies. Requires the update-status parameter. |
@ -40,11 +44,11 @@ They are set in the container spec of the `nginx-ingress-controller` Deployment
| `--udp-services-configmap string` | Name of the ConfigMap containing the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form "namespace/name:port", where "port" can either be a port name or number. |
| `--update-status` | Update the load-balancer status of Ingress objects this controller satisfies. Requires setting the publish-service parameter to a valid Service reference. (default true) |
| `--update-status-on-shutdown` | Update the load-balancer status of Ingress objects when the controller shuts down. Requires the update-status parameter. (default true) |
| `--status-update-interval` | Time interval in seconds in which the status should check if an update is required. (default 60 seconds) |
| `-v`, `--v Level` | log level for V logs |
| `--version` | Show release information about the NGINX Ingress controller and exit. |
| `--vmodule moduleSpec` | comma-separated list of pattern=N settings for file-filtered logging |
| `--watch-namespace string` | Namespace the controller watches for updates to Kubernetes objects. This includes Ingresses, Services and all configuration resources. All namespaces are watched if this parameter is left empty. |
| `--disable-catch-all` | Disable support for catch-all Ingresses. |
|`--validating-webhook`|The address to start an admission controller on|
|`--validating-webhook-certificate`|The certificate the webhook is using for its TLS handling|
|`--validating-webhook-key`|The key the webhook is using for its TLS handling|

2
docs/user-guide/custom-errors.md
View file

@ -28,4 +28,4 @@ See also the [Custom errors][example-custom-errors] example.
[cm-custom-http-errors]: ./nginx-configuration/configmap.md#custom-http-errors
[img-custom-error-pages]: https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages
[example-custom-errors]: ../examples/customization/custom-errors
[example-custom-errors]: ../../examples/customization/custom-errors

4
docs/user-guide/default-backend.md
View file

@ -8,10 +8,6 @@ Basically a default backend exposes two URLs:
- `/healthz` that returns 200
- `/` that returns 404
!!! example
The sub-directory [`/images/404-server`](https://github.com/kubernetes/ingress-nginx/tree/master/images/404-server)
provides a service which satisfies the requirements for a default backend.
!!! example
The sub-directory [`/images/custom-error-pages`](https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages)
provides an additional service for the purpose of customizing the error pages served via the default backend.

115
docs/user-guide/fcgi-services.md Normal file
View file

@ -0,0 +1,115 @@
# Exposing FastCGI Servers
> **FastCGI** is a [binary protocol](https://en.wikipedia.org/wiki/Binary_protocol "Binary protocol") for interfacing interactive programs with a [web server](https://en.wikipedia.org/wiki/Web_server "Web server"). [...] (It's) aim is to reduce the overhead related to interfacing between web server and CGI programs, allowing a server to handle more web page requests per unit of time.
>
> &mdash; Wikipedia
The _ingress-nginx_ ingress controller can be used to directly expose [FastCGI](https://en.wikipedia.org/wiki/FastCGI) servers. Enabling FastCGI in your Ingress only requires setting the _backend-protocol_ annotation to `FCGI`, and with a couple more annotations you can customize the way _ingress-nginx_ handles the communication with your FastCGI _server_.
## Example Objects to Expose a FastCGI Pod
The _Pod_ example object below exposes port `9000`, which is the conventional FastCGI port.
```yaml
apiVersion: v1
kind: Pod
metadata:
name: example-app
labels:
app: example-app
spec:
containers:
- name: example-app
image: example-app:1.0
ports:
- containerPort: 9000
name: fastcgi
```
The _Service_ object example below matches port `9000` from the _Pod_ object above.
```yaml
apiVersion: v1
kind: Service
metadata:
name: example-service
spec:
selector:
app: example-app
ports:
- port: 9000
targetPort: 9000
name: fastcgi
```
And the _Ingress_ and _ConfigMap_ objects below demonstrates the supported _FastCGI_ specific annotations (NGINX actually has 50 FastCGI directives, all of which have not been exposed in the ingress yet), and matches the service `example-service`, and the port named `fastcgi` from above. The _ConfigMap_ **must** be created first for the _Ingress Controller_ to be able to find it when the _Ingress_ object is created, otherwise you will need to restart the _Ingress Controller_ pods.
```yaml
# The ConfigMap MUST be created first for the ingress controller to be able to
# find it when the Ingress object is created.
apiVersion: v1
kind: ConfigMap
metadata:
name: example-cm
data:
SCRIPT_FILENAME: "/example/index.php"
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: "nginx"
nginx.ingress.kubernetes.io/backend-protocol: "FCGI"
nginx.ingress.kubernetes.io/fastcgi-index: "index.php"
nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-cm"
name: example-app
spec:
rules:
- host: app.example.com
http:
paths:
- backend:
serviceName: example-service
servicePort: fastcgi
```
## FastCGI Ingress Annotations
To enable FastCGI, the `nginx.ingress.kubernetes.io/backend-protocol` annotation needs to be set to `FCGI`, which overrides the default `HTTP` value.
> `nginx.ingress.kubernetes.io/backend-protocol: "FCGI"`
**This enables the _FastCGI_ mode for all paths defined in the _Ingress_ object**
### The `nginx.ingress.kubernetes.io/fastcgi-index` Annotation
To specify an index file, the `fastcgi-index` annotation value can optionally be set. In the example below, the value is set to `index.php`. This annotation corresponds to [the _NGINX_ `fastcgi_index` directive](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_index).
> `nginx.ingress.kubernetes.io/fastcgi-index: "index.php"`
### The `nginx.ingress.kubernetes.io/fastcgi-params-configmap` Annotation
To specify [_NGINX_ `fastcgi_param` directives](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param), the `fastcgi-params-configmap` annotation is used, which in turn must lead to a _ConfigMap_ object containing the _NGINX_ `fastcgi_param` directives as key/values.
> `nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-configmap"`
And the _ConfigMap_ object to specify the `SCRIPT_FILENAME` and `HTTP_PROXY` _NGINX's_ `fastcgi_param` directives will look like the following:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: example-configmap
data:
SCRIPT_FILENAME: "/example/index.php"
HTTP_PROXY: ""
```
Using the _namespace/_ prefix is also supported, for example:
> `nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-namespace/example-configmap"`

19
docs/user-guide/ingress-path-matching.md
View file

@ -2,15 +2,20 @@
## Regular Expression Support
!!! important
Regular expressions and wild cards are not supported in the `spec.rules.host` field. Full hostnames must be used.
!!! important
Regular expressions and wild cards are not supported in the `spec.rules.host` field. Full hostnames must be used.
The ingress controller supports **case insensitive** regular expressions in the `spec.rules.http.paths.path` field.
This can be enabled by setting the `nginx.ingress.kubernetes.io/use-regex` annotation to `true` (the default is false).
!!! hint
Kubernetes only accept expressions that comply with the RE2 engine syntax. It is possible that valid expressions accepted by NGINX cannot be used with ingress-nginx, because the PCRE library (used in NGINX) supports a wider syntax than RE2.
See the [RE2 Syntax](https://github.com/google/re2/wiki/Syntax) documentation for differences.
See the [description](./nginx-configuration/annotations.md#use-regex) of the `use-regex` annotation for more details.
```yaml
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: test-ingress
@ -46,7 +51,7 @@ In NGINX, regular expressions follow a **first match** policy. In order to enabl
Let the following two ingress definitions be created:
```yaml
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: test-ingress-1
@ -66,7 +71,7 @@ spec:
```
```yaml
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: test-ingress-2
@ -120,7 +125,7 @@ This case is expected and a result of NGINX's a first match policy for paths tha
Let the following ingress be defined:
```yaml
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: test-ingress-3
@ -153,4 +158,4 @@ location ~* "^/foo/bar/bar" {
}
```
A request to `test.com/foo/bar/bar` would match the `^/foo/[A-Z0-9]{3}` location block instead of the longest EXACT matching path.
A request to `test.com/foo/bar/bar` would match the `^/foo/bar/[A-Z0-9]{3}` location block instead of the longest EXACT matching path.

6
docs/user-guide/monitoring.md
View file

@ -21,12 +21,6 @@ Running the following command deploys prometheus in Kubernetes:
```console
kubectl apply --kustomize github.com/kubernetes/ingress-nginx/deploy/prometheus/
serviceaccount/prometheus-server created
role.rbac.authorization.k8s.io/prometheus-server created
rolebinding.rbac.authorization.k8s.io/prometheus-server created
configmap/prometheus-configuration-bc6bcg7b65 created
service/prometheus-server created
deployment.apps/prometheus-server created
```
### Prometheus Dashboard

193
docs/user-guide/nginx-configuration/annotations.md
View file

@ -17,8 +17,10 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|---------------------------|------|
|[nginx.ingress.kubernetes.io/app-root](#rewrite)|string|
|[nginx.ingress.kubernetes.io/affinity](#session-affinity)|cookie|
|[nginx.ingress.kubernetes.io/affinity-mode](#session-affinity)|"balanced" or "persistent"|
|[nginx.ingress.kubernetes.io/auth-realm](#authentication)|string|
|[nginx.ingress.kubernetes.io/auth-secret](#authentication)|string|
|[nginx.ingress.kubernetes.io/auth-secret-type](#authentication)|string|
|[nginx.ingress.kubernetes.io/auth-type](#authentication)|basic or digest|
|[nginx.ingress.kubernetes.io/auth-tls-secret](#client-certificate-authentication)|string|
|[nginx.ingress.kubernetes.io/auth-tls-verify-depth](#client-certificate-authentication)|number|
@ -26,12 +28,16 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|[nginx.ingress.kubernetes.io/auth-tls-error-page](#client-certificate-authentication)|string|
|[nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream](#client-certificate-authentication)|"true" or "false"|
|[nginx.ingress.kubernetes.io/auth-url](#external-authentication)|string|
|[nginx.ingress.kubernetes.io/auth-cache-key](#external-authentication)|string|
|[nginx.ingress.kubernetes.io/auth-cache-duration](#external-authentication)|string|
|[nginx.ingress.kubernetes.io/auth-proxy-set-headers](#external-authentication)|string|
|[nginx.ingress.kubernetes.io/auth-snippet](#external-authentication)|string|
|[nginx.ingress.kubernetes.io/enable-global-auth](#external-authentication)|"true" or "false"|
|[nginx.ingress.kubernetes.io/backend-protocol](#backend-protocol)|string|HTTP,HTTPS,GRPC,GRPCS,AJP|
|[nginx.ingress.kubernetes.io/canary](#canary)|"true" or "false"|
|[nginx.ingress.kubernetes.io/canary-by-header](#canary)|string|
|[nginx.ingress.kubernetes.io/canary-by-header-value](#canary)|string
|[nginx.ingress.kubernetes.io/canary-by-header-value](#canary)|string|
|[nginx.ingress.kubernetes.io/canary-by-header-pattern](#canary)|string|
|[nginx.ingress.kubernetes.io/canary-by-cookie](#canary)|string|
|[nginx.ingress.kubernetes.io/canary-weight](#canary)|number|
|[nginx.ingress.kubernetes.io/client-body-buffer-size](#client-body-buffer-size)|string|
@ -64,15 +70,24 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|[nginx.ingress.kubernetes.io/proxy-request-buffering](#custom-timeouts)|string|
|[nginx.ingress.kubernetes.io/proxy-redirect-from](#proxy-redirect)|string|
|[nginx.ingress.kubernetes.io/proxy-redirect-to](#proxy-redirect)|string|
|[nginx.ingress.kubernetes.io/proxy-http-version](#proxy-http-version)|"1.0" or "1.1"|
|[nginx.ingress.kubernetes.io/proxy-ssl-secret](#backend-certificate-authentication)|string|
|[nginx.ingress.kubernetes.io/proxy-ssl-ciphers](#backend-certificate-authentication)|string|
|[nginx.ingress.kubernetes.io/proxy-ssl-name](#backend-certificate-authentication)|string|
|[nginx.ingress.kubernetes.io/proxy-ssl-protocols](#backend-certificate-authentication)|string|
|[nginx.ingress.kubernetes.io/proxy-ssl-verify](#backend-certificate-authentication)|string|
|[nginx.ingress.kubernetes.io/proxy-ssl-verify-depth](#backend-certificate-authentication)|number|
|[nginx.ingress.kubernetes.io/enable-rewrite-log](#enable-rewrite-log)|"true" or "false"|
|[nginx.ingress.kubernetes.io/rewrite-target](#rewrite)|URI|
|[nginx.ingress.kubernetes.io/satisfy](#satisfy)|string|
|[nginx.ingress.kubernetes.io/secure-verify-ca-secret](#secure-backends)|string|
|[nginx.ingress.kubernetes.io/server-alias](#server-alias)|string|
|[nginx.ingress.kubernetes.io/server-snippet](#server-snippet)|string|
|[nginx.ingress.kubernetes.io/service-upstream](#service-upstream)|"true" or "false"|
|[nginx.ingress.kubernetes.io/session-cookie-name](#cookie-affinity)|string|
|[nginx.ingress.kubernetes.io/session-cookie-path](#cookie-affinity)|string|
|[nginx.ingress.kubernetes.io/session-cookie-change-on-failure](#cookie-affinity)|"true" or "false"|
|[nginx.ingress.kubernetes.io/session-cookie-samesite](#cookie-affinity)|string|
|[nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none](#cookie-affinity)|"true" or "false"|
|[nginx.ingress.kubernetes.io/ssl-redirect](#server-side-https-enforcement-through-redirect)|"true" or "false"|
|[nginx.ingress.kubernetes.io/ssl-passthrough](#ssl-passthrough)|"true" or "false"|
|[nginx.ingress.kubernetes.io/upstream-hash-by](#custom-nginx-upstream-hashing)|string|
@ -83,9 +98,11 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|[nginx.ingress.kubernetes.io/proxy-buffering](#proxy-buffering)|string|
|[nginx.ingress.kubernetes.io/proxy-buffers-number](#proxy-buffers-number)|number|
|[nginx.ingress.kubernetes.io/proxy-buffer-size](#proxy-buffer-size)|string|
|[nginx.ingress.kubernetes.io/proxy-max-temp-file-size](#proxy-max-temp-file-size)|string|
|[nginx.ingress.kubernetes.io/ssl-ciphers](#ssl-ciphers)|string|
|[nginx.ingress.kubernetes.io/connection-proxy-header](#connection-proxy-header)|string|
|[nginx.ingress.kubernetes.io/enable-access-log](#enable-access-log)|"true" or "false"|
|[nginx.ingress.kubernetes.io/enable-opentracing](#enable-opentracing)|"true" or "false"|
|[nginx.ingress.kubernetes.io/lua-resty-waf](#lua-resty-waf)|string|
|[nginx.ingress.kubernetes.io/lua-resty-waf-debug](#lua-resty-waf)|"true" or "false"|
|[nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets](#lua-resty-waf)|string|
@ -103,6 +120,8 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|[nginx.ingress.kubernetes.io/enable-owasp-core-rules](#modsecurity)|bool|
|[nginx.ingress.kubernetes.io/modsecurity-transaction-id](#modsecurity)|string|
|[nginx.ingress.kubernetes.io/modsecurity-snippet](#modsecurity)|string|
|[nginx.ingress.kubernetes.io/mirror-request-body](#mirror)|string|
|[nginx.ingress.kubernetes.io/mirror-target](#mirror)|string|
### Canary
@ -112,18 +131,20 @@ In some cases, you may want to "canary" a new set of changes by sending a small
* `nginx.ingress.kubernetes.io/canary-by-header-value`: The header value to match for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the request header is set to this value, it will be routed to the canary. For any other header value, the header will be ignored and the request compared against the other canary rules by precedence. This annotation has to be used together with . The annotation is an extension of the `nginx.ingress.kubernetes.io/canary-by-header` to allow customizing the header value instead of using hardcoded values. It doesn't have any effect if the `nginx.ingress.kubernetes.io/canary-by-header` annotation is not defined.
* `nginx.ingress.kubernetes.io/canary-by-cookie`: The cookie to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the cookie value is set to `always`, it will be routed to the canary. When the cookie is set to `never`, it will never be routed to the canary. For any other value, the cookie will be ingored and the request compared against the other canary rules by precedence.
* `nginx.ingress.kubernetes.io/canary-by-header-pattern`: This works the same way as `canary-by-header-value` except it does PCRE Regex matching. Note that when `canary-by-header-value` is set this annotation will be ignored. When the given Regex causes error during request processing, the request will be considered as not matching.
* `nginx.ingress.kubernetes.io/canary-weight`: The integer based (0 - 100) percent of random requests that should be routed to the service specified in the canary Ingress. A weight of 0 implies that no requests will be sent to the service in the Canary ingress by this canary rule. A weight of 100 means implies all requests will be sent to the alternative service specified in the Ingress.
* `nginx.ingress.kubernetes.io/canary-by-cookie`: The cookie to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the cookie value is set to `always`, it will be routed to the canary. When the cookie is set to `never`, it will never be routed to the canary. For any other value, the cookie will be ignored and the request compared against the other canary rules by precedence.
Canary rules are evaluated in order of precedence. Precedence is as follows:
`canary-by-header -> canary-by-cookie -> canary-weight`
* `nginx.ingress.kubernetes.io/canary-weight`: The integer based (0 - 100) percent of random requests that should be routed to the service specified in the canary Ingress. A weight of 0 implies that no requests will be sent to the service in the Canary ingress by this canary rule. A weight of 100 means implies all requests will be sent to the alternative service specified in the Ingress.
Canary rules are evaluated in order of precedence. Precedence is as follows:
`canary-by-header -> canary-by-cookie -> canary-weight`
**Note** that when you mark an ingress as canary, then all the other non-canary annotations will be ignored (inherited from the corresponding main ingress) except `nginx.ingress.kubernetes.io/load-balance` and `nginx.ingress.kubernetes.io/upstream-hash-by`.
**Known Limitations**
Currently a maximum of one canary ingress can be applied per Ingress rule.
Currently a maximum of one canary ingress can be applied per Ingress rule.
### Rewrite
@ -140,8 +161,10 @@ If the Application Root is exposed in a different path and needs to be redirecte
The annotation `nginx.ingress.kubernetes.io/affinity` enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.
The only affinity type available for NGINX is `cookie`.
The annotation `nginx.ingress.kubernetes.io/affinity-mode` defines the stickyness of a session. Setting this to `balanced` (default) will redistribute some sessions if a deployment gets scaled up, therefore rebalancing the load on the servers. Setting this to `persistent` will not rebalance sessions to new servers, therefore providing maximum stickyness.
!!! attention
If more than one Ingress is defined for a host and at least one Ingress uses `nginx.ingress.kubernetes.io/affinity: cookie`, then only paths on the Ingress using `nginx.ingress.kubernetes.io/affinity` will use session cookie affinity. All paths defined on other Ingresses for the host will be load balanced through the random selection of a backend server.
If more than one Ingress is defined for a host and at least one Ingress uses `nginx.ingress.kubernetes.io/affinity: cookie`, then only paths on the Ingress using `nginx.ingress.kubernetes.io/affinity` will use session cookie affinity. All paths defined on other Ingresses for the host will be load balanced through the random selection of a backend server.
!!! example
Please check the [affinity](../../examples/affinity/cookie/README.md) example.
@ -150,12 +173,13 @@ The only affinity type available for NGINX is `cookie`.
If you use the ``cookie`` affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation `nginx.ingress.kubernetes.io/session-cookie-name`. The default is to create a cookie named 'INGRESSCOOKIE'.
The NGINX annotation `nginx.ingress.kubernetes.io/session-cookie-path` defines the path that will be set on the cookie. This is optional unless the annotation `nginx.ingress.kubernetes.io/use-regex` is set to true; Session cookie paths do not support regex.
The NGINX annotation `nginx.ingress.kubernetes.io/session-cookie-path` defines the path that will be set on the cookie. This is optional unless the annotation `nginx.ingress.kubernetes.io/use-regex` is set to true; Session cookie paths do not support regex.
Use `nginx.ingress.kubernetes.io/session-cookie-samesite` to apply a `SameSite` attribute to the sticky cookie. Browser accepted values are `None`, `Lax`, and `Strict`. Some browsers reject cookies with `SameSite=None`, including those created before the `SameSite=None` specification (e.g. Chrome 5X). Other browsers mistakenly treat `SameSite=None` cookies as `SameSite=Strict` (e.g. Safari running on OSX 14). To omit `SameSite=None` from browsers with these incompatibilities, add the annotation `nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true"`.
### Authentication
Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key `auth`.
Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords.
The annotations are:
```
@ -171,6 +195,15 @@ nginx.ingress.kubernetes.io/auth-secret: secretName
The name of the Secret that contains the usernames and passwords which are granted access to the `path`s defined in the Ingress rules.
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.
```
nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]
```
The `auth-secret` can have two forms:
- `auth-file` - default, an htpasswd file in the key `auth` within the secret
- `auth-map` - the keys of the secret are the usernames, and the values are the hashed passwords
```
nginx.ingress.kubernetes.io/auth-realm: "realm string"
```
@ -229,6 +262,23 @@ The annotations are:
Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: [https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls](https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls)
### Backend Certificate Authentication
It is possible to authenticate to a proxied HTTPS backend with certificate using additional annotations in Ingress Rule.
* `nginx.ingress.kubernetes.io/proxy-ssl-secret: secretName`:
Specifies a Secret with the certificate `tls.crt`, key `tls.key` in PEM format used for authentication to a proxied HTTPS server. It should also contain trusted CA certificates `ca.crt` in PEM format used to verify the certificate of the proxied HTTPS server.
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.
* `nginx.ingress.kubernetes.io/proxy-ssl-verify`:
Enables or disables verification of the proxied HTTPS server certificate. (default: off)
* `nginx.ingress.kubernetes.io/proxy-ssl-verify-depth`:
Sets the verification depth in the proxied HTTPS server certificates chain. (default: 1)
* `nginx.ingress.kubernetes.io/proxy-ssl-ciphers`:
Specifies the enabled [ciphers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_ciphers) for requests to a proxied HTTPS server. The ciphers are specified in the format understood by the OpenSSL library.
* `nginx.ingress.kubernetes.io/proxy-ssl-name`:
Allows to set [proxy_ssl_name](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_name). This allows overriding the server name used to verify the certificate of the proxied HTTPS server. This value is also passed through SNI when a connection is established to the proxied HTTPS server.
* `nginx.ingress.kubernetes.io/proxy-ssl-protocols`:
Enables the specified [protocols](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_protocols) for requests to a proxied HTTPS server.
### Configuration snippet
@ -293,7 +343,7 @@ CORS can be controlled with the following annotations:
Example: `nginx.ingress.kubernetes.io/cors-max-age: 600`
!!! note
For more information please see [https://enable-cors.org](https://enable-cors.org/server_nginx.html)
For more information please see [https://enable-cors.org](https://enable-cors.org/server_nginx.html)
### HTTP2 Push Preload.
@ -305,13 +355,13 @@ Enables automatic conversion of preload links specified in the “Link” respon
### Server Alias
To add Server Aliases to an Ingress rule add the annotation `nginx.ingress.kubernetes.io/server-alias: "<alias>"`.
This will create a server with the same configuration, but a different `server_name` as the provided host.
Allows the definition of one or more aliases in the server definition of the NGINX configuration using the annotation `nginx.ingress.kubernetes.io/server-alias: "<alias 1>,<alias 2>"`.
This will create a server with the same configuration, but adding new values to the `server_name` directive.
!!! Note
A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored.
If a server-alias is created and later a new server with the same hostname is created,
the new server configuration will take place over the alias configuration.
!!! note
A server-alias name cannot conflict with the hostname of an existing server. If it does, the server-alias annotation will be ignored.
If a server-alias is created and later a new server with the same hostname is created, the new server configuration will take
place over the alias configuration.
For more information please see [the `server_name` documentation](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name).
@ -320,17 +370,17 @@ For more information please see [the `server_name` documentation](http://nginx.o
Using the annotation `nginx.ingress.kubernetes.io/server-snippet` it is possible to add custom configuration in the server configuration block.
```yaml
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
annotations:
nginx.ingress.kubernetes.io/server-snippet: |
set $agentflag 0;
if ($http_user_agent ~* "(Mobile)" ){
set $agentflag 1;
}
if ( $agentflag = 1 ) {
return 301 https://m.example.com;
}
@ -375,8 +425,14 @@ Additionally it is possible to set:
`<SignIn_URL>` to specify the location of the error page.
* `nginx.ingress.kubernetes.io/auth-response-headers`:
`<Response_Header_1, ..., Response_Header_n>` to specify headers to pass to backend once authentication request completes.
* `nginx.ingress.kubernetes.io/auth-proxy-set-headers`:
`<ConfigMap>` the name of a ConfigMap that specifies headers to pass to the authentication service
* `nginx.ingress.kubernetes.io/auth-request-redirect`:
`<Request_Redirect_URL>` to specify the X-Auth-Request-Redirect header value.
* `nginx.ingress.kubernetes.io/auth-cache-key`:
`<Cache_Key>` this enables caching for auth requests. specify a lookup key for auth responses. e.g. `$remote_user$http_authorization`. Each server and location has it's own keyspace. Hence a cached response is only valid on a per-server and per-location basis.
* `nginx.ingress.kubernetes.io/auth-cache-duration`:
`<Cache_duration>` to specify a caching time for auth responses based on their response codes, e.g. `200 202 30m`. See [proxy_cache_valid](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid) for details. You may specify multiple, comma-separated values: `200 202 10m, 401 5m`. defaults to `200 202 401 5m`.
* `nginx.ingress.kubernetes.io/auth-snippet`:
`<Auth_Snippet>` to specify a custom snippet to use with external authentication, e.g.
@ -396,26 +452,25 @@ By default the controller redirects all requests to an existing service that pro
`nginx.ingress.kubernetes.io/enable-global-auth`:
indicates if GlobalExternalAuth configuration should be applied or not to this Ingress rule. Default values is set to `"true"`.
!!! note For more information please see [global-auth-url](./configmap.md#global-auth-url).
!!! note
For more information please see [global-auth-url](./configmap.md#global-auth-url).
### Rate limiting
These annotations define a limit on the connections that can be opened by a single client IP address.
This can be used to mitigate [DDoS Attacks](https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus).
These annotations define limits on connections and transmission rates. These can be used to mitigate [DDoS Attacks](https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus).
* `nginx.ingress.kubernetes.io/limit-connections`: number of concurrent connections allowed from a single IP address.
* `nginx.ingress.kubernetes.io/limit-rps`: number of connections that may be accepted from a given IP each second.
* `nginx.ingress.kubernetes.io/limit-rpm`: number of connections that may be accepted from a given IP each minute.
* `nginx.ingress.kubernetes.io/limit-rate-after`: sets the initial amount after which the further transmission of a response to a client will be rate limited.
* `nginx.ingress.kubernetes.io/limit-rate`: rate of request that accepted from a client each second.
* `nginx.ingress.kubernetes.io/limit-connections`: number of concurrent connections allowed from a single IP address. A 503 error is returned when exceeding this limit.
* `nginx.ingress.kubernetes.io/limit-rps`: number of requests accepted from a given IP each second. The burst limit is set to 5 times the limit. When clients exceed this limit, [limit-req-status-code](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code) ***default:*** 503 is returned.
* `nginx.ingress.kubernetes.io/limit-rpm`: number of requests accepted from a given IP each minute. The burst limit is set to 5 times the limit. When clients exceed this limit, [limit-req-status-code](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code) ***default:*** 503 is returned.
* `nginx.ingress.kubernetes.io/limit-rate-after`: initial number of kilobytes after which the further transmission of a response to a given connection will be rate limited. This feature must be used with [proxy-buffering](#proxy-buffering) enabled.
* `nginx.ingress.kubernetes.io/limit-rate`: number of kilobytes per second allowed to send to a given connection. The zero value disables rate limiting. This feature must be used with [proxy-buffering](#proxy-buffering) enabled.
* `nginx.ingress.kubernetes.io/limit-whitelist`: client IP source ranges to be excluded from rate-limiting. The value is a comma separated list of CIDRs.
You can specify the client IP source ranges to be excluded from rate-limiting through the `nginx.ingress.kubernetes.io/limit-whitelist` annotation. The value is a comma separated list of CIDRs.
If you specify multiple annotations in a single Ingress rule, limits are applied in the order `limit-connections`, `limit-rpm`, `limit-rps`.
If you specify multiple annotations in a single Ingress rule, `limit-rpm`, and then `limit-rps` takes precedence.
To configure settings globally for all Ingress rules, the `limit-rate-after` and `limit-rate` values may be set in the [NGINX ConfigMap](./configmap.md#limit-rate). The value set in an Ingress annotation will override the global setting.
The annotation `nginx.ingress.kubernetes.io/limit-rate`, `nginx.ingress.kubernetes.io/limit-rate-after` define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.
To configure this setting globally for all Ingress rules, the `limit-rate-after` and `limit-rate` value may be set in the [NGINX ConfigMap](./configmap.md#limit-rate). if you set the value in ingress annotation will cover global setting.
The client IP address will be set based on the use of [PROXY protocol](./configmap.md#use-proxy-protocol) or from the `X-Forwarded-For` header value when [use-forwarded-headers](./configmap.md#use-forwarded-headers) is enabled.
### Permanent Redirect
@ -550,7 +605,7 @@ nginx.ingress.kubernetes.io/proxy-buffering: "on"
### Proxy buffers Number
Sets the number of the buffers in [`proxy_buffers`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) used for reading the first part of the response received from the proxied server.
Sets the number of the buffers in [`proxy_buffers`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) used for reading the first part of the response received from the proxied server.
By default proxy buffers number is set as 4
To configure this setting globally, set `proxy-buffers-number` in [NGINX ConfigMap](./configmap.md#proxy-buffers-number). To use custom values in an Ingress rule, define this annotation:
@ -568,6 +623,26 @@ To configure this setting globally, set `proxy-buffer-size` in [NGINX ConfigMap]
nginx.ingress.kubernetes.io/proxy-buffer-size: "8k"
```
### Proxy max temp file size
When [`buffering`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) of responses from the proxied server is enabled, and the whole response does not fit into the buffers set by the [`proxy_buffer_size`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [`proxy_buffers`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directives, a part of the response can be saved to a temporary file. This directive sets the maximum `size` of the temporary file setting the [`proxy_max_temp_file_size`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size). The size of data written to the temporary file at a time is set by the [`proxy_temp_file_write_size`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_temp_file_write_size) directive.
The zero value disables buffering of responses to temporary files.
To use custom values in an Ingress rule, define this annotation:
```yaml
nginx.ingress.kubernetes.io/proxy-max-temp-file-size: "1024m"
```
### Proxy HTTP version
Using this annotation sets the [`proxy_http_version`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) that the Nginx reverse proxy will use to communicate with the backend.
By default this is set to "1.1".
```yaml
nginx.ingress.kubernetes.io/proxy-http-version: "1.0"
```
### SSL ciphers
Specifies the [enabled ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers).
@ -605,6 +680,15 @@ Note that rewrite logs are sent to the error_log file at the notice level. To en
nginx.ingress.kubernetes.io/enable-rewrite-log: "true"
```
### Enable Opentracing
Opentracing can be enabled or disabled globally through the ConfigMap but this will sometimes need to be overridden
to enable it or disable it for a specific ingress (e.g. to turn off tracing of external health check endpoints)
```yaml
nginx.ingress.kubernetes.io/enable-opentracing: "true"
```
### X-Forwarded-Prefix Header
To add the non-standard `X-Forwarded-Prefix` header to the upstream request with a string value, the following annotation can be used:
@ -680,7 +764,7 @@ of ingress locations. The ModSecurity module must first be enabled by enabling M
[ConfigMap](./configmap.md#enable-modsecurity). Note this will enable ModSecurity for all paths, and each path
must be disabled manually.
It can be enabled using the following annotation:
It can be enabled using the following annotation:
```yaml
nginx.ingress.kubernetes.io/enable-modsecurity: "true"
```
@ -705,14 +789,21 @@ SecDebugLog /tmp/modsec_debug.log
```
Note: If you use both `enable-owasp-core-rules` and `modsecurity-snippet` annotations together, only the
`modsecurity-snippet` will take effect. If you wish to include the [OWASP Core Rule Set](https://www.modsecurity.org/CRS/Documentation/) or
`modsecurity-snippet` will take effect. If you wish to include the [OWASP Core Rule Set](https://www.modsecurity.org/CRS/Documentation/) or
[recommended configuration](https://github.com/SpiderLabs/ModSecurity/blob/v3/master/modsecurity.conf-recommended) simply use the include
statement:
nginx 0.24.1 and below
```yaml
nginx.ingress.kubernetes.io/modsecurity-snippet: |
Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf
Include /etc/nginx/modsecurity/modsecurity.conf
```
nginx 0.25.0 and above
```yaml
nginx.ingress.kubernetes.io/modsecurity-snippet: |
Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf
```
### InfluxDB
@ -729,7 +820,7 @@ nginx.ingress.kubernetes.io/influxdb-server-name: "nginx-ingress"
For the `influxdb-host` parameter you have two options:
- Use an InfluxDB server configured with the [UDP protocol](https://docs.influxdata.com/influxdb/v1.5/supported_protocols/udp/) enabled.
- Use an InfluxDB server configured with the [UDP protocol](https://docs.influxdata.com/influxdb/v1.5/supported_protocols/udp/) enabled.
- Deploy Telegraf as a sidecar proxy to the Ingress controller configured to listen UDP with the [socket listener input](https://github.com/influxdata/telegraf/tree/release-1.6/plugins/inputs/socket_listener) and to write using
anyone of the [outputs plugins](https://github.com/influxdata/telegraf/tree/release-1.7/plugins/outputs) like InfluxDB, Apache Kafka,
Prometheus, etc.. (recommended)
@ -753,7 +844,7 @@ nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
### Use Regex
!!! attention
When using this annotation with the NGINX annotation `nginx.ingress.kubernetes.io/affinity` of type `cookie`, `nginx.ingress.kubernetes.io/session-cookie-path` must be also set; Session cookie paths do not support regex.
When using this annotation with the NGINX annotation `nginx.ingress.kubernetes.io/affinity` of type `cookie`, `nginx.ingress.kubernetes.io/session-cookie-path` must be also set; Session cookie paths do not support regex.
Using the `nginx.ingress.kubernetes.io/use-regex` annotation will indicate whether or not the paths defined on an Ingress use regular expressions. The default value is `false`.
@ -769,9 +860,9 @@ nginx.ingress.kubernetes.io/use-regex: "false"
When this annotation is set to `true`, the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
Additionally, if the [`rewrite-target` annotation](#rewrite) is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
Additionally, if the [`rewrite-target` annotation](#rewrite) is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
Please read about [ingress path matching](../ingress-path-matching.md) before using this modifier.
Please read about [ingress path matching](../ingress-path-matching.md) before using this modifier.
### Satisfy
@ -780,3 +871,25 @@ By default, a request would need to satisfy all authentication requirements in o
```yaml
nginx.ingress.kubernetes.io/satisfy: "any"
```
### Mirror
Enables a request to be mirrored to a mirror backend. Responses by mirror backends are ignored. This feature is useful, to see how requests will react in "test" backends.
The mirror backend can be set by applying:
```yaml
nginx.ingress.kubernetes.io/mirror-target: https://test.env.com/$request_uri
```
By default the request-body is sent to the mirror backend, but can be turned off by applying:
```yaml
nginx.ingress.kubernetes.io/mirror-request-body: "off"
```
**Note:** The mirror directive will be applied to all paths within the ingress resource.
The request sent to the mirror is linked to the original request. If you have a slow mirror backend, then the original request will throttle.
For more information on the mirror module see [ngx_http_mirror_module](https://nginx.org/en/docs/http/ngx_http_mirror_module.html)

169
docs/user-guide/nginx-configuration/configmap.md
View file

@ -14,7 +14,7 @@ data:
ssl-protocols: SSLv2
```
!!! Important
!!! important
The key and values in a ConfigMap can only be strings.
This means that we want a value with boolean values we need to quote the values, like "true" or "false".
Same for numbers, like "100".
@ -34,8 +34,8 @@ The following table shows a configuration option's name, type, and the default v
|[access-log-path](#access-log-path)|string|"/var/log/nginx/access.log"|
|[enable-access-log-for-default-backend](#enable-access-log-for-default-backend)|bool|"false"|
|[error-log-path](#error-log-path)|string|"/var/log/nginx/error.log"|
|[enable-dynamic-tls-records](#enable-dynamic-tls-records)|bool|"true"|
|[enable-modsecurity](#enable-modsecurity)|bool|"false"|
|[modsecurity-snippet](#modsecurity-snippet)|string|""|
|[enable-owasp-modsecurity-crs](#enable-owasp-modsecurity-crs)|bool|"false"|
|[client-header-buffer-size](#client-header-buffer-size)|string|"1k"|
|[client-header-timeout](#client-header-timeout)|int|60|
@ -51,6 +51,7 @@ The following table shows a configuration option's name, type, and the default v
|[http2-max-field-size](#http2-max-field-size)|string|"4k"|
|[http2-max-header-size](#http2-max-header-size)|string|"16k"|
|[http2-max-requests](#http2-max-requests)|int|1000|
|[http2-max-concurrent-streams](#http2-max-concurrent-streams)|int|1000|
|[hsts](#hsts)|bool|"true"|
|[hsts-include-subdomains](#hsts-include-subdomains)|bool|"true"|
|[hsts-max-age](#hsts-max-age)|string|"15724800"|
@ -59,8 +60,8 @@ The following table shows a configuration option's name, type, and the default v
|[keep-alive-requests](#keep-alive-requests)|int|100|
|[large-client-header-buffers](#large-client-header-buffers)|string|"4 8k"|
|[log-format-escape-json](#log-format-escape-json)|bool|"false"|
|[log-format-upstream](#log-format-upstream)|string|`%v - [$the_real_ip] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id`|
|[log-format-stream](#log-format-stream)|string|`[$time_local] $protocol $status $bytes_sent $bytes_received $session_time`|
|[log-format-upstream](#log-format-upstream)|string|`$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id`|
|[log-format-stream](#log-format-stream)|string|`[$remote_addr] [$time_local] $protocol $status $bytes_sent $bytes_received $session_time`|
|[enable-multi-accept](#enable-multi-accept)|bool|"true"|
|[max-worker-connections](#max-worker-connections)|int|16384|
|[max-worker-open-files](#max-worker-open-files)|int|0|
@ -92,13 +93,13 @@ The following table shows a configuration option's name, type, and the default v
|[use-geoip2](#use-geoip2)|bool|"false"|
|[enable-brotli](#enable-brotli)|bool|"false"|
|[brotli-level](#brotli-level)|int|4|
|[brotli-types](#brotli-types)|string|"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component"|
|[brotli-types](#brotli-types)|string|"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component"|
|[use-http2](#use-http2)|bool|"true"|
|[gzip-level](#gzip-level)|int|5|
|[gzip-types](#gzip-types)|string|"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component"|
|[gzip-types](#gzip-types)|string|"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component"|
|[worker-processes](#worker-processes)|string|`<Number of CPUs>`|
|[worker-cpu-affinity](#worker-cpu-affinity)|string|""|
|[worker-shutdown-timeout](#worker-shutdown-timeout)|string|"10s"|
|[worker-shutdown-timeout](#worker-shutdown-timeout)|string|"240s"|
|[load-balance](#load-balance)|string|"round_robin"|
|[variables-hash-bucket-size](#variables-hash-bucket-size)|int|128|
|[variables-hash-max-size](#variables-hash-max-size)|int|2048|
@ -112,7 +113,7 @@ The following table shows a configuration option's name, type, and the default v
|[use-forwarded-headers](#use-forwarded-headers)|bool|"false"|
|[forwarded-for-header](#forwarded-for-header)|string|"X-Forwarded-For"|
|[compute-full-forwarded-for](#compute-full-forwarded-for)|bool|"false"|
|[proxy-add-original-uri-header](#proxy-add-original-uri-header)|bool|"true"|
|[proxy-add-original-uri-header](#proxy-add-original-uri-header)|bool|"false"|
|[generate-request-id](#generate-request-id)|bool|"true"|
|[enable-opentracing](#enable-opentracing)|bool|"false"|
|[zipkin-collector-host](#zipkin-collector-host)|string|""|
@ -126,6 +127,16 @@ The following table shows a configuration option's name, type, and the default v
|[jaeger-sampler-param](#jaeger-sampler-param)|string|"1"|
|[jaeger-sampler-host](#jaeger-sampler-host)|string|"http://127.0.0.1"|
|[jaeger-sampler-port](#jaeger-sampler-port)|int|5778|
|[jaeger-trace-context-header-name](#jaeger-trace-context-header-name)|string|uber-trace-id|
|[jaeger-debug-header](#jaeger-debug-header)|string|uber-debug-id|
|[jaeger-baggage-header](#jaeger-baggage-header)|string|jaeger-baggage|
|[jaeger-trace-baggage-header-prefix](#jaeger-trace-baggage-header-prefix)|string|uberctx-|
|[datadog-collector-host](#datadog-collector-host)|string|""|
|[datadog-collector-port](#datadog-collector-port)|int|8126|
|[datadog-service-name](#datadog-service-name)|service|"nginx"|
|[datadog-operation-name-override](#datadog-operation-name-override)|service|"nginx.handle"|
|[datadog-priority-sampling](#datadog-priority-sampling)|bool|"true"|
|[datadog-sample-rate](#datadog-sample-rate)|float|1.0|
|[main-snippet](#main-snippet)|string|""|
|[http-snippet](#http-snippet)|string|""|
|[server-snippet](#server-snippet)|string|""|
@ -149,6 +160,7 @@ The following table shows a configuration option's name, type, and the default v
|[skip-access-log-urls](#skip-access-log-urls)|[]string|[]string{}|
|[limit-rate](#limit-rate)|int|0|
|[limit-rate-after](#limit-rate-after)|int|0|
|[lua-shared-dicts](#lua-shared-dicts)|string|""|
|[http-redirect-code](#http-redirect-code)|int|308|
|[proxy-buffering](#proxy-buffering)|string|"off"|
|[limit-req-status-code](#limit-req-status-code)|int|503|
@ -160,10 +172,13 @@ The following table shows a configuration option's name, type, and the default v
|[global-auth-response-headers](#global-auth-response-headers)|string|""|
|[global-auth-request-redirect](#global-auth-request-redirect)|string|""|
|[global-auth-snippet](#global-auth-snippet)|string|""|
|[global-auth-cache-key](#global-auth-cache-key)|string|""|
|[global-auth-cache-duration](#global-auth-cache-duration)|string|"200 202 401 5m"|
|[no-auth-locations](#no-auth-locations)|string|"/.well-known/acme-challenge"|
|[block-cidrs](#block-cidrs)|[]string|""|
|[block-user-agents](#block-user-agents)|[]string|""|
|[block-referers](#block-referers)|[]string|""|
|[proxy-ssl-location-only](#proxy-ssl-location-only)|bool|"false"|
## add-headers
@ -196,7 +211,7 @@ __Note:__ the file `/var/log/nginx/access.log` is a symlink to `/dev/stdout`
## enable-access-log-for-default-backend
Enables logging access to default backend. _**default:**_ is disabled.
Enables logging access to default backend. _**default:**_ is disabled.
## error-log-path
@ -207,13 +222,6 @@ __Note:__ the file `/var/log/nginx/error.log` is a symlink to `/dev/stderr`
_References:_
[http://nginx.org/en/docs/ngx_core_module.html#error_log](http://nginx.org/en/docs/ngx_core_module.html#error_log)
## enable-dynamic-tls-records
Enables dynamically sized TLS records to improve time-to-first-byte. _**default:**_ is enabled
_References:_
[https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency](https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency)
## enable-modsecurity
Enables the modsecurity module for NGINX. _**default:**_ is disabled
@ -222,6 +230,10 @@ Enables the modsecurity module for NGINX. _**default:**_ is disabled
Enables the OWASP ModSecurity Core Rule Set (CRS). _**default:**_ is disabled
## modsecurity-snippet
Adds custom rules to modsecurity section of nginx configration
## client-header-buffer-size
Allows to configure a custom buffer size for reading client request header.
@ -306,6 +318,13 @@ Sets the maximum number of requests (including push requests) that can be served
_References:_
[http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_requests](http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_requests)
## http2-max-concurrent-streams
Sets the maximum number of concurrent HTTP/2 streams in a connection.
_References:_
[http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_concurrent_streams](http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_concurrent_streams)
## hsts
Enables or disables the header HSTS in servers running SSL.
@ -358,15 +377,13 @@ Sets if the escape parameter allows JSON ("true") or default characters escaping
Sets the nginx [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format).
Example for json output:
```console
log-format-upstream: '{ "time": "$time_iso8601", "remote_addr": "$proxy_protocol_addr",
"x-forward-for": "$proxy_add_x_forwarded_for", "request_id": "$req_id", "remote_user":
"$remote_user", "bytes_sent": $bytes_sent, "request_time": $request_time, "status":
$status, "vhost": "$host", "request_proto": "$server_protocol", "path": "$uri",
"request_query": "$args", "request_length": $request_length, "duration": $request_time,
"method": "$request_method", "http_referrer": "$http_referer", "http_user_agent":
"$http_user_agent" }'
```
```json
log-format-upstream: '{"time": "$time_iso8601", "remote_addr": "$proxy_protocol_addr", "x-forward-for": "$proxy_add_x_forwarded_for", "request_id": "$req_id",
"remote_user": "$remote_user", "bytes_sent": $bytes_sent, "request_time": $request_time, "status":$status, "vhost": "$host", "request_proto": "$server_protocol",
"path": "$uri", "request_query": "$args", "request_length": $request_length, "duration": $request_time,"method": "$request_method", "http_referrer": "$http_referer",
"http_user_agent": "$http_user_agent" }'
```
Please check the [log-format](log-format.md) for definition of each field.
@ -439,7 +456,7 @@ _References:_
Instructs NGINX to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes
_**default:**_ true
## proxy-headers-hash-bucket-size
## proxy-headers-hash-bucket-size
Sets the size of the bucket for the proxy headers hash tables.
@ -486,6 +503,14 @@ Sets the [SSL protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#
Please check the result of the configuration using `https://ssllabs.com/ssltest/analyze.html` or `https://testssl.sh`.
## ssl-early-data
Enables or disables TLS 1.3 [early data](https://tools.ietf.org/html/rfc8446#section-2.3)
This requires `ssl-protocols` to have `TLSv1.3` enabled.
[ssl_early_data](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data). The default is: `false`.
## ssl-session-cache
Enables or disables the use of shared [SSL cache](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) among worker processes.
@ -503,7 +528,7 @@ Enables or disables session resumption through [TLS session tickets](http://ngin
Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string.
To create a ticket: `openssl rand 80 | openssl enc -A -base64`
[TLS session ticket-key](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets), by default, a randomly generated key is used.
[TLS session ticket-key](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets), by default, a randomly generated key is used.
## ssl-session-timeout
@ -539,6 +564,13 @@ _**default:**_ true
## use-geoip2
Enables the [geoip2 module](https://github.com/leev/ngx_http_geoip2_module) for NGINX.
Since `0.27.0` and due to a [change in the MaxMind databases](https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases) a license is required to have access to the databases.
For this reason, it is required to define a new flag `--maxmind-license-key` in the ingress controller deployment to download the databases needed during the initialization of the ingress controller.
Alternatively, it is possible to use a volume to mount the files `/etc/nginx/geoip/GeoLite2-City.mmdb` and `/etc/nginx/geoip/GeoLite2-ASN.mmdb`, avoiding the overhead of the download.
!!! important
If the feature is enabled but the files are missing, GeoIP2 will not be enabled.
_**default:**_ false
## enable-brotli
@ -565,6 +597,10 @@ Enables or disables [HTTP/2](http://nginx.org/en/docs/http/ngx_http_v2_module.ht
Sets the gzip Compression Level that will be used. _**default:**_ 5
## gzip-min-length
Minimum length of responses to be returned to the client before it is eligible for gzip compression, in bytes. _**default:**_ 256
## gzip-types
Sets the MIME types in addition to "text/html" to compress. The special value "\*" matches any MIME type. Responses with the "text/html" type are always compressed if `[use-gzip](#use-gzip)` is enabled.
@ -586,7 +622,7 @@ By default worker processes are not bound to any specific CPUs. The value can be
## worker-shutdown-timeout
Sets a timeout for Nginx to [wait for worker to gracefully shutdown](http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout). _**default:**_ "10s"
Sets a timeout for Nginx to [wait for worker to gracefully shutdown](http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout). _**default:**_ "240s"
## load-balance
@ -622,7 +658,7 @@ _References:_
Activates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle
keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is
exceeded, the least recently used connections are closed.
exceeded, the least recently used connections are closed.
_**default:**_ 32
_References:_
@ -643,7 +679,7 @@ _References:_
Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of
requests is made, the connection is closed.
_**default:**_ 100
_References:_
[http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests)
@ -746,6 +782,48 @@ Leave blank to use default value (localhost). _**default:**_ http://127.0.0.1
Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. _**default:**_ 5778
## jaeger-trace-context-header-name
Specifies the header name used for passing trace context. _**default:**_ uber-trace-id
## jaeger-debug-header
Specifies the header name used for force sampling. _**default:**_ jaeger-debug-id
## jaeger-baggage-header
Specifies the header name used to submit baggage if there is no root span. _**default:**_ jaeger-baggage
## jaeger-tracer-baggage-header-prefix
Specifies the header prefix used to propagate baggage. _**default:**_ uberctx-
## datadog-collector-host
Specifies the datadog agent host to use when uploading traces. It must be a valid URL.
## datadog-collector-port
Specifies the port to use when uploading traces. _**default:**_ 8126
## datadog-service-name
Specifies the service name to use for any traces created. _**default:**_ nginx
## datadog-operation-name-override
Overrides the operation naem to use for any traces crated. _**default:**_ nginx.handle
## datadog-priority-sampling
Specifies to use client-side sampling.
If true disables client-side sampling (thus ignoring `sample_rate`) and enables distributed priority sampling, where traces are sampled based on a combination of user-assigned priorities and configuration from the agent. _**default:**_ true
## datadog-sample-rate
Specifies sample rate for any traces created.
This is effective only when `datadog-priority-sampling` is `false` _**default:**_ 1.0
## main-snippet
Adds custom configuration to the main section of the nginx configuration.
@ -853,6 +931,21 @@ _References:_
Sets the initial amount after which the further transmission of a response to a client will be rate limited.
## lua-shared-dicts
Customize default Lua shared dictionaries or define more. You can use the following syntax to do so:
```
lua-shared-dicts: "<my dict name>: <my dict size>, [<my dict name>: <my dict size>], ..."
```
For example following will set default `certificate_data` dictionary to `100M` and will introduce a new dictionary called
`my_custom_plugin`:
```
lua-shared-dicts: "certificate_data: 100, my_custom_plugin: 5"
```
_References:_
[http://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after](http://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after)
@ -864,7 +957,7 @@ _**default:**_ 308
> __Why the default code is 308?__
> [RFC 7238](https://tools.ietf.org/html/rfc7238) was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if the we send a redirect in methods like POST.
> [RFC 7238](https://tools.ietf.org/html/rfc7238) was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if we send a redirect in methods like POST.
## proxy-buffering
@ -922,6 +1015,14 @@ Sets a custom snippet to use with external authentication. Applied to all the lo
Similar to the Ingress rule annotation `nginx.ingress.kubernetes.io/auth-request-redirect`.
_**default:**_ ""
## global-auth-cache-key
Enables caching for global auth requests. Specify a lookup key for auth responses, e.g. `$remote_user$http_authorization`.
## global-auth-cache-duration
Set a caching time for auth responses based on their response codes, e.g. `200 202 30m`. See [proxy_cache_valid](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid) for details. You may specify multiple, comma-separated values: `200 202 10m, 401 5m`. defaults to `200 202 401 5m`.
## no-auth-locations
A comma-separated list of locations that should not get authenticated.
@ -949,3 +1050,9 @@ It's possible to use here full strings and regular expressions. More details abo
_References:_
[http://nginx.org/en/docs/http/ngx_http_map_module.html#map](http://nginx.org/en/docs/http/ngx_http_map_module.html#map)
## proxy-ssl-location-only
Set if proxy-ssl parameters should be applied only on locations and not on servers.
_**default:**_ is disabled

4
docs/user-guide/nginx-configuration/custom-template.md
View file

@ -2,7 +2,7 @@
The NGINX template is located in the file `/etc/nginx/template/nginx.tmpl`.
Using a [Volume](https://kubernetes.io/docs/concepts/storage/volumes/) it is possible to use a custom template.
Using a [Volume](https://kubernetes.io/docs/concepts/storage/volumes/) it is possible to use a custom template.
This includes using a [Configmap](https://kubernetes.io/docs/concepts/storage/volumes/#example-pod-with-a-secret-a-downward-api-and-a-configmap) as source of the template
```yaml
@ -30,6 +30,7 @@ In addition to the built-in functions provided by the Go package the following f
- hasSuffix: [strings.HasSuffix](https://golang.org/pkg/strings/#HasSuffix)
- toUpper: [strings.ToUpper](https://golang.org/pkg/strings/#ToUpper)
- toLower: [strings.ToLower](https://golang.org/pkg/strings/#ToLower)
- quote: wraps a string in double quotes
- buildLocation: helps to build the NGINX Location section in each server
- buildProxyPass: builds the reverse proxy configuration
- buildRateLimit: helps to build a limit zone inside a location if contains a rate limit annotation
@ -39,7 +40,6 @@ TODO:
- buildAuthLocation:
- buildAuthResponseHeaders:
- buildResolvers:
- buildLogFormatUpstream:
- buildDenyVariable:
- buildUpstreamName:
- buildForwardedFor:

11
docs/user-guide/nginx-configuration/log-format.md
View file

@ -4,18 +4,16 @@ The default configuration uses a custom logging format to add additional informa
```
log_format upstreaminfo
'{{ if $cfg.useProxyProtocol }}$proxy_protocol_addr{{ else }}$remote_addr{{ end }} - '
'[$the_real_ip] - $remote_user [$time_local] "$request" '
'$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" "$http_user_agent" '
'$request_length $request_time [$proxy_upstream_name] $upstream_addr '
'$request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr '
'$upstream_response_length $upstream_response_time $upstream_status $req_id';
```
| Placeholder | Description |
|-------------|-------------|
| `$proxy_protocol_addr` | remote address if proxy protocol is enabled |
| `$remote_addr` | remote address if proxy protocol is disabled (default) |
| `$the_real_ip` | the source IP address of the client |
| `$remote_addr` | the source IP address of the client |
| `$remote_user` | user name supplied with the Basic authentication |
| `$time_local` | local time in the Common Log Format |
| `$request` | full original request line |
@ -26,6 +24,7 @@ log_format upstreaminfo
| `$request_length` | request length (including request line, header, and request body) |
| `$request_time` | time elapsed since the first bytes were read from the client |
| `$proxy_upstream_name` | name of the upstream. The format is `upstream-<namespace>-<service name>-<service port>` |
| `$proxy_alternative_upstream_name` | name of the alternative upstream. The format is `upstream-<namespace>-<service name>-<service port>` |
| `$upstream_addr` | the IP address and port (or the path to the domain socket) of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas. |
| `$upstream_response_length` | the length of the response obtained from the upstream server |
| `$upstream_response_time` | time spent on receiving the response from the upstream server as seconds with millisecond resolution |
@ -45,4 +44,4 @@ Additional available variables:
Sources:
- [Upstream variables](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#variables)
- [Embedded variables](http://nginx.org/en/docs/http/ngx_http_core_module.html#variables)
- [Embedded variables](http://nginx.org/en/docs/http/ngx_http_core_module.html#variables)

4
docs/user-guide/third-party-addons/modsecurity.md
View file

@ -8,8 +8,8 @@ The default ModSecurity configuration file is located in `/etc/nginx/modsecurity
To enable the ModSecurity feature we need to specify `enable-modsecurity: "true"` in the configuration configmap.
>__Note:__ the default configuration use detection only, because that minimizes the chances of post-installation disruption.
The file `/var/log/modsec_audit.log` contains the log of ModSecurity.
Due to the value of the setting [SecAuditLogType=Concurrent](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#secauditlogtype) the ModSecurity log is stored in multiple files inside the directory `/var/log/audit`.
The default `Serial` value in SecAuditLogType can impact performance.
The OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. The CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts.
The directory `/etc/nginx/owasp-modsecurity-crs` contains the [owasp-modsecurity-crs repository](https://github.com/SpiderLabs/owasp-modsecurity-crs).

34
docs/user-guide/third-party-addons/opentracing.md
View file

@ -13,6 +13,15 @@ data:
enable-opentracing: "true"
```
To enable or disable instrumentation for a single Ingress, use
the `enable-opentracing` annotation:
```
kind: Ingress
metadata:
annotations:
nginx.ingress.kubernetes.io/enable-opentracing: "true"
```
We must also set the host to use when uploading traces:
```
@ -20,7 +29,7 @@ zipkin-collector-host: zipkin.default.svc.cluster.local
jaeger-collector-host: jaeger-agent.default.svc.cluster.local
datadog-collector-host: datadog-agent.default.svc.cluster.local
```
NOTE: While the option is called `jaeger-collector-host`, you will need to point this to a `jaeger-agent`, and not the `jaeger-collector` component.
NOTE: While the option is called `jaeger-collector-host`, you will need to point this to a `jaeger-agent`, and not the `jaeger-collector` component.
Next you will need to deploy a distributed tracing system which uses OpenTracing.
[Zipkin](https://github.com/openzipkin/zipkin) and
@ -59,6 +68,18 @@ jaeger-sampler-host
# Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. Default: 5778
jaeger-sampler-port
# Specifies the header name used for passing trace context. Must be a string. Default: uber-trace-id
jaeger-trace-context-header-name
# Specifies the header name used for force sampling. Must be a string. Default: jaeger-debug-id
jaeger-debug-header
# Specifies the header name used to submit baggage if there is no root span. Must be a string. Default: jaeger-baggage
jaeger-baggage-header
# Specifies the header prefix used to propagate baggage. Must be a string. Default: uberctx-
jaeger-tracer-baggage-header-prefix
# specifies the port to use when uploading traces, Default 8126
datadog-collector-port
@ -67,14 +88,19 @@ datadog-service-name
# specifies the operation name to use for any traces collected, Default: nginx.handle
datadog-operation-name-override
# Specifies to use client-side sampling for distributed priority sampling and ignore sample rate, Default: true
datadog-priority-sampling
# specifies sample rate for any traces created, Default: 1.0
datadog-sample-rate
```
All these options (including host) allow environment variables, such as `$HOSTNAME` or `$HOST_IP`. In the case of Jaeger, if you have a Jaeger agent running on each machine in your cluster, you can use something like `$HOST_IP` (which can be 'mounted' with the `status.hostIP` fieldpath, as described [here](https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#capabilities-of-the-downward-api)) to make sure traces will be sent to the local agent.
## Examples
The following examples show how to deploy and test different distributed tracing systems. These example can be performed
using Minikube.
The following examples show how to deploy and test different distributed tracing systems. These example can be performed using Minikube.
### Zipkin
@ -126,7 +152,7 @@ In the Zipkin interface we can see the details:
# Apply the Ingress Resource
$ echo '
apiVersion: extensions/v1beta1
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: echo-ingress

6
docs/user-guide/tls.md
View file

@ -34,9 +34,12 @@ If this flag is not provided NGINX will use a self-signed certificate.
For instance, if you have a TLS secret `foo-tls` in the `default` namespace,
add `--default-ssl-certificate=default/foo-tls` in the `nginx-controller` deployment.
The default certificate will also be used for ingress `tls:` sections that do not
have a `secretName` option.
## SSL Passthrough
The [`--enable-ssl-passthrough`](cli-arguments/) flag enables the SSL Passthrough feature, which is disabled by
The [`--enable-ssl-passthrough`](cli-arguments.md) flag enables the SSL Passthrough feature, which is disabled by
default. This is required to enable passthrough backends in Ingress objects.
!!! warning
@ -75,7 +78,6 @@ or per-Ingress with the `nginx.ingress.kubernetes.io/ssl-redirect: "false"`
annotation in the particular resource.
!!! tip
When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a
redirect to HTTPS even when there is no TLS certificate available.
This can be achieved by using the `nginx.ingress.kubernetes.io/force-ssl-redirect: "true"`