When working with Kubernetes Ingress resources, annotations play a crucial role in efficiently customizing the behaviour of the Ingress Controller. NGINX Ingress annotations allow fine-grained control over how incoming traffic is handled. In this blog, we will explore Kubernetes annotations for ingress and how they can improve traffic management in your cluster.
What are annotations ?
Annotations in Kubernetes are simple key-value pairs you can add to objects. Annotations store extra information without affecting how the object behaves or is selected. For example, they hold metadata or configuration details that tools or external systems can use, even though Kubernetes itself doesn’t use them directly.
Annotations in Kubernetes Ingress resources
In Kubernetes, an Ingress resource manages external access to services inside your cluster, typically for HTTP or HTTPS traffic. An Ingress controller normally handles traffic routing with default settings but sometimes you need to customize how it manages traffic like setting up special routing rules, or other behaviours.
Instead of modifying the Ingress resource itself, annotation is a way to customize the behaviour of the Ingress controller.
Key Annotations for Ingress
nginx.ingress.kubernetes.io/rewrite-target
The nginx.ingress.kubernetes.io/rewrite-target annotation specifies the new path to which incoming requests should be rewritten.
Let’s understand it with an example:
Suppose you host multiple microservices under a same domain, with each microservice designed to handle requests at its root path (/). But for some reason you need to expose these services under distinct paths externally (e.g., /service1, /service2).
Solution:
You can use the nginx.ingress.kubernetes.io/rewrite-target annotation in your Ingress object that will redirect incoming requests from /service1 to /. This means that when a user access http://example.com/service1, the Ingress controller rewrites the path to / and forwards the request to the service1 backend.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- host: example.com
http:
paths:
- path: /service1
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80 With this ingress configuration, requests to http://example.com/service1 rewrite to http://example.com/. And the backend service (example-service) receives the request at its root path (/).
While this approach works for certain use cases, it is not always ideal—especially if your backend service has multiple endpoints like /login, /dashboard, or /api/data. Rewriting everything to / can break functionality because it removes all paths. To overcome this, you can use $2 to retain the part of the URL after the specified prefix.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /$2
nginx.ingress.kubernetes.io/use-regex: "true"
spec:
rules:
- host: example.com
http:
paths:
- path: /service1(/|$)(.*)
pathType: ImplementationSpecific
backend:
service:
name: example-service
port:
number: 80
How It Works
| Incoming Request | Backend Receives |
| /service1 | / |
| /service1/login | /login |
| /service1/api/data | /api/data |
This ensures that requests to http://example.com/service1/login are correctly forwarded to /login on the backend.
nginx.ingress.kubernetes.io/use-regex
By default, Kubernetes Ingress rules match paths exactly, which means that without this annotation, you would need to create multiple rules to handle similar URLs.
For the above rewrite-target: /$2, we use use-regex: “true” to enable regex-based path matching. The annotation nginx.ingress.kubernetes.io/use-regex: “true” tells Nginx to treat the path as a regular expression instead of a simple string match. In our Ingress configuration, the path:
/service1(/|$)(.*) - /service1(/|$) → Matches /service1 with or without a trailing slash.
- (.*) → Captures everything after /service1 into $2.
- With rewrite-target: /$2, Kubernetes removes only /service1 and the rest of the path stays the same.
nginx.ingress.kubernetes.io/app-root
The annotation nginx.ingress.kubernetes.io/app-root redirects the root path (/) to a specific sub path in a Nginx Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
nginx.ingress.kubernetes.io/app-root: "/app"
spec:
rules:
- host: example.com
http:
paths:
- path: /app
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80 This annotation helps when your application runs on a sub path (e.g., /app), but you want users accessing the root URL (/) to be redirected there automatically. If a user visit http://example.com/, they instantly redirected to http://example.com/app.
Conclusion
By understanding and utilizing annotations effectively, you can enhance observability, automate processes, and integrate seamlessly with external tools.If you want the entire code for this blog, I have published it in my repository.