Note: Your applications need to be capable of running on a non-root path either by default or by setting the base path in their configuration.

TLS

If your cluster has TLS enabled, you can terminate TLS either in your application itself by enabling SSL passthrough or let the Ingress Controller terminate for you.

SSL Passthrough

Warning: This feature was disabled by default in Nginx ingress controller managed by Giant Swarm. Reason is a potential crash of internal TCP proxier. We recommend to terminate TLS in ingress controller instead.

For SSL passthrough you need to set an annotation and enable TLS for the host:

Warning: When enabling TLS with the NGINX Ingress Controller, some more configuration settings become important. Notably HSTS will be enabled by default with a duration of six month for your specified domain. Once a browser retrieved these HSTS instructions it will refuse to read any unencrypted resource from that domain and un-setting HSTS on your server will not have any affect on that browser for half a year. So you might want to disable this at first to avoid unwanted surprises. Please contact our support team to find out details on how to disable HSTS in your cluster.

Tip: If you want to use Let’s Encrypt certificates with your domains you can automate their creation and renewal with the help of cert-manager. After configuring cert-manager there is only an annotation with your Ingresses needed and your web page will be secured by a valid TLS certificate.

Authentication

First, you need to create a file called auth containing your usernames and passwords (one per line). You can do this either by using the htpasswd command line tool (like in the following example) or an online htpasswd generator.

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 nginx.ingress.kubernetes.io/auth-method to specify the HTTP method to use (GET or POST).

This functionality is based on the auth_request module, which expects a 2xx response code from the external service if the access is allowed and 401 or 403 if denied.

CORS

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. To circumvent this you can set the annotation ingress.kubernetes.io/rewrite-target to the path expected by the service.

This can for example be used together with path based routing, when the application expects to be on /:

If the application contains relative links it is possible to add an additional annotation ingress.kubernetes.io/add-base-url that will prepend a base tag in the header of the returned HTML from the backend.

Rate limiting

The annotations ingress.kubernetes.io/limit-connections and ingress.kubernetes.io/limit-rps define a limit on the connections that can be opened by a single client IP address. This can be used to mitigate DDoS Attacks.

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.

If you specify both annotations in a single Ingress rule, limit-rps takes precedence.

Secure backends

By default NGINX uses http to reach the services. Adding the annotation nginx.ingress.kubernetes.io/secure-backends: "true" in the Ingress rule changes the protocol to https.

Server-side HTTPS enforcement through redirect

By default the controller redirects (301) to HTTPS if TLS is enabled for that Ingress. If you want to disable that behaviour, you can use the nginx.ingress.kubernetes.io/ssl-redirect: "false" annotation.

Whitelist source range

You can specify the allowed client IP source ranges through the nginx.ingress.kubernetes.io/whitelist-source-range annotation. The value is a comma separated list of CIDRs, e.g. 10.0.0.0/24,172.10.0.1.

Note: Adding an annotation to an Ingress rule overrides any global restrictions set in the NGINX Ingress Controller.

Custom max body size

A 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter client_max_body_size and is set to 1m (1 Megabyte) by default.

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 a specific Ingress add following annotation:

nginx.ingress.kubernetes.io/proxy-body-size: 8m

Session Affinity

The annotation nginx.ingress.kubernetes.io/affinity enables and sets the affinity type in all upstreams of an Ingress. This way, a request will always be directed to the same upstream server.

Cookie affinity

If you use the cookie type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name. The default is to create a cookie named route.

The annotation nginx.ingress.kubernetes.io/session-cookie-hash defines which algorithm will be used to hash the used upstream. Default value is md5 and possible values are md5, sha1 and index.

The index option is not hashed, an in-memory index is used instead, it’s quicker and the overhead is shorter. Warning: The matching against the upstream servers list is inconsistent. So, at reload, if upstreams servers have changed, index values are not guaranted to correspond to the same server as before! Use with caution and only if you need to!

Configuration snippets

The NGINX Ingress Controller creates an NGINX configuration file. You can directly pass chunks of configuration, so-called configuration snippets, into any ingress manifest. These snippets will be added to the NGINX configuration.

Global (per Cluster) Options

Your Giant Swarm installation comes with some global defaults for Ingress Controller configuration. However, you can override these defaults by setting your per cluster configuration in form of a ConfigMap named nginx-ingress-controller-user-values located in your kube-system namespace.

Note: This feature is only available in more recent cluster versions. To check if your cluster version supports customization of the ConfigMap, you can check if the above-mentioned ConfigMap is present.

Warning: Please do not edit any of the other nginx ingress related ConfigMaps. Only the user ConfigMap is safe to edit.

On cluster creation the ConfigMap is empty and above defaults will be applied to the final Ingress Controller deployment. To override any of the above values, you just need to add the respective line in the data field of the user ConfigMap.

Giant Swarm uses cookies to give you the best online experience. If you continue to use this site, you agree to our use of cookies. To disable all but strictly necessary cookies, you may disagree by clicking the button to the right. Please see our privacy policy for details.