Agent skill

NGINX Ingress Controller Debugging

by nginx in nginx/kubernetes-ingress

Troubleshooting patterns for the NGINX Ingress Controller: reload failures, custom resources that have no effect, controller panics and snapshot test failures.

Apache-2.0Auto-check passedDevOps & Cloud

Install NGINX Ingress Controller Debugging

skills CLI
$ npx skills add nginx/kubernetes-ingress --skill nic-debugging -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install nginx/kubernetes-ingress nic-debugging --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/nginx/kubernetes-ingress.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/nic-debugging .claude/skills/nic-debugging && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
nic-debugging
GitHub stars
5.1k
Token cost
~1.7k tokens
SKILL.md length
874 words
Files
1
Skills in repo
9
Repo updated
First seen
Licence
Apache-2.0

At a glance

Troubleshooting patterns for the NGINX Ingress Controller: reload failures, custom resources that have no effect, controller panics and snapshot test failures.

  • Works in 3 steps: Check controller logs for the generated… → Look for nginx -t output in logs — shows… → Common causes
  • Diagnosing an NGINX reload failure in the ingress controller
  • SKILL.md covers Common Failure Modes, Log Locations, Validation and Diagnostic Tools and Debugging Workflow, plus 3 more sections
  • Calls make, kubectl and git

What it does

The skill lists the most common failures in the NGINX Ingress Controller, each with a symptom, a diagnosis and a fix pattern. For a reload failure, check the controller logs for the generated config and the `nginx -t` output, which gives the exact syntax error and line. Typical causes are an unsanitized user string missing the `containsDangerousChars()` check, a template guard missing for an optional field, duplicate directives from conflicting policies and an invalid upstream when no endpoints exist. The fix is to validate earlier or repair the guard, then verify with `make test`.

A custom resource that has no effect is traced through `kubectl get vs`, its `.status.message`, controller sync errors, validation rejections, missing TLS, JWT or OIDC secrets, policies not found in the namespace and host or path conflicts. Controller panics are followed from the stack trace, usually into `internal/configs/` or `internal/k8s/`, with nil pointers on optional fields, unchecked map access and races as common causes. A snapshot test failure means template output changed, so you review the diff and either run `make test-update-snaps` or fix the template.

When your agent uses it

  • Diagnosing an NGINX reload failure in the ingress controller
  • Finding out why a VirtualServer or Policy resource has no effect
  • Tracing a controller panic or pod restart from its logs
  • Resolving snapshot test mismatches after a template change

Example prompts

  • “The controller logs say reload failed; find which generated directive broke nginx -t.”
  • “My VirtualServer shows state Invalid; work out why.”
  • “make test fails with a snapshot mismatch after my template edit; help me decide if it is intended.”
  • “Trace this controller panic back to the nil pointer in internal/configs.”

Requirements

  • A checkout of the nginx/kubernetes-ingress repository
  • kubectl access to the cluster running the controller
  • make to run the test suite

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Check controller logs for the generated config that failed
  2. Look for nginx -t output in logs — shows exact syntax error and line number
  3. Common causes

What it can do on your machine

Read from SKILL.md and the folder at commit f6d0615. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • make
    • kubectl
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use kubectl and git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

NGINX Ingress Controller Debugging loads about 1.7k tokens when it runs. Until then it costs about 49 tokens; SKILL.md has 874 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~49
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from nginx/kubernetes-ingress at commit f6d0615, republished under its Apache-2.0 licence (© nginx). 874 words, ~1,726 tokens.

Download SKILL.mdSave it as .claude/skills/nic-debugging/SKILL.md (or your agent's skills folder).
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.

Debugging and Troubleshooting

Common Failure Modes

NGINX Reload Failure

Symptom: Controller logs show "reload failed" or NGINX returns error status.

Diagnosis:

  1. Check controller logs for the generated config that failed
  2. Look for nginx -t output in logs — shows exact syntax error and line number
  3. Common causes:
    • Unsanitized user string injected into config (missing containsDangerousChars() check)
    • Template guard missing ({{- if }} / {{- with }}) for optional field
    • Duplicate directive from conflicting policies
    • Invalid upstream when no endpoints available

Fix pattern:

  • Find the template or config generation code that produced the bad directive
  • Add validation to reject the input earlier, OR fix the template guard
  • Verify with make test — snapshot tests catch most template output issues
CRD Not Taking Effect

Symptom: User applies VirtualServer/Policy but NGINX config doesn't change.

Diagnosis:

  1. Check CRD status: kubectl get vs <name> -o yaml — look at .status.message
  2. Check controller logs for sync errors on that resource
  3. Common causes:
    • Validation rejecting the resource (check status.state: Invalid)
    • Missing secret reference (TLS, JWT, OIDC secrets)
    • Policy referenced but not found in namespace
    • Resource conflicts (duplicate host/path)
Controller Crash / Panic

Symptom: Pod restarts, panic in logs.

Diagnosis:

  1. Check logs for the panic stack trace
  2. Common causes:
    • Nil pointer on optional CRD field (forgot *bool/*int check)
    • Map access without nil check on .Spec.X field
    • Race condition in concurrent secret/config access
  3. Look for the file:line in the stack trace → usually in internal/configs/ or internal/k8s/
Snapshot Test Failure

Symptom: make test fails with snapshot mismatch.

Diagnosis:

  1. This means template output changed — could be intentional or regression
  2. Review the diff shown in test output
  3. If change is intentional: make test-update-snaps, then re-read git diff -- '**/__snapshots__/**' to confirm only the expected directives moved
  4. If change is unintentional: your template edit had side effects — fix the template

The inverse failure is more dangerous: you edited a .tmpl and make test-update-snaps produced no diff. That is not a pass — it means no fixture sets the field your new branch depends on. Add the fixture in template_test.go / templates_test.go and regenerate.

Log Locations

ContextLocationWhat to look for
Controller logsPod stdout/stderrSync errors, reload status, validation failures
NGINX error log/var/log/nginx/error.log in containerConfig syntax errors, upstream failures
NGINX access log/var/log/nginx/access.log in containerRequest routing verification

Validation and Diagnostic Tools

ToolCommandPurpose
Config testnginx -t (inside container)Validate NGINX config syntax
CRD statuskubectl get vs,vsr,ts,pol -ACheck resource state
Controller logskubectl logs <pod> -n nginx-ingressRuntime errors
Describe eventskubectl describe vs <name>Kubernetes events for the resource
Generated configkubectl exec <pod> -- cat /etc/nginx/conf.d/<file>Inspect actual generated NGINX config

Debugging Workflow

  1. Reproduce — Get the exact error. Is it a reload failure? Wrong routing? Crash?
  2. Assess security impact — Before diving into the fix, ask:
    • Is this bug exploitable? (Can external input trigger it?)
    • Does the failure expose sensitive data in logs or error messages?
    • Could an attacker craft input to reach this code path?
    • If exploitable: flag for security review BEFORE fixing
  3. Locate the layer — Use logs and status to determine:
    • Validation layer? → status.state: Invalid with reason
    • Config generation? → Generated config has wrong directives
    • Template? → Snapshot test shows the issue
    • Controller? → Sync error in logs, resource not processed
  4. Isolate — Find minimum CRD/annotation that triggers the issue
  5. Fix — Make the change in the correct layer (don't fix templates for validation bugs)
  6. Verify — make test passes, snapshot output is correct
  7. Prevent — Add a test case that would catch this regression (include negative/malicious input tests if the bug was in a validation path)
Show full SKILL.md (280 more words)Show less

Config Generation Debugging

When the generated NGINX config is wrong:

  1. Find the template struct — Which struct feeds the template? Check internal/configs/version2/http.go (VS) or internal/configs/version1/config.go (Ingress)
  2. Find the config generator — Where is the struct populated? Check internal/configs/virtualserver.go or internal/configs/ingress.go
  3. Find the template — Which .tmpl file renders it? Check internal/configs/version2/nginx-plus.virtualserver.tmpl or the OSS variant
  4. Add a snapshot test — Create a test case in the appropriate _test.go file with the input that triggers the bug, run make test-update-snaps to capture current (wrong) output, then fix and regenerate

Common Gotchas When Debugging

  • NGINX config errors show line numbers in the GENERATED file, not your template — map back manually
  • Secret-related failures often show as "file not found" in NGINX logs (secret not written to filesystem yet)
  • Policy ordering matters — first matching policy wins, check generatePolicies() logic
  • Plus-only features will work in Plus template but silently produce invalid config in OSS template
  • containsDangerousChars() failures are validation errors and typically result in status.state: Invalid — check the CRD status message and controller logs

Security-Sensitive Debugging

When debugging an issue that involves user-provided input reaching NGINX config:

  1. Trace the input path — From CRD field / annotation → validation → config struct → template → NGINX config file. Identify every point where sanitization SHOULD happen.
  2. Check for injection — Can crafted input inject NGINX directives? Look for ;, {, }, $, newlines, backticks in the user-controlled value.
  3. Verify the guard — Does containsDangerousChars() or ValidateEscapedString() cover this path? If not, the bug is a security vulnerability.
  4. Never log secrets — When debugging TLS/JWT/OIDC issues, mask credential values. Log key names and paths, not contents.
  5. Check RBAC — If the issue involves unauthorized access, verify ServiceAccount permissions and RBAC role bindings before looking at code.

© nginx, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .github/skills/nic-debugging of nginx/kubernetes-ingress.

Open the folder on GitHubat commit f6d0615

Compare with similar skills

NGINX Ingress Controller Debugging next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

NGINX Ingress Controller Debugging compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
NGINX Ingress Controller Debugging this skillnginx/kubernetes-ingress5.1k—~1.7kAutomated safety check: PassApache-2.0
Nginx To Higress Migrationhigress-group/higress9.5k—~3.9kAutomated safety check: PassApache-2.0
Intrinsic Core Debuggingintrinsic-ai/intrinsic-core552—~3.8kAutomated safety check: NotesApache-2.0
Frontend Forge Extension Operationskubesphere/kubesphere17k—~3.2kAutomated safety check: PassCustom licence
Tgf Server Devthkhxm/tgf128—~1.3kAutomated safety check: NotesMIT
Kubernetes Troubleshooting with Inspektor Gadgetinspektor-gadget/inspektor-gadget2.9k—~2.3kAutomated safety check: PassApache-2.0

Similar skills

  • Nginx To Higress Migration

    higress-group/higress

    Migrate from ingress-nginx to Higress in Kubernetes environments.

    9.5k GitHub stars~3.9k tokensUpdated 2 days ago
    DevOps & CloudAuto-check passed
  • Intrinsic Core Debugging

    intrinsic-ai/intrinsic-core

    Meta-level debugging workflows, architectural layer isolation, and progressive disclosure routing across Envoy ingress, Kubernetes pods, Behavior Trees, ObjectWorld synchronization, ICON real-time…

    552 GitHub stars~3.8k tokensUpdated today
    DevOps & CloudAuto-check: notes
  • Runs the lifecycle of FrontendExtension resources in a Kubernetes cluster: create, rebuild, package, publish, unpublish, delete and debug stuck states.

    17k GitHub stars~3.2k tokensUpdated 2 mo ago
    DevOps & CloudAuto-check passed
  • Tgf Server Dev

    thkhxm/tgf

    基于 tgf v2(github.com/thkhxm/tgf/v2)用确定性的 tgfctl 工作流创建、验证和维护 Go 游戏服务器项目。

    128 GitHub stars~1.3k tokensUpdated 2 mo ago
    DatabasesAuto-check: notes
  • Kubernetes Troubleshooting with Inspektor Gadget

    inspektor-gadget/inspektor-gadget

    Traces what the kernel is doing for a misbehaving pod using Inspektor Gadget's eBPF tools, tagged with namespace, pod, container and node, without changing workloads.

    2.9k GitHub stars~2.3k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Frontend Forge FI Operations

    kubesphere/kubesphere

    Operates FrontendIntegration resources and the frontend-forge extension with kubectl: create from YAML, update, enable, disable, delete, inspect and troubleshoot builds.

    17k GitHub stars~1.3k tokensUpdated 2 mo ago
    DevOps & CloudAuto-check passed

More from nginx/kubernetes-ingress

All 9 skills in this repo
  • Gives step-by-step checklists for adding Ingress annotations, VirtualServer fields and Helm values to the NGINX Kubernetes Ingress Controller, with common gotchas.

    5.1k GitHub stars~1.4k tokensUpdated today
    Auto-check passed
  • NGINX Ingress Policy CRD Guide

    nginx/kubernetes-ingress

    Step-by-step checklist for adding a new Policy CRD type to the NGINX Ingress Controller, from the Go types and validation to config generation and templates.

    5.1k GitHub stars~2k tokensUpdated today
    Auto-check passed
  • NGINX Ingress CI Pipelines

    nginx/kubernetes-ingress

    Explains how the NGINX Ingress Controller's GitHub Actions workflows, reusable workflows, build matrices and release pipeline fit together across two repositories.

    5.1k GitHub stars~5k tokensUpdated today
    Auto-check passed
  • Explains the multi-stage Dockerfile, the 25 image variant combinations, and the Makefile targets for building NGINX Ingress Controller images.

    5.1k GitHub stars~2.9k tokensUpdated today
    Auto-check passed
  • NGINX Ingress Controller Structure

    nginx/kubernetes-ingress

    Maps the NGINX Kubernetes Ingress Controller codebase: repository layout, architectural layers, layer-crossing rules and which files are generated.

    5.1k GitHub stars~3.8k tokensUpdated today
    Auto-check passed
  • NIC Testing Patterns

    nginx/kubernetes-ingress

    Testing conventions for the NGINX Ingress Controller repo: Go table-driven tests, mandatory snapshot regeneration, Helm tests and Python pytest integration tests.

    5.1k GitHub stars~2.8k tokensUpdated today
    Auto-check passed

Questions about NGINX Ingress Controller Debugging

What does NGINX Ingress Controller Debugging do?

Troubleshooting patterns for the NGINX Ingress Controller: reload failures, custom resources that have no effect, controller panics and snapshot test failures. The skill lists the most common failures in the NGINX Ingress Controller, each with a symptom, a diagnosis and a fix pattern. For a reload failure, check the controller logs for the generated config and the `nginx -t` output, which gives the exact syntax error and line.

When should I use NGINX Ingress Controller Debugging?

NGINX Ingress Controller Debugging fits situations like: diagnosing an NGINX reload failure in the ingress controller; finding out why a VirtualServer or Policy resource has no effect; tracing a controller panic or pod restart from its logs; resolving snapshot test mismatches after a template change.

How do I install NGINX Ingress Controller Debugging in Claude Code?

Run `npx skills add nginx/kubernetes-ingress --skill nic-debugging -a claude-code`. Or copy the skill folder (.github/skills/nic-debugging in nginx/kubernetes-ingress) into .claude/skills/nic-debugging in your project. Claude Code loads it when a task matches its description.

How do I install NGINX Ingress Controller Debugging in Codex?

Run `npx skills add nginx/kubernetes-ingress --skill nic-debugging -a codex`. Or copy the skill folder (.github/skills/nic-debugging in nginx/kubernetes-ingress) into .agents/skills/nic-debugging in your project. Codex loads it when a task matches its description.

Can I use NGINX Ingress Controller Debugging in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add nginx/kubernetes-ingress --skill nic-debugging -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/nic-debugging, .gemini/skills/nic-debugging, .github/skills/nic-debugging and .opencode/skills/nic-debugging in your project.

What does NGINX Ingress Controller Debugging need to run?

Going by SKILL.md and its folder, NGINX Ingress Controller Debugging needs the command-line tools its instructions call (make, kubectl and git). Our summary lists: A checkout of the nginx/kubernetes-ingress repository; kubectl access to the cluster running the controller; make to run the test suite.

Does NGINX Ingress Controller Debugging access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is NGINX Ingress Controller Debugging safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does NGINX Ingress Controller Debugging use?

NGINX Ingress Controller Debugging is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does NGINX Ingress Controller Debugging use?

About 1.7k tokens (SKILL.md is roughly 6.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to NGINX Ingress Controller Debugging?

Skills that share tags, products or a category with NGINX Ingress Controller Debugging: Nginx To Higress Migration (higress-group/higress, 9.5k stars), Intrinsic Core Debugging (intrinsic-ai/intrinsic-core, 552 stars), Frontend Forge Extension Operations (kubesphere/kubesphere, 17k stars) and Tgf Server Dev (thkhxm/tgf, 128 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains NGINX Ingress Controller Debugging?

nginx (a GitHub organization) maintains it in nginx/kubernetes-ingress, which has 5,082 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 7, 2026.

Source: nginx/kubernetes-ingress on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.