Introduction

The usual way to add a custom nginx.conf to a Kubernetes workload is to store the file in a ConfigMap and mount it into the container. That keeps the image immutable, makes configuration changes reviewable in manifests, and gives you a predictable rollout path when NGINX behavior changes.

Create the NGINX Configuration First

Start with a valid nginx.conf. Kubernetes will mount exactly what you give it, so syntax problems become pod startup or reload failures.

1worker_processes auto;
2
3events {
4  worker_connections 1024;
5}
6
7http {
8  server {
9    listen 80;
10
11    location /healthz {
12      return 200 "ok\n";
13    }
14
15    location / {
16      proxy_pass http://app.default.svc.cluster.local:8080;
17      proxy_set_header Host $host;
18      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
19    }
20  }
21}

Testing the file locally before pushing it into the cluster saves time, especially if the configuration is complex.

Put nginx.conf in a ConfigMap

You can create the ConfigMap imperatively from the file.

kubectl create configmap nginx-conf --from-file=nginx.conf
kubectl get configmap nginx-conf -o yaml

In team environments, it is usually better to represent the ConfigMap as YAML in source control so the configuration change is reviewable like code.

Mount the ConfigMap into the Pod

Mount the config file at /etc/nginx/nginx.conf. Using subPath is important when you want to replace one file rather than hide the whole directory.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: nginx-proxy
5spec:
6  replicas: 2
7  selector:
8    matchLabels:
9      app: nginx-proxy
10  template:
11    metadata:
12      labels:
13        app: nginx-proxy
14    spec:
15      containers:
16        - name: nginx
17          image: nginx:1.27
18          ports:
19            - containerPort: 80
20          volumeMounts:
21            - name: nginx-config
22              mountPath: /etc/nginx/nginx.conf
23              subPath: nginx.conf
24      volumes:
25        - name: nginx-config
26          configMap:
27            name: nginx-conf

If you mount the entire /etc/nginx directory accidentally, you can mask other files the image expects and create confusing startup failures.

Validate the Mounted File

After deploying, verify that the file is present and that NGINX accepts it.

1kubectl rollout status deployment/nginx-proxy
2pod=$(kubectl get pod -l app=nginx-proxy -o jsonpath='{.items[0].metadata.name}')
3kubectl exec "$pod" -- cat /etc/nginx/nginx.conf
4kubectl exec "$pod" -- nginx -t

nginx -t is the key validation step. Kubernetes can mount a file successfully even if the file is not a valid NGINX configuration.

Roll Out Configuration Changes Safely

Updating a ConfigMap does not guarantee that an existing NGINX container will reload the new file automatically. A common approach is to update the ConfigMap and then restart the deployment.

kubectl apply -f nginx-configmap.yaml
kubectl rollout restart deployment/nginx-proxy
kubectl rollout status deployment/nginx-proxy

In more advanced setups, teams add a checksum annotation to the pod template so configuration changes trigger a rollout automatically.

Add Health Checks and Service Wiring

If NGINX fronts real traffic, pair the configuration with readiness and liveness probes. That keeps broken pods out of rotation while a bad configuration is being fixed.

1readinessProbe:
2  httpGet:
3    path: /healthz
4    port: 80
5  initialDelaySeconds: 3
6  periodSeconds: 5
7livenessProbe:
8  httpGet:
9    path: /healthz
10    port: 80
11  initialDelaySeconds: 10
12  periodSeconds: 10

Expose the deployment with a Service only after the pod-level behavior is correct.

Common Pitfalls

• Mounting the ConfigMap to the wrong path leaves NGINX reading the image default config instead of your file.
• Replacing the whole /etc/nginx directory instead of using subPath can hide required image files.
• Updating the ConfigMap and assuming the running pods automatically reload it leads to stale configuration.
• Skipping nginx -t lets invalid configuration reach production pods.
• Deploying without readiness probes can route traffic to pods that started but are not actually usable.

Summary

• Store nginx.conf in a ConfigMap so configuration stays separate from the image.
• Mount the file precisely at /etc/nginx/nginx.conf using subPath.
• Validate the mounted configuration from inside the pod with nginx -t.
• Restart or roll out the deployment after updating the ConfigMap.
• Add probes and service wiring so NGINX joins cluster traffic safely.