Introduction

When you install the NGINX Ingress controller with Helm, the usual way to set controller-level NGINX options is through chart values that render into the controller ConfigMap. The key idea is that Helm manages the ConfigMap for you, so you generally change values.yaml and upgrade the release instead of editing the generated ConfigMap by hand.

Use controller.config in Helm values

For the common ingress-nginx chart pattern, the controller configuration lives under controller.config. Each key becomes a ConfigMap entry consumed by the controller.

1controller:
2  config:
3    use-forwarded-headers: "true"
4    proxy-body-size: "16m"
5    proxy-read-timeout: "120"
6    proxy-send-timeout: "120"

Then apply the change with Helm:

1helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \
2  --namespace ingress-nginx \
3  --create-namespace \
4  -f values.yaml

This keeps the Helm release as the source of truth.

Verify the generated ConfigMap

After the upgrade, inspect the rendered ConfigMap instead of assuming the values were applied.

kubectl get configmap -n ingress-nginx
kubectl get configmap ingress-nginx-controller -n ingress-nginx -o yaml

The exact ConfigMap name depends on the chart and release name, but the controller usually references it automatically when Helm created the resource.

Do not edit the ConfigMap manually if Helm owns it

You can patch the ConfigMap directly with kubectl edit, but Helm may overwrite those changes on the next upgrade. That creates configuration drift and makes debugging harder.

The reliable workflow is:

1. Change values.yaml.
2. Run helm upgrade.
3. Verify the generated ConfigMap and controller behavior.

That way the deployed state stays reproducible.

Use extra ConfigMaps only when the chart explicitly supports them

Some charts allow a reference to an externally managed ConfigMap, but you should confirm the chart values before assuming that pattern exists. In many setups, controller.config is enough. If your organization wants a separately managed ConfigMap, make sure the chart has a value for that integration and document who owns it.

When the chart does not support an external reference cleanly, forcing the issue usually creates brittle templates.

Example: enable client IP and timeouts

A common real-world configuration is trusting forwarded headers from a load balancer and increasing proxy timeouts.

1controller:
2  config:
3    use-forwarded-headers: "true"
4    compute-full-forwarded-for: "true"
5    proxy-connect-timeout: "30"
6    proxy-read-timeout: "180"
7    proxy-send-timeout: "180"

That configuration affects the controller globally, so review the impact on every ingress that uses it.

Test before and after deployment

Helm can render templates locally before applying them.

helm template ingress-nginx ingress-nginx/ingress-nginx -f values.yaml

This is useful for confirming that your values land in the ConfigMap exactly as intended. After deployment, inspect controller logs and behavior for the setting you changed. Configuration that looks right in YAML can still be ineffective if the key name is wrong or if the controller version does not support it.

Common Pitfalls

• Editing the live ConfigMap manually even though Helm will overwrite it later.
• Putting controller settings in the wrong place in values.yaml instead of under controller.config.
• Forgetting that ConfigMap changes affect the ingress controller globally, not just one application.
• Assuming every chart version supports the same ConfigMap keys or external ConfigMap references.
• Skipping verification after helm upgrade and assuming the controller consumed the new values.

Summary

• Prefer controller.config in Helm values for NGINX Ingress controller settings.
• Treat Helm values as the source of truth, not ad hoc kubectl edit changes.
• Inspect the rendered ConfigMap after deployment.
• Test keys locally with helm template when you are unsure.
• Be careful because controller ConfigMap changes are global to that controller instance.