Advanced Configuration with Annotations

This document explains how to use advanced features using annotations.

The Ingress resource only allows you to use basic NGINX features – host and path-based routing and TLS termination. Thus, advanced features like rewriting the request URI or inserting additional response headers are not available.

In addition to using advanced features, often it is necessary to customize or fine tune NGINX behavior. For example, set the value of connection timeouts.

Annotations applied to an Ingress resource allow you to use advanced NGINX features and customize/fine tune NGINX behavior for that Ingress resource.

Customization and fine-tuning is also available through the ConfigMap. Annotations take precedence over the ConfigMap.

Using Annotations

Here is an example of using annotations to customize the configuration for a particular Ingress resource:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-with-annotations
  annotations:
    nginx.org/proxy-connect-timeout: "30s"
    nginx.org/proxy-read-timeout: "20s"
    nginx.org/client-max-body-size: "4m"
    nginx.org/server-snippets: |
      location / {
        return 302 /coffee;
      }      
spec:
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee
        pathType: Prefix
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

Validation

The Ingress Controller validates the annotations of Ingress resources. If an Ingress is invalid, the Ingress Controller will reject it: the Ingress will continue to exist in the cluster, but the Ingress Controller will ignore it.

You can check if the Ingress Controller successfully applied the configuration for an Ingress. For our example cafe-ingress-with-annotations Ingress, we can run:

$ kubectl describe ing cafe-ingress-with-annotations
. . .
Events:
  Type     Reason          Age   From                      Message
  ----     ------          ----  ----                      -------
  Normal   AddedOrUpdated  3s    nginx-ingress-controller  Configuration for default/cafe-ingress-with-annotations was added or updated

Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied.

If you create an invalid Ingress, the Ingress Controller will reject it and emit a Rejected event. For example, if you create an Ingress cafe-ingress-with-annotations, with an annotation nginx.org/redirect-to-https set to yes please instead of true, you will get:

$ kubectl describe ing cafe-ingress-with-annotations
. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  13s   nginx-ingress-controller  annotations.nginx.org/redirect-to-https: Invalid value: "yes please": must be a boolean

Note how the events section includes a Warning event with the Rejected reason.

Note: If you make an existing Ingress invalid, the Ingress Controller will reject it and remove the corresponding configuration from NGINX.

The following Ingress annotation currently has limited validation:

• nginx.com/jwt-token.

Summary of Annotations

The table below summarizes the available annotations.

Note: The annotations that start with nginx.com are only supported with NGINX Plus.

General Customization

Request URI/Header Manipulation

Auth and SSL/TLS

Listeners

Backend Services (Upstreams)

Snippets and Custom Templates

App Protect

Note: The App Protect annotations only work if App Protect WAF module is installed.

App Protect DoS

Note: The App Protect DoS annotations only work if App Protect DoS module is installed.