Merge pull request #2464 from valohai/doc-fixes
Documentation fixes & improvements
This commit is contained in:
k8s-ci-robot
GitHub
commit
87d1b8bbf2
19 changed files with 407 additions and 365 deletions
50
docs/deploy/upgrade.md
Normal file
50
docs/deploy/upgrade.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# Upgrading
|
||||
|
||||
!!! important
|
||||
No matter the method you use for upgrading, *if you use template overrides,
|
||||
make sure your templates are compatible with the new version of ingress-nginx*.
|
||||
|
||||
## Without Helm
|
||||
|
||||
To upgrade your ingress-nginx installation, it should be enough to change the version of the image
|
||||
in the controller Deployment.
|
||||
|
||||
I.e. if your deployment resource looks like (partial example):
|
||||
|
||||
```yaml
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: nginx-ingress-controller
|
||||
namespace: ingress-nginx
|
||||
spec:
|
||||
replicas: 1
|
||||
selector: ...
|
||||
template:
|
||||
metadata: ...
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx-ingress-controller
|
||||
image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.9.0
|
||||
args: ...
|
||||
```
|
||||
|
||||
simply change the `0.9.0` tag to the version you wish to upgrade to.
|
||||
The easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):
|
||||
|
||||
```
|
||||
kubectl set image deployment/nginx-ingress-controller \
|
||||
nginx-ingress-controller=nginx:quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.14.0
|
||||
```
|
||||
|
||||
For interactive editing, use `kubectl edit deployment nginx-ingress-controller`.
|
||||
|
||||
|
||||
## With Helm
|
||||
|
||||
If you installed ingress-nginx using the Helm command in the deployment docs so its name is `ngx-ingress`,
|
||||
you should be able to upgrade using
|
||||
|
||||
```shell
|
||||
helm upgrade --reuse-values ngx-ingress stable/nginx-ingress
|
||||
```
|
||||
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# Ingress examples
|
||||
|
||||
This directory contains a catalog of examples on how to run, configure and
|
||||
scale Ingress. Please review the [prerequisites](PREREQUISITES.md) before
|
||||
trying them.
|
||||
|
||||
## Scaling
|
||||
|
||||
Name | Description | Complexity Level
|
||||
-----| ----------- | ----------------
|
||||
[Static-ip](static-ip/README.md) | a single ingress gets a single static ip | Intermediate
|
||||
|
||||
## Algorithms
|
||||
|
||||
Name | Description | Complexity Level
|
||||
-----| ----------- | ----------------
|
||||
[Session stickyness](affinity/cookie/README.md) | route requests consistently to the same endpoint | Advanced
|
||||
|
||||
## Auth
|
||||
|
||||
Name | Description | Complexity Level
|
||||
-----| ----------- | ----------------
|
||||
[Basic auth](auth/basic/README.md) | password protect your website | nginx | Intermediate
|
||||
[Client certificate authentication](auth/client-certs/README.md) | secure your website with client certificate authentication | nginx | Intermediate
|
||||
[External auth plugin](external-auth/README.md) | defer to an external auth service | Intermediate
|
||||
|
||||
## Customization
|
||||
|
||||
Name | Description | Complexity Level
|
||||
-----| ----------- | ----------------
|
||||
[configuration-snippets](customization/configuration-snippets/README.md) | customize nginx location configuration using annotations | Advanced
|
||||
[custom-headers](customization/custom-headers/README.md) | set custom headers before send traffic to backends | Advanced
|
||||
|
Before Width: | Height: | Size: 86 KiB After Width: | Height: | Size: 86 KiB |
|
Before Width: | Height: | Size: 27 KiB After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 50 KiB |
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 90 KiB |
|
Before Width: | Height: | Size: 84 KiB After Width: | Height: | Size: 84 KiB |
|
|
@ -1,4 +1,4 @@
|
|||
# Deploying the Nginx Ingress controller
|
||||
# Custom VTS metrics with Prometheus
|
||||
|
||||
This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable [nginx vts module](https://github.com/vozlt/nginx-module-vts
|
||||
) to export metrics in prometheus format.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Deploying the Nginx Ingress controller
|
||||
# Custom DH parameters for perfect forward secrecy
|
||||
|
||||
This example aims to demonstrate the deployment of an nginx ingress controller and
|
||||
use a ConfigMap to configure custom Diffie-Hellman parameters file to help with
|
||||
|
|
|
|||
26
docs/examples/index.md
Normal file
26
docs/examples/index.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# Ingress examples
|
||||
|
||||
This directory contains a catalog of examples on how to run, configure and scale Ingress.
|
||||
Please review the [prerequisites](PREREQUISITES.md) before trying them.
|
||||
|
||||
Category | Name | Description | Complexity Level
|
||||
---------| ---- | ----------- | ----------------
|
||||
Apps | [Docker Registry](docker-registry/README.md) | TODO | TODO
|
||||
Auth | [Basic authentication](auth/basic/README.md) | password protect your website | Intermediate
|
||||
Auth | [Client certificate authentication](auth/client-certs/README.md) | secure your website with client certificate authentication | Intermediate
|
||||
Auth | [External authentication plugin](auth/external-auth/README.md) | defer to an external authentication service | Intermediate
|
||||
Auth | [OAuth external auth](auth/oauth-external-auth/README.md) | TODO | TODO
|
||||
Customization | [Configuration snippets](customization/configuration-snippets/README.md) | customize nginx location configuration using annotations | Advanced
|
||||
Customization | [Custom configuration](customization/custom-configuration/README.md) | TODO | TODO
|
||||
Customization | [Custom DH parameters for perfect forward secrecy](customization/ssl-dh-param/README.md) | TODO | TODO
|
||||
Customization | [Custom errors](customization/custom-errors/README.md) | TODO | TODO
|
||||
Customization | [Custom headers](customization/custom-headers/README.md) | set custom headers before sending traffic to backends | Advanced
|
||||
Customization | [Custom upstream check](customization/custom-upstream-check/README.md) | TODO | TODO
|
||||
Customization | [Custom VTS metrics with Prometheus](customization/custom-vts-metrics-prometheus/README.md) | TODO | TODO
|
||||
Customization | [External authentication with response header propagation](customization/external-auth-headers/README.md) | TODO | TODO
|
||||
Customization | [Sysctl tuning](customization/sysctl/README.md) | TODO | TODO
|
||||
Features | [Rewrite](rewrite/README.md) | TODO | TODO
|
||||
Features | [Session stickiness](affinity/cookie/README.md) | route requests consistently to the same endpoint | Advanced
|
||||
Scaling | [Static IP](static-ip/README.md) | a single ingress gets a single static IP | Intermediate
|
||||
TLS | [Multi TLS certificate termination](multi-tls/README.md) | TODO | TODO
|
||||
TLS | [TLS termination](tls-termination/README.md) | TODO | TODO
|
||||
17
docs/user-guide/default-backend.md
Normal file
17
docs/user-guide/default-backend.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
# Default backend
|
||||
|
||||
The default backend is a service which handles all URL paths and hosts the nginx controller doesn't understand
|
||||
(i.e., all the requests that are not mapped with an Ingress).
|
||||
|
||||
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.
|
||||
|
|
@ -1,21 +1,5 @@
|
|||
# Miscellaneous
|
||||
|
||||
## Conventions
|
||||
|
||||
Anytime we reference a tls secret, we mean (x509, pem encoded, RSA 2048, etc). You can generate such a certificate with:
|
||||
`openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${CERT_FILE} -subj "/CN=${HOST}/O=${HOST}"`
|
||||
and create the secret via `kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE}`
|
||||
|
||||
## Requirements
|
||||
|
||||
The default backend is a service which handles all url paths and hosts the nginx controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).
|
||||
Basically a default backend exposes two URLs:
|
||||
|
||||
- `/healthz` that returns 200
|
||||
- `/` that returns 404
|
||||
|
||||
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. 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.
|
||||
|
||||
## 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 trusted external load balancer.
|
||||
|
|
|
|||
|
|
@ -1,30 +1,10 @@
|
|||
# Multiple ingress controllers
|
||||
# Multiple Ingress controllers
|
||||
|
||||
## Running multiple ingress controllers
|
||||
|
||||
If you're running multiple ingress controllers, or running on a cloud provider 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.
|
||||
|
||||
This mechanism also provides users the ability to run _multiple_ NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic). When utilizing this functionality the option `--ingress-class` should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example:
|
||||
|
||||
```
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx-ingress-internal-controller
|
||||
args:
|
||||
- /nginx-ingress-controller
|
||||
- '--default-backend-service=ingress/nginx-ingress-default-backend'
|
||||
- '--election-id=ingress-controller-leader-internal'
|
||||
- '--ingress-class=nginx-internal'
|
||||
- '--configmap=ingress/nginx-ingress-internal-controller'
|
||||
```
|
||||
If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,
|
||||
you need to specify the annotation `kubernetes.io/ingress.class: "nginx"` in all ingresses that you would like the ingress-nginx controller to claim.
|
||||
|
||||
|
||||
## Annotation 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
|
||||
For instance,
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
|
|
@ -44,11 +24,32 @@ metadata:
|
|||
|
||||
will target the nginx controller, forcing the GCE controller to ignore it.
|
||||
|
||||
__Note__: Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.
|
||||
|
||||
## Disabling NGINX ingress controller
|
||||
|
||||
Setting the annotation `kubernetes.io/ingress.class` to any other value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress. If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except "nginx" or an empty string.
|
||||
To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.
|
||||
If you are only running a single NGINX ingress controller, this can be achieved by setting the annotation to any value except "nginx" or an empty string.
|
||||
|
||||
Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
|
||||
|
||||
!!! important
|
||||
Deploying multiple Ingress controllers and not specifying a class annotation will
|
||||
result in both or all controllers fighting to satisfy the Ingress, and all of them
|
||||
updating the Ingress status field in confusing ways.
|
||||
|
||||
## Multiple ingress-nginx controllers
|
||||
|
||||
This mechanism also provides users the ability to run _multiple_ NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic).
|
||||
To do this, the option `--ingress-class` must be changed to a value unique for the cluster within the definition of the replication controller.
|
||||
Here is a partial example:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx-ingress-internal-controller
|
||||
args:
|
||||
- /nginx-ingress-controller
|
||||
- '--default-backend-service=ingress/nginx-ingress-default-backend'
|
||||
- '--election-id=ingress-controller-leader-internal'
|
||||
- '--ingress-class=nginx-internal'
|
||||
- '--configmap=ingress/nginx-ingress-internal-controller'
|
||||
```
|
||||
|
|
|
|||
|
|
@ -7,6 +7,11 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|
|||
Other types, such as boolean or numeric values must be quoted,
|
||||
i.e. `"true"`, `"false"`, `"100"`.
|
||||
|
||||
!!! note
|
||||
The annotation prefix can be changed using the
|
||||
[`--annotations-prefix` command line argument](../cli-arguments.md),
|
||||
but the default is `nginx.ingress.kubernetes.io`, as described in the
|
||||
table below.
|
||||
|
||||
|Name | type |
|
||||
|---------------------------|------|
|
||||
|
|
@ -84,14 +89,31 @@ If the scheme of [`base` tag](https://developer.mozilla.org/en/docs/Web/HTML/Ele
|
|||
|
||||
If the Application Root is exposed in a different path and needs to be redirected, set the annotation `nginx.ingress.kubernetes.io/app-root` to redirect requests for `/`.
|
||||
|
||||
Please check the [rewrite](../../examples/rewrite/README.md) example.
|
||||
!!! example
|
||||
Please check the [rewrite](../../examples/rewrite/README.md) example.
|
||||
|
||||
### Session Affinity
|
||||
|
||||
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`.
|
||||
|
||||
Please check the [affinity](../../examples/affinity/cookie/README.md) example.
|
||||
!!! example
|
||||
Please check the [affinity](../../examples/affinity/cookie/README.md) example.
|
||||
|
||||
#### Cookie affinity
|
||||
|
||||
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'.
|
||||
|
||||
In case of NGINX the annotation `nginx.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`.
|
||||
|
||||
!!! attention
|
||||
The `index` option is not an actual hash; an in-memory index is used instead, which has less overhead.
|
||||
However, with `index`, matching against a changing upstream server list is inconsistent.
|
||||
So, at reload, if upstream servers have changed, index values are not guaranteed to correspond to the same server as before!
|
||||
**Use `index` with caution** and only if you need to!
|
||||
|
||||
In NGINX this feature is implemented by the third party module [nginx-sticky-module-ng](https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng). The workflow used to define which upstream server will be used is explained [here](https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/raw/08a395c66e425540982c00482f55034e1fee67b6/docs/sticky.pdf)
|
||||
|
||||
|
||||
### Authentication
|
||||
|
||||
|
|
@ -115,7 +137,8 @@ This annotation also accepts the alternative form "namespace/secretName", in whi
|
|||
nginx.ingress.kubernetes.io/auth-realm: "realm string"
|
||||
```
|
||||
|
||||
Please check the [auth](../../examples/auth/basic/README.md) example.
|
||||
!!! example
|
||||
Please check the [auth](../../examples/auth/basic/README.md) example.
|
||||
|
||||
### Custom NGINX upstream checks
|
||||
|
||||
|
|
@ -133,10 +156,12 @@ To use custom values in an Ingress rule define these annotations:
|
|||
|
||||
In NGINX, backend server pools are called "[upstreams](http://nginx.org/en/docs/http/ngx_http_upstream_module.html)". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined.
|
||||
|
||||
!!! Important
|
||||
All Ingress rules using the same service will use the same upstream. Only one of the Ingress rules should define annotations to configure the upstream servers.
|
||||
!!! attention
|
||||
All Ingress rules using the same service will use the same upstream.
|
||||
Only one of the Ingress rules should define annotations to configure the upstream servers.
|
||||
|
||||
Please check the [custom upstream check](../../examples/customization/custom-upstream-check/README.md) example.
|
||||
!!! example
|
||||
Please check the [custom upstream check](../../examples/customization/custom-upstream-check/README.md) example.
|
||||
|
||||
### Custom NGINX upstream hashing
|
||||
|
||||
|
|
@ -160,42 +185,24 @@ This configuration setting allows you to control the value for host in the follo
|
|||
It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.
|
||||
|
||||
The annotations are:
|
||||
```
|
||||
nginx.ingress.kubernetes.io/auth-tls-secret: secretName
|
||||
```
|
||||
|
||||
The name of the Secret that contains the full Certificate Authority chain `ca.crt` that is enabled to authenticate against this Ingress.
|
||||
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-tls-secret: secretName`:
|
||||
The name of the Secret that contains the full Certificate Authority chain `ca.crt` that is enabled to authenticate against this Ingress.
|
||||
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-tls-verify-depth`:
|
||||
The validation depth between the provided client certificate and the Certification Authority chain.
|
||||
* `nginx.ingress.kubernetes.io/auth-tls-verify-client`:
|
||||
Enables verification of client certificates.
|
||||
* `nginx.ingress.kubernetes.io/auth-tls-error-page`:
|
||||
The URL/Page that user should be redirected in case of a Certificate Authentication Error
|
||||
* `nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream`:
|
||||
Indicates if the received certificates should be passed or not to the upstream server. By default this is disabled.
|
||||
|
||||
```
|
||||
nginx.ingress.kubernetes.io/auth-tls-verify-depth
|
||||
```
|
||||
!!! example
|
||||
Please check the [client-certs](../../examples/auth/client-certs/README.md) example.
|
||||
|
||||
The validation depth between the provided client certificate and the Certification Authority chain.
|
||||
|
||||
```
|
||||
nginx.ingress.kubernetes.io/auth-tls-verify-client
|
||||
```
|
||||
|
||||
Enables verification of client certificates.
|
||||
|
||||
```
|
||||
nginx.ingress.kubernetes.io/auth-tls-error-page
|
||||
```
|
||||
|
||||
The URL/Page that user should be redirected in case of a Certificate Authentication Error
|
||||
|
||||
```
|
||||
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream
|
||||
```
|
||||
|
||||
Indicates if the received certificates should be passed or not to the upstream server.
|
||||
By default this is disabled.
|
||||
|
||||
Please check the [client-certs](../../examples/auth/client-certs/README.md) example.
|
||||
|
||||
!!! Important
|
||||
TLS with Client Authentication is NOT possible in Cloudflare as is not allowed it and might result in unexpected behavior.
|
||||
!!! attention
|
||||
TLS with Client Authentication is **not** possible in Cloudflare and might result in unexpected behavior.
|
||||
|
||||
Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: [https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/](https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/)
|
||||
|
||||
|
|
@ -213,47 +220,55 @@ nginx.ingress.kubernetes.io/configuration-snippet: |
|
|||
|
||||
### Default Backend
|
||||
|
||||
The ingress controller requires a default backend. This service handles the response when the service in the Ingress rule does not have endpoints.
|
||||
The ingress controller requires a [default backend](../default-backend.md).
|
||||
This service handles the response when the service in the Ingress rule does not have endpoints.
|
||||
This is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation `nginx.ingress.kubernetes.io/default-backend: <svc name>` to specify a custom default backend.
|
||||
|
||||
### Enable CORS
|
||||
|
||||
To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule add the annotation `nginx.ingress.kubernetes.io/enable-cors: "true"`. This will add a section in the server location enabling this functionality.
|
||||
To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule,
|
||||
add the annotation `nginx.ingress.kubernetes.io/enable-cors: "true"`.
|
||||
This will add a section in the server location enabling this functionality.
|
||||
|
||||
CORS can be controlled with the following annotations:
|
||||
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-methods` controls which methods are accepted. This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-methods`
|
||||
controls which methods are accepted.
|
||||
This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"`
|
||||
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"`
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-headers`
|
||||
controls which headers are accepted.
|
||||
This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"`
|
||||
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-headers` controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-origin`
|
||||
controls what's the accepted Origin for CORS and defaults to '*'.
|
||||
This is a single field value, with the following format: `http(s)://origin-site.com` or `http(s)://origin-site.com:port`
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443"`
|
||||
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"`
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-credentials`
|
||||
controls if credentials can be passed during CORS operations.
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`
|
||||
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-origin` controls what's the accepted Origin for CORS and defaults to '*'. This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port
|
||||
* `nginx.ingress.kubernetes.io/cors-max-age`
|
||||
controls how long preflight requests can be cached.
|
||||
Example: `nginx.ingress.kubernetes.io/cors-max-age: 600`
|
||||
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443"`
|
||||
|
||||
* `nginx.ingress.kubernetes.io/cors-allow-credentials` controls if credentials can be passed during CORS operations.
|
||||
|
||||
Example: `nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`
|
||||
|
||||
* `nginx.ingress.kubernetes.io/cors-max-age` controls how long preflight requests can be cached.
|
||||
|
||||
Example: `nginx.ingress.kubernetes.io/cors-max-age: 600`
|
||||
|
||||
|
||||
For more information please see [https://enable-cors.org](https://enable-cors.org/server_nginx.html)
|
||||
!!! note
|
||||
For more information please see [https://enable-cors.org](https://enable-cors.org/server_nginx.html)
|
||||
|
||||
### 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.
|
||||
This will create a server with the same configuration, but a different `server_name` as the provided host.
|
||||
|
||||
!!! 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.
|
||||
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 [http://nginx.org](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name)
|
||||
For more information please see [the `server_name` documentation](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name).
|
||||
|
||||
### Server snippet
|
||||
|
||||
|
|
@ -276,8 +291,8 @@ if ( $agentflag = 1 ) {
|
|||
}
|
||||
```
|
||||
|
||||
!!! Important
|
||||
This annotation can be used only once per host
|
||||
!!! attention
|
||||
This annotation can be used only once per host.
|
||||
|
||||
### Client Body Buffer Size
|
||||
|
||||
|
|
@ -286,14 +301,16 @@ the whole body or only its part is written to a temporary file. By default, buff
|
|||
This is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is
|
||||
applied to each location provided in the ingress rule.
|
||||
|
||||
__Note:__ The annotation value must be given in a valid format otherwise the
|
||||
For example to set the client-body-buffer-size the following can be done:
|
||||
!!! note
|
||||
The annotation value must be given in a format understood by Nginx.
|
||||
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: "1000"` # 1000 bytes
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1k` # 1 kilobyte
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1K` # 1 kilobyte
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1m` # 1 megabyte
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1M` # 1 megabyte
|
||||
!!! example
|
||||
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: "1000"` # 1000 bytes
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1k` # 1 kilobyte
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1K` # 1 kilobyte
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1m` # 1 megabyte
|
||||
* `nginx.ingress.kubernetes.io/client-body-buffer-size: 1M` # 1 megabyte
|
||||
|
||||
For more information please see [http://nginx.org](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size)
|
||||
|
||||
|
|
@ -307,25 +324,28 @@ nginx.ingress.kubernetes.io/auth-url: "URL to the authentication service"
|
|||
|
||||
Additionally it is possible to set:
|
||||
|
||||
`nginx.ingress.kubernetes.io/auth-method`: `<Method>` to specify the HTTP method to use.
|
||||
* `nginx.ingress.kubernetes.io/auth-method`:
|
||||
`<Method>` to specify the HTTP method to use.
|
||||
* `nginx.ingress.kubernetes.io/auth-signin`:
|
||||
`<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 authorization request completes.
|
||||
* `nginx.ingress.kubernetes.io/auth-request-redirect`:
|
||||
`<Request_Redirect_URL>` to specify the X-Auth-Request-Redirect header value.
|
||||
|
||||
`nginx.ingress.kubernetes.io/auth-signin`: `<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 authorization request completes.
|
||||
|
||||
`nginx.ingress.kubernetes.io/auth-request-redirect`: `<Request_Redirect_URL>` to specify the X-Auth-Request-Redirect header value.
|
||||
|
||||
Please check the [external-auth](../../examples/auth/external-auth/README.md) example.
|
||||
!!! example
|
||||
Please check the [external-auth](../../examples/auth/external-auth/README.md) example.
|
||||
|
||||
### Rate limiting
|
||||
|
||||
The annotations `nginx.ingress.kubernetes.io/limit-connections`, `nginx.ingress.kubernetes.io/limit-rps`, and `nginx.ingress.kubernetes.io/limit-rpm` 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 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).
|
||||
|
||||
`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-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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -333,34 +353,44 @@ If you specify multiple annotations in a single Ingress rule, `limit-rpm`, and t
|
|||
|
||||
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.
|
||||
|
||||
`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.
|
||||
|
||||
To configure this setting globally for all Ingress rules, the `limit-rate-after` and `limit-rate` value may be set in the NGINX ConfigMap. if you set the value in ingress annotation will cover global setting.
|
||||
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]. if you set the value in ingress annotation will cover global setting.
|
||||
|
||||
### Permanent Redirect
|
||||
|
||||
This annotation allows to return a permanent redirect instead of sending data to the upstream. For example `nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com` would redirect everything to Google.
|
||||
|
||||
### SSL Passthrough
|
||||
|
||||
The annotation `nginx.ingress.kubernetes.io/ssl-passthrough` allows to configure TLS termination in the pod and not in NGINX.
|
||||
|
||||
!!! Important
|
||||
- Using the annotation `nginx.ingress.kubernetes.io/ssl-passthrough` invalidates all the other available annotations. This is because SSL Passthrough works in L4 (TCP).
|
||||
!!! attention
|
||||
Using the annotation `nginx.ingress.kubernetes.io/ssl-passthrough` invalidates all the other available annotations.
|
||||
This is because SSL Passthrough works on level 4 of the OSI stack (TCP), not on the HTTP/HTTPS level.
|
||||
|
||||
- The use of this annotation requires Proxy Protocol to be enabled in the load-balancer. For example enabling Proxy Protocol for AWS ELB is described [here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-proxy-protocol.html). If you're using ingress-controller without load balancer then the flag `--enable-ssl-passthrough` is required (by default it is disabled).
|
||||
!!! attention
|
||||
The use of this annotation requires the Proxy Protocol to be enabled in the front-end load-balancer.
|
||||
For example enabling Proxy Protocol for AWS ELB is described [here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-proxy-protocol.html).
|
||||
If you're using ingress-controller without load balancer then the flag
|
||||
`--enable-ssl-passthrough` is required (by default it is disabled).
|
||||
|
||||
### Secure backends
|
||||
|
||||
By default NGINX uses `http` to reach the services. Adding the annotation `nginx.ingress.kubernetes.io/secure-backends: "true"` in the Ingress rule changes the protocol to `https`.
|
||||
By default NGINX uses plain HTTP to reach the services.
|
||||
Adding the annotation `nginx.ingress.kubernetes.io/secure-backends: "true"` in the Ingress rule changes the protocol to HTTPS.
|
||||
If you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation `nginx.ingress.kubernetes.io/secure-verify-ca-secret`.
|
||||
|
||||
> Note that if an invalid or non-existent secret is given, the NGINX ingress controller will ignore the `secure-backends` annotation.
|
||||
!!! attention
|
||||
|
||||
Note that if an invalid or non-existent secret is given,
|
||||
the ingress controller will ignore the `secure-backends` annotation.
|
||||
|
||||
### Service Upstream
|
||||
|
||||
By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration. This annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port. This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue [#257](https://github.com/kubernetes/ingress-nginx/issues/257).
|
||||
By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.
|
||||
|
||||
The `nginx.ingress.kubernetes.io/service-upstream` annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port.
|
||||
|
||||
This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue [#257](https://github.com/kubernetes/ingress-nginx/issues/257).
|
||||
|
||||
#### Known Issues
|
||||
|
||||
|
|
@ -371,36 +401,33 @@ If the `service-upstream` annotation is specified the following things should be
|
|||
|
||||
### Server-side HTTPS enforcement through redirect
|
||||
|
||||
By default the controller redirects (301) to `HTTPS` if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use `ssl-redirect: "false"` in the NGINX config map.
|
||||
By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress.
|
||||
If you want to disable this behavior globally, you can use `ssl-redirect: "false"` in the NGINX [config map][configmap].
|
||||
|
||||
To configure this feature for specific ingress resources, you can use the `nginx.ingress.kubernetes.io/ssl-redirect: "false"` annotation in the particular resource.
|
||||
To configure this feature for specific ingress resources, you can use the `nginx.ingress.kubernetes.io/ssl-redirect: "false"`
|
||||
annotation in the particular resource.
|
||||
|
||||
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 not TLS cert available. This can be achieved by using the `nginx.ingress.kubernetes.io/force-ssl-redirect: "true"` annotation in the particular resource.
|
||||
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"` annotation in the particular resource.
|
||||
|
||||
### Redirect from to www
|
||||
### Redirect from/to www.
|
||||
|
||||
In some scenarios is required to redirect from `www.domain.com` to `domain.com` or viceversa.
|
||||
In some scenarios is required to redirect from `www.domain.com` to `domain.com` or vice versa.
|
||||
To enable this feature use the annotation `nginx.ingress.kubernetes.io/from-to-www-redirect: "true"`
|
||||
|
||||
!!! Important
|
||||
!!! attention
|
||||
If at some point a new Ingress is created with a host equal to one of the options (like `domain.com`) the annotation will be omitted.
|
||||
|
||||
### Whitelist source range
|
||||
|
||||
You can specify the allowed client IP source ranges through the `nginx.ingress.kubernetes.io/whitelist-source-range` annotation. The value is a comma separated list of [CIDRs](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing), e.g. `10.0.0.0/24,172.10.0.1`.
|
||||
You can specify allowed client IP source ranges through the `nginx.ingress.kubernetes.io/whitelist-source-range` annotation.
|
||||
The value is a comma separated list of [CIDRs](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing), e.g. `10.0.0.0/24,172.10.0.1`.
|
||||
|
||||
To configure this setting globally for all Ingress rules, the `whitelist-source-range` value may be set in the NGINX ConfigMap.
|
||||
To configure this setting globally for all Ingress rules, the `whitelist-source-range` value may be set in the [NGINX ConfigMap][configmap].
|
||||
|
||||
__Note:__ Adding an annotation to an Ingress rule overrides any global restriction.
|
||||
|
||||
### 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 `nginx.ingress.kubernetes.io/session-cookie-name`. The default is to create a cookie named 'INGRESSCOOKIE'.
|
||||
|
||||
In case of NGINX the annotation `nginx.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`.
|
||||
The `index` option is not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter Warning: the matching against upstream servers list is inconsistent. So, at reload, if upstreams servers has changed, index values are not guaranteed to correspond to the same server as before! **USE IT WITH CAUTION** and only if you need to!
|
||||
|
||||
In NGINX this feature is implemented by the third party module [nginx-sticky-module-ng](https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng). The workflow used to define which upstream server will be used is explained [here](https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/raw/08a395c66e425540982c00482f55034e1fee67b6/docs/sticky.pdf)
|
||||
!!! note
|
||||
Adding an annotation to an Ingress rule overrides any global restriction.
|
||||
|
||||
### Custom timeouts
|
||||
|
||||
|
|
@ -417,15 +444,16 @@ In some scenarios is required to have different values. To allow this we provide
|
|||
### Proxy redirect
|
||||
|
||||
With the annotations `nginx.ingress.kubernetes.io/proxy-redirect-from` and `nginx.ingress.kubernetes.io/proxy-redirect-to` it is possible to set the text that should be changed in the `Location` and `Refresh` header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)
|
||||
Setting "off" or "default" in the annotation `nginx.ingress.kubernetes.io/proxy-redirect-from` disables `nginx.ingress.kubernetes.io/proxy-redirect-to`
|
||||
Both annotations will be used in any other case
|
||||
By default the value is "off".
|
||||
|
||||
Setting "off" or "default" in the annotation `nginx.ingress.kubernetes.io/proxy-redirect-from` disables `nginx.ingress.kubernetes.io/proxy-redirect-to`.
|
||||
|
||||
Both annotations will be used in any other case. By default the value is "off".
|
||||
|
||||
### Custom max body size
|
||||
|
||||
For NGINX, 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter [`client_max_body_size`](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size).
|
||||
For NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter [`client_max_body_size`](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size).
|
||||
|
||||
To configure this setting globally for all Ingress rules, the `proxy-body-size` value may be set in the NGINX ConfigMap.
|
||||
To configure this setting globally for all Ingress rules, the `proxy-body-size` value may be set in the [NGINX ConfigMap][configmap].
|
||||
To use custom values in an Ingress rule define these annotation:
|
||||
|
||||
```yaml
|
||||
|
|
@ -435,9 +463,9 @@ nginx.ingress.kubernetes.io/proxy-body-size: 8m
|
|||
### Proxy buffering
|
||||
|
||||
Enable or disable proxy buffering [`proxy_buffering`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering).
|
||||
By default proxy buffering is disabled in the nginx config.
|
||||
By default proxy buffering is disabled in the NGINX config.
|
||||
|
||||
To configure this setting globally for all Ingress rules, the `proxy-buffering` value may be set in the NGINX ConfigMap.
|
||||
To configure this setting globally for all Ingress rules, the `proxy-buffering` value may be set in the [NGINX ConfigMap][configmap].
|
||||
To use custom values in an Ingress rule define these annotation:
|
||||
|
||||
```yaml
|
||||
|
|
@ -455,7 +483,9 @@ nginx.ingress.kubernetes.io/ssl-ciphers: "ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+ME
|
|||
```
|
||||
|
||||
### Connection proxy header
|
||||
Using this annotation will override the default connection header set by nginx. To use custom values in an Ingress rule, define the annotation:
|
||||
|
||||
Using this annotation will override the default connection header set by NGINX.
|
||||
To use custom values in an Ingress rule, define the annotation:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/connection-proxy-header: "keep-alive"
|
||||
|
|
@ -463,7 +493,8 @@ nginx.ingress.kubernetes.io/connection-proxy-header: "keep-alive"
|
|||
|
||||
### Enable Access Log
|
||||
|
||||
In some scenarios could be required to disable NGINX access logs. To enable this feature use the annotation:
|
||||
Access logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given
|
||||
ingress. To do this, use the annotation:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/enable-access-log: "false"
|
||||
|
|
@ -471,7 +502,8 @@ nginx.ingress.kubernetes.io/enable-access-log: "false"
|
|||
|
||||
### Enable Rewrite Log
|
||||
|
||||
In some scenarios it could be required to enable NGINX rewrite logs. Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:
|
||||
Rewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs.
|
||||
Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/enable-rewrite-log: "true"
|
||||
|
|
@ -479,19 +511,21 @@ nginx.ingress.kubernetes.io/enable-rewrite-log: "true"
|
|||
|
||||
### Lua Resty WAF
|
||||
|
||||
Using `lua-resty-waf-*` annotations we can enable and control [lua-resty-waf](https://github.com/p0pr0ck5/lua-resty-waf) per location.
|
||||
Following configuration will enable WAF for the paths defined in the corresponding ingress:
|
||||
Using `lua-resty-waf-*` annotations we can enable and control the [lua-resty-waf](https://github.com/p0pr0ck5/lua-resty-waf)
|
||||
Web Application Firewall per location.
|
||||
|
||||
Following configuration will enable the WAF for the paths defined in the corresponding ingress:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/lua-resty-waf: "active"
|
||||
```
|
||||
|
||||
In order to run it in debugging mode you can set `nginx.ingress.kubernetes.io/lua-resty-waf-debug` to `"true"` in addition to the above configuration.
|
||||
The other possible values for `nginx.ingress.kubernetes.io/lua-resty-waf` are `inactive` and `simulate`. In `inactive` mode WAF won't do anything, whereas
|
||||
in `simulate` mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.
|
||||
The other possible values for `nginx.ingress.kubernetes.io/lua-resty-waf` are `inactive` and `simulate`.
|
||||
In `inactive` mode WAF won't do anything, whereas in `simulate` mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.
|
||||
|
||||
`lua-resty-waf` comes with predefined set of rules [https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules](https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules) that covers ModSecurity CRS.
|
||||
You can use `nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets` to ignore subset of those rulesets. For an example:
|
||||
You can use `nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets` to ignore a subset of those rulesets. For an example:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets: "41000_sqli, 42000_xss"
|
||||
|
|
@ -499,8 +533,7 @@ nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets: "41000_sqli, 42000_xs
|
|||
|
||||
will ignore the two mentioned rulesets.
|
||||
|
||||
It is also possible to configure custom WAF rules per ingress using `nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules` annotation. For an example the following snippet will
|
||||
configure a WAF rule to deny requests with query string value that contains word `foo`:
|
||||
It is also possible to configure custom WAF rules per ingress using the `nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules` annotation. For an example the following snippet will configure a WAF rule to deny requests with query string value that contains word `foo`:
|
||||
|
||||
|
||||
```yaml
|
||||
|
|
@ -513,8 +546,11 @@ For details on how to write WAF rules, please refer to [https://github.com/p0pr0
|
|||
|
||||
Since NGINX 1.13.10 it is possible to expose [gRPC services natively](http://nginx.org/en/docs/http/ngx_http_grpc_module.html)
|
||||
|
||||
You only need to add the annotation `nginx.ingress.kubernetes.io/grpc-backend: "true"` to enable this feature. Additionally, if the gRPC service requires TLS `nginx.ingress.kubernetes.io/secure-backends: "true"`
|
||||
You only need to add the annotation `nginx.ingress.kubernetes.io/grpc-backend: "true"` to enable this feature.
|
||||
Additionally, if the gRPC service requires TLS, add `nginx.ingress.kubernetes.io/secure-backends: "true"`.
|
||||
|
||||
!!! Important
|
||||
!!! attention
|
||||
This feature requires HTTP2 to work which means we need to expose this service using HTTPS.
|
||||
Exposing a gRPC service using HTTP is not supported.
|
||||
Exposing a gRPC service using HTTP is not supported.
|
||||
|
||||
[configmap]: ./configmap.md
|
||||
|
|
@ -1,34 +1,38 @@
|
|||
# Log format
|
||||
|
||||
The default configuration uses a custom logging format to add additional information about upstreams, response time and status
|
||||
The default configuration uses a custom logging format to add additional information about upstreams, response time and status.
|
||||
|
||||
```
|
||||
log_format upstreaminfo '{{ if $cfg.useProxyProtocol }}$proxy_protocol_addr{{ else }}$remote_addr{{ end }} - '
|
||||
'[$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';
|
||||
log_format upstreaminfo
|
||||
'{{ if $cfg.useProxyProtocol }}$proxy_protocol_addr{{ else }}$remote_addr{{ end }} - '
|
||||
'[$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';
|
||||
```
|
||||
|
||||
| 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_user` | user name supplied with the Basic authentication |
|
||||
| `$time_local` | local time in the Common Log Format |
|
||||
| `$request` | full original request line |
|
||||
| `$status` | response status |
|
||||
| `$body_bytes_sent` | number of bytes sent to a client, not counting the response header |
|
||||
| `$http_referer` | value of the Referer header |
|
||||
| `$http_user_agent` | value of User-Agent header |
|
||||
| `$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>` |
|
||||
| `$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 |
|
||||
| `$upstream_status` | status code of the response obtained from the upstream server |
|
||||
|
||||
|
||||
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)
|
||||
|
||||
Description:
|
||||
|
||||
- `$proxy_protocol_addr`: if PROXY protocol is enabled
|
||||
- `$remote_addr`: if PROXY protocol is disabled (default)
|
||||
- `$the_real_ip`: 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
|
||||
- `$status`: response status
|
||||
- `$body_bytes_sent`: number of bytes sent to a client, not counting the response header
|
||||
- `$http_referer`: value of the Referer header
|
||||
- `$http_user_agent`: value of User-Agent header
|
||||
- `$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>`
|
||||
- `$upstream_addr`: keeps the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas
|
||||
- `$upstream_response_length`: keeps the length of the response obtained from the upstream server
|
||||
- `$upstream_response_time`: keeps time spent on receiving the response from the upstream server; the time is kept in seconds with millisecond resolution
|
||||
- `$upstream_status`: keeps status code of the response obtained from the upstream server
|
||||
- [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)
|
||||
|
|
@ -1,162 +1,110 @@
|
|||
# TLS
|
||||
# TLS/HTTPS
|
||||
|
||||
- [Default SSL Certificate](#default-ssl-certificate)
|
||||
- [SSL Passthrough](#ssl-passthrough)
|
||||
- [HTTPS enforcement](#server-side-https-enforcement)
|
||||
- [HSTS](#http-strict-transport-security)
|
||||
- [Server-side HTTPS enforcement through redirect](#server-side-https-enforcement-through-redirect)
|
||||
- [Kube-Lego](#automated-certificate-management-with-kube-lego)
|
||||
- [Default TLS Version and Ciphers](#default-tls-version-and-ciphers)
|
||||
- [Legacy TLS](#legacy-tls)
|
||||
## TLS Secrets
|
||||
|
||||
Anytime we reference a TLS secret, we mean a PEM-encoded X.509, RSA (2048) secret.
|
||||
|
||||
You can generate a self-signed certificate and private key with with:
|
||||
|
||||
```bash
|
||||
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${CERT_FILE} -subj "/CN=${HOST}/O=${HOST}"`
|
||||
```
|
||||
|
||||
Then create the secret in the cluster via:
|
||||
|
||||
```bash
|
||||
kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE}
|
||||
```
|
||||
|
||||
The resulting secret will be of type `kubernetes.io/tls`.
|
||||
|
||||
## Default SSL Certificate
|
||||
|
||||
NGINX provides the option to configure a server as a catch-all with [server_name](http://nginx.org/en/docs/http/server_names.html) for requests that do not match any of the configured server names. This configuration works without issues for HTTP traffic.
|
||||
In case of HTTPS, NGINX requires a certificate.
|
||||
For this reason the Ingress controller provides the flag `--default-ssl-certificate`. The secret behind this flag contains the default certificate to be used in the mentioned scenario. If this flag is not provided NGINX will use a self signed certificate.
|
||||
NGINX provides the option to configure a server as a catch-all with
|
||||
[server_name](http://nginx.org/en/docs/http/server_names.html)
|
||||
for requests that do not match any of the configured server names.
|
||||
This configuration works without out-of-the-box for HTTP traffic.
|
||||
For HTTPS, a certificate is naturally required.
|
||||
|
||||
Running without the flag `--default-ssl-certificate`:
|
||||
For this reason the Ingress controller provides the flag `--default-ssl-certificate`.
|
||||
The secret referred to by this flag contains the default certificate to be used when
|
||||
accessing the catch-all server.
|
||||
If this flag is not provided NGINX will use a self-signed certificate.
|
||||
|
||||
```console
|
||||
$ curl -v https://10.2.78.7:443 -k
|
||||
* Rebuilt URL to: https://10.2.78.7:443/
|
||||
* Trying 10.2.78.4...
|
||||
* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)
|
||||
* ALPN, offering http/1.1
|
||||
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
|
||||
* successfully set certificate verify locations:
|
||||
* CAfile: /etc/ssl/certs/ca-certificates.crt
|
||||
CApath: /etc/ssl/certs
|
||||
* TLSv1.2 (OUT), TLS header, Certificate Status (22):
|
||||
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
|
||||
* TLSv1.2 (IN), TLS handshake, Server hello (2):
|
||||
* TLSv1.2 (IN), TLS handshake, Certificate (11):
|
||||
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
|
||||
* TLSv1.2 (IN), TLS handshake, Server finished (14):
|
||||
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
|
||||
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
|
||||
* TLSv1.2 (OUT), TLS handshake, Finished (20):
|
||||
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
|
||||
* TLSv1.2 (IN), TLS handshake, Finished (20):
|
||||
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
|
||||
* ALPN, server accepted to use http/1.1
|
||||
* Server certificate:
|
||||
* subject: CN=foo.bar.com
|
||||
* start date: Apr 13 00:50:56 2016 GMT
|
||||
* expire date: Apr 13 00:50:56 2017 GMT
|
||||
* issuer: CN=foo.bar.com
|
||||
* SSL certificate verify result: self signed certificate (18), continuing anyway.
|
||||
> GET / HTTP/1.1
|
||||
> Host: 10.2.78.7
|
||||
> User-Agent: curl/7.47.1
|
||||
> Accept: */*
|
||||
>
|
||||
< HTTP/1.1 404 Not Found
|
||||
< Server: nginx/1.11.1
|
||||
< Date: Thu, 21 Jul 2016 15:38:46 GMT
|
||||
< Content-Type: text/html
|
||||
< Transfer-Encoding: chunked
|
||||
< Connection: keep-alive
|
||||
< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload
|
||||
<
|
||||
<span>The page you're looking for could not be found.</span>
|
||||
|
||||
* Connection #0 to host 10.2.78.7 left intact
|
||||
```
|
||||
|
||||
Specifying `--default-ssl-certificate=default/foo-tls`:
|
||||
|
||||
```console
|
||||
core@localhost ~ $ curl -v https://10.2.78.7:443 -k
|
||||
* Rebuilt URL to: https://10.2.78.7:443/
|
||||
* Trying 10.2.78.7...
|
||||
* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)
|
||||
* ALPN, offering http/1.1
|
||||
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
|
||||
* successfully set certificate verify locations:
|
||||
* CAfile: /etc/ssl/certs/ca-certificates.crt
|
||||
CApath: /etc/ssl/certs
|
||||
* TLSv1.2 (OUT), TLS header, Certificate Status (22):
|
||||
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
|
||||
* TLSv1.2 (IN), TLS handshake, Server hello (2):
|
||||
* TLSv1.2 (IN), TLS handshake, Certificate (11):
|
||||
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
|
||||
* TLSv1.2 (IN), TLS handshake, Server finished (14):
|
||||
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
|
||||
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
|
||||
* TLSv1.2 (OUT), TLS handshake, Finished (20):
|
||||
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
|
||||
* TLSv1.2 (IN), TLS handshake, Finished (20):
|
||||
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
|
||||
* ALPN, server accepted to use http/1.1
|
||||
* Server certificate:
|
||||
* subject: CN=foo.bar.com
|
||||
* start date: Apr 13 00:50:56 2016 GMT
|
||||
* expire date: Apr 13 00:50:56 2017 GMT
|
||||
* issuer: CN=foo.bar.com
|
||||
* SSL certificate verify result: self signed certificate (18), continuing anyway.
|
||||
> GET / HTTP/1.1
|
||||
> Host: 10.2.78.7
|
||||
> User-Agent: curl/7.47.1
|
||||
> Accept: */*
|
||||
>
|
||||
< HTTP/1.1 404 Not Found
|
||||
< Server: nginx/1.11.1
|
||||
< Date: Mon, 18 Jul 2016 21:02:59 GMT
|
||||
< Content-Type: text/html
|
||||
< Transfer-Encoding: chunked
|
||||
< Connection: keep-alive
|
||||
< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload
|
||||
<
|
||||
<span>The page you're looking for could not be found.</span>
|
||||
|
||||
* Connection #0 to host 10.2.78.7 left intact
|
||||
```
|
||||
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.
|
||||
|
||||
## SSL Passthrough
|
||||
|
||||
The flag `--enable-ssl-passthrough` enables SSL passthrough feature.
|
||||
By default this feature is disabled
|
||||
The flag `--enable-ssl-passthrough` enables the SSL passthrough feature.
|
||||
By default this feature is disabled.
|
||||
|
||||
This is required to enable passthrough backends in Ingress configurations.
|
||||
|
||||
TODO: Improve this documentation.
|
||||
|
||||
## HTTP Strict Transport Security
|
||||
|
||||
HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS.
|
||||
HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified
|
||||
through the use of a special response header. Once a supported browser receives
|
||||
this header that browser will prevent any communications from being sent over
|
||||
HTTP to the specified domain and will instead send all communications over HTTPS.
|
||||
|
||||
By default the controller redirects (301) to HTTPS if there is a TLS Ingress rule.
|
||||
HSTS is enabled by default.
|
||||
|
||||
To disable this behavior use `hsts: "false"` in the configuration ConfigMap.
|
||||
To disable this behavior use `hsts: "false"` in the configuration [ConfigMap][ConfigMap].
|
||||
|
||||
## Server-side HTTPS enforcement through redirect
|
||||
|
||||
By default the controller redirects (301) to `HTTPS` if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use `ssl-redirect: "false"` in the NGINX config map.
|
||||
By default the controller redirects HTTP clients to the HTTPS port
|
||||
443 using a 308 Permanent Redirect response if TLS is enabled for that Ingress.
|
||||
|
||||
To configure this feature for specific ingress resources, you can use the `nginx.ingress.kubernetes.io/ssl-redirect: "false"` annotation in the particular resource.
|
||||
This can be disabled globally using `ssl-redirect: "false"` in the NGINX [config map][ConfigMap],
|
||||
or per-Ingress with the `nginx.ingress.kubernetes.io/ssl-redirect: "false"`
|
||||
annotation in the particular resource.
|
||||
|
||||
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 not TLS cert available. This can be achieved by using the `nginx.ingress.kubernetes.io/force-ssl-redirect: "true"` 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"`
|
||||
annotation in the particular resource.
|
||||
|
||||
## Automated Certificate Management with Kube-Lego
|
||||
|
||||
[Kube-Lego] automatically requests missing or expired certificates from [Let's Encrypt] by monitoring ingress resources and their referenced secrets. To enable this for an ingress resource you have to add an annotation:
|
||||
!!! tip
|
||||
Kube-Lego has reached end-of-life and is being
|
||||
replaced by [cert-manager](https://github.com/jetstack/cert-manager/).
|
||||
|
||||
[Kube-Lego] automatically requests missing or expired certificates from [Let's Encrypt]
|
||||
by monitoring ingress resources and their referenced secrets.
|
||||
|
||||
To enable this for an ingress resource you have to add an annotation:
|
||||
|
||||
```console
|
||||
kubectl annotate ing ingress-demo kubernetes.io/tls-acme="true"
|
||||
```
|
||||
|
||||
To setup Kube-Lego you can take a look at this [full example]. The first
|
||||
version to fully support Kube-Lego is nginx Ingress controller 0.8.
|
||||
|
||||
[full example]:https://github.com/jetstack/kube-lego/tree/master/examples
|
||||
[Kube-Lego]:https://github.com/jetstack/kube-lego
|
||||
[Let's Encrypt]:https://letsencrypt.org
|
||||
To setup Kube-Lego you can take a look at this [full example][full-kube-lego-example].
|
||||
The first version to fully support Kube-Lego is Nginx Ingress controller 0.8.
|
||||
|
||||
## Default TLS Version and Ciphers
|
||||
|
||||
To provide the most secure baseline configuration possible, nginx-ingress defaults to using TLS 1.2 and a [secure set of TLS ciphers](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#ssl-ciphers)
|
||||
To provide the most secure baseline configuration possible,
|
||||
|
||||
## Legacy TLS
|
||||
The default configuration, though secure, does not support some older browsers and operating systems. For instance, 20% of Android phones in use today are not compatible with nginx-ingress's default configuration. To change this default behavior, use a [ConfigMap](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#ssl-ciphers).
|
||||
nginx-ingress defaults to using TLS 1.2 only and a [secure set of TLS ciphers][ssl-ciphers].
|
||||
|
||||
A sample ConfigMap to allow these older clients connect could look something like the following:
|
||||
### Legacy TLS
|
||||
|
||||
The default configuration, though secure, does not support some older browsers and operating systems.
|
||||
|
||||
For instance, TLS 1.1+ is only enabled by default from Android 5.0 on. At the time of writing,
|
||||
May 2018, [approximately 15% of Android devices](https://developer.android.com/about/dashboards/#Platform)
|
||||
are not compatible with nginx-ingress's default configuration.
|
||||
|
||||
To change this default behavior, use a [ConfigMap][ConfigMap].
|
||||
|
||||
A sample ConfigMap fragment to allow these older clients to connect could look something like the following:
|
||||
|
||||
```
|
||||
kind: ConfigMap
|
||||
|
|
@ -167,3 +115,11 @@ data:
|
|||
ssl-ciphers: "ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA"
|
||||
ssl-protocols: "TLSv1 TLSv1.1 TLSv1.2"
|
||||
```
|
||||
|
||||
|
||||
|
||||
[full-kube-lego-example]:https://github.com/jetstack/kube-lego/tree/master/examples
|
||||
[Kube-Lego]:https://github.com/jetstack/kube-lego
|
||||
[Let's Encrypt]:https://letsencrypt.org
|
||||
[ConfigMap]: ./nginx-configuration/configmap.md
|
||||
[ssl-ciphers]: ./nginx-configuration/configmap.md#ssl-ciphers
|
||||
Loading…
Reference in a new issue