// Debugging and troubleshooting patterns for NIC. Use when diagnosing failures, tracing issues, investigating NGINX reload errors, config generation bugs, or controller sync problems.
Task planning and approach strategy for NIC. Use when starting any non-trivial task, reading issues or specs, planning before implementing, or when asked to create a plan for a change.
CI/CD pipeline structure, GitHub Actions workflows, reusable workflow patterns, and matrix builds for NIC. Use when working on CI workflows, debugging build failures, adding new workflow steps, modifying build matrices, or understanding the release pipeline.
Docker image build system, Dockerfile structure, image variants, build scripts, and Makefile targets for NIC. Use when building container images, modifying the Dockerfile, adding new image variants, debugging image builds, or working with build scripts.
NIC architecture, resource processing pipeline, template systems, and key type definitions. Use when exploring the codebase, understanding data flow, debugging config generation, or working on controller logic.
Checklists for adding Ingress annotations, VirtualServer/VSR fields, or Helm chart values to NIC. Use when adding new configuration options, new NGINX directives, new annotations, new CRD fields, or new Helm values.
Step-by-step checklist for adding a new Policy CRD type to NIC. Use when implementing a new policy like AccessControl, RateLimit, JWTAuth, ExternalAuth, BasicAuth, IngressMTLS, EgressMTLS, OIDC, WAF, APIKey, Cache, or CORS, or extending the policy system with a new policy type.
| name | nic-debugging |
| description | Debugging and troubleshooting patterns for NIC. Use when diagnosing failures, tracing issues, investigating NGINX reload errors, config generation bugs, or controller sync problems. |
Symptom: Controller logs show "reload failed" or NGINX returns error status.
Diagnosis:
nginx -t output in logs — shows exact syntax error and line numbercontainsDangerousChars() check){{- if }} / {{- with }}) for optional fieldFix pattern:
make test — snapshot tests catch most template output issuesSymptom: User applies VirtualServer/Policy but NGINX config doesn't change.
Diagnosis:
kubectl get vs <name> -o yaml — look at .status.messagestatus.state: Invalid)Symptom: Pod restarts, panic in logs.
Diagnosis:
*bool/*int check).Spec.X fieldinternal/configs/ or internal/k8s/Symptom: make test fails with snapshot mismatch.
Diagnosis:
make test-update-snaps to regenerate| Context | Location | What to look for |
|---|---|---|
| Controller logs | Pod stdout/stderr | Sync errors, reload status, validation failures |
| NGINX error log | /var/log/nginx/error.log in container | Config syntax errors, upstream failures |
| NGINX access log | /var/log/nginx/access.log in container | Request routing verification |
| Tool | Command | Purpose |
|---|---|---|
| Config test | nginx -t (inside container) | Validate NGINX config syntax |
| CRD status | kubectl get vs,vsr,ts,pol -A | Check resource state |
| Controller logs | kubectl logs <pod> -n nginx-ingress | Runtime errors |
| Describe events | kubectl describe vs <name> | Kubernetes events for the resource |
| Generated config | kubectl exec <pod> -- cat /etc/nginx/conf.d/<file> | Inspect actual generated NGINX config |
status.state: Invalid with reasonmake test passes, snapshot output is correctWhen the generated NGINX config is wrong:
internal/configs/version2/http.go (VS) or internal/configs/version1/config.go (Ingress)internal/configs/virtualserver.go or internal/configs/ingress.go.tmpl file renders it? Check internal/configs/version2/nginx-plus.virtualserver.tmpl or the OSS variant_test.go file with the input that triggers the bug, run make test-update-snaps to capture current (wrong) output, then fix and regenerategeneratePolicies() logiccontainsDangerousChars() rejections appear as validation warnings, not hard errors — check the warnings map