nginx ingress ssl redirect

TLS/HTTPS ¶

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:

Then create the secret in the cluster via:

Host names ¶

Default SSL Certificate ¶

NGINX provides the option to configure a server as a catch-all with server_name for requests that do not match any of the configured server names. This configuration works out-of-the-box for HTTP traffic. For HTTPS, a certificate is naturally required.

The default certificate will also be used for ingress tls: sections that do not have a secretName option.

SSL Passthrough ¶

This feature is implemented by intercepting all traffic on the configured HTTPS port (default: 443) and handing it over to a local TCP proxy. This bypasses NGINX completely and introduces a non-negligible performance penalty.

SSL Passthrough leverages SNI and reads the virtual domain from the TLS negotiation, which requires compatible clients. After a connection has been accepted by the TLS listener, it is handled by the controller itself and piped back and forth between the backend and the client.

If there is no hostname matching the requested host name, the request is handed over to NGINX on the configured passthrough proxy port (default: 442), which proxies the request to the default backend.

Unlike HTTP backends, traffic to Passthrough backends is sent to the clusterIP of the backing Service instead of individual Endpoints.

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.

HSTS is enabled by default.

To disable this behavior use hsts: «false» in the configuration ConfigMap.

Server-side HTTPS enforcement through redirect ¶

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.

This can be disabled globally using ssl-redirect: «false» in the NGINX config map, 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 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 has reached end-of-life and is being replaced by 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:

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.

Default TLS Version and Ciphers ¶

To provide the most secure baseline configuration possible,

nginx-ingress defaults to using TLS 1.2 and 1.3 only, with a secure set of TLS ciphers.

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 are not compatible with nginx-ingress’s default configuration.

To change this default behavior, use a ConfigMap.

A sample ConfigMap fragment to allow these older clients to connect could look something like the following (generated using the Mozilla SSL Configuration Generator)mozilla-ssl-config-old:

Источник

Kubernetes Nginx ingress: traffic redirect using annotations demystified

Redirect HTTP traffic or rewrite URLs using Kubernetes ingress annotations and Nginx ingress controller. This article explains annotations usage and their effect on the resulting nginx.conf configuration file.

1. nginx.ingress.kubernetes.io/rewrite-target

kubernetes/ingress-nginx

This example demonstrates how to use the Rewrite annotations You will need to make sure your Ingress targets exactly…

This one does a transparent reverse proxy.
It does not update the Location header so the URL in the browser does not change.

This one changes the Location header and the URL in the browser is updated:

If you need to control the return code using a rewrite rule, then you need to use a return directive after the rewrite directive. More info here: https://www.nginx.com/blog/creating-nginx-rewrite-rules.
I assume this can be used using nginx.ingress.kubernetes.io/configuration-snippet: | (I have not tried it yet).

This one is nice: defines the Application Root that the Controller must redirect if it’s in / context:

In the resulting nginx.conf an if statement will be added to the server context :

2. nginx.ingress.kubernetes.io/configuration-snippet: |

This one looks like it gives the greatest control over the redirect/rewrite as it will add the additional configuration snippet to the resulting nginx.conf location.

permanent: returns a permanent redirect with the 301 code.

3. nginx.ingress.kubernetes.io/server-snippet: |

4. nginx.ingress.kubernetes.io/permanent-redirect

Источник

Annotations ¶

You can add these Kubernetes annotations to specific Ingress objects to customize their behavior.

Canary ¶

In some cases, you may want to «canary» a new set of changes by sending a small number of requests to a different service than the production service. The canary annotation enables the Ingress spec to act as an alternative service for requests to route to depending on the rules applied. The following annotations to configure canary can be enabled after nginx.ingress.kubernetes.io/canary: «true» is set:

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.

Known Limitations

Currently a maximum of one canary ingress can be applied per Ingress rule.

Rewrite ¶

In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404. Set the annotation nginx.ingress.kubernetes.io/rewrite-target to the path expected by the service.

Please check the rewrite example.

Session Affinity ¶

The annotation nginx.ingress.kubernetes.io/affinity-mode defines the stickiness 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 stickiness.

The annotation nginx.ingress.kubernetes.io/affinity-canary-behavior defines the behavior of canaries when session affinity is enabled. Setting this to sticky (default) will ensure that users that were served by canaries, will continue to be served by canaries. Setting this to legacy will restore original canary behavior, when session affinity was ignored.

Please check the affinity example.

Cookie affinity ¶

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.

Authentication ¶

It is possible to add authentication by adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords.

The annotations are:

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.

The auth-secret can have two forms:

Please check the auth example.

Custom NGINX upstream hashing ¶

NGINX supports load balancing by client-server mapping based on consistent hashing for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The ketama consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.

There is a special mode of upstream hashing called subset. In this mode, upstream servers are grouped into subsets, and stickiness works by mapping keys to a subset instead of individual upstream servers. Specific server is chosen uniformly at random from the selected sticky subset. It provides a balance between stickiness and load distribution.

To enable consistent hashing for a backend:

nginx.ingress.kubernetes.io/upstream-hash-by : the nginx variable, text value or any combination thereof to use for consistent hashing. For example: nginx.ingress.kubernetes.io/upstream-hash-by: «$request_uri» or nginx.ingress.kubernetes.io/upstream-hash-by: «$request_uri$host» or nginx.ingress.kubernetes.io/upstream-hash-by: «$-text-value» to consistently hash upstream requests by the current request URI.

«subset» hashing can be enabled setting nginx.ingress.kubernetes.io/upstream-hash-by-subset : «true». This maps requests to subset of nodes instead of a single one. upstream-hash-by-subset-size determines the size of each subset (default 3).

Please check the chashsubset example.

Custom NGINX load balancing ¶

This is similar to load-balance in ConfigMap, but configures load balancing algorithm per ingress.

Note that nginx.ingress.kubernetes.io/upstream-hash-by takes preference over this. If this and nginx.ingress.kubernetes.io/upstream-hash-by are not set then we fallback to using globally configured load balancing algorithm.

Custom NGINX upstream vhost ¶

Client Certificate Authentication ¶

It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.

Client Certificate Authentication is applied per host and it is not possible to specify rules that differ for individual paths.

You can further customize client certificate authentication and behaviour with these annotations:

The following headers are sent to the upstream service according to the auth-tls-* annotations:

Please check the client-certs example.

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/

Backend Certificate Authentication ¶

It is possible to authenticate to a proxied HTTPS backend with certificate using additional annotations in Ingress Rule.

Configuration snippet ¶

Using this annotation you can add additional configuration to the NGINX location. For example:

Custom HTTP Errors ¶

Default Backend ¶

This annotation is of the form nginx.ingress.kubernetes.io/default-backend: to specify a custom default backend. This is a reference to a service inside of the same namespace in which you are applying this annotation. This annotation overrides the global default backend. In case the service has multiple ports, the first one is the one which will received the backend traffic.

This service will be used to handle the response when the configured service in the Ingress rule does not have any active endpoints. It will also be used to handle the error responses if both this annotation and the custom-http-errors annotation are set.

Enable CORS ¶

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-headers : Controls which headers are accepted.

nginx.ingress.kubernetes.io/cors-expose-headers : Controls which headers are exposed to response.

nginx.ingress.kubernetes.io/cors-allow-origin : Controls what’s the accepted Origin for CORS.

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-allow-credentials : Controls if credentials can be passed during CORS operations.

nginx.ingress.kubernetes.io/cors-max-age : Controls how long preflight requests can be cached.

For more information please see https://enable-cors.org

HTTP2 Push Preload. ¶

Enables automatic conversion of preload links specified in the “Link” response header fields into push requests.

Server Alias ¶

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.

Server snippet ¶

Using the annotation nginx.ingress.kubernetes.io/server-snippet it is possible to add custom configuration in the server configuration block.

This annotation can be used only once per host.

Client Body Buffer Size ¶

Sets buffer size for reading client request body per location. In case the request body is larger than the buffer, the whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages. 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.

The annotation value must be given in a format understood by Nginx.

For more information please see http://nginx.org

External Authentication ¶

To use an existing service that provides authentication the Ingress rule can be annotated with nginx.ingress.kubernetes.io/auth-url to indicate the URL where the HTTP request should be sent.

Additionally it is possible to set:

Note: nginx.ingress.kubernetes.io/auth-snippet is an optional annotation. However, it may only be used in conjunction with nginx.ingress.kubernetes.io/auth-url and will be ignored if nginx.ingress.kubernetes.io/auth-url is not set

Please check the external-auth example.

Global External Authentication ¶

For more information please see global-auth-url.

Rate Limiting ¶

These annotations define limits on connections and transmission rates. These can be used to mitigate DDoS Attacks.

To configure settings globally for all Ingress rules, the limit-rate-after and limit-rate values may be set in the NGINX ConfigMap. The value set in an Ingress annotation will override the global setting.

The client IP address will be set based on the use of PROXY protocol or from the X-Forwarded-For header value when use-forwarded-headers is enabled.

Global Rate Limiting ¶

Note: Be careful when configuring both (Local) Rate Limiting and Global Rate Limiting at the same time. They are two completely different rate limiting implementations. Whichever limit exceeds first will reject the requests. It might be a good idea to configure both of them to ease load on Global Rate Limiting backend in cases of spike in traffic.

Here are a few remarks for ingress-nginx integration of lua-resty-global-throttle :

The annotations below creates Global Rate Limiting instance per ingress. That means if there are multuple paths configured under the same ingress, the Global Rate Limiting will count requests to all the paths under the same counter. Extract a path out into its own ingress if you need to isolate a certain path.

nginx.ingress.kubernetes.io/global-rate-limit : Configures maximum allowed number of requests per window. Required.

Permanent Redirect ¶

This annotation allows to return a permanent redirect (Return Code 301) instead of sending data to the upstream. For example nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com would redirect everything to Google.

Permanent Redirect Code ¶

This annotation allows you to modify the status code used for permanent redirects. For example nginx.ingress.kubernetes.io/permanent-redirect-code: ‘308’ would return your permanent-redirect with a 308.

Temporal Redirect ¶

This annotation allows you to return a temporal redirect (Return Code 302) instead of sending data to the upstream. For example nginx.ingress.kubernetes.io/temporal-redirect: https://www.google.com would redirect everything to Google with a Return Code of 302 (Moved Temporarily)

SSL Passthrough ¶

The annotation nginx.ingress.kubernetes.io/ssl-passthrough instructs the controller to send TLS connections directly to the backend instead of letting NGINX decrypt the communication. See also TLS/HTTPS in the User guide.

Because SSL Passthrough works on layer 4 of the OSI model (TCP) and not on the layer 7 (HTTP), using SSL Passthrough invalidates all the other annotations set on an Ingress object.

Service Upstream ¶

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.

Known Issues ¶

If the service-upstream annotation is specified the following things should be taken into consideration:

Server-side HTTPS enforcement through redirect ¶

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 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.

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 ¶

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»

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.

For HTTPS to HTTPS redirects is mandatory the SSL Certificate defined in the Secret, located in the TLS section of Ingress, contains both FQDN in the common name of the certificate.

Whitelist source range ¶

To configure this setting globally for all Ingress rules, the whitelist-source-range value may be set in the NGINX ConfigMap.

Adding an annotation to an Ingress rule overrides any global restriction.

Custom timeouts ¶

Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers. In some scenarios is required to have different values. To allow this we provide annotations that allows this customization:

Note: All timeout values are unitless and in seconds e.g. nginx.ingress.kubernetes.io/proxy-read-timeout: «120» sets a valid 120 seconds proxy read timeout.

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

By default the value of each annotation is «off».

Custom 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 use custom values in an Ingress rule define these annotation:

Proxy cookie domain ¶

Sets a text that should be changed in the domain attribute of the «Set-Cookie» header fields of a proxied server response.

To configure this setting globally for all Ingress rules, the proxy-cookie-domain value may be set in the NGINX ConfigMap.

Proxy cookie path ¶

Sets a text that should be changed in the path attribute of the «Set-Cookie» header fields of a proxied server response.

To configure this setting globally for all Ingress rules, the proxy-cookie-path value may be set in the NGINX ConfigMap.

Proxy buffering ¶

To configure this setting globally for all Ingress rules, the proxy-buffering value may be set in the NGINX ConfigMap. To use custom values in an Ingress rule define these annotation:

Proxy buffers Number ¶

Sets the number of the buffers in 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. To use custom values in an Ingress rule, define this annotation:

Proxy buffer size ¶

Sets the size of the buffer proxy_buffer_size used for reading the first part of the response received from the proxied server. By default proxy buffer size is set as «4k»

To configure this setting globally, set proxy-buffer-size in NGINX ConfigMap. To use custom values in an Ingress rule, define this annotation:

Proxy max temp file size ¶

The zero value disables buffering of responses to temporary files.

To use custom values in an Ingress rule, define this annotation:

Proxy HTTP version ¶

Using this annotation sets the proxy_http_version that the Nginx reverse proxy will use to communicate with the backend. By default this is set to «1.1».

SSL ciphers ¶

Using this annotation will set the ssl_ciphers directive at the server level. This configuration is active for all the paths in the host.

The following annotation will set the ssl_prefer_server_ciphers directive at the server level. This configuration specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols.

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:

Enable Access Log ¶

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:

Enable Rewrite Log ¶

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:

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)

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:

ModSecurity ¶

ModSecurity is an OpenSource Web Application firewall. It can be enabled for a particular set of ingress locations. The ModSecurity module must first be enabled by enabling ModSecurity in the ConfigMap. Note this will enable ModSecurity for all paths, and each path must be disabled manually.

It can be enabled using the following annotation:

You can enable the OWASP Core Rule Set by setting the following annotation:

You can pass transactionIDs from nginx by setting up the following:

You can also add your own set of modsecurity rules via a snippet:

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 or recommended configuration simply use the include statement:

nginx 0.24.1 and below

InfluxDB ¶

Using influxdb-* annotations we can monitor requests passing through a Location by sending them to an InfluxDB backend exposing the UDP socket using the nginx-influxdb-module.

For the influxdb-host parameter you have two options:

Backend Protocol ¶

Using backend-protocol annotations is possible to indicate how NGINX should communicate with the backend service. (Replaces secure-backends in older versions) Valid Values: HTTP, HTTPS, GRPC, GRPCS, AJP and FCGI

Use Regex ¶

The following will indicate that regular expression paths are being used:

The following will indicate that regular expression paths are not being used:

Additionally, if the rewrite-target annotation is used on any Ingress for a given host, then the case insensitive regular expression location modifier will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.

Please read about ingress path matching before using this modifier.

Satisfy ¶

By default, a request would need to satisfy all authentication requirements in order to be allowed. By using this annotation, requests that satisfy either any or all authentication requirements are allowed, based on the configuration value.

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:

By default the request-body is sent to the mirror backend, but can be turned off by applying:

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

Источник