Customizing Ingress objects with annotations

A few examples of useful Kubernetes annotations for customizing behavior of Ingress objects in kubernetes cluster.

Custom max body size

For NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter client_max_body_size. 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:

nginx.ingress.kubernetes.io/proxy-body-size: value

Example of using body-size annotation:

kind: Ingress
metadata:
  annotations:
    certmanager.k8s.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/tls-acme: "true"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"

In this case setting size to 0 disables checking of client request body size.

--

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 you can use annotations that allows this customization:

nginx.ingress.kubernetes.io/proxy-connect-timeout: value

nginx.ingress.kubernetes.io/proxy-send-timeout: value

nginx.ingress.kubernetes.io/proxy-read-timeout: value

Example of using timeout annotation:

kind: Ingress
metadata:
  annotations:
    certmanager.k8s.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/tls-acme: "true"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

All timeout values are unitless and in seconds. In this example setting timeout to "120" sets a valid 120 seconds proxy read timeout.

--

Redirect using rewrite-target

You can simply redirect incoming requests to another url by using rewrite-target annotation:

nginx.ingress.kubernetes.io/rewrite-target: value

Example of using rewrite-target:

kind: Ingress
metadata:
  annotations:
    certmanager.k8s.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/tls-acme: "true"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/from-to-www-redirect: "true"
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/rewrite-target: https://example1.com/
  name: example-rewrite
spec:
  rules:
  - host: example2.com

In this example all trafic to www.example2.com is redirected to https://www.example1.com/

--

Redirect using server snippet

Using the annotation nginx.ingress.kubernetes.io/server-snippet it is possible to add custom configuration in the server configuration block. Be aware that this annotation can be used only once per host.

Example of using server snippet for redirect of specific url:

kind: Ingress
metadata:
  annotations:
    certmanager.k8s.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/ingress.class: nginx
    kubernetes.io/tls-acme: "true"
    nginx.ingress.kubernetes.io/server-snippet: |
      location ~ /b {
        rewrite / https:www.example1.sk$uri permanent;
      }
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/use-regex: "true"
  name: example-snippet
spec:
  rules:
  - host: www.example2.sk

In this example all trafic to www.example2.sk is directed to www.example2.sk, but www.example2.sk/b is redirected to www.example1.sk/b.

--

A word in conclusion

In this blog, I've only given a few examples. There are plenty of other annotations, for modifying the behavior of Ingress objects. You can find more on https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/