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

Improve documentation and examples [ci skip]

Browse source
This commit is contained in:
Manuel de Brito Fontes 2017-10-13 18:50:37 -03:00
parent a30d3775c4
commit 026bb52469
15 changed files with 340 additions and 306 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
README.md
View file

@ -28,14 +28,12 @@ An Ingress Controller is a daemon, deployed as a Kubernetes Pod, that watches th
- [Requirements](#requirements)
- [Deployment](deploy/README.md)
- [Command line arguments](docs/user-guide/cli-arguments.md)
- [Contribute](#contribute)
- [Contribute](CONTRIBUTING.md)
- [TLS](docs/user-guide/tls.md)
- [Annotation ingress.class](#annotation-ingressclass)
- [Customizing NGINX](#customizing-nginx)
- [Custom NGINX configuration](docs/user-guide/configmap.md)
- [Annotation ingress.class](#annotation-ingress.class)
- [Annotations](docs/user-guide/annotations.md)
- [Allowed parameters in configuration ConfigMap](docs/user-guide/configmap.md)
- [Retries in non-idempotent methods](#retries-in-non-idempotent-methods)
- [Custom NGINX configuration](docs/user-guide/configmap.md)
- [Annotations](docs/user-guide/annotations.md)
- [Source IP address](#source-ip-address)
- [Exposing TCP and UDP Services](docs/user-guide/exposing-tcp-udp-services.md)
- [Proxy Protocol](#proxy-protocol)
@ -45,6 +43,7 @@ An Ingress Controller is a daemon, deployed as a Kubernetes Pod, that watches th
- [NGINX status page](docs/user-guide/nginx-status-page.md)
- [Running multiple ingress controllers](#running-multiple-ingress-controllers)
- [Disabling NGINX ingress controller](#disabling-nginx-ingress-controller)
- [Retries in non-idempotent methods](#retries-in-non-idempotent-methods)
- [Log format](docs/user-guide/log-format.md)
- [Websockets](#websockets)
- [Optimizing TLS Time To First Byte (TTTFB)](#optimizing-tls-time-to-first-byte-tttfb)
@ -64,19 +63,13 @@ and create the secret via `kubectl create secret tls ${CERT_NAME} --key ${KEY_FI
The default backend is a service of handling all url paths and hosts the nginx controller doesn't understand, i.e., all the request that are not mapped with an Ingress
Basically a default backend exposes two URLs:
- /healthz that returns 200
- / that returns 404
- `/healthz` that returns 200
- `/` that returns 404
The location [404-server](https://github.com/kubernetes/ingress-nginx/tree/master/images/404-server) contains the image of the default backend and [custom-error-pages](https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages) an example that shows how it is possible to customize
## Contribute
See the [contributor guidelines](CONTRIBUTING.md)
## Annotation ingress.class
## Ingress Class
If you have multiple Ingress controllers in a single cluster, you can pick one by specifying the `ingress.class`
annotation, eg creating an Ingress with an annotation like
@ -104,15 +97,18 @@ __Note__: Deploying multiple ingress controller and not specifying the annotatio
There are three ways to customize NGINX:
1. [ConfigMap](docs/user-guide/configmap.md): uses a Configmap to set global configurations in NGINX.
2. [annotations](docs/user-guide/annotations.md): use this if you want a specific configuration for a particular Ingress rule.
3. custom template: when more specific settings are required, like [open_file_cache](http://nginx.org/en/docs/http/ngx_http_core_module.html#open_file_cache), custom [log_format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format), adjust [listen](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen) options as `rcvbuf` or when is not possible to change the configuration through the ConfigMap.
1. [ConfigMap](docs/user-guide/configmap.md): using a Configmap to set global configurations in NGINX.
2. [Annotations](docs/user-guide/annotations.md): use this if you want a specific configuration for a particular Ingress rule.
3. [Custom template](docs/user-guide/custom-template.md): when more specific settings are required, like [open_file_cache](http://nginx.org/en/docs/http/ngx_http_core_module.html#open_file_cache), adjust [listen](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen) options as `rcvbuf` or when is not possible to change the configuration through the ConfigMap.
## Source IP address
By default NGINX uses the content of the header `X-Forwarded-For` as the source of truth to get information about the client IP address. This works without issues in L7 **if we configure the setting `proxy-real-ip-cidr`** with the correct information of the IP/network address of the external load balancer.
If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR. This allows NGINX to avoid the spoofing of the header.
By default NGINX uses the content of the header `X-Forwarded-For` as the source of truth to get information about the client IP address. This works without issues in L7 **if we configure the setting `proxy-real-ip-cidr`** with the correct information of the IP/network address of trusted external load balancer.
If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR.
Another option is to enable proxy protocol using `use-proxy-protocol: "true"`.
In this mode NGINX do not uses the content of the header to get the source IP address of the connection.
## Proxy Protocol
@ -121,8 +117,6 @@ If you are using a L4 proxy to forward the traffic to the NGINX pods and termina
Amongst others [ELBs in AWS](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/enable-proxy-protocol.html) and [HAProxy](http://www.haproxy.org/) support Proxy Protocol.
Please check the [proxy-protocol](examples/proxy-protocol/) example
### Running multiple ingress controllers
If you're running multiple ingress controllers, or running on a cloudprovider that natively handles ingress, you need to specify the annotation `kubernetes.io/ingress.class: "nginx"` in all ingresses that you would like this controller to claim.
@ -134,11 +128,16 @@ Multiple ingress controllers running in the same cluster was not supported in Ku
Support for websockets is provided by NGINX out of the box. No special configuration required.
The only requirement to avoid the close of connections is the increase of the values of `proxy-read-timeout` and `proxy-send-timeout`.
The default value of this settings is `60 seconds`. A more adequate value to support websockets is a value higher than one hour (`3600`).
The default value of this settings is `60 seconds`.
A more adequate value to support websockets is a value higher than one hour (`3600`).
### Optimizing TLS Time To First Byte (TTTFB)
NGINX provides the configuration option [ssl_buffer_size](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size) to allow the optimization of the TLS record size. This improves the [Time To First Byte](https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/) (TTTFB). The default value in the Ingress controller is `4k` (NGINX default is `16k`).
NGINX provides the configuration option [ssl_buffer_size](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size) to allow the optimization of the TLS record size.
This improves the [Time To First Byte](https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/) (TTTFB).
The default value in the Ingress controller is `4k` (NGINX default is `16k`).
### Retries in non-idempotent methods
@ -147,7 +146,9 @@ The previous behavior can be restored using `retry-non-idempotent=true` in the c
### Disabling NGINX ingress controller
Setting the annotation `kubernetes.io/ingress.class` to any value other than "nginx" or the empty string, will force the NGINX Ingress controller to ignore your Ingress. Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
Setting the annotation `kubernetes.io/ingress.class` to any value other than "nginx" or the empty string, will force the NGINX Ingress controller to ignore your Ingress.
Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
### Limitations

39
deploy/README.md
View file

@ -95,13 +95,13 @@ This example creates an ELB with just two listeners, one in port 80 and another
If the ingress controller uses RBAC run:
```console
kubectl apply -f provider/aws/patch-service-with-rbac.yaml
kubectl apply -f provider/patch-service-with-rbac.yaml
```
If not run:
```console
kubectl apply -f provider/aws/patch-service-without-rbac.yaml
kubectl apply -f provider/patch-service-without-rbac.yaml
```
### GCE - GKE
@ -111,6 +111,20 @@ curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/pr
| kubectl apply -f -
```
If the ingress controller uses RBAC run:
```console
kubectl apply -f provider/patch-service-with-rbac.yaml
```
If not run:
```console
kubectl apply -f provider/patch-service-without-rbac.yaml
```
**Important Note:** proxy protocol is not supported in GCE/GKE
### Azure
```console
@ -118,6 +132,20 @@ curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/pr
| kubectl apply -f -
```
If the ingress controller uses RBAC run:
```console
kubectl apply -f provider/patch-service-with-rbac.yaml
```
If not run:
```console
kubectl apply -f provider/patch-service-without-rbac.yaml
```
**Important Note:** proxy protocol is not supported in GCE/GKE
### Baremetal
Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport):
@ -127,13 +155,6 @@ curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/pr
| kubectl apply -f -
```
Using HostPort:
```console
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-hostport.yaml \
| kubectl apply -f -
```
## Using Helm
NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [stable/nginx](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) from the official charts repository.

17
deploy/provider/baremetal/service-hostport.yml
View file

@ -1,17 +0,0 @@
apiVersion: v1
kind: Service
metadata:
name: ingress-nginx
namespace: ingress-nginx
spec:
ports:
- name: http
hostPort: 80
targetPort: 80
protocol: TCP
- name: https
hostPort: 443
targetPort: 443
protocol: TCP
selector:
app: ingress-nginx

2
deploy/provider/baremetal/service-nodeport.yml
View file

@ -7,9 +7,11 @@ spec:
type: NodePort
ports:
- name: http
port: 80
targetPort: 80
protocol: TCP
- name: https
port: 443
targetPort: 443
protocol: TCP
selector:

0
deploy/provider/aws/patch-service-with-rbac.yaml → deploy/provider/patch-service-with-rbac.yaml
View file

0
deploy/provider/aws/patch-service-without-rbac.yaml → deploy/provider/patch-service-without-rbac.yaml
View file

1
docs/examples/auth/client-certs/nginx-tls-auth.yaml
View file

@ -7,7 +7,6 @@ metadata:
ingress.kubernetes.io/auth-tls-verify-depth: "3"
ingress.kubernetes.io/auth-tls-verify-client: "on"
auth-tls-error-page: "http://www.mysite.com/error-cert.html"
kubernetes.io/ingress.class: "nginx"
name: nginx-test
namespace: default
spec:

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

@ -3,7 +3,6 @@ kind: Ingress
metadata:
name: nginx-configuration-snippet
annotations:
kubernetes.io/ingress.class: "nginx"
ingress.kubernetes.io/configuration-snippet: |
more_set_headers "Request-Id: $request_id";

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

@ -2,8 +2,6 @@ apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: ingress-nginx
annotations:
kubernetes.io/ingress.class: "nginx"
spec:
tls:
# This assumes tls-secret exists.

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

@ -2,8 +2,6 @@ apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: nginx-test
annotations:
kubernetes.io/ingress.class: "nginx"
spec:
tls:
# This assumes tls-secret exists.

158
docs/troubleshooting.md
View file

@ -165,13 +165,12 @@ If it is not working, there are two possible reasons:
1. The contents of the tokens are invalid. Find the secret name with `kubectl get secrets | grep service-account` and
delete it with `kubectl delete secret <name>`. It will automatically be recreated.
2. You have a non-standard Kubernetes installation and the file containing the token
may not be present. The API server will mount a volume containing this file, but
only if the API server is configured to use the ServiceAccount admission controller.
If you experience this error, verify that your API server is using the ServiceAccount
admission controller. If you are configuring the API server by hand, you can set
this with the `--admission-control` parameter. Please note that you should use
other admission controllers as well. Before configuring this option, you should
2. You have a non-standard Kubernetes installation and the file containing the token may not be present.
The API server will mount a volume containing this file, but only if the API server is configured to use
the ServiceAccount admission controller.
If you experience this error, verify that your API server is using the ServiceAccount admission controller.
If you are configuring the API server by hand, you can set this with the `--admission-control` parameter.
Please note that you should use other admission controllers as well. Before configuring this option, you should
read about admission controllers.
More information:
@ -180,146 +179,5 @@ More information:
* [Cluster Administrator Guide: Managing Service Accounts](http://kubernetes.io/docs/admin/service-accounts-admin/)
### Kubeconfig
If you want to use a kubeconfig file for authentication, create a deployment file similar to the one below:
*Note:* the important part is the flag `--kubeconfig=/etc/kubernetes/kubeconfig.yaml`.
```yaml
kind: Service
apiVersion: v1
metadata:
name: nginx-default-backend
labels:
k8s-addon: ingress-nginx.addons.k8s.io
spec:
ports:
- port: 80
targetPort: http
selector:
app: nginx-default-backend
---
kind: Deployment
apiVersion: extensions/v1beta1
metadata:
name: nginx-default-backend
labels:
k8s-addon: ingress-nginx.addons.k8s.io
spec:
replicas: 1
template:
metadata:
labels:
k8s-addon: ingress-nginx.addons.k8s.io
app: nginx-default-backend
spec:
terminationGracePeriodSeconds: 60
containers:
- name: default-http-backend
image: gcr.io/google_containers/defaultbackend:1.0
volumeMounts:
- mountPath: /etc/kubernetes
name: kubeconfig
livenessProbe:
httpGet:
path: /healthz
port: 8080
scheme: HTTP
initialDelaySeconds: 30
timeoutSeconds: 5
resources:
limits:
cpu: 10m
memory: 20Mi
requests:
cpu: 10m
memory: 20Mi
ports:
- name: http
containerPort: 8080
protocol: TCP
---
kind: ConfigMap
apiVersion: v1
metadata:
name: ingress-nginx
labels:
k8s-addon: ingress-nginx.addons.k8s.io
---
kind: Service
apiVersion: v1
metadata:
name: ingress-nginx
labels:
k8s-addon: ingress-nginx.addons.k8s.io
spec:
type: LoadBalancer
selector:
app: ingress-nginx
ports:
- name: http
port: 80
targetPort: http
- name: https
port: 443
targetPort: https
---
kind: Deployment
apiVersion: extensions/v1beta1
metadata:
name: ingress-nginx
labels:
k8s-addon: ingress-nginx.addons.k8s.io
spec:
replicas: 1
template:
metadata:
labels:
app: ingress-nginx
k8s-addon: ingress-nginx.addons.k8s.io
spec:
terminationGracePeriodSeconds: 60
containers:
- image: gcr.io/google_containers/nginx-ingress-controller:0.9.0-beta.15
name: ingress-nginx
imagePullPolicy: Always
ports:
- name: http
containerPort: 80
protocol: TCP
- name: https
containerPort: 443
protocol: TCP
livenessProbe:
httpGet:
path: /healthz
port: 10254
scheme: HTTP
initialDelaySeconds: 30
timeoutSeconds: 5
env:
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
args:
- /nginx-ingress-controller
- --default-backend-service=$(POD_NAMESPACE)/nginx-default-backend
- --configmap=$(POD_NAMESPACE)/ingress-nginx
- --kubeconfig=/etc/kubernetes/kubeconfig.yaml
volumes:
- name: "kubeconfig"
hostPath:
path: "/etc/kubernetes/"
```
If you want to use a kubeconfig file for authentication, follow the deploy procedure and
add the flag `--kubeconfig=/etc/kubernetes/kubeconfig.yaml` to the deployment

3
docs/user-guide/annotations.md
View file

@ -296,9 +296,8 @@ To configure this setting globally for all Ingress rules, the `whitelist-source-
*Note:* Adding an annotation to an Ingress rule overrides any global restriction.
Please check the [whitelist](../examples/whitelist/README.md) example.
### Cookie affinity
If you use the ``cookie`` type you can also specify the name of the cookie that will be used to route the requests with the annotation `ingress.kubernetes.io/session-cookie-name`. The default is to create a cookie named 'route'.
In case of NGINX the annotation `ingress.kubernetes.io/session-cookie-hash` defines which algorithm will be used to 'hash' the used upstream. Default value is `md5` and possible values are `md5`, `sha1` and `index`.

362
docs/user-guide/configmap.md
View file

@ -1,68 +1,129 @@
# NGINX Ingress controller configuration ConfigMap
#### proxy-body-size: Sets the maximum allowed size of the client request body.
---
#### proxy-body-size:
Sets the maximum allowed size of the client request body.
See NGINX [client_max_body_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size).
#### custom-http-errors: Enables which HTTP codes should be passed for processing with the [error_page directive](http://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
#### custom-http-errors:
Enables which HTTP codes should be passed for processing with the [error_page directive](http://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
Setting at least one code also enables [proxy_intercept_errors](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_intercept_errors) which are required to process error_page.
Example usage: `custom-http-errors: 404,415`
#### disable-access-log: Disables the Access Log from the entire Ingress Controller. This is 'false' by default.
#### disable-access-log
#### access-log-path: Access log path. Goes to '/var/log/nginx/access.log' by default. http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log
Disables the Access Log from the entire Ingress Controller. This is 'false' by default.
#### error-log-path: Error log path. Goes to '/var/log/nginx/error.log' by default. http://nginx.org/en/docs/ngx_core_module.html#error_log
#### access-log-path
#### enable-modsecurity: enables the modsecurity module for NGINX
Access log path. Goes to '/var/log/nginx/access.log' by default. http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log
#### error-log-path
Error log path. Goes to '/var/log/nginx/error.log' by default. http://nginx.org/en/docs/ngx_core_module.html#error_log
#### enable-modsecurity
Enables the modsecurity module for NGINX
By default this is disabled.
#### enable-owasp-modsecurity-crs: enables the OWASP ModSecurity Core Rule Set (CRS)
#### enable-owasp-modsecurity-crs
Eenables the OWASP ModSecurity Core Rule Set (CRS)
By default this is disabled.
#### disable-ipv6: Disable listening on IPV6.
#### disable-ipv6:
Disable listening on IPV6.
By default this is disabled.
#### enable-dynamic-tls-records: Enables dynamically sized TLS records to improve time-to-first-byte.
#### enable-dynamic-tls-records
Enables dynamically sized TLS records to improve time-to-first-byte.
By default this is enabled.
See [CloudFlare's blog](https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency) for more information.
#### enable-underscores-in-headers: Enables underscores in header names.
#### enable-underscores-in-headers
Enables underscores in header names.
By default this is disabled.
#### enable-vts-status: Allows the replacement of the default status page with a third party module named [nginx-module-vts](https://github.com/vozlt/nginx-module-vts).
#### enable-vts-status
Allows the replacement of the default status page with a third party module named [nginx-module-vts](https://github.com/vozlt/nginx-module-vts).
By default this is disabled.
#### error-log-level: Configures the logging level of errors. Log levels above are listed in the order of increasing severity.
http://nginx.org/en/docs/ngx_core_module.html#error_log
#### error-log-level
#### gzip-types: Sets the MIME types in addition to "text/html" to compress. The special value "\*" matches any MIME type.
Configures the logging level of errors. Log levels above are listed in the order of increasing severity.
_References:_
- http://nginx.org/en/docs/ngx_core_module.html#error_log
#### 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` is enabled.
#### hsts: Enables or disables the header HSTS in servers running SSL.
#### hsts
Enables or disables the header HSTS in servers running SSL.
HTTP Strict Transport Security (often abbreviated as HSTS) is a security feature (HTTP header) that tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. It provides protection against protocol downgrade attacks and cookie theft.
https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security
https://blog.qualys.com/securitylabs/2016/03/28/the-importance-of-a-proper-http-strict-transport-security-implementation-on-your-web-server
#### hsts-include-subdomains: Enables or disables the use of HSTS in all the subdomains of the server-name.
_References:_
#### hsts-max-age: Sets the time, in seconds, that the browser should remember that this site is only to be accessed using HTTPS.
- https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security
- https://blog.qualys.com/securitylabs/2016/03/28/the-importance-of-a-proper-http-strict-transport-security-implementation-on-your-web-server
#### hsts-preload: Enables or disables the preload attribute in the HSTS feature (when it is enabled)
#### hsts-include-subdomains
#### ignore-invalid-headers: set if header fields with invalid names should be ignored. This is 'true' by default.
Enables or disables the use of HSTS in all the subdomains of the server-name.
#### keep-alive: Sets the time during which a keep-alive client connection will stay open on the server side.
#### hsts-max-age
Sets the time, in seconds, that the browser should remember that this site is only to be accessed using HTTPS.
#### hsts-preload
Enables or disables the preload attribute in the HSTS feature (when it is enabled)
#### ignore-invalid-headers
Set if header fields with invalid names should be ignored.
By default this is enabled.
#### keep-alive:
Sets the time during which a keep-alive client connection will stay open on the server side.
The zero value disables keep-alive client connections.
http://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout
#### load-balance: Sets the algorithm to use for load balancing. The value can either be round_robin to
use the default round robin loadbalancer, least_conn to use the least connected method, or
ip_hash to use a hash of the server for routing. The default is least_conn.
http://nginx.org/en/docs/http/load_balancing.html.
_References:_
#### log-format-upstream: Sets the nginx [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format).
- http://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout
#### load-balance
Sets the algorithm to use for load balancing.
The value can either be:
- round_robin: to use the default round robin loadbalancer
- least_conn: to use the least connected method
- ip_hash: to use a hash of the server for routing.
The default is least_conn.
_References:_
- http://nginx.org/en/docs/http/load_balancing.html.
#### log-format-upstream
Sets the nginx [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format).
Example for json output:
```console
@ -75,54 +136,108 @@ log-format-upstream: '{ "time": "$time_iso8601", "remote_addr": "$proxy_protocol
"$http_user_agent" }'
```
#### log-format-stream: Sets the nginx [stream format](https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format).
Please check [log-format](log-format.md) for definition of each field.
#### max-worker-connections: Sets the maximum number of simultaneous connections that can be opened by each [worker process](http://nginx.org/en/docs/ngx_core_module.html#worker_connections).
#### log-format-stream
#### proxy-buffer-size: Sets the size of the buffer used for [reading the first part of the response](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) received from the proxied server. This part usually contains a small response header.
Sets the nginx [stream format](https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format).
#### proxy-connect-timeout: Sets the timeout for [establishing a connection with a proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout). It should be noted that this timeout cannot usually exceed 75 seconds.
#### max-worker-connections
#### proxy-cookie-domain: Sets a text that [should be changed in the domain attribute](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_domain) of the “Set-Cookie” header fields of a proxied server response.
Sets the maximum number of simultaneous connections that can be opened by each [worker process](http://nginx.org/en/docs/ngx_core_module.html#worker_connections)
#### proxy-cookie-path: Sets a text that [should be changed in the path attribute](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_path) of the “Set-Cookie” header fields of a proxied server response.
#### proxy-buffer-size
#### proxy-read-timeout: Sets the timeout in seconds for [reading a response from the proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout). The timeout is set only between two successive read operations, not for the transmission of the whole response.
Sets the size of the buffer used for [reading the first part of the response](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) received from the proxied server. This part usually contains a small response header.
#### proxy-send-timeout: Sets the timeout in seconds for [transmitting a request to the proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout). The timeout is set only between two successive write operations, not for the transmission of the whole request.
#### proxy-connect-timeout
#### proxy-next-upstream: Specifies in [which cases](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream) a request should be passed to the next server.
Sets the timeout for [establishing a connection with a proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout). It should be noted that this timeout cannot usually exceed 75 seconds.
#### proxy-request-buffering: Enables or disables [buffering of a client request body](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering).
#### proxy-cookie-domain
#### retry-non-idempotent: Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error in the upstream server.
Sets a text that [should be changed in the domain attribute](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_domain) of the “Set-Cookie” header fields of a proxied server response.
#### proxy-cookie-path
Sets a text that [should be changed in the path attribute](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_path) of the “Set-Cookie” header fields of a proxied server response.
#### proxy-read-timeout
Sets the timeout in seconds for [reading a response from the proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout). The timeout is set only between two successive read operations, not for the transmission of the whole response.
#### proxy-send-timeout
Sets the timeout in seconds for [transmitting a request to the proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout). The timeout is set only between two successive write operations, not for the transmission of the whole request.
#### proxy-next-upstream
Specifies in [which cases](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream) a request should be passed to the next server.
#### proxy-request-buffering
Enables or disables [buffering of a client request body](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering).
#### retry-non-idempotent
Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error in the upstream server.
The previous behavior can be restored using the value "true".
#### server-name-hash-bucket-size: Sets the size of the bucket for the server names hash tables.
http://nginx.org/en/docs/hash.html
http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size
#### server-name-hash-bucket-size
#### server-name-hash-max-size: Sets the maximum size of the [server names hash tables](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) used in server names, map directive’s values, MIME types, names of request header strings, etc.
http://nginx.org/en/docs/hash.html
Sets the size of the bucket for the server names hash tables.
#### proxy-headers-hash-bucket-size: Sets the size of the bucket for the proxy headers hash tables.
http://nginx.org/en/docs/hash.html
https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size
_References:_
#### proxy-headers-hash-max-size: Sets the maximum size of the proxy headers hash tables.
http://nginx.org/en/docs/hash.html
https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size
- http://nginx.org/en/docs/hash.html
- http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size
#### server-tokens: Send NGINX Server header in responses and display NGINX version in error pages. Enabled by default.
#### server-name-hash-max-size
#### map-hash-bucket-size: Sets the bucket size for the [map variables hash tables](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_bucket_size). The details of setting up hash tables are provided in a separate [document](http://nginx.org/en/docs/hash.html).
Sets the maximum size of the [server names hash tables](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) used in server names,map directive’s values, MIME types, names of request header strings, etc.
#### ssl-buffer-size: Sets the size of the [SSL buffer](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size) used for sending data.
_References:_
- http://nginx.org/en/docs/hash.html
#### proxy-headers-hash-bucket-size
Sets the size of the bucket for the proxy headers hash tables.
_References:_
- http://nginx.org/en/docs/hash.html
- https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size
#### proxy-headers-hash-max-size
Sets the maximum size of the proxy headers hash tables.
_References:_
- http://nginx.org/en/docs/hash.html
- https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size
#### server-tokens
Send NGINX Server header in responses and display NGINX version in error pages.
By default this is enabled.
#### map-hash-bucket-size
Sets the bucket size for the [map variables hash tables](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_bucket_size).
The details of setting up hash tables are provided in a separate [document](http://nginx.org/en/docs/hash.html).
#### ssl-buffer-size
Sets the size of the [SSL buffer](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size) used for sending data.
The default of 4k helps NGINX to improve TLS Time To First Byte (TTTFB).
https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/
#### ssl-ciphers: Sets the [ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) list to enable. The ciphers are specified in the format understood by the OpenSSL library.
#### ssl-ciphers
Sets the [ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) list to enable.
The ciphers are specified in the format understood by the OpenSSL library.
The default cipher list is:
`ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256`.
@ -132,81 +247,140 @@ The recommendation above prioritizes algorithms that provide perfect [forward se
Please check the [Mozilla SSL Configuration Generator](https://mozilla.github.io/server-side-tls/ssl-config-generator/).
#### ssl-dh-param: Sets the name of the secret that contains Diffie-Hellman key to help with "Perfect Forward Secrecy".
https://www.openssl.org/docs/manmaster/apps/dhparam.html
https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam
http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam
#### ssl-dh-param
#### ssl-protocols: Sets the [SSL protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) to use.
Sets the name of the secret that contains Diffie-Hellman key to help with "Perfect Forward Secrecy".
_References:_
- https://www.openssl.org/docs/manmaster/apps/dhparam.html
- https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam
- http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam
#### ssl-protocols
Sets the [SSL protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) to use.
The default is: `TLSv1.2`.
TLSv1 is enabled to allow old clients like:
- [IE 8-10 / Win 7](https://www.ssllabs.com/ssltest/viewClient.html?name=IE&version=8-10&platform=Win%207&key=113)
- [Java 7u25](https://www.ssllabs.com/ssltest/viewClient.html?name=Java&version=7u25&key=26)
If you don't need to support these clients please remove `TLSv1` to improve security.
Please check the result of the configuration using `https://ssllabs.com/ssltest/analyze.html` or `https://testssl.sh`.
#### ssl-redirect: Sets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule)
#### ssl-redirect
Sets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule).
Default is "true".
#### 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.
#### ssl-session-cache
#### ssl-session-cache-size: Sets the size of the [SSL shared session cache](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) between all worker processes.
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.
#### ssl-session-tickets: Enables or disables session resumption through [TLS session tickets](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets).
#### ssl-session-cache-size
#### ssl-session-ticket-key: sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string.
Sets the size of the [SSL shared session cache](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) between all worker processes.
#### ssl-session-tickets
Enables or disables session resumption through [TLS session tickets](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets).
#### ssl-session-ticket-key
Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string.
http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets
By default, a randomly generated key is used.
To create a ticket: `openssl rand 80 | base64 -w0`
#### ssl-session-timeout: Sets the time during which a client may [reuse the session](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout) parameters stored in a cache.
#### ssl-session-timeout
#### upstream-max-fails: Sets the number of unsuccessful attempts to communicate with the [server](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) that should happen in the duration set by the `fail_timeout` parameter to consider the server unavailable.
Sets the time during which a client may [reuse the session](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout) parameters stored in a cache.
#### upstream-fail-timeout: Sets the time during which the specified number of unsuccessful attempts to communicate with the [server](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) should happen to consider the server unavailable.
#### upstream-max-fails
Sets the number of unsuccessful attempts to communicate with the [server](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) that should happen in the duration set by the `fail_timeout` parameter to consider the server unavailable.
#### upstream-fail-timeout
Sets the time during which the specified number of unsuccessful attempts to communicate with the [server](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) should happen to consider the server unavailable.
#### use-gzip
Enables or disables compression of HTTP responses using the ["gzip" module](http://nginx.org/en/docs/http/ngx_http_gzip_module.html).
#### use-gzip: Enables or disables compression of HTTP responses using the ["gzip" module](http://nginx.org/en/docs/http/ngx_http_gzip_module.html)
The default mime type list to compress is: `application/atom+xml application/javascript aplication/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`.
#### use-http2: Enables or disables [HTTP/2](http://nginx.org/en/docs/http/ngx_http_v2_module.html) support in secure connections.
#### use-http2
#### use-proxy-protocol: Enables or disables the [PROXY protocol](https://www.nginx.com/resources/admin-guide/proxy-protocol/) to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).
Enables or disables [HTTP/2](http://nginx.org/en/docs/http/ngx_http_v2_module.html) support in secure connections.
#### whitelist-source-range: Sets the default whitelisted IPs for each `server` block. This can be overwritten by an annotation on an Ingress rule. See [ngx_http_access_module](http://nginx.org/en/docs/http/ngx_http_access_module.html).
#### use-proxy-protocol
#### worker-processes: Sets the number of [worker processes](http://nginx.org/en/docs/ngx_core_module.html#worker_processes). The default of "auto" means number of available CPU cores.
Enables or disables the [PROXY protocol](https://www.nginx.com/resources/admin-guide/proxy-protocol/) to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).
#### 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). The default is "10s".
#### whitelist-source-range
#### limit-conn-zone-variable: Sets parameters for a shared memory zone that will keep states for various keys of [limit_conn_zone](http://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone). The default of "$binary_remote_addr" variable’s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.
Sets the default whitelisted IPs for each `server` block.
This can be overwritten by an annotation on an Ingress rule.
See [ngx_http_access_module](http://nginx.org/en/docs/http/ngx_http_access_module.html).
#### proxy-set-headers: Sets custom headers from a configmap before sending traffic to backends. See [example](https://github.com/kubernetes/ingress-nginx/tree/master/deploy/examples/customization/custom-headers)
#### worker-processes
#### add-headers: Sets custom headers from a configmap before sending traffic to the client. See `proxy-set-headers` [example](https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/customization/custom-headers)
Sets the number of [worker processes](http://nginx.org/en/docs/ngx_core_module.html#worker_processes).
The default of "auto" means number of available CPU cores.
#### bind-address: Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.
#### worker-shutdown-timeout
#### enable-opentracing: enables the nginx Opentracing extension https://github.com/rnburn/nginx-opentracing
Default is "false"
Sets a timeout for Nginx to [wait for worker to gracefully shutdown](http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout).
The default is "10s".
#### zipkin-collector-host: specifies the host to use when uploading traces. It must be a valid URL
#### limit-conn-zone-variable
#### zipkin-collector-port: specifies the port to use when uploading traces
Sets parameters for a shared memory zone that will keep states for various keys of [limit_conn_zone](http://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone). The default of "$binary_remote_addr" variable’s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.
#### proxy-set-headers
Sets custom headers from a configmap before sending traffic to backends. See [example](https://github.com/kubernetes/ingress-nginx/tree/master/deploy/examples/customization/custom-headers)
#### add-headers
Sets custom headers from a configmap before sending traffic to the client. See `proxy-set-headers` [example](https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/customization/custom-headers)
#### bind-address
Sets the addresses on which the server will accept requests instead of *.
It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.
#### enable-opentracing
Enables the nginx Opentracing extension https://github.com/rnburn/nginx-opentracing
By default this is disabled
#### zipkin-collector-host
Specifies the host to use when uploading traces. It must be a valid URL
#### zipkin-collector-port
Specifies the port to use when uploading traces
Default: 9411
#### zipkin-service-name: specifies the service name to use for any traces created
#### zipkin-service-name
Specifies the service name to use for any traces created
Default: nginx
#### http-snippet: adds custom configuration to the http section of the nginx configuration
#### http-snippet
Adds custom configuration to the http section of the nginx configuration
Default: ""
#### server-snippet: adds custom configuration to all the servers in the nginx configuration
#### server-snippet
Adds custom configuration to all the servers in the nginx configuration
Default: ""
#### location-snippet: adds custom configuration to all the locations in the nginx configuration
#### location-snippet
Adds custom configuration to all the locations in the nginx configuration
Default: ""
@ -214,8 +388,8 @@ Default: ""
The following table shows the options, the default value and a description.
|name |default|
|---------------------------|------|
|name | default |
|:--- |:-------|
|body-size|1m|
|custom-http-errors|" "|
|enable-dynamic-tls-records|"true"|
@ -250,7 +424,7 @@ The following table shows the options, the default value and a description.
|ssl-buffer-size|4k|
|ssl-ciphers||
|ssl-dh-param|value from openssl|
|ssl-protocols|TLSv1 TLSv1.1 TLSv1.2|
|ssl-protocols|TLSv1.2|
|ssl-session-cache|"true"|
|ssl-session-cache-size|10m|
|ssl-session-tickets|"true"|

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

@ -1,6 +1,6 @@
# TLS
- [Default SSL Certificate](docs/user-guide/default-ssl-certificate.md)
- [Default SSL Certificate](#default-ssl-certificate)
- [SSL Passthrough](#ssl-passthrough)
- [HTTPS enforcement](#server-side-https-enforcement)
- [HSTS](#http-strict-transport-security)

8
rootfs/ingress-controller/clean-nginx-conf.sh
View file

@ -3,6 +3,8 @@
# This script removes consecutive empty lines in nginx.conf
# Using sed is more simple than using a go regex
# first sed removes empty lines
# second sed command replaces the empty lines
sed -e 's/\r//g' | sed -e 's/^ *$/\'$'\n/g' | sed -e '/^$/{N;/^\n$/d;}'
# Sed commands:
# 1. remove the return carrier character/s
# 2. remove empty lines
# 3. replace multiple empty lines
sed -e 's/\r//g' | sed -e 's/^ *$/\'$'\n/g' | sed -e '/^$/{N;/^\n$/D;}'