nginx.ingress.kubernetes.io/rewrite-target annotation to adapt backend expectations.
Environment overview
Start by checking cluster nodes and deployments to locate the Ingress controller and application workloads.default namespace:
ingress-nginx-controller at 0/1 while it starts; it will transition to 1/1.)
List pods across all namespaces to confirm which namespace hosts the controller and the application pods:
- The NGINX Ingress controller runs in the
ingress-nginxnamespace. - Application workloads are deployed in the
app-spacenamespace.
Best practice: Keep Ingress resources in the same namespace as the application wherever possible so teams can manage access with namespace-scoped RBAC. This guide follows that approach for the new critical app.
Inspect the Ingress resource
List all Ingress resources to locate the one currently routing traffic for/wear and /watch:
ingress-wear-watch Ingress in app-space to see paths, backends, and annotations:
- The Ingress exposes
/wearand/watch, routing respectively towear-service:8080andvideo-service:8080. - The annotation
nginx.ingress.kubernetes.io/rewrite-target: /is present — this will rewrite matched prefixes to/before forwarding to the backend.
Change /watch to /stream
Requirement: make the video application available at /stream instead of /watch.
Edit the existing ingress-wear-watch to replace the /watch path with /stream. Ensure you use pathType: Prefix so that prefixes are matched and the existing rewrite remains functional.
Example spec.rules excerpt after editing:
/ by the annotation.
Add food delivery app at /eat
A new food delivery application (food-service) was migrated into app-space. Inspect services to confirm service names and ports:
ingress-wear-watch Ingress to add /eat routing to food-service:8080. Example spec snippet after the change:
kubectl edit or kubectl apply) and verify:
/eat. Verify with:
Expose a critical payment service in its own namespace
A critical payment application is deployed incritical-space and needs to be exposed at /pay. This demonstrates creating a namespace-scoped Ingress for a high-sensitivity app.
Inspect the new deployment and service:
pay-service exposes service port 8282; the pod may still serve on 8080. kubectl describe pod and kubectl describe svc will show the mappings.
Create a namespace-scoped Ingress that maps /pay to pay-service:8282. A quick create command:
/pay, check application logs:
- The Ingress forwards requests including the
/payprefix. The payment application expects requests at root/(it has no/payroute), so the backend returns 404.
- Add the
nginx.ingress.kubernetes.io/rewrite-target: /annotation to theingress-paymetadata and ensure the path usespathType: Prefix. This strips/paybefore forwarding the request to the service, allowing the backend to receive/.
kubectl edit or kubectl apply) and verify:
/:
/pay.
Summary & best practices
- Always inspect namespaces, services, and ports (
kubectl get svc -n <ns>) before editing Ingress resources. - Keep Ingress resources scoped to the application namespace when possible to simplify RBAC and team ownership.
- Use
nginx.ingress.kubernetes.io/rewrite-target: /to strip path prefixes if the backend expects root paths. - Use
pathType: Prefixfor prefix-based routing and combine it withrewrite-targetto ensure clean backend paths. - For multi-namespace exposure, either create namespace-local Ingress resources or use a central gateway with appropriate RBAC and routing rules.
When exposing apps from multiple namespaces, prefer namespace-local Ingress resources (or a central gateway with appropriate RBAC). Always verify annotations and
pathType settings so requests are routed and rewritten as intended.Quick reference tables
Service list inapp-space:
Ingress path → backend mapping (final state):