Introduction

The nginx.ingress.kubernetes.io/rewrite-target annotation changes the request path before traffic reaches the backend service. It is commonly used when clients access a service under a prefix such as /api, but the upstream application expects requests to arrive as / or with a different internal path.

The important detail is that the rewrite rule works together with your path match. If the Ingress path and the rewrite target do not agree, the backend will receive the wrong URL and the result is usually a 404 or an unexpected route.

Basic Rewrite Behavior

A classic example is exposing a service under /app while stripping that prefix before proxying.

1apiVersion: networking.k8s.io/v1
2kind: Ingress
3metadata:
4  name: demo-ingress
5  annotations:
6    nginx.ingress.kubernetes.io/rewrite-target: /
7spec:
8  ingressClassName: nginx
9  rules:
10    - host: example.com
11      http:
12        paths:
13          - path: /app
14            pathType: Prefix
15            backend:
16              service:
17                name: demo-service
18                port:
19                  number: 80

A request to https://example.com/app is sent to the backend as /. That is useful when the application does not know anything about the public /app prefix.

However, requests such as /app/users need more care. A plain rewrite to / discards the remainder of the path. If you want /app/users to become /users, use regex capture groups.

Rewriting With Captures

For prefix-stripping with the rest of the path preserved, use use-regex and a capture group.

1apiVersion: networking.k8s.io/v1
2kind: Ingress
3metadata:
4  name: demo-ingress
5  annotations:
6    nginx.ingress.kubernetes.io/use-regex: "true"
7    nginx.ingress.kubernetes.io/rewrite-target: /$2
8spec:
9  ingressClassName: nginx
10  rules:
11    - host: example.com
12      http:
13        paths:
14          - path: /app(/|$)(.*)
15            pathType: ImplementationSpecific
16            backend:
17              service:
18                name: demo-service
19                port:
20                  number: 80

Now the behavior is:

• '/app becomes /'
• '/app/ becomes /'
• '/app/users becomes /users'
• '/app/users/42 becomes /users/42'

This is the pattern most teams actually want.

How to Think About It

Read the path expression and rewrite target as one unit:

• The path decides what part of the incoming URL gets matched.
• The capture groups decide what parts are preserved.
• The rewrite target decides the final path sent upstream.

If the path is regex-based, pathType: ImplementationSpecific is usually the right choice with the NGINX Ingress Controller. If you use Prefix but still expect regex behavior, you will get confusing results.

You can verify what the backend receives by adding a temporary echo service and sending a few curl requests.

curl -H 'Host: example.com' http://INGRESS_IP/app
curl -H 'Host: example.com' http://INGRESS_IP/app/users

When You Should Avoid Rewriting

If the application can be configured with a base path, that is often cleaner than rewriting at the ingress layer. Rewrites are useful, but they add another place where path semantics can drift from application semantics.

For example, frameworks that generate links or redirects may need to know the public prefix. If ingress strips /app but the application thinks it lives at /, generated URLs may be wrong unless proxy headers and app configuration are aligned.

Common Pitfalls

A common mistake is setting rewrite-target: / and expecting deeper subpaths to survive automatically. They do not unless your rule captures and reuses them.

Another issue is forgetting nginx.ingress.kubernetes.io/use-regex: "true" while writing a regex-like path. Without regex mode, the controller interprets the path differently and the rewrite will not behave as expected.

Developers also often choose the wrong pathType. Regex-style matching with Prefix is a frequent source of confusion.

Finally, always test redirects, not only route handling. Even if incoming traffic reaches the backend, the application may still generate incorrect outbound links if it is unaware of the public path structure.

Summary

• 'rewrite-target changes the path before the request reaches the service.'
• Use a simple rewrite to / only when you want to discard the matched prefix entirely.
• Use regex capture groups when you need to preserve the remainder of the path.
• Match the rewrite rule, use-regex, and pathType consistently.
• If the app can understand a base path directly, that may be simpler than ingress rewrites.