Introduction

Rewriting one path in ingress-nginx is a common requirement when migrating APIs or preserving legacy routes. The subtle part is that rewrite annotations often apply to all paths in the same Ingress resource. This guide shows a safe pattern to rewrite only one path while leaving others unchanged.

Core Topic Sections

Why single-path rewrite is tricky

The annotation nginx.ingress.kubernetes.io/rewrite-target applies at the Ingress object level, not per-path in the same object. If you place many routes in one resource and add rewrite annotations, all matching paths may be affected.

The practical solution is:

1. Put the rewritten path in its own Ingress resource.
2. Keep non-rewritten routes in a separate Ingress resource.
3. Use the same host in both resources.

ingress-nginx merges rules by host and path, so this layout works well.

Base routes without rewrite

Create an Ingress for normal routes that should pass through unchanged.

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

No rewrite annotation is present, so these paths keep original URI semantics.

Separate Ingress for the single rewrite

Now isolate only the legacy path that must be rewritten.

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

Request behavior:

1. /legacy/orders becomes /api/v1/orders upstream.
2. /api/v1/orders and /api/v2/orders remain unchanged.

Validate generated NGINX behavior

After apply, verify status and test routes.

1kubectl apply -f app-routes.yaml
2kubectl apply -f legacy-rewrite.yaml
3kubectl describe ingress -n web app-routes
4kubectl describe ingress -n web legacy-rewrite

Quick functional tests:

curl -i https://api.example.com/legacy/health
curl -i https://api.example.com/api/v1/health
curl -i https://api.example.com/api/v2/health

Use backend logs to confirm request URI seen by each service.

Path matching and precedence notes

ingress-nginx path precedence can surprise teams when regex and prefix rules mix. Keep regex usage explicit and document intent in each rule. Avoid overlapping patterns when possible.

Recommended hygiene:

1. Use specific patterns for rewritten routes.
2. Keep rewritten route in dedicated resource.
3. Add regression tests for representative URLs.

This prevents accidental routing changes during future edits.

Migration pattern for legacy APIs

Single-path rewrites are often temporary during API migration. Treat them as transitional infrastructure:

1. Add metrics for rewritten route volume.
2. Notify clients about deprecation timeline.
3. Remove rewrite once traffic has moved to canonical path.

Tracking usage prevents permanent accumulation of compatibility rules.

Security and observability considerations

Rewrites can hide the original URI context if logging is limited. Ensure logs include both incoming path and upstream path when debugging auth and rate-limiting behavior.

Also verify that WAF or policy engines evaluate the intended path stage, especially in regulated workloads.

Common Pitfalls

• Putting rewrite annotations on a multi-path Ingress and unintentionally rewriting every path.
• Forgetting use-regex while using capture groups in paths.
• Using overlapping regex paths that cause unexpected route selection.
• Skipping end-to-end tests and discovering rewrite mistakes in production.
• Leaving temporary legacy rewrites in place without ownership or cleanup plan.

Summary

• Rewrite annotations are resource-level, so isolate rewritten path in its own Ingress.
• Keep normal routes in a separate Ingress to avoid collateral changes.
• Use regex capture groups carefully and validate with real requests.
• Monitor rewritten traffic as part of migration strategy.
• Document path precedence and test routing behavior continuously.