kubectl ingress-nginx: Debug the Ingress Controller
kubectl ingress-nginx is a krew plugin that inspects the ingress-nginx controller: its backends, the generated nginx.conf, and per-Ingress config.
When an Ingress route misbehaves, this plugin shows what the controller actually generated, which is far faster than exec-ing into the pod by hand.
What it does
kubectl ingress-nginx wraps common ingress-nginx debugging tasks: backends prints the controllers view of upstream backends, conf prints the generated nginx.conf (optionally for one host), ingresses lists Ingress objects and their state, and lint checks for deprecated or invalid annotations.
Common usage
# list what the controller sees
kubectl ingress-nginx ingresses -n ingress-nginx
# dump generated nginx.conf for a host
kubectl ingress-nginx conf -n ingress-nginx --host example.com
# lint for deprecated annotations
kubectl ingress-nginx lint --all-namespacesOptions
| Subcommand / flag | What it does |
|---|---|
| backends | Show the controllers backend/upstream state |
| conf --host <h> | Print the generated nginx.conf (optionally per host) |
| ingresses | List Ingress objects and their addresses |
| lint | Flag deprecated or invalid annotations |
| -n, --namespace <ns> | Controller namespace |
In CI
Run kubectl ingress-nginx lint --all-namespaces in a pipeline to catch deprecated annotations before an ingress-nginx upgrade removes them. Snapshot conf in a smoke test to assert a route was generated as expected.
Common errors in CI
"Error: unknown command \"ingress-nginx\" for \"kubectl\"" means the krew plugin is not installed on the runner; install it with kubectl krew install ingress-nginx. "no ingress-nginx pods found" means the controller is in another namespace; pass -n. A KUBECONFIG that is unset yields "The connection to the server ... was refused".