Merge remote-tracking branch 'base/master' into fix/collect-metrics-if-metrics-per-host-false
This commit is contained in:
Christian Hoffmeister
commit
19770f5b41
2674 changed files with 371760 additions and 171868 deletions
|
|
@ -1,11 +1,11 @@
|
|||
# Basic usage - host based routing
|
||||
|
||||
ingress-nginx can be used for many use cases, inside various cloud provider and supports a lot of configurations. In this section you can find a common usage scenario where a single load balancer powerd by ingress-nginx will route traffic to 2 different HTTP backend services based on the host name.
|
||||
ingress-nginx can be used for many use cases, inside various cloud provider and supports a lot of configurations. In this section you can find a common usage scenario where a single load balancer powered by ingress-nginx will route traffic to 2 different HTTP backend services based on the host name.
|
||||
|
||||
First of all follow the instructions to install ingress-nginx. Then imagine that you need to expose 2 HTTP services already installed: `myServiceA`, `myServiceB`. Let's say that you want to expose the first at `myServiceA.foo.org` and the second at `myServiceB.foo.org`. One possible solution is to create two **ingress** resources:
|
||||
|
||||
```
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: ingress-myServiceA
|
||||
|
|
@ -22,7 +22,7 @@ spec:
|
|||
serviceName: myServiceA
|
||||
servicePort: 80
|
||||
---
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: ingress-myServiceB
|
||||
|
|
|
|||
|
|
@ -15,7 +15,8 @@ They are set in the container spec of the `nginx-ingress-controller` Deployment
|
|||
| `--default-ssl-certificate string` | Secret containing a SSL certificate to be used by the default HTTPS server (catch-all). Takes the form "namespace/name". |
|
||||
| `--disable-catch-all` | Disable support for catch-all Ingresses. |
|
||||
| `--election-id string` | Election id to use for Ingress status updates. (default "ingress-controller-leader") |
|
||||
| `--enable-dynamic-certificates` | Dynamically serves certificates instead of reloading NGINX when certificates are created, updated, or deleted. Currently does not support OCSP stapling, so --enable-ssl-chain-completion must be turned off (default behaviour). Assuming the certificate is generated with a 2048 bit RSA key/cert pair, this feature can store roughly 5000 certificates. (enabled by default) |
|
||||
| `--enable-dynamic-certificates` | Dynamically serves certificates instead of reloading NGINX when certificates are created, updated, or deleted. Currently does not support OCSP stapling, so --enable-ssl-chain-completion must be turned off (default behaviour). Assuming the certificate is generated with a 2048 bit RSA key/cert pair, this feature can store roughly 5000 certificates. Once the backing Lua shared dictionary `certificate_data` is full, the least recently used certificate will be removed to store new ones. (enabled by default) |
|
||||
| `--enable-metrics` | Enable the collection of metrics for scraping by Prometheus (default true) |
|
||||
| `--enable-ssl-chain-completion` | Autocomplete SSL certificate chains with missing intermediate CA certificates. A valid certificate chain is required to enable OCSP stapling. Certificates uploaded to Kubernetes must have the "Authority Information Access" X.509 v3 extension for this to succeed. (default true) |
|
||||
| `--enable-ssl-passthrough` | Enable SSL Passthrough. |
|
||||
| `--health-check-path string` | URL path of the health check endpoint. Configured inside the NGINX status server. All requests received on the port defined by the healthz-port parameter are forwarded internally to this path. (default "/healthz") |
|
||||
|
|
@ -23,11 +24,14 @@ They are set in the container spec of the `nginx-ingress-controller` Deployment
|
|||
| `--healthz-port int` | Port to use for the healthz endpoint. (default 10254) |
|
||||
| `--http-port int` | Port to use for servicing HTTP traffic. (default 80) |
|
||||
| `--https-port int` | Port to use for servicing HTTPS traffic. (default 443) |
|
||||
| `--status-port int` | Port to use for the lua HTTP endpoint configuration. (default 10246) |
|
||||
| `--stream-port int` | Port to use for the lua TCP/UDP endpoint configuration. (default 10247) |
|
||||
| `--ingress-class string` | Name of the ingress class this controller satisfies. The class of an Ingress object is set using the annotation "kubernetes.io/ingress.class". All ingress classes are satisfied if this parameter is left empty. |
|
||||
| `--kubeconfig string` | Path to a kubeconfig file containing authorization and API server information. |
|
||||
| `--log_backtrace_at traceLocation` | when logging hits line file:N, emit a stack trace (default :0) |
|
||||
| `--log_dir string` | If non-empty, write log files in this directory |
|
||||
| `--logtostderr` | log to standard error instead of files (default true) |
|
||||
| `--metrics-per-host` | enable host labels for prometheus metrics. You may want to disable this to reduce the number of time-series created. (default true) |
|
||||
| `--profiling` | Enable profiling via web interface host:port/debug/pprof/ (default true) |
|
||||
| `--publish-service string` | Service fronting the Ingress controller. Takes the form "namespace/name". When used together with update-status, the controller mirrors the address of this service's endpoints to the load-balancer status of all Ingress objects it satisfies. |
|
||||
| `--publish-status-address string` | Customized address to set as the load-balancer status of Ingress objects this controller satisfies. Requires the update-status parameter. |
|
||||
|
|
@ -40,11 +44,11 @@ They are set in the container spec of the `nginx-ingress-controller` Deployment
|
|||
| `--udp-services-configmap string` | Name of the ConfigMap containing the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form "namespace/name:port", where "port" can either be a port name or number. |
|
||||
| `--update-status` | Update the load-balancer status of Ingress objects this controller satisfies. Requires setting the publish-service parameter to a valid Service reference. (default true) |
|
||||
| `--update-status-on-shutdown` | Update the load-balancer status of Ingress objects when the controller shuts down. Requires the update-status parameter. (default true) |
|
||||
| `--status-update-interval` | Time interval in seconds in which the status should check if an update is required. (default 60 seconds) |
|
||||
| `-v`, `--v Level` | log level for V logs |
|
||||
| `--version` | Show release information about the NGINX Ingress controller and exit. |
|
||||
| `--vmodule moduleSpec` | comma-separated list of pattern=N settings for file-filtered logging |
|
||||
| `--watch-namespace string` | Namespace the controller watches for updates to Kubernetes objects. This includes Ingresses, Services and all configuration resources. All namespaces are watched if this parameter is left empty. |
|
||||
| `--disable-catch-all` | Disable support for catch-all Ingresses. |
|
||||
|`--validating-webhook`|The address to start an admission controller on|
|
||||
|`--validating-webhook-certificate`|The certificate the webhook is using for its TLS handling|
|
||||
|`--validating-webhook-key`|The key the webhook is using for its TLS handling|
|
||||
|
|
|
|||
|
|
@ -28,4 +28,4 @@ See also the [Custom errors][example-custom-errors] example.
|
|||
|
||||
[cm-custom-http-errors]: ./nginx-configuration/configmap.md#custom-http-errors
|
||||
[img-custom-error-pages]: https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages
|
||||
[example-custom-errors]: ../examples/customization/custom-errors
|
||||
[example-custom-errors]: ../../examples/customization/custom-errors
|
||||
|
|
|
|||
|
|
@ -8,10 +8,6 @@ Basically a default backend exposes two URLs:
|
|||
- `/healthz` that returns 200
|
||||
- `/` that returns 404
|
||||
|
||||
!!! example
|
||||
The sub-directory [`/images/404-server`](https://github.com/kubernetes/ingress-nginx/tree/master/images/404-server)
|
||||
provides a service which satisfies the requirements for a default backend.
|
||||
|
||||
!!! example
|
||||
The sub-directory [`/images/custom-error-pages`](https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages)
|
||||
provides an additional service for the purpose of customizing the error pages served via the default backend.
|
||||
|
|
|
|||
115
docs/user-guide/fcgi-services.md
Normal file
115
docs/user-guide/fcgi-services.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
|
||||
|
||||
# Exposing FastCGI Servers
|
||||
|
||||
> **FastCGI** is a [binary protocol](https://en.wikipedia.org/wiki/Binary_protocol "Binary protocol") for interfacing interactive programs with a [web server](https://en.wikipedia.org/wiki/Web_server "Web server"). [...] (It's) aim is to reduce the overhead related to interfacing between web server and CGI programs, allowing a server to handle more web page requests per unit of time.
|
||||
>
|
||||
> — Wikipedia
|
||||
|
||||
The _ingress-nginx_ ingress controller can be used to directly expose [FastCGI](https://en.wikipedia.org/wiki/FastCGI) servers. Enabling FastCGI in your Ingress only requires setting the _backend-protocol_ annotation to `FCGI`, and with a couple more annotations you can customize the way _ingress-nginx_ handles the communication with your FastCGI _server_.
|
||||
|
||||
|
||||
## Example Objects to Expose a FastCGI Pod
|
||||
|
||||
The _Pod_ example object below exposes port `9000`, which is the conventional FastCGI port.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: example-app
|
||||
labels:
|
||||
app: example-app
|
||||
spec:
|
||||
containers:
|
||||
- name: example-app
|
||||
image: example-app:1.0
|
||||
ports:
|
||||
- containerPort: 9000
|
||||
name: fastcgi
|
||||
```
|
||||
|
||||
The _Service_ object example below matches port `9000` from the _Pod_ object above.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: example-service
|
||||
spec:
|
||||
selector:
|
||||
app: example-app
|
||||
ports:
|
||||
- port: 9000
|
||||
targetPort: 9000
|
||||
name: fastcgi
|
||||
```
|
||||
|
||||
And the _Ingress_ and _ConfigMap_ objects below demonstrates the supported _FastCGI_ specific annotations (NGINX actually has 50 FastCGI directives, all of which have not been exposed in the ingress yet), and matches the service `example-service`, and the port named `fastcgi` from above. The _ConfigMap_ **must** be created first for the _Ingress Controller_ to be able to find it when the _Ingress_ object is created, otherwise you will need to restart the _Ingress Controller_ pods.
|
||||
|
||||
```yaml
|
||||
# The ConfigMap MUST be created first for the ingress controller to be able to
|
||||
# find it when the Ingress object is created.
|
||||
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: example-cm
|
||||
data:
|
||||
SCRIPT_FILENAME: "/example/index.php"
|
||||
|
||||
---
|
||||
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
annotations:
|
||||
kubernetes.io/ingress.class: "nginx"
|
||||
nginx.ingress.kubernetes.io/backend-protocol: "FCGI"
|
||||
nginx.ingress.kubernetes.io/fastcgi-index: "index.php"
|
||||
nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-cm"
|
||||
name: example-app
|
||||
spec:
|
||||
rules:
|
||||
- host: app.example.com
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: example-service
|
||||
servicePort: fastcgi
|
||||
```
|
||||
|
||||
## FastCGI Ingress Annotations
|
||||
|
||||
To enable FastCGI, the `nginx.ingress.kubernetes.io/backend-protocol` annotation needs to be set to `FCGI`, which overrides the default `HTTP` value.
|
||||
|
||||
> `nginx.ingress.kubernetes.io/backend-protocol: "FCGI"`
|
||||
|
||||
**This enables the _FastCGI_ mode for all paths defined in the _Ingress_ object**
|
||||
|
||||
### The `nginx.ingress.kubernetes.io/fastcgi-index` Annotation
|
||||
|
||||
To specify an index file, the `fastcgi-index` annotation value can optionally be set. In the example below, the value is set to `index.php`. This annotation corresponds to [the _NGINX_ `fastcgi_index` directive](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_index).
|
||||
|
||||
> `nginx.ingress.kubernetes.io/fastcgi-index: "index.php"`
|
||||
|
||||
### The `nginx.ingress.kubernetes.io/fastcgi-params-configmap` Annotation
|
||||
|
||||
To specify [_NGINX_ `fastcgi_param` directives](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param), the `fastcgi-params-configmap` annotation is used, which in turn must lead to a _ConfigMap_ object containing the _NGINX_ `fastcgi_param` directives as key/values.
|
||||
|
||||
> `nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-configmap"`
|
||||
|
||||
And the _ConfigMap_ object to specify the `SCRIPT_FILENAME` and `HTTP_PROXY` _NGINX's_ `fastcgi_param` directives will look like the following:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: example-configmap
|
||||
data:
|
||||
SCRIPT_FILENAME: "/example/index.php"
|
||||
HTTP_PROXY: ""
|
||||
```
|
||||
Using the _namespace/_ prefix is also supported, for example:
|
||||
|
||||
> `nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-namespace/example-configmap"`
|
||||
|
|
@ -2,15 +2,20 @@
|
|||
|
||||
## Regular Expression Support
|
||||
|
||||
!!! important
|
||||
Regular expressions and wild cards are not supported in the `spec.rules.host` field. Full hostnames must be used.
|
||||
!!! important
|
||||
Regular expressions and wild cards are not supported in the `spec.rules.host` field. Full hostnames must be used.
|
||||
|
||||
The ingress controller supports **case insensitive** regular expressions in the `spec.rules.http.paths.path` field.
|
||||
This can be enabled by setting the `nginx.ingress.kubernetes.io/use-regex` annotation to `true` (the default is false).
|
||||
|
||||
!!! hint
|
||||
Kubernetes only accept expressions that comply with the RE2 engine syntax. It is possible that valid expressions accepted by NGINX cannot be used with ingress-nginx, because the PCRE library (used in NGINX) supports a wider syntax than RE2.
|
||||
See the [RE2 Syntax](https://github.com/google/re2/wiki/Syntax) documentation for differences.
|
||||
|
||||
See the [description](./nginx-configuration/annotations.md#use-regex) of the `use-regex` annotation for more details.
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: test-ingress
|
||||
|
|
@ -46,7 +51,7 @@ In NGINX, regular expressions follow a **first match** policy. In order to enabl
|
|||
Let the following two ingress definitions be created:
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: test-ingress-1
|
||||
|
|
@ -66,7 +71,7 @@ spec:
|
|||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: test-ingress-2
|
||||
|
|
@ -120,7 +125,7 @@ This case is expected and a result of NGINX's a first match policy for paths tha
|
|||
Let the following ingress be defined:
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: test-ingress-3
|
||||
|
|
@ -153,4 +158,4 @@ location ~* "^/foo/bar/bar" {
|
|||
}
|
||||
```
|
||||
|
||||
A request to `test.com/foo/bar/bar` would match the `^/foo/[A-Z0-9]{3}` location block instead of the longest EXACT matching path.
|
||||
A request to `test.com/foo/bar/bar` would match the `^/foo/bar/[A-Z0-9]{3}` location block instead of the longest EXACT matching path.
|
||||
|
|
|
|||
|
|
@ -21,12 +21,6 @@ Running the following command deploys prometheus in Kubernetes:
|
|||
|
||||
```console
|
||||
kubectl apply --kustomize github.com/kubernetes/ingress-nginx/deploy/prometheus/
|
||||
serviceaccount/prometheus-server created
|
||||
role.rbac.authorization.k8s.io/prometheus-server created
|
||||
rolebinding.rbac.authorization.k8s.io/prometheus-server created
|
||||
configmap/prometheus-configuration-bc6bcg7b65 created
|
||||
service/prometheus-server created
|
||||
deployment.apps/prometheus-server created
|
||||
```
|
||||
|
||||
### Prometheus Dashboard
|
||||
|
|
|
|||
|
|
@ -17,8 +17,10 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|
|||
|---------------------------|------|
|
||||
|[nginx.ingress.kubernetes.io/app-root](#rewrite)|string|
|
||||
|[nginx.ingress.kubernetes.io/affinity](#session-affinity)|cookie|
|
||||
|[nginx.ingress.kubernetes.io/affinity-mode](#session-affinity)|"balanced" or "persistent"|
|
||||
|[nginx.ingress.kubernetes.io/auth-realm](#authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-secret](#authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-secret-type](#authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-type](#authentication)|basic or digest|
|
||||
|[nginx.ingress.kubernetes.io/auth-tls-secret](#client-certificate-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-tls-verify-depth](#client-certificate-authentication)|number|
|
||||
|
|
@ -26,12 +28,16 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|
|||
|[nginx.ingress.kubernetes.io/auth-tls-error-page](#client-certificate-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream](#client-certificate-authentication)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/auth-url](#external-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-cache-key](#external-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-cache-duration](#external-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-proxy-set-headers](#external-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/auth-snippet](#external-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/enable-global-auth](#external-authentication)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/backend-protocol](#backend-protocol)|string|HTTP,HTTPS,GRPC,GRPCS,AJP|
|
||||
|[nginx.ingress.kubernetes.io/canary](#canary)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/canary-by-header](#canary)|string|
|
||||
|[nginx.ingress.kubernetes.io/canary-by-header-value](#canary)|string
|
||||
|[nginx.ingress.kubernetes.io/canary-by-header-value](#canary)|string|
|
||||
|[nginx.ingress.kubernetes.io/canary-by-header-pattern](#canary)|string|
|
||||
|[nginx.ingress.kubernetes.io/canary-by-cookie](#canary)|string|
|
||||
|[nginx.ingress.kubernetes.io/canary-weight](#canary)|number|
|
||||
|[nginx.ingress.kubernetes.io/client-body-buffer-size](#client-body-buffer-size)|string|
|
||||
|
|
@ -64,15 +70,24 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|
|||
|[nginx.ingress.kubernetes.io/proxy-request-buffering](#custom-timeouts)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-redirect-from](#proxy-redirect)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-redirect-to](#proxy-redirect)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-http-version](#proxy-http-version)|"1.0" or "1.1"|
|
||||
|[nginx.ingress.kubernetes.io/proxy-ssl-secret](#backend-certificate-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-ssl-ciphers](#backend-certificate-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-ssl-name](#backend-certificate-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-ssl-protocols](#backend-certificate-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-ssl-verify](#backend-certificate-authentication)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-ssl-verify-depth](#backend-certificate-authentication)|number|
|
||||
|[nginx.ingress.kubernetes.io/enable-rewrite-log](#enable-rewrite-log)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/rewrite-target](#rewrite)|URI|
|
||||
|[nginx.ingress.kubernetes.io/satisfy](#satisfy)|string|
|
||||
|[nginx.ingress.kubernetes.io/secure-verify-ca-secret](#secure-backends)|string|
|
||||
|[nginx.ingress.kubernetes.io/server-alias](#server-alias)|string|
|
||||
|[nginx.ingress.kubernetes.io/server-snippet](#server-snippet)|string|
|
||||
|[nginx.ingress.kubernetes.io/service-upstream](#service-upstream)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/session-cookie-name](#cookie-affinity)|string|
|
||||
|[nginx.ingress.kubernetes.io/session-cookie-path](#cookie-affinity)|string|
|
||||
|[nginx.ingress.kubernetes.io/session-cookie-change-on-failure](#cookie-affinity)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/session-cookie-samesite](#cookie-affinity)|string|
|
||||
|[nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none](#cookie-affinity)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/ssl-redirect](#server-side-https-enforcement-through-redirect)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/ssl-passthrough](#ssl-passthrough)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/upstream-hash-by](#custom-nginx-upstream-hashing)|string|
|
||||
|
|
@ -83,9 +98,11 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|
|||
|[nginx.ingress.kubernetes.io/proxy-buffering](#proxy-buffering)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-buffers-number](#proxy-buffers-number)|number|
|
||||
|[nginx.ingress.kubernetes.io/proxy-buffer-size](#proxy-buffer-size)|string|
|
||||
|[nginx.ingress.kubernetes.io/proxy-max-temp-file-size](#proxy-max-temp-file-size)|string|
|
||||
|[nginx.ingress.kubernetes.io/ssl-ciphers](#ssl-ciphers)|string|
|
||||
|[nginx.ingress.kubernetes.io/connection-proxy-header](#connection-proxy-header)|string|
|
||||
|[nginx.ingress.kubernetes.io/enable-access-log](#enable-access-log)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/enable-opentracing](#enable-opentracing)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/lua-resty-waf](#lua-resty-waf)|string|
|
||||
|[nginx.ingress.kubernetes.io/lua-resty-waf-debug](#lua-resty-waf)|"true" or "false"|
|
||||
|[nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets](#lua-resty-waf)|string|
|
||||
|
|
@ -103,6 +120,8 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|
|||
|[nginx.ingress.kubernetes.io/enable-owasp-core-rules](#modsecurity)|bool|
|
||||
|[nginx.ingress.kubernetes.io/modsecurity-transaction-id](#modsecurity)|string|
|
||||
|[nginx.ingress.kubernetes.io/modsecurity-snippet](#modsecurity)|string|
|
||||
|[nginx.ingress.kubernetes.io/mirror-request-body](#mirror)|string|
|
||||
|[nginx.ingress.kubernetes.io/mirror-target](#mirror)|string|
|
||||
|
||||
### Canary
|
||||
|
||||
|
|
@ -112,18 +131,20 @@ In some cases, you may want to "canary" a new set of changes by sending a small
|
|||
|
||||
* `nginx.ingress.kubernetes.io/canary-by-header-value`: The header value to match for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the request header is set to this value, it will be routed to the canary. For any other header value, the header will be ignored and the request compared against the other canary rules by precedence. This annotation has to be used together with . The annotation is an extension of the `nginx.ingress.kubernetes.io/canary-by-header` to allow customizing the header value instead of using hardcoded values. It doesn't have any effect if the `nginx.ingress.kubernetes.io/canary-by-header` annotation is not defined.
|
||||
|
||||
* `nginx.ingress.kubernetes.io/canary-by-cookie`: The cookie to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the cookie value is set to `always`, it will be routed to the canary. When the cookie is set to `never`, it will never be routed to the canary. For any other value, the cookie will be ingored and the request compared against the other canary rules by precedence.
|
||||
* `nginx.ingress.kubernetes.io/canary-by-header-pattern`: This works the same way as `canary-by-header-value` except it does PCRE Regex matching. Note that when `canary-by-header-value` is set this annotation will be ignored. When the given Regex causes error during request processing, the request will be considered as not matching.
|
||||
|
||||
* `nginx.ingress.kubernetes.io/canary-weight`: The integer based (0 - 100) percent of random requests that should be routed to the service specified in the canary Ingress. A weight of 0 implies that no requests will be sent to the service in the Canary ingress by this canary rule. A weight of 100 means implies all requests will be sent to the alternative service specified in the Ingress.
|
||||
* `nginx.ingress.kubernetes.io/canary-by-cookie`: The cookie to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the cookie value is set to `always`, it will be routed to the canary. When the cookie is set to `never`, it will never be routed to the canary. For any other value, the cookie will be ignored and the request compared against the other canary rules by precedence.
|
||||
|
||||
Canary rules are evaluated in order of precedence. Precedence is as follows:
|
||||
`canary-by-header -> canary-by-cookie -> canary-weight`
|
||||
* `nginx.ingress.kubernetes.io/canary-weight`: The integer based (0 - 100) percent of random requests that should be routed to the service specified in the canary Ingress. A weight of 0 implies that no requests will be sent to the service in the Canary ingress by this canary rule. A weight of 100 means implies all requests will be sent to the alternative service specified in the Ingress.
|
||||
|
||||
Canary rules are evaluated in order of precedence. Precedence is as follows:
|
||||
`canary-by-header -> canary-by-cookie -> canary-weight`
|
||||
|
||||
**Note** that when you mark an ingress as canary, then all the other non-canary annotations will be ignored (inherited from the corresponding main ingress) except `nginx.ingress.kubernetes.io/load-balance` and `nginx.ingress.kubernetes.io/upstream-hash-by`.
|
||||
|
||||
**Known Limitations**
|
||||
|
||||
Currently a maximum of one canary ingress can be applied per Ingress rule.
|
||||
Currently a maximum of one canary ingress can be applied per Ingress rule.
|
||||
|
||||
### Rewrite
|
||||
|
||||
|
|
@ -140,8 +161,10 @@ If the Application Root is exposed in a different path and needs to be redirecte
|
|||
The annotation `nginx.ingress.kubernetes.io/affinity` enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.
|
||||
The only affinity type available for NGINX is `cookie`.
|
||||
|
||||
The annotation `nginx.ingress.kubernetes.io/affinity-mode` defines the stickyness of a session. Setting this to `balanced` (default) will redistribute some sessions if a deployment gets scaled up, therefore rebalancing the load on the servers. Setting this to `persistent` will not rebalance sessions to new servers, therefore providing maximum stickyness.
|
||||
|
||||
!!! attention
|
||||
If more than one Ingress is defined for a host and at least one Ingress uses `nginx.ingress.kubernetes.io/affinity: cookie`, then only paths on the Ingress using `nginx.ingress.kubernetes.io/affinity` will use session cookie affinity. All paths defined on other Ingresses for the host will be load balanced through the random selection of a backend server.
|
||||
If more than one Ingress is defined for a host and at least one Ingress uses `nginx.ingress.kubernetes.io/affinity: cookie`, then only paths on the Ingress using `nginx.ingress.kubernetes.io/affinity` will use session cookie affinity. All paths defined on other Ingresses for the host will be load balanced through the random selection of a backend server.
|
||||
|
||||
!!! example
|
||||
Please check the [affinity](../../examples/affinity/cookie/README.md) example.
|
||||
|
|
@ -150,12 +173,13 @@ The only affinity type available for NGINX is `cookie`.
|
|||
|
||||
If you use the ``cookie`` affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation `nginx.ingress.kubernetes.io/session-cookie-name`. The default is to create a cookie named 'INGRESSCOOKIE'.
|
||||
|
||||
The NGINX annotation `nginx.ingress.kubernetes.io/session-cookie-path` defines the path that will be set on the cookie. This is optional unless the annotation `nginx.ingress.kubernetes.io/use-regex` is set to true; Session cookie paths do not support regex.
|
||||
The NGINX annotation `nginx.ingress.kubernetes.io/session-cookie-path` defines the path that will be set on the cookie. This is optional unless the annotation `nginx.ingress.kubernetes.io/use-regex` is set to true; Session cookie paths do not support regex.
|
||||
|
||||
Use `nginx.ingress.kubernetes.io/session-cookie-samesite` to apply a `SameSite` attribute to the sticky cookie. Browser accepted values are `None`, `Lax`, and `Strict`. Some browsers reject cookies with `SameSite=None`, including those created before the `SameSite=None` specification (e.g. Chrome 5X). Other browsers mistakenly treat `SameSite=None` cookies as `SameSite=Strict` (e.g. Safari running on OSX 14). To omit `SameSite=None` from browsers with these incompatibilities, add the annotation `nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true"`.
|
||||
|
||||
### Authentication
|
||||
|
||||
Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key `auth`.
|
||||
Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords.
|
||||
|
||||
The annotations are:
|
||||
```
|
||||
|
|
@ -171,6 +195,15 @@ nginx.ingress.kubernetes.io/auth-secret: secretName
|
|||
The name of the Secret that contains the usernames and passwords which are granted access to the `path`s defined in the Ingress rules.
|
||||
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.
|
||||
|
||||
```
|
||||
nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]
|
||||
```
|
||||
|
||||
The `auth-secret` can have two forms:
|
||||
|
||||
- `auth-file` - default, an htpasswd file in the key `auth` within the secret
|
||||
- `auth-map` - the keys of the secret are the usernames, and the values are the hashed passwords
|
||||
|
||||
```
|
||||
nginx.ingress.kubernetes.io/auth-realm: "realm string"
|
||||
```
|
||||
|
|
@ -229,6 +262,23 @@ The annotations are:
|
|||
|
||||
Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: [https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls](https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls)
|
||||
|
||||
### Backend Certificate Authentication
|
||||
|
||||
It is possible to authenticate to a proxied HTTPS backend with certificate using additional annotations in Ingress Rule.
|
||||
|
||||
* `nginx.ingress.kubernetes.io/proxy-ssl-secret: secretName`:
|
||||
Specifies a Secret with the certificate `tls.crt`, key `tls.key` in PEM format used for authentication to a proxied HTTPS server. It should also contain trusted CA certificates `ca.crt` in PEM format used to verify the certificate of the proxied HTTPS server.
|
||||
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.
|
||||
* `nginx.ingress.kubernetes.io/proxy-ssl-verify`:
|
||||
Enables or disables verification of the proxied HTTPS server certificate. (default: off)
|
||||
* `nginx.ingress.kubernetes.io/proxy-ssl-verify-depth`:
|
||||
Sets the verification depth in the proxied HTTPS server certificates chain. (default: 1)
|
||||
* `nginx.ingress.kubernetes.io/proxy-ssl-ciphers`:
|
||||
Specifies the enabled [ciphers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_ciphers) for requests to a proxied HTTPS server. The ciphers are specified in the format understood by the OpenSSL library.
|
||||
* `nginx.ingress.kubernetes.io/proxy-ssl-name`:
|
||||
Allows to set [proxy_ssl_name](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_name). This allows overriding the server name used to verify the certificate of the proxied HTTPS server. This value is also passed through SNI when a connection is established to the proxied HTTPS server.
|
||||
* `nginx.ingress.kubernetes.io/proxy-ssl-protocols`:
|
||||
Enables the specified [protocols](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_protocols) for requests to a proxied HTTPS server.
|
||||
|
||||
### Configuration snippet
|
||||
|
||||
|
|
@ -293,7 +343,7 @@ CORS can be controlled with the following annotations:
|
|||
Example: `nginx.ingress.kubernetes.io/cors-max-age: 600`
|
||||
|
||||
!!! note
|
||||
For more information please see [https://enable-cors.org](https://enable-cors.org/server_nginx.html)
|
||||
For more information please see [https://enable-cors.org](https://enable-cors.org/server_nginx.html)
|
||||
|
||||
### HTTP2 Push Preload.
|
||||
|
||||
|
|
@ -305,13 +355,13 @@ Enables automatic conversion of preload links specified in the “Link” respon
|
|||
|
||||
### Server Alias
|
||||
|
||||
To add Server Aliases to an Ingress rule add the annotation `nginx.ingress.kubernetes.io/server-alias: "<alias>"`.
|
||||
This will create a server with the same configuration, but a different `server_name` as the provided host.
|
||||
Allows the definition of one or more aliases in the server definition of the NGINX configuration using the annotation `nginx.ingress.kubernetes.io/server-alias: "<alias 1>,<alias 2>"`.
|
||||
This will create a server with the same configuration, but adding new values to the `server_name` directive.
|
||||
|
||||
!!! Note
|
||||
A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored.
|
||||
If a server-alias is created and later a new server with the same hostname is created,
|
||||
the new server configuration will take place over the alias configuration.
|
||||
!!! note
|
||||
A server-alias name cannot conflict with the hostname of an existing server. If it does, the server-alias annotation will be ignored.
|
||||
If a server-alias is created and later a new server with the same hostname is created, the new server configuration will take
|
||||
place over the alias configuration.
|
||||
|
||||
For more information please see [the `server_name` documentation](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name).
|
||||
|
||||
|
|
@ -320,17 +370,17 @@ For more information please see [the `server_name` documentation](http://nginx.o
|
|||
Using the annotation `nginx.ingress.kubernetes.io/server-snippet` it is possible to add custom configuration in the server configuration block.
|
||||
|
||||
```yaml
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/server-snippet: |
|
||||
set $agentflag 0;
|
||||
|
||||
|
||||
if ($http_user_agent ~* "(Mobile)" ){
|
||||
set $agentflag 1;
|
||||
}
|
||||
|
||||
|
||||
if ( $agentflag = 1 ) {
|
||||
return 301 https://m.example.com;
|
||||
}
|
||||
|
|
@ -375,8 +425,14 @@ Additionally it is possible to set:
|
|||
`<SignIn_URL>` to specify the location of the error page.
|
||||
* `nginx.ingress.kubernetes.io/auth-response-headers`:
|
||||
`<Response_Header_1, ..., Response_Header_n>` to specify headers to pass to backend once authentication request completes.
|
||||
* `nginx.ingress.kubernetes.io/auth-proxy-set-headers`:
|
||||
`<ConfigMap>` the name of a ConfigMap that specifies headers to pass to the authentication service
|
||||
* `nginx.ingress.kubernetes.io/auth-request-redirect`:
|
||||
`<Request_Redirect_URL>` to specify the X-Auth-Request-Redirect header value.
|
||||
* `nginx.ingress.kubernetes.io/auth-cache-key`:
|
||||
`<Cache_Key>` this enables caching for auth requests. specify a lookup key for auth responses. e.g. `$remote_user$http_authorization`. Each server and location has it's own keyspace. Hence a cached response is only valid on a per-server and per-location basis.
|
||||
* `nginx.ingress.kubernetes.io/auth-cache-duration`:
|
||||
`<Cache_duration>` to specify a caching time for auth responses based on their response codes, e.g. `200 202 30m`. See [proxy_cache_valid](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid) for details. You may specify multiple, comma-separated values: `200 202 10m, 401 5m`. defaults to `200 202 401 5m`.
|
||||
* `nginx.ingress.kubernetes.io/auth-snippet`:
|
||||
`<Auth_Snippet>` to specify a custom snippet to use with external authentication, e.g.
|
||||
|
||||
|
|
@ -396,26 +452,25 @@ By default the controller redirects all requests to an existing service that pro
|
|||
`nginx.ingress.kubernetes.io/enable-global-auth`:
|
||||
indicates if GlobalExternalAuth configuration should be applied or not to this Ingress rule. Default values is set to `"true"`.
|
||||
|
||||
!!! note For more information please see [global-auth-url](./configmap.md#global-auth-url).
|
||||
!!! note
|
||||
For more information please see [global-auth-url](./configmap.md#global-auth-url).
|
||||
|
||||
### Rate limiting
|
||||
|
||||
These annotations define a limit on the connections that can be opened by a single client IP address.
|
||||
This can be used to mitigate [DDoS Attacks](https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus).
|
||||
These annotations define limits on connections and transmission rates. These can be used to mitigate [DDoS Attacks](https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus).
|
||||
|
||||
* `nginx.ingress.kubernetes.io/limit-connections`: number of concurrent connections allowed from a single IP address.
|
||||
* `nginx.ingress.kubernetes.io/limit-rps`: number of connections that may be accepted from a given IP each second.
|
||||
* `nginx.ingress.kubernetes.io/limit-rpm`: number of connections that may be accepted from a given IP each minute.
|
||||
* `nginx.ingress.kubernetes.io/limit-rate-after`: sets the initial amount after which the further transmission of a response to a client will be rate limited.
|
||||
* `nginx.ingress.kubernetes.io/limit-rate`: rate of request that accepted from a client each second.
|
||||
* `nginx.ingress.kubernetes.io/limit-connections`: number of concurrent connections allowed from a single IP address. A 503 error is returned when exceeding this limit.
|
||||
* `nginx.ingress.kubernetes.io/limit-rps`: number of requests accepted from a given IP each second. The burst limit is set to 5 times the limit. When clients exceed this limit, [limit-req-status-code](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code) ***default:*** 503 is returned.
|
||||
* `nginx.ingress.kubernetes.io/limit-rpm`: number of requests accepted from a given IP each minute. The burst limit is set to 5 times the limit. When clients exceed this limit, [limit-req-status-code](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code) ***default:*** 503 is returned.
|
||||
* `nginx.ingress.kubernetes.io/limit-rate-after`: initial number of kilobytes after which the further transmission of a response to a given connection will be rate limited. This feature must be used with [proxy-buffering](#proxy-buffering) enabled.
|
||||
* `nginx.ingress.kubernetes.io/limit-rate`: number of kilobytes per second allowed to send to a given connection. The zero value disables rate limiting. This feature must be used with [proxy-buffering](#proxy-buffering) enabled.
|
||||
* `nginx.ingress.kubernetes.io/limit-whitelist`: client IP source ranges to be excluded from rate-limiting. The value is a comma separated list of CIDRs.
|
||||
|
||||
You can specify the client IP source ranges to be excluded from rate-limiting through the `nginx.ingress.kubernetes.io/limit-whitelist` annotation. The value is a comma separated list of CIDRs.
|
||||
If you specify multiple annotations in a single Ingress rule, limits are applied in the order `limit-connections`, `limit-rpm`, `limit-rps`.
|
||||
|
||||
If you specify multiple annotations in a single Ingress rule, `limit-rpm`, and then `limit-rps` takes precedence.
|
||||
To configure settings globally for all Ingress rules, the `limit-rate-after` and `limit-rate` values may be set in the [NGINX ConfigMap](./configmap.md#limit-rate). The value set in an Ingress annotation will override the global setting.
|
||||
|
||||
The annotation `nginx.ingress.kubernetes.io/limit-rate`, `nginx.ingress.kubernetes.io/limit-rate-after` define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.
|
||||
|
||||
To configure this setting globally for all Ingress rules, the `limit-rate-after` and `limit-rate` value may be set in the [NGINX ConfigMap](./configmap.md#limit-rate). if you set the value in ingress annotation will cover global setting.
|
||||
The client IP address will be set based on the use of [PROXY protocol](./configmap.md#use-proxy-protocol) or from the `X-Forwarded-For` header value when [use-forwarded-headers](./configmap.md#use-forwarded-headers) is enabled.
|
||||
|
||||
### Permanent Redirect
|
||||
|
||||
|
|
@ -550,7 +605,7 @@ nginx.ingress.kubernetes.io/proxy-buffering: "on"
|
|||
|
||||
### Proxy buffers Number
|
||||
|
||||
Sets the number of the buffers in [`proxy_buffers`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) used for reading the first part of the response received from the proxied server.
|
||||
Sets the number of the buffers in [`proxy_buffers`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) used for reading the first part of the response received from the proxied server.
|
||||
By default proxy buffers number is set as 4
|
||||
|
||||
To configure this setting globally, set `proxy-buffers-number` in [NGINX ConfigMap](./configmap.md#proxy-buffers-number). To use custom values in an Ingress rule, define this annotation:
|
||||
|
|
@ -568,6 +623,26 @@ To configure this setting globally, set `proxy-buffer-size` in [NGINX ConfigMap]
|
|||
nginx.ingress.kubernetes.io/proxy-buffer-size: "8k"
|
||||
```
|
||||
|
||||
### Proxy max temp file size
|
||||
|
||||
When [`buffering`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) of responses from the proxied server is enabled, and the whole response does not fit into the buffers set by the [`proxy_buffer_size`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [`proxy_buffers`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directives, a part of the response can be saved to a temporary file. This directive sets the maximum `size` of the temporary file setting the [`proxy_max_temp_file_size`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size). The size of data written to the temporary file at a time is set by the [`proxy_temp_file_write_size`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_temp_file_write_size) directive.
|
||||
|
||||
The zero value disables buffering of responses to temporary files.
|
||||
|
||||
To use custom values in an Ingress rule, define this annotation:
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/proxy-max-temp-file-size: "1024m"
|
||||
```
|
||||
|
||||
### Proxy HTTP version
|
||||
|
||||
Using this annotation sets the [`proxy_http_version`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) that the Nginx reverse proxy will use to communicate with the backend.
|
||||
By default this is set to "1.1".
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/proxy-http-version: "1.0"
|
||||
```
|
||||
|
||||
### SSL ciphers
|
||||
|
||||
Specifies the [enabled ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers).
|
||||
|
|
@ -605,6 +680,15 @@ Note that rewrite logs are sent to the error_log file at the notice level. To en
|
|||
nginx.ingress.kubernetes.io/enable-rewrite-log: "true"
|
||||
```
|
||||
|
||||
### Enable Opentracing
|
||||
|
||||
Opentracing can be enabled or disabled globally through the ConfigMap but this will sometimes need to be overridden
|
||||
to enable it or disable it for a specific ingress (e.g. to turn off tracing of external health check endpoints)
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/enable-opentracing: "true"
|
||||
```
|
||||
|
||||
### X-Forwarded-Prefix Header
|
||||
To add the non-standard `X-Forwarded-Prefix` header to the upstream request with a string value, the following annotation can be used:
|
||||
|
||||
|
|
@ -680,7 +764,7 @@ of ingress locations. The ModSecurity module must first be enabled by enabling M
|
|||
[ConfigMap](./configmap.md#enable-modsecurity). Note this will enable ModSecurity for all paths, and each path
|
||||
must be disabled manually.
|
||||
|
||||
It can be enabled using the following annotation:
|
||||
It can be enabled using the following annotation:
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/enable-modsecurity: "true"
|
||||
```
|
||||
|
|
@ -705,14 +789,21 @@ SecDebugLog /tmp/modsec_debug.log
|
|||
```
|
||||
|
||||
Note: If you use both `enable-owasp-core-rules` and `modsecurity-snippet` annotations together, only the
|
||||
`modsecurity-snippet` will take effect. If you wish to include the [OWASP Core Rule Set](https://www.modsecurity.org/CRS/Documentation/) or
|
||||
`modsecurity-snippet` will take effect. If you wish to include the [OWASP Core Rule Set](https://www.modsecurity.org/CRS/Documentation/) or
|
||||
[recommended configuration](https://github.com/SpiderLabs/ModSecurity/blob/v3/master/modsecurity.conf-recommended) simply use the include
|
||||
statement:
|
||||
|
||||
nginx 0.24.1 and below
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/modsecurity-snippet: |
|
||||
Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf
|
||||
Include /etc/nginx/modsecurity/modsecurity.conf
|
||||
```
|
||||
nginx 0.25.0 and above
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/modsecurity-snippet: |
|
||||
Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf
|
||||
```
|
||||
|
||||
### InfluxDB
|
||||
|
||||
|
|
@ -729,7 +820,7 @@ nginx.ingress.kubernetes.io/influxdb-server-name: "nginx-ingress"
|
|||
|
||||
For the `influxdb-host` parameter you have two options:
|
||||
|
||||
- Use an InfluxDB server configured with the [UDP protocol](https://docs.influxdata.com/influxdb/v1.5/supported_protocols/udp/) enabled.
|
||||
- Use an InfluxDB server configured with the [UDP protocol](https://docs.influxdata.com/influxdb/v1.5/supported_protocols/udp/) enabled.
|
||||
- Deploy Telegraf as a sidecar proxy to the Ingress controller configured to listen UDP with the [socket listener input](https://github.com/influxdata/telegraf/tree/release-1.6/plugins/inputs/socket_listener) and to write using
|
||||
anyone of the [outputs plugins](https://github.com/influxdata/telegraf/tree/release-1.7/plugins/outputs) like InfluxDB, Apache Kafka,
|
||||
Prometheus, etc.. (recommended)
|
||||
|
|
@ -753,7 +844,7 @@ nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
|
|||
### Use Regex
|
||||
|
||||
!!! attention
|
||||
When using this annotation with the NGINX annotation `nginx.ingress.kubernetes.io/affinity` of type `cookie`, `nginx.ingress.kubernetes.io/session-cookie-path` must be also set; Session cookie paths do not support regex.
|
||||
When using this annotation with the NGINX annotation `nginx.ingress.kubernetes.io/affinity` of type `cookie`, `nginx.ingress.kubernetes.io/session-cookie-path` must be also set; Session cookie paths do not support regex.
|
||||
|
||||
Using the `nginx.ingress.kubernetes.io/use-regex` annotation will indicate whether or not the paths defined on an Ingress use regular expressions. The default value is `false`.
|
||||
|
||||
|
|
@ -769,9 +860,9 @@ nginx.ingress.kubernetes.io/use-regex: "false"
|
|||
|
||||
When this annotation is set to `true`, the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
|
||||
|
||||
Additionally, if the [`rewrite-target` annotation](#rewrite) is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
|
||||
Additionally, if the [`rewrite-target` annotation](#rewrite) is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
|
||||
|
||||
Please read about [ingress path matching](../ingress-path-matching.md) before using this modifier.
|
||||
Please read about [ingress path matching](../ingress-path-matching.md) before using this modifier.
|
||||
|
||||
### Satisfy
|
||||
|
||||
|
|
@ -780,3 +871,25 @@ By default, a request would need to satisfy all authentication requirements in o
|
|||
```yaml
|
||||
nginx.ingress.kubernetes.io/satisfy: "any"
|
||||
```
|
||||
|
||||
### Mirror
|
||||
|
||||
Enables a request to be mirrored to a mirror backend. Responses by mirror backends are ignored. This feature is useful, to see how requests will react in "test" backends.
|
||||
|
||||
The mirror backend can be set by applying:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/mirror-target: https://test.env.com/$request_uri
|
||||
```
|
||||
|
||||
By default the request-body is sent to the mirror backend, but can be turned off by applying:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/mirror-request-body: "off"
|
||||
```
|
||||
|
||||
**Note:** The mirror directive will be applied to all paths within the ingress resource.
|
||||
|
||||
The request sent to the mirror is linked to the original request. If you have a slow mirror backend, then the original request will throttle.
|
||||
|
||||
For more information on the mirror module see [ngx_http_mirror_module](https://nginx.org/en/docs/http/ngx_http_mirror_module.html)
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ data:
|
|||
ssl-protocols: SSLv2
|
||||
```
|
||||
|
||||
!!! Important
|
||||
!!! important
|
||||
The key and values in a ConfigMap can only be strings.
|
||||
This means that we want a value with boolean values we need to quote the values, like "true" or "false".
|
||||
Same for numbers, like "100".
|
||||
|
|
@ -34,8 +34,8 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[access-log-path](#access-log-path)|string|"/var/log/nginx/access.log"|
|
||||
|[enable-access-log-for-default-backend](#enable-access-log-for-default-backend)|bool|"false"|
|
||||
|[error-log-path](#error-log-path)|string|"/var/log/nginx/error.log"|
|
||||
|[enable-dynamic-tls-records](#enable-dynamic-tls-records)|bool|"true"|
|
||||
|[enable-modsecurity](#enable-modsecurity)|bool|"false"|
|
||||
|[modsecurity-snippet](#modsecurity-snippet)|string|""|
|
||||
|[enable-owasp-modsecurity-crs](#enable-owasp-modsecurity-crs)|bool|"false"|
|
||||
|[client-header-buffer-size](#client-header-buffer-size)|string|"1k"|
|
||||
|[client-header-timeout](#client-header-timeout)|int|60|
|
||||
|
|
@ -51,6 +51,7 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[http2-max-field-size](#http2-max-field-size)|string|"4k"|
|
||||
|[http2-max-header-size](#http2-max-header-size)|string|"16k"|
|
||||
|[http2-max-requests](#http2-max-requests)|int|1000|
|
||||
|[http2-max-concurrent-streams](#http2-max-concurrent-streams)|int|1000|
|
||||
|[hsts](#hsts)|bool|"true"|
|
||||
|[hsts-include-subdomains](#hsts-include-subdomains)|bool|"true"|
|
||||
|[hsts-max-age](#hsts-max-age)|string|"15724800"|
|
||||
|
|
@ -59,8 +60,8 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[keep-alive-requests](#keep-alive-requests)|int|100|
|
||||
|[large-client-header-buffers](#large-client-header-buffers)|string|"4 8k"|
|
||||
|[log-format-escape-json](#log-format-escape-json)|bool|"false"|
|
||||
|[log-format-upstream](#log-format-upstream)|string|`%v - [$the_real_ip] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id`|
|
||||
|[log-format-stream](#log-format-stream)|string|`[$time_local] $protocol $status $bytes_sent $bytes_received $session_time`|
|
||||
|[log-format-upstream](#log-format-upstream)|string|`$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id`|
|
||||
|[log-format-stream](#log-format-stream)|string|`[$remote_addr] [$time_local] $protocol $status $bytes_sent $bytes_received $session_time`|
|
||||
|[enable-multi-accept](#enable-multi-accept)|bool|"true"|
|
||||
|[max-worker-connections](#max-worker-connections)|int|16384|
|
||||
|[max-worker-open-files](#max-worker-open-files)|int|0|
|
||||
|
|
@ -92,13 +93,13 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[use-geoip2](#use-geoip2)|bool|"false"|
|
||||
|[enable-brotli](#enable-brotli)|bool|"false"|
|
||||
|[brotli-level](#brotli-level)|int|4|
|
||||
|[brotli-types](#brotli-types)|string|"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component"|
|
||||
|[brotli-types](#brotli-types)|string|"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component"|
|
||||
|[use-http2](#use-http2)|bool|"true"|
|
||||
|[gzip-level](#gzip-level)|int|5|
|
||||
|[gzip-types](#gzip-types)|string|"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component"|
|
||||
|[gzip-types](#gzip-types)|string|"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component"|
|
||||
|[worker-processes](#worker-processes)|string|`<Number of CPUs>`|
|
||||
|[worker-cpu-affinity](#worker-cpu-affinity)|string|""|
|
||||
|[worker-shutdown-timeout](#worker-shutdown-timeout)|string|"10s"|
|
||||
|[worker-shutdown-timeout](#worker-shutdown-timeout)|string|"240s"|
|
||||
|[load-balance](#load-balance)|string|"round_robin"|
|
||||
|[variables-hash-bucket-size](#variables-hash-bucket-size)|int|128|
|
||||
|[variables-hash-max-size](#variables-hash-max-size)|int|2048|
|
||||
|
|
@ -112,7 +113,7 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[use-forwarded-headers](#use-forwarded-headers)|bool|"false"|
|
||||
|[forwarded-for-header](#forwarded-for-header)|string|"X-Forwarded-For"|
|
||||
|[compute-full-forwarded-for](#compute-full-forwarded-for)|bool|"false"|
|
||||
|[proxy-add-original-uri-header](#proxy-add-original-uri-header)|bool|"true"|
|
||||
|[proxy-add-original-uri-header](#proxy-add-original-uri-header)|bool|"false"|
|
||||
|[generate-request-id](#generate-request-id)|bool|"true"|
|
||||
|[enable-opentracing](#enable-opentracing)|bool|"false"|
|
||||
|[zipkin-collector-host](#zipkin-collector-host)|string|""|
|
||||
|
|
@ -126,6 +127,16 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[jaeger-sampler-param](#jaeger-sampler-param)|string|"1"|
|
||||
|[jaeger-sampler-host](#jaeger-sampler-host)|string|"http://127.0.0.1"|
|
||||
|[jaeger-sampler-port](#jaeger-sampler-port)|int|5778|
|
||||
|[jaeger-trace-context-header-name](#jaeger-trace-context-header-name)|string|uber-trace-id|
|
||||
|[jaeger-debug-header](#jaeger-debug-header)|string|uber-debug-id|
|
||||
|[jaeger-baggage-header](#jaeger-baggage-header)|string|jaeger-baggage|
|
||||
|[jaeger-trace-baggage-header-prefix](#jaeger-trace-baggage-header-prefix)|string|uberctx-|
|
||||
|[datadog-collector-host](#datadog-collector-host)|string|""|
|
||||
|[datadog-collector-port](#datadog-collector-port)|int|8126|
|
||||
|[datadog-service-name](#datadog-service-name)|service|"nginx"|
|
||||
|[datadog-operation-name-override](#datadog-operation-name-override)|service|"nginx.handle"|
|
||||
|[datadog-priority-sampling](#datadog-priority-sampling)|bool|"true"|
|
||||
|[datadog-sample-rate](#datadog-sample-rate)|float|1.0|
|
||||
|[main-snippet](#main-snippet)|string|""|
|
||||
|[http-snippet](#http-snippet)|string|""|
|
||||
|[server-snippet](#server-snippet)|string|""|
|
||||
|
|
@ -149,6 +160,7 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[skip-access-log-urls](#skip-access-log-urls)|[]string|[]string{}|
|
||||
|[limit-rate](#limit-rate)|int|0|
|
||||
|[limit-rate-after](#limit-rate-after)|int|0|
|
||||
|[lua-shared-dicts](#lua-shared-dicts)|string|""|
|
||||
|[http-redirect-code](#http-redirect-code)|int|308|
|
||||
|[proxy-buffering](#proxy-buffering)|string|"off"|
|
||||
|[limit-req-status-code](#limit-req-status-code)|int|503|
|
||||
|
|
@ -160,10 +172,13 @@ The following table shows a configuration option's name, type, and the default v
|
|||
|[global-auth-response-headers](#global-auth-response-headers)|string|""|
|
||||
|[global-auth-request-redirect](#global-auth-request-redirect)|string|""|
|
||||
|[global-auth-snippet](#global-auth-snippet)|string|""|
|
||||
|[global-auth-cache-key](#global-auth-cache-key)|string|""|
|
||||
|[global-auth-cache-duration](#global-auth-cache-duration)|string|"200 202 401 5m"|
|
||||
|[no-auth-locations](#no-auth-locations)|string|"/.well-known/acme-challenge"|
|
||||
|[block-cidrs](#block-cidrs)|[]string|""|
|
||||
|[block-user-agents](#block-user-agents)|[]string|""|
|
||||
|[block-referers](#block-referers)|[]string|""|
|
||||
|[proxy-ssl-location-only](#proxy-ssl-location-only)|bool|"false"|
|
||||
|
||||
## add-headers
|
||||
|
||||
|
|
@ -196,7 +211,7 @@ __Note:__ the file `/var/log/nginx/access.log` is a symlink to `/dev/stdout`
|
|||
|
||||
## enable-access-log-for-default-backend
|
||||
|
||||
Enables logging access to default backend. _**default:**_ is disabled.
|
||||
Enables logging access to default backend. _**default:**_ is disabled.
|
||||
|
||||
## error-log-path
|
||||
|
||||
|
|
@ -207,13 +222,6 @@ __Note:__ the file `/var/log/nginx/error.log` is a symlink to `/dev/stderr`
|
|||
_References:_
|
||||
[http://nginx.org/en/docs/ngx_core_module.html#error_log](http://nginx.org/en/docs/ngx_core_module.html#error_log)
|
||||
|
||||
## enable-dynamic-tls-records
|
||||
|
||||
Enables dynamically sized TLS records to improve time-to-first-byte. _**default:**_ is enabled
|
||||
|
||||
_References:_
|
||||
[https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency](https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency)
|
||||
|
||||
## enable-modsecurity
|
||||
|
||||
Enables the modsecurity module for NGINX. _**default:**_ is disabled
|
||||
|
|
@ -222,6 +230,10 @@ Enables the modsecurity module for NGINX. _**default:**_ is disabled
|
|||
|
||||
Enables the OWASP ModSecurity Core Rule Set (CRS). _**default:**_ is disabled
|
||||
|
||||
## modsecurity-snippet
|
||||
|
||||
Adds custom rules to modsecurity section of nginx configration
|
||||
|
||||
## client-header-buffer-size
|
||||
|
||||
Allows to configure a custom buffer size for reading client request header.
|
||||
|
|
@ -306,6 +318,13 @@ Sets the maximum number of requests (including push requests) that can be served
|
|||
_References:_
|
||||
[http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_requests](http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_requests)
|
||||
|
||||
## http2-max-concurrent-streams
|
||||
|
||||
Sets the maximum number of concurrent HTTP/2 streams in a connection.
|
||||
|
||||
_References:_
|
||||
[http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_concurrent_streams](http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_concurrent_streams)
|
||||
|
||||
## hsts
|
||||
|
||||
Enables or disables the header HSTS in servers running SSL.
|
||||
|
|
@ -358,15 +377,13 @@ Sets if the escape parameter allows JSON ("true") or default characters escaping
|
|||
Sets the nginx [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format).
|
||||
Example for json output:
|
||||
|
||||
```console
|
||||
log-format-upstream: '{ "time": "$time_iso8601", "remote_addr": "$proxy_protocol_addr",
|
||||
"x-forward-for": "$proxy_add_x_forwarded_for", "request_id": "$req_id", "remote_user":
|
||||
"$remote_user", "bytes_sent": $bytes_sent, "request_time": $request_time, "status":
|
||||
$status, "vhost": "$host", "request_proto": "$server_protocol", "path": "$uri",
|
||||
"request_query": "$args", "request_length": $request_length, "duration": $request_time,
|
||||
"method": "$request_method", "http_referrer": "$http_referer", "http_user_agent":
|
||||
"$http_user_agent" }'
|
||||
```
|
||||
```json
|
||||
|
||||
log-format-upstream: '{"time": "$time_iso8601", "remote_addr": "$proxy_protocol_addr", "x-forward-for": "$proxy_add_x_forwarded_for", "request_id": "$req_id",
|
||||
"remote_user": "$remote_user", "bytes_sent": $bytes_sent, "request_time": $request_time, "status":$status, "vhost": "$host", "request_proto": "$server_protocol",
|
||||
"path": "$uri", "request_query": "$args", "request_length": $request_length, "duration": $request_time,"method": "$request_method", "http_referrer": "$http_referer",
|
||||
"http_user_agent": "$http_user_agent" }'
|
||||
```
|
||||
|
||||
Please check the [log-format](log-format.md) for definition of each field.
|
||||
|
||||
|
|
@ -439,7 +456,7 @@ _References:_
|
|||
Instructs NGINX to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes
|
||||
_**default:**_ true
|
||||
|
||||
## proxy-headers-hash-bucket-size
|
||||
## proxy-headers-hash-bucket-size
|
||||
|
||||
Sets the size of the bucket for the proxy headers hash tables.
|
||||
|
||||
|
|
@ -486,6 +503,14 @@ Sets the [SSL protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#
|
|||
|
||||
Please check the result of the configuration using `https://ssllabs.com/ssltest/analyze.html` or `https://testssl.sh`.
|
||||
|
||||
## ssl-early-data
|
||||
|
||||
Enables or disables TLS 1.3 [early data](https://tools.ietf.org/html/rfc8446#section-2.3)
|
||||
|
||||
This requires `ssl-protocols` to have `TLSv1.3` enabled.
|
||||
|
||||
[ssl_early_data](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data). The default is: `false`.
|
||||
|
||||
## ssl-session-cache
|
||||
|
||||
Enables or disables the use of shared [SSL cache](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) among worker processes.
|
||||
|
|
@ -503,7 +528,7 @@ Enables or disables session resumption through [TLS session tickets](http://ngin
|
|||
Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string.
|
||||
To create a ticket: `openssl rand 80 | openssl enc -A -base64`
|
||||
|
||||
[TLS session ticket-key](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets), by default, a randomly generated key is used.
|
||||
[TLS session ticket-key](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets), by default, a randomly generated key is used.
|
||||
|
||||
## ssl-session-timeout
|
||||
|
||||
|
|
@ -539,6 +564,13 @@ _**default:**_ true
|
|||
## use-geoip2
|
||||
|
||||
Enables the [geoip2 module](https://github.com/leev/ngx_http_geoip2_module) for NGINX.
|
||||
Since `0.27.0` and due to a [change in the MaxMind databases](https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases) a license is required to have access to the databases.
|
||||
For this reason, it is required to define a new flag `--maxmind-license-key` in the ingress controller deployment to download the databases needed during the initialization of the ingress controller.
|
||||
Alternatively, it is possible to use a volume to mount the files `/etc/nginx/geoip/GeoLite2-City.mmdb` and `/etc/nginx/geoip/GeoLite2-ASN.mmdb`, avoiding the overhead of the download.
|
||||
|
||||
!!! important
|
||||
If the feature is enabled but the files are missing, GeoIP2 will not be enabled.
|
||||
|
||||
_**default:**_ false
|
||||
|
||||
## enable-brotli
|
||||
|
|
@ -565,6 +597,10 @@ Enables or disables [HTTP/2](http://nginx.org/en/docs/http/ngx_http_v2_module.ht
|
|||
|
||||
Sets the gzip Compression Level that will be used. _**default:**_ 5
|
||||
|
||||
## gzip-min-length
|
||||
|
||||
Minimum length of responses to be returned to the client before it is eligible for gzip compression, in bytes. _**default:**_ 256
|
||||
|
||||
## gzip-types
|
||||
|
||||
Sets the MIME types in addition to "text/html" to compress. The special value "\*" matches any MIME type. Responses with the "text/html" type are always compressed if `[use-gzip](#use-gzip)` is enabled.
|
||||
|
|
@ -586,7 +622,7 @@ By default worker processes are not bound to any specific CPUs. The value can be
|
|||
|
||||
## worker-shutdown-timeout
|
||||
|
||||
Sets a timeout for Nginx to [wait for worker to gracefully shutdown](http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout). _**default:**_ "10s"
|
||||
Sets a timeout for Nginx to [wait for worker to gracefully shutdown](http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout). _**default:**_ "240s"
|
||||
|
||||
## load-balance
|
||||
|
||||
|
|
@ -622,7 +658,7 @@ _References:_
|
|||
|
||||
Activates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle
|
||||
keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is
|
||||
exceeded, the least recently used connections are closed.
|
||||
exceeded, the least recently used connections are closed.
|
||||
_**default:**_ 32
|
||||
|
||||
_References:_
|
||||
|
|
@ -643,7 +679,7 @@ _References:_
|
|||
Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of
|
||||
requests is made, the connection is closed.
|
||||
_**default:**_ 100
|
||||
|
||||
|
||||
|
||||
_References:_
|
||||
[http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests)
|
||||
|
|
@ -746,6 +782,48 @@ Leave blank to use default value (localhost). _**default:**_ http://127.0.0.1
|
|||
|
||||
Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. _**default:**_ 5778
|
||||
|
||||
## jaeger-trace-context-header-name
|
||||
|
||||
Specifies the header name used for passing trace context. _**default:**_ uber-trace-id
|
||||
|
||||
## jaeger-debug-header
|
||||
|
||||
Specifies the header name used for force sampling. _**default:**_ jaeger-debug-id
|
||||
|
||||
## jaeger-baggage-header
|
||||
|
||||
Specifies the header name used to submit baggage if there is no root span. _**default:**_ jaeger-baggage
|
||||
|
||||
## jaeger-tracer-baggage-header-prefix
|
||||
|
||||
Specifies the header prefix used to propagate baggage. _**default:**_ uberctx-
|
||||
|
||||
## datadog-collector-host
|
||||
|
||||
Specifies the datadog agent host to use when uploading traces. It must be a valid URL.
|
||||
|
||||
## datadog-collector-port
|
||||
|
||||
Specifies the port to use when uploading traces. _**default:**_ 8126
|
||||
|
||||
## datadog-service-name
|
||||
|
||||
Specifies the service name to use for any traces created. _**default:**_ nginx
|
||||
|
||||
## datadog-operation-name-override
|
||||
|
||||
Overrides the operation naem to use for any traces crated. _**default:**_ nginx.handle
|
||||
|
||||
## datadog-priority-sampling
|
||||
|
||||
Specifies to use client-side sampling.
|
||||
If true disables client-side sampling (thus ignoring `sample_rate`) and enables distributed priority sampling, where traces are sampled based on a combination of user-assigned priorities and configuration from the agent. _**default:**_ true
|
||||
|
||||
## datadog-sample-rate
|
||||
|
||||
Specifies sample rate for any traces created.
|
||||
This is effective only when `datadog-priority-sampling` is `false` _**default:**_ 1.0
|
||||
|
||||
## main-snippet
|
||||
|
||||
Adds custom configuration to the main section of the nginx configuration.
|
||||
|
|
@ -853,6 +931,21 @@ _References:_
|
|||
|
||||
Sets the initial amount after which the further transmission of a response to a client will be rate limited.
|
||||
|
||||
## lua-shared-dicts
|
||||
|
||||
Customize default Lua shared dictionaries or define more. You can use the following syntax to do so:
|
||||
|
||||
```
|
||||
lua-shared-dicts: "<my dict name>: <my dict size>, [<my dict name>: <my dict size>], ..."
|
||||
```
|
||||
|
||||
For example following will set default `certificate_data` dictionary to `100M` and will introduce a new dictionary called
|
||||
`my_custom_plugin`:
|
||||
|
||||
```
|
||||
lua-shared-dicts: "certificate_data: 100, my_custom_plugin: 5"
|
||||
```
|
||||
|
||||
_References:_
|
||||
[http://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after](http://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after)
|
||||
|
||||
|
|
@ -864,7 +957,7 @@ _**default:**_ 308
|
|||
|
||||
> __Why the default code is 308?__
|
||||
|
||||
> [RFC 7238](https://tools.ietf.org/html/rfc7238) was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if the we send a redirect in methods like POST.
|
||||
> [RFC 7238](https://tools.ietf.org/html/rfc7238) was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if we send a redirect in methods like POST.
|
||||
|
||||
## proxy-buffering
|
||||
|
||||
|
|
@ -922,6 +1015,14 @@ Sets a custom snippet to use with external authentication. Applied to all the lo
|
|||
Similar to the Ingress rule annotation `nginx.ingress.kubernetes.io/auth-request-redirect`.
|
||||
_**default:**_ ""
|
||||
|
||||
## global-auth-cache-key
|
||||
|
||||
Enables caching for global auth requests. Specify a lookup key for auth responses, e.g. `$remote_user$http_authorization`.
|
||||
|
||||
## global-auth-cache-duration
|
||||
|
||||
Set a caching time for auth responses based on their response codes, e.g. `200 202 30m`. See [proxy_cache_valid](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid) for details. You may specify multiple, comma-separated values: `200 202 10m, 401 5m`. defaults to `200 202 401 5m`.
|
||||
|
||||
## no-auth-locations
|
||||
|
||||
A comma-separated list of locations that should not get authenticated.
|
||||
|
|
@ -949,3 +1050,9 @@ It's possible to use here full strings and regular expressions. More details abo
|
|||
|
||||
_References:_
|
||||
[http://nginx.org/en/docs/http/ngx_http_map_module.html#map](http://nginx.org/en/docs/http/ngx_http_map_module.html#map)
|
||||
|
||||
## proxy-ssl-location-only
|
||||
|
||||
Set if proxy-ssl parameters should be applied only on locations and not on servers.
|
||||
_**default:**_ is disabled
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
The NGINX template is located in the file `/etc/nginx/template/nginx.tmpl`.
|
||||
|
||||
Using a [Volume](https://kubernetes.io/docs/concepts/storage/volumes/) it is possible to use a custom template.
|
||||
Using a [Volume](https://kubernetes.io/docs/concepts/storage/volumes/) it is possible to use a custom template.
|
||||
This includes using a [Configmap](https://kubernetes.io/docs/concepts/storage/volumes/#example-pod-with-a-secret-a-downward-api-and-a-configmap) as source of the template
|
||||
|
||||
```yaml
|
||||
|
|
@ -30,6 +30,7 @@ In addition to the built-in functions provided by the Go package the following f
|
|||
- hasSuffix: [strings.HasSuffix](https://golang.org/pkg/strings/#HasSuffix)
|
||||
- toUpper: [strings.ToUpper](https://golang.org/pkg/strings/#ToUpper)
|
||||
- toLower: [strings.ToLower](https://golang.org/pkg/strings/#ToLower)
|
||||
- quote: wraps a string in double quotes
|
||||
- buildLocation: helps to build the NGINX Location section in each server
|
||||
- buildProxyPass: builds the reverse proxy configuration
|
||||
- buildRateLimit: helps to build a limit zone inside a location if contains a rate limit annotation
|
||||
|
|
@ -39,7 +40,6 @@ TODO:
|
|||
- buildAuthLocation:
|
||||
- buildAuthResponseHeaders:
|
||||
- buildResolvers:
|
||||
- buildLogFormatUpstream:
|
||||
- buildDenyVariable:
|
||||
- buildUpstreamName:
|
||||
- buildForwardedFor:
|
||||
|
|
|
|||
|
|
@ -4,18 +4,16 @@ The default configuration uses a custom logging format to add additional informa
|
|||
|
||||
```
|
||||
log_format upstreaminfo
|
||||
'{{ if $cfg.useProxyProtocol }}$proxy_protocol_addr{{ else }}$remote_addr{{ end }} - '
|
||||
'[$the_real_ip] - $remote_user [$time_local] "$request" '
|
||||
'$remote_addr - $remote_user [$time_local] "$request" '
|
||||
'$status $body_bytes_sent "$http_referer" "$http_user_agent" '
|
||||
'$request_length $request_time [$proxy_upstream_name] $upstream_addr '
|
||||
'$request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr '
|
||||
'$upstream_response_length $upstream_response_time $upstream_status $req_id';
|
||||
```
|
||||
|
||||
| Placeholder | Description |
|
||||
|-------------|-------------|
|
||||
| `$proxy_protocol_addr` | remote address if proxy protocol is enabled |
|
||||
| `$remote_addr` | remote address if proxy protocol is disabled (default) |
|
||||
| `$the_real_ip` | the source IP address of the client |
|
||||
| `$remote_addr` | the source IP address of the client |
|
||||
| `$remote_user` | user name supplied with the Basic authentication |
|
||||
| `$time_local` | local time in the Common Log Format |
|
||||
| `$request` | full original request line |
|
||||
|
|
@ -26,6 +24,7 @@ log_format upstreaminfo
|
|||
| `$request_length` | request length (including request line, header, and request body) |
|
||||
| `$request_time` | time elapsed since the first bytes were read from the client |
|
||||
| `$proxy_upstream_name` | name of the upstream. The format is `upstream-<namespace>-<service name>-<service port>` |
|
||||
| `$proxy_alternative_upstream_name` | name of the alternative upstream. The format is `upstream-<namespace>-<service name>-<service port>` |
|
||||
| `$upstream_addr` | the IP address and port (or the path to the domain socket) of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas. |
|
||||
| `$upstream_response_length` | the length of the response obtained from the upstream server |
|
||||
| `$upstream_response_time` | time spent on receiving the response from the upstream server as seconds with millisecond resolution |
|
||||
|
|
@ -45,4 +44,4 @@ Additional available variables:
|
|||
Sources:
|
||||
|
||||
- [Upstream variables](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#variables)
|
||||
- [Embedded variables](http://nginx.org/en/docs/http/ngx_http_core_module.html#variables)
|
||||
- [Embedded variables](http://nginx.org/en/docs/http/ngx_http_core_module.html#variables)
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@ The default ModSecurity configuration file is located in `/etc/nginx/modsecurity
|
|||
To enable the ModSecurity feature we need to specify `enable-modsecurity: "true"` in the configuration configmap.
|
||||
|
||||
>__Note:__ the default configuration use detection only, because that minimizes the chances of post-installation disruption.
|
||||
The file `/var/log/modsec_audit.log` contains the log of ModSecurity.
|
||||
|
||||
Due to the value of the setting [SecAuditLogType=Concurrent](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#secauditlogtype) the ModSecurity log is stored in multiple files inside the directory `/var/log/audit`.
|
||||
The default `Serial` value in SecAuditLogType can impact performance.
|
||||
|
||||
The OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. The CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts.
|
||||
The directory `/etc/nginx/owasp-modsecurity-crs` contains the [owasp-modsecurity-crs repository](https://github.com/SpiderLabs/owasp-modsecurity-crs).
|
||||
|
|
|
|||
|
|
@ -13,6 +13,15 @@ data:
|
|||
enable-opentracing: "true"
|
||||
```
|
||||
|
||||
To enable or disable instrumentation for a single Ingress, use
|
||||
the `enable-opentracing` annotation:
|
||||
```
|
||||
kind: Ingress
|
||||
metadata:
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/enable-opentracing: "true"
|
||||
```
|
||||
|
||||
We must also set the host to use when uploading traces:
|
||||
|
||||
```
|
||||
|
|
@ -20,7 +29,7 @@ zipkin-collector-host: zipkin.default.svc.cluster.local
|
|||
jaeger-collector-host: jaeger-agent.default.svc.cluster.local
|
||||
datadog-collector-host: datadog-agent.default.svc.cluster.local
|
||||
```
|
||||
NOTE: While the option is called `jaeger-collector-host`, you will need to point this to a `jaeger-agent`, and not the `jaeger-collector` component.
|
||||
NOTE: While the option is called `jaeger-collector-host`, you will need to point this to a `jaeger-agent`, and not the `jaeger-collector` component.
|
||||
|
||||
Next you will need to deploy a distributed tracing system which uses OpenTracing.
|
||||
[Zipkin](https://github.com/openzipkin/zipkin) and
|
||||
|
|
@ -59,6 +68,18 @@ jaeger-sampler-host
|
|||
# Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. Default: 5778
|
||||
jaeger-sampler-port
|
||||
|
||||
# Specifies the header name used for passing trace context. Must be a string. Default: uber-trace-id
|
||||
jaeger-trace-context-header-name
|
||||
|
||||
# Specifies the header name used for force sampling. Must be a string. Default: jaeger-debug-id
|
||||
jaeger-debug-header
|
||||
|
||||
# Specifies the header name used to submit baggage if there is no root span. Must be a string. Default: jaeger-baggage
|
||||
jaeger-baggage-header
|
||||
|
||||
# Specifies the header prefix used to propagate baggage. Must be a string. Default: uberctx-
|
||||
jaeger-tracer-baggage-header-prefix
|
||||
|
||||
# specifies the port to use when uploading traces, Default 8126
|
||||
datadog-collector-port
|
||||
|
||||
|
|
@ -67,14 +88,19 @@ datadog-service-name
|
|||
|
||||
# specifies the operation name to use for any traces collected, Default: nginx.handle
|
||||
datadog-operation-name-override
|
||||
|
||||
# Specifies to use client-side sampling for distributed priority sampling and ignore sample rate, Default: true
|
||||
datadog-priority-sampling
|
||||
|
||||
# specifies sample rate for any traces created, Default: 1.0
|
||||
datadog-sample-rate
|
||||
```
|
||||
|
||||
All these options (including host) allow environment variables, such as `$HOSTNAME` or `$HOST_IP`. In the case of Jaeger, if you have a Jaeger agent running on each machine in your cluster, you can use something like `$HOST_IP` (which can be 'mounted' with the `status.hostIP` fieldpath, as described [here](https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#capabilities-of-the-downward-api)) to make sure traces will be sent to the local agent.
|
||||
|
||||
## Examples
|
||||
|
||||
The following examples show how to deploy and test different distributed tracing systems. These example can be performed
|
||||
using Minikube.
|
||||
The following examples show how to deploy and test different distributed tracing systems. These example can be performed using Minikube.
|
||||
|
||||
### Zipkin
|
||||
|
||||
|
|
@ -126,7 +152,7 @@ In the Zipkin interface we can see the details:
|
|||
|
||||
# Apply the Ingress Resource
|
||||
$ echo '
|
||||
apiVersion: extensions/v1beta1
|
||||
apiVersion: networking.k8s.io/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: echo-ingress
|
||||
|
|
|
|||
|
|
@ -34,9 +34,12 @@ If this flag is not provided NGINX will use a self-signed certificate.
|
|||
For instance, if you have a TLS secret `foo-tls` in the `default` namespace,
|
||||
add `--default-ssl-certificate=default/foo-tls` in the `nginx-controller` deployment.
|
||||
|
||||
The default certificate will also be used for ingress `tls:` sections that do not
|
||||
have a `secretName` option.
|
||||
|
||||
## SSL Passthrough
|
||||
|
||||
The [`--enable-ssl-passthrough`](cli-arguments/) flag enables the SSL Passthrough feature, which is disabled by
|
||||
The [`--enable-ssl-passthrough`](cli-arguments.md) flag enables the SSL Passthrough feature, which is disabled by
|
||||
default. This is required to enable passthrough backends in Ingress objects.
|
||||
|
||||
!!! warning
|
||||
|
|
@ -75,7 +78,6 @@ or per-Ingress with the `nginx.ingress.kubernetes.io/ssl-redirect: "false"`
|
|||
annotation in the particular resource.
|
||||
|
||||
!!! tip
|
||||
|
||||
When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a
|
||||
redirect to HTTPS even when there is no TLS certificate available.
|
||||
This can be achieved by using the `nginx.ingress.kubernetes.io/force-ssl-redirect: "true"`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue