Menu
Diagnoses unhealthy Control Plane workloads. Use when asked why a workload is crashing, not starting, OOMKilled, ImagePullBackOff, returning 502s, failing health checks, unreachable, or stuck deploying.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Writes cpln CLI commands and workflows for Control Plane. Use when the user asks about cpln login, cpln apply, cpln workload, CLI or CI/CD deploys, container debugging with cpln exec/logs, or any cpln resource command.
Promotes workloads across dev/staging/production on Control Plane. Use when the user asks about environment promotion, org-per-environment, cross-org image pulls, image promotion, deploying to production, or rollback.
Sets up CI/CD pipelines and GitOps for Control Plane. Use when the user asks about GitHub Actions, GitLab CI, Bitbucket, CircleCI, building images in CI, kaniko, cpln apply in pipelines, or service-account tokens for CI.
Builds, pushes, and manages container images on Control Plane. Use when the user asks about Docker build, remote build, image registry, tags, digests, Dockerfile, buildpacks, pull secrets, ECR/GCR, or image permissions.
Primary skill for creating, updating, running, and debugging workloads on Control Plane; routes to a deeper skill per subject. Use when the user asks to deploy or run a container, app, API, service, worker, or job, or to change, scale, expose, secure, or diagnose one.
CDN caching and request rate limiting for Control Plane workloads. Use when the user asks about CDN, Cloudflare, CloudFront, edge caching, rate limiting, request throttling, per-key or per-route limits, or DDoS protection.
| name | workload-troubleshooting |
| description | Diagnoses unhealthy Control Plane workloads. Use when asked why a workload is crashing, not starting, OOMKilled, ImagePullBackOff, returning 502s, failing health checks, unreachable, or stuck deploying. |
The symptom-first companion to the workload skill (which owns workload types, the spec shape, and the create/update tools). Given an unhealthy workload, map what you observe to its platform-specific root cause and a fix the schema will actually accept. Diagnosis is read-only and MCP-first; most failures trace to a Control Plane rule a generic engineer would not guess โ deny-by-default firewalls, the secret identity+policy chain, blocked ports, the sleep-binary shutdown rule. The single most common is OOMKilled. Deep remediation for each area lives in the domain skill named in that section; this skill is the diagnostic map.
| Tool | What it tells you |
|---|---|
mcp__cpln__list_deployments | Start here. Per-location readiness with reason/message. Pass location to drill into one failing location. |
mcp__cpln__get_workload_events | Image pulls, crashes, scheduling, probe failures, OOMKilled. |
mcp__cpln__get_workload_logs | App logs (LogQL); the _accesslog container holds HTTP status codes and latency. |
mcp__cpln__get_resource (kind=workload) | The spec and current status. |
mcp__cpln__list_metrics then mcp__cpln__query_metrics | Resource pressure โ memory before OOM, CPU, latency. |
mcp__cpln__list_workload_replicas then mcp__cpln__workload_exec | Inspect a live replica. workload_exec runs in a production container and is audit-logged โ read-only commands only (ls, cat, netstat); never dump resolved secret values (env prints them on a secret-consuming workload), and confirm before anything that mutates. |
mcp__cpln__query_traces then mcp__cpln__get_trace | For a slow or intermittently failing request: which span in the path spent the time or errored. Needs tracing enabled on the GVC (opt-in). Deep dive in metrics-observability. |
CLI fallback (MCP unavailable, interactive shell, or CI/CD):
cpln workload get WORKLOAD --gvc GVC -o json
cpln workload eventlog WORKLOAD --gvc GVC -o json
cpln logs '{gvc="GVC", workload="WORKLOAD"}' --limit 50 # |= "error" filters; container="_accesslog" for HTTP codes
cpln workload connect WORKLOAD --gvc GVC --location LOCATION # interactive shell
Symptoms: container restarts repeatedly, events show OOMKilled, crashes under load.
memory is a hard cap โ exceed it (app + runtime + GC + buffers) and the kernel kills the container. Usual culprits: Java without -Xmx, Node without --max-old-space-size, Python loading large datasets. Each container, sidecars included, has its own limit. With Capacity AI on, spiky workloads can be downsized too aggressively โ set minMemory as a floor (Capacity AI never downscales CPU below 25 millicores).
Fix: check real usage with query_metrics, then raise memory โ but memory (MiB) must stay within 8ร CPU (millicores), so raise cpu alongside it or the update is rejected (the default cpu: 50m caps memory at 400Mi). See Apply fixes within the schema's limits.
Symptoms: events show ImagePullBackOff / ErrImagePull, deployment stuck.
//image/NAME:TAG (org registry), bare NAME:TAG (Docker Hub, no docker.io/), full URL (other registries).linux/amd64 for managed locations (BYOK allows more).pullSecretLinks; only docker, ecr, gcp secret types work, and org //image/ images need none.The registry secret must already exist (created by the user โ offer a manifest scaffold for them to fill and apply, setup-secret skill); attach with update_gvc. Deep setup: image skill.
Symptoms: env vars empty, logs show missing config, secret-access errors in events.
A workload reaches a secret only with all three in place: an identity linked to it (spec.identityLink), a policy granting that identity reveal on the secret, and a correct reference. Fastest fix: grant_workload_secret_access builds the whole chain in one call. Reference format by type:
| Type | Reference |
|---|---|
| Opaque (decoded / raw) | cpln://secret/NAME.payload / cpln://secret/NAME |
| Dictionary | cpln://secret/NAME.KEY |
| Username & password | cpln://secret/NAME.username / .password |
| Keypair | cpln://secret/NAME.secretKey / .publicKey / .passphrase |
| TLS | cpln://secret/NAME.cert / .key / .chain |
| AWS | cpln://secret/NAME.accessKey / .secretKey / .roleArn / .externalId |
The manual chain: access-control and setup-secret skills.
netstat -tln via workload_exec.PORT and rejects a PORT env var that doesn't equal the exposed port.8012, 8022, 9090, 9091, 15000, 15001, 15006, 15020, 15021, 15090, 41000.Symptoms: unreachable externally, can't reach external APIs, or can't talk to other workloads.
Deny-by-default: external inbound disabled, external outbound disabled, internal none. Fix via update_workload:
external.inboundAllowCIDR (e.g. 0.0.0.0/0, or specific CIDRs).external.outboundAllowCIDR, or outboundAllowHostname (hostname rules reach only ports 80, 443, 445).internal.inboundAllowType: same-gvc / same-org / workload-list (default none blocks all workload-to-workload traffic).Full model: firewall-networking skill.
Symptoms: events show probe failures, replicas unready, restarts.
Default probes: serverless gets readiness + liveness TCP on the container port; standard, stateful, and cron have none (cron strips them). Common fixes: raise initialDelaySeconds (0-600; default 10 readiness / 60 liveness) for slow starts; raise periodSeconds (1-600, default 10) or timeoutSeconds (1-600, default 1) for over-aggressive probes; ensure an HTTP path returns 200-399. Readiness failure removes the replica from the pool and pauses rollout; liveness failure restarts it. An autoscaled workload with no real readiness probe gets traffic before it's ready, causing 502s on scale-up โ add an httpGet readiness probe (it needs a port; defaults to the container's). Probe tuning: workload-security skill.
Symptoms: won't schedule, throttled, or Capacity AI not adjusting.
maxScale ร per-replica resources is enforced at scheduling.minCpu / minMemory instead (those persist; capacityAI is stripped on stateful).minCpu/cpu at most 4000m apart (ratio โค 4:1); minMemory/memory at most 4096Mi apart (ratio โค 4:1).Deep model: autoscaling-capacity skill.
runAsUser to another UID in 1-65534 (0/root is rejected).istio-proxy / queue-proxy / istio-validation (or other reserved names); cannot start with cpln- or debugger-.CPLN_, plus K_SERVICE / K_CONFIGURATION / K_REVISION, are rejected; each value caps at 4096 characters.spec.defaultOptions.suspend: true stops the workload (min/max scale 0). Clear it, or cpln workload start WORKLOAD --gvc GVC.Symptoms: won't scale, 502s on scale-up, scale-to-zero not working, or an invalid-strategy error on create.
Strategies: concurrency, cpu, memory, rps, latency, keda, disabled. Per type: serverless has no latency or multi-metric; standard has no concurrency; stateful has no concurrency; cron has no autoscaling at all (the block is removed). Scale-to-zero: serverless with rps or concurrency; standard and stateful only with metric: keda (otherwise the update is rejected); cron cannot. For 502s on scale-up, fix the readiness probe (above). Details: autoscaling-capacity skill.
Symptoms: requests fail during deploys or scale-down, 502/503 on rollout, containers killed abruptly.
sleep โ if sleep is absent from any container, all containers get SIGKILL immediately (no drain). Many distroless/minimal images lack it; confirm with which sleep. Fix: include sleep or add a custom preStop.preStop in any container SIGKILLs all of them.sleep 45) the container gets the termination signal, then SIGKILL once terminationGracePeriodSeconds (default 90; max 900 without the cpln/relaxGracePeriodMax tag) elapses.Sequence and rollout options: workload-security skill.
Symptoms: can't read mounted files, permission denied, empty cloud volume.
reveal policy chain (as Secret access failures).*.amazonaws.com, *.googleapis.com, *.blob.core.windows.net / *.file.core.windows.net plus *.azure.com); auth is identity-only โ embedded keys do not work. Read-only except Azure Files./dev, /dev/log, /tmp, /var, /var/log. Max 15 volumes; no path may be a parent of another.filesystemGroupId defaults to 0 (root) when unset โ set it (1-65534) for a non-root app.Volume sets: stateful-storage skill.
Symptoms: a workload can't reach another internally (connection refused or timeout).
same-gvc / same-org / workload-list (default none); listing a workload needs view on it.http://WORKLOAD.GVC.cpln.local:PORT (use http://; the sidecar adds mTLS). An omitted port defaults to the target's first container port; only listed ports are reachable.same-org or list the caller; traffic may span locations and incur egress charges.Symptoms: unreachable after enabling a dedicated LB, TCP broken, wrong Host header.
Host (the custom domain moves to X-Forwarded-Host); standard and stateful workloads get the custom domain as Host.Routing, TLS, and LBs: domain and ipset-load-balancing skills.
A fix the Joi schema rejects at update_workload time is worse than none. Before applying a resource or option change, confirm it stays within these (the validator names the violated rule):
memory (MiB) at most 8ร cpu (millicores); CPU โฅ 25m; memory โฅ 32MiB; minCpu/minMemory never above cpu/memory.runAsUser / filesystemGroupId: 1-65534 (0/root rejected).terminationGracePeriodSeconds: โค 900 (higher only with the cpln/relaxGracePeriodMax tag).capacityAI with metric: cpu is rejected; capacityAI is stripped on stateful, cron, and vm.minScale: 0 requires metric: keda; cron and vm cannot scale to zero.Prefer update_workload (PATCH โ only the fields you set change). For full manifest control, author against get_resource_schema then cpln apply -f workload.yaml --gvc GVC.
After applying, poll mcp__cpln__list_deployments until every location reports ready, confirm the original symptom cleared (events/logs), and report the canonical endpoint list_deployments returns โ never a constructed URL. For a public workload, confirm it actually responds, not just that it is ready.
| Symptom | Likely cause | First check |
|---|---|---|
Restarts; OOMKilled in events | memory cap too low (or Capacity AI downsized) | query_metrics memory; raise memory + cpu |
ImagePullBackOff / stuck | bad image ref, wrong platform, missing pull secret | events; GVC pullSecretLinks |
| Env vars empty | broken identity + reveal chain or wrong reference | grant_workload_secret_access |
| Healthy but 502/503 | spec port โ listening port, or a blocked port | netstat via workload_exec |
| Unreachable / can't call out | deny-by-default firewall | firewallConfig |
| Won't become ready | probe path/port wrong or too aggressive | events; probe config |
| Can't reach another workload | target internal firewall none, or https:// used | target inboundAllowType; use http:// |
| 502/503 during deploys | missing sleep, or app ignores SIGTERM | which sleep; SIGTERM handling |
update_workload rejected | the fix violates a schema limit | Apply fixes within the schema's limits |
| Tool | Purpose |
|---|---|
mcp__cpln__list_deployments | Primary per-location readiness monitor |
mcp__cpln__get_workload_events | Image / crash / probe / schedule events |
mcp__cpln__get_workload_logs | App and _accesslog logs |
mcp__cpln__list_workload_replicas / mcp__cpln__workload_exec | Target and inspect a live replica (audited) |
mcp__cpln__query_metrics (after mcp__cpln__list_metrics) | Memory / CPU / latency pressure |
mcp__cpln__update_workload | Apply a spec fix (PATCH) |
mcp__cpln__grant_workload_secret_access | Build the identity + reveal chain in one call |
mcp__cpln__get_resource_schema | Exact fields before a manifest-level fix |
Use when MCP is unavailable, for an interactive shell, or in CI/CD (service-account CPLN_TOKEN).
cpln workload get WORKLOAD --gvc GVC -o json
cpln workload eventlog WORKLOAD --gvc GVC -o json
cpln workload connect WORKLOAD --gvc GVC --location LOCATION
cpln apply -f workload.yaml --gvc GVC
workload โ primary skill (types, spec shape, tool division); start here.workload-security โ probe tuning, termination, securityOptions, direct LBs.firewall-networking โ inbound / outbound / internal rules.autoscaling-capacity โ scaling strategies and Capacity AI.access-control / setup-secret โ the identity + reveal chain.stateful-storage โ volume sets; domain / ipset-load-balancing โ routing and LBs; image โ registries and pull secrets.