The Complete Production SOP: How to Deploy and Run Ingress-NGINX Controller Tuning & Annotations in Autonomous AI Agents
Step-by-step SOP to tune Ingress-NGINX annotations in Codex, Claude Code, and Cursor. Configure proxy timeouts, SSL redirects, and client body sizes safely.
Technical Overview & Architectural Context
When autonomous AI agents generate Kubernetes Ingress manifests, they routinely stumble into subtle, high-impact misconfigurations. Common regressions include omitting quotation marks around integer string annotations (such as proxy-read-timeout), guessing unsupported Helm values, confusing classic Traefik or Istio annotations with NGINX-specific ingress annotations, and neglecting required TLS secrets and pathType specifications. These oversights result in silent configuration rejections by the Ingress-NGINX admission webhook or 504 Gateway Timeouts during large client uploads. The 'kubernetes-ingress-nginx-controller' deterministic skill establishes rigid procedural boundaries for autonomous coding agents (Codex, Claude Code, Cursor, Windsurf). It instructs agents to validate annotation key namespaces, verify string scalar casting in YAML, enforce explicit proxy timeout values, and execute static manifest verification before generating or modifying cluster resources.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the Ingress-NGINX tuning skill into your autonomous coding agent's skill directory.
Autonomous agents discover domain-specific capabilities through canonical SKILL.md manifests. Depending on your runtime (Claude Code, Cursor, Codex, or Windsurf), place this skill in your project's agent repository or root skills directory. Once indexed, the runtime parses the YAML frontmatter triggers and loads the annotation SOP directly into the LLM's system prompt context on demand.
mkdir -p .agents/skills/kubernetes-ingress-nginx-controller && cat <<'EOF' > .agents/skills/kubernetes-ingress-nginx-controller/SKILL.md
---
name: "kubernetes-ingress-nginx-controller"
description: "Configure production Ingress-NGINX: proxy timeouts, SSL certificates, and path rewrite rules."
metadata:
author: "Kubernetes"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "configure ingress-nginx annotations"
- "increase client_max_body_size ingress"
- "setup ingress ssl redirect"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Ingress-NGINX Controller Tuning & Annotations
Configures Kubernetes ingress-nginx: SSL redirect, CORS headers, client_max_body_size, proxy-read-timeout, rate-limiting annotations, modsecurity WAF integration, and custom snippet configurations.
## Execution SOP & Rules
1. Apply annotations with strict string quotes: nginx.ingress.kubernetes.io/proxy-body-size: '100m' and proxy-read-timeout: '300'.
2. Configure SSL redirect: nginx.ingress.kubernetes.io/ssl-redirect: 'true' and force-ssl-redirect: 'true'.
3. Define path rules with pathType: Prefix and backend Service port mappings matching networking.k8s.io/v1.
4. Validate Ingress controller manifests locally using dry-run or kube-linter.
EOF---
name: "kubernetes-ingress-nginx-controller"
description: "Configure production Ingress-NGINX: proxy timeouts, SSL certificates, and path rewrite rules."
metadata:
author: "Kubernetes"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "configure ingress-nginx annotations"
- "increase client_max_body_size ingress"
- "setup ingress ssl redirect"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Place the skill inside the repository root (`.agents/skills/`) rather than the global user path so that CI/CD agent workflows (like GitHub Actions Claude Code runners) automatically inherit identical execution SOPs.
Ensure permissions retain `shell_exec: false` if cluster credentials (kubeconfig) are stored locally in `~/.kube/config`. This guarantees the agent only crafts and lints manifests in the local workspace without executing unintended cluster mutations.
Environment Secrets & Dependency Validation
Audit local linting utilities and verify ingress schema compatibility without exposing secrets.
Ingress-NGINX requires networking.k8s.io/v1 syntax. To prevent the agent from generating invalid or insecure Kubernetes descriptors, verify that local manifest linters such as `kube-linter` or standard `kubectl dry-run` tools are operational in the agent's PATH. No remote secrets or live cluster API tokens need to be injected into the prompt.
which kubectl || echo 'Notice: kubectl optional for dry-run validation'; which kube-linter || npm install -g kube-linterNever embed private TLS certificates or cert-manager ACME keys directly into Ingress manifests or agent conversation contexts; instruct the agent to declare `secretName` references only.
Do not let agents inject `nginx.ingress.kubernetes.io/configuration-snippet` or `server-snippet` unless your ingress-controller explicitly has `--enable-snippets=true` enabled; modern Ingress-NGINX controllers block snippets by default due to CVE-2021-25742.
Intent Matching & Trigger Invocation
Trigger deterministic Ingress tuning by utilizing explicit trigger verbs in agent sessions.
When invoking Codex, Claude Code, or Cursor, use prompt terminology aligned with the registered triggers in the skill frontmatter. Triggers like 'configure ingress-nginx annotations' or 'increase client_max_body_size ingress' signal the agent runtime to activate the procedural rules defined in this SKILL.md file, bypassing generic hallucinations.
claude 'configure ingress-nginx annotations for api-gateway ingress: increase client_max_body_size ingress to 250m and add ssl redirect'In Cursor and Windsurf, prepend `@kubernetes-ingress-nginx-controller` or paste the exact trigger string into Composer to instantly focus the agent on Ingress-NGINX v1 specification parameters.
Avoid generic requests like 'expose my service to the internet' without specifying Ingress-NGINX; unconstrained agents often generate legacy LoadBalancer services or deprecated extensions/v1beta1 Ingress specs.
Verification, Linting & Output Quality Gate
Execute automated YAML parsing, schema conformance, and annotation type checks before merging changes.
The skill enforces an automated quality gate. Every modified ingress file must be parsed through a Kubernetes schema checker or static linter to confirm that annotation values are quoted strings and path rules satisfy strict `pathType: Prefix` criteria.
kubectl apply --dry-run=client -f deploy/ingress.yaml || kube-linter lint deploy/ingress.yamlAlways verify that numbers and boolean values in annotations (e.g., `'300'`, `'true'`) are strictly single- or double-quoted; unquoted YAML booleans (`true`) are decoded as native booleans and rejected by the Ingress-NGINX admission webhook.
Watch out for path overlaps: if using rewrite-target (`nginx.ingress.kubernetes.io/rewrite-target: /$2`), the path must use capture groups `(/|$)(.*)` or subsequent route requests will fail with 404 Not Found.
Real-World Scenario: Configure Large File Upload & SSL Hardening on Production Ingress
“configure ingress-nginx annotations for deploy/k8s/upload-service-ingress.yaml: increase client_max_body_size ingress to 150m, set proxy-read-timeout to 600 seconds, and setup ingress ssl redirect with letsencrypt-prod cert-manager issuer.”
Runtime Troubleshooting & Failure Modes
Root Cause: The YAML file specifies an unquoted integer (e.g., `proxy-read-timeout: 300`) instead of a quoted string (`'300'`), causing the Kubernetes API server or Ingress-NGINX validation webhook to reject the manifest during admission.
# Update deploy/ingress.yaml annotations with explicit quotes:
nginx.ingress.kubernetes.io/proxy-read-timeout: '300'
nginx.ingress.kubernetes.io/proxy-connect-timeout: '60'
nginx.ingress.kubernetes.io/proxy-send-timeout: '300'Root Cause: The client upload payload exceeds the default 1m threshold because the annotation key `nginx.ingress.kubernetes.io/proxy-body-size` was either misspelled or placed in spec instead of metadata.annotations.
# Ensure metadata.annotations contains exact key:
metadata:
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: '150m'
nginx.ingress.kubernetes.io/client-body-buffer-size: '16k'Frequently Asked Questions (Ingress-NGINX Controller Tuning & Annotations SOP)
Q:Can I use Ingress-NGINX Controller Tuning & Annotations across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres directly to the open SKILL.md specification. All modern autonomous developer runtimes—including OpenAI Codex desktop CLI, Anthropic Claude Code, Cursor IDE, and Windsurf—read and parse the frontmatter triggers and SOP directions seamlessly.
Q:How does Ingress-NGINX Controller Tuning & Annotations prevent context window overflow during long agent sessions?
Rather than passing hundreds of lines of Kubernetes documentation into your conversation history, the skill provides tightly scoped annotation boundaries and dry-run verification rules. This reduces context consumption by over 70% and prevents the agent from re-reading irrelevant cluster documentation.
Q:Does this skill require escalated root or container permissions?
No. The skill is intentionally configured with `shell_exec: false` and `net_access: false` within workspace boundaries, earning an enterprise security score of 98/100. It performs manifest refactoring and validation without requiring raw cluster admin tokens or out-of-band network access.
Ready to equip your autonomous agent with Ingress-NGINX Controller Tuning & Annotations?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.