Introduction

Kubernetes does not expose an nginx.conf file where you directly type proxy_pass for every application. Instead, you usually express proxying through higher-level resources such as Service and Ingress, and the ingress controller translates those resources into reverse-proxy configuration.

Start with a Service

The backend target for any proxy rule is normally a Kubernetes Service. That gives your proxy layer a stable DNS name and port even if Pods are replaced.

1apiVersion: v1
2kind: Service
3metadata:
4  name: api-service
5spec:
6  selector:
7    app: api
8  ports:
9    - port: 80
10      targetPort: 8080

The service above routes traffic sent to port 80 toward Pods listening on port 8080.

Express the Proxy Rule with Ingress

With the NGINX Ingress Controller, an Ingress resource is the common replacement for a manual proxy_pass directive. You declare host and path rules, and the controller builds the reverse-proxy configuration for you.

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

This setup tells the ingress controller to receive requests for example.com, match the /api path, rewrite the request path, and forward the result to api-service. Conceptually, that is your proxy pass behavior.

Path Rewriting and Header Forwarding

A lot of proxy configuration questions are really about rewriting or headers, not just forwarding. NGINX ingress exposes many of those behaviors through annotations.

For example, to add common proxy headers:

1metadata:
2  annotations:
3    nginx.ingress.kubernetes.io/configuration-snippet: |
4      proxy_set_header X-Forwarded-Host $host;
5      proxy_set_header X-Forwarded-Proto $scheme;

That snippet injects raw NGINX directives into the generated location block. It should be used carefully, because it ties the manifest to a specific ingress controller implementation.

When Ingress Is Not Enough

If you need behavior that is too custom for a standard ingress resource, you have a few options:

• Use controller-specific annotations or snippets.
• Deploy your own NGINX or Envoy proxy inside the cluster.
• Use a Gateway API implementation if your platform supports it.

For many teams, standard ingress rules are enough. The need for direct proxy_pass syntax usually appears only when complex rewrites, auth subrequests, or unusual upstream behavior are involved.

Internal Proxying Without Ingress

Sometimes the traffic never enters through an external ingress at all. A Pod can proxy directly to another service name inside the cluster.

An in-cluster NGINX config might look like this:

location /api/ {
    proxy_pass http://api-service.default.svc.cluster.local:80/;
}

That works, but note the difference: this is NGINX running as your own workload, not the Kubernetes Ingress abstraction. The manifest and operations model are different.

Debugging a Misbehaving Proxy Rule

When traffic does not route correctly, verify the chain in order:

1. The target Pods are healthy.
2. The Service selects the correct Pods.
3. The Ingress points to the right service name and port.
4. The ingress controller picked up the resource.
5. Path rewriting matches the application's expected URLs.

A surprising number of proxy issues are really path mismatches. The backend works, but the upstream application expects / while the ingress forwards /api/... unchanged.

Common Pitfalls

The most common mistake is looking for proxy_pass inside a normal Service. Services do not do HTTP path routing. They work at a lower networking layer.

Another mistake is relying on controller-specific annotations without confirming the installed ingress controller. An annotation for NGINX will not configure Traefik or another controller.

Path rewrite errors are also common. A route can appear correct while the backend still returns 404 because the rewritten path is not what the application expects.

Summary

• In Kubernetes, proxy behavior is usually declared with Service plus Ingress, not raw proxy_pass lines.
• The backend target is a service, not a Pod IP.
• Path rewriting and header control are commonly handled with ingress annotations.
• Use raw NGINX config only when you run your own proxy workload.
• Debug service selection, ingress rules, and rewrite behavior in that order.