| name | troubleshoot |
| description | adapter-k8s deployment diagnosis expert guidance. Use when debugging a deployed release — pods CrashLoopBackOff, 404s or wrong routing, middleware not running at the edge, cache not shared across replicas, NetworkPolicy not enforced, ImagePullBackOff, 503 from the load balancer, or failing doctor checks. Triggers on "why isn't my deploy working" and any adapter-k8s doctor FAIL output. |
Deployed Release Troubleshooting
You are a diagnosis orchestrator for @next-community/adapter-k8s releases. Do not guess from symptoms alone — run npx adapter-k8s doctor first, read its PASS/WARN/FAIL lines, and branch from there. Every FAIL prints a Fix: line; start with it. Ground claims in command output, never in what "should" be true.
Rules
- Doctor first, always. It checks tools,
infrastructure.json, adapter.config.*, deploy state, Gateway/HTTPRoute acceptance, per-pool Deployment health, active Service endpoints, pod logs, LB backend health, ext_proc wiring, and per-host DNS/TLS — in one pass. Exit code 1 means at least one FAIL.
- Trust names, not labels. Release name resolution is:
--release-name flag → releaseName in .k8s-adapter/infrastructure.json → sanitized directory name. Running doctor from the wrong directory targets the wrong cluster (e2e-cluster vs test-app-cluster).
- A "Deploy state" FAIL blocks deploy — deploy refuses to run until cluster state is readable, because an unreadable state would look like a first deploy.
- Never edit the
<release>-routing-manifest ConfigMap or Service selectors by hand. The routing pod refuses to start on a manifest that does not match its baked copy (fail-closed by design), and deploy/rollback patch Services by name because Helm rewrites the managed-by label.
