Advanced configuration with Annotations

This topic explains how to enable advanced features in F5 NGINX Ingress Controller with Annotations.

The Ingress resource can use basic NGINX features such as host or path-based routing and TLS termination. Advanced features like rewriting the request URI or inserting additional response headers can be enabled with Annotations.

Outside of advanced features, Annotations are necessary for customizing NGINX behavior such as setting the value of connection timeouts.

Customization is also available through the ConfigMap resources: Annotations take priority.

Using Annotations

This example uses Annotations to customize the configuration for an 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

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

You can check if NGINX Ingress Controller successfully applied the configuration for an Ingress resource. For the example cafe-ingress-with-annotations Ingress, you 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

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, NGINX 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, NGINX Ingress Controller will reject it and remove the corresponding configuration from NGINX.

The nginx.com/jwt-token Ingress annotation has limited validation.

Summary of Annotations

The table below summarizes the available annotations.

Note:
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)

Rate limiting

Snippets and custom templates

App Protect WAF

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

App Protect DoS

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