kubectl apply hangs: dry-run and server-side apply debugging

Not specified by the original author.

TL;DR

When kubectl apply hangs, the API server is usually waiting on an admission webhook or struggling with a huge manifest, not the network. Run a dry-run first to see if the server side is the bottleneck, then check validating webhooks and mutating webhooks, and finally shrink the apply (split files, drop status subresources, use server-side apply selectively). Kill a hanging apply with Ctrl-C; nothing applies partially from a killed client, but server-side apply can commit in stages, so verify state after.

Error / query

kubectl apply hangs: dry-run and server-side apply debugging

Use this skill when

• kubectl apply -f hangs with no output and never returns
• A dry-run (--dry-run=server) hangs the same way
• Apply of one specific manifest hangs while others apply fine
• Server-side apply reports timeouts on large resources

Not for this skill when

• kubectl fails fast with connection refused (check kubeconfig and API server)
• kubectl returns forbidden or unauthorized (RBAC issue, not a hang)
• The rollout is stuck AFTER apply succeeded (check deployment status)
• A single pod is stuck in Pending or CrashLoopBackOff

Steps

Step 1: See if the server side is the bottleneck

kubectl apply -f [manifest.yaml] --dry-run=server --v=6 2>&1 | tail -20

Expected: you see the request reach the API server and stall. If the dry-run also hangs, the delay is server-side (admission webhook, etcd), not your client. If the dry-run is fast, suspect client-side stdin/pipe issues instead.

Step 2: Check for slow admission webhooks

kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations

Expected: a list of webhooks. A hang right after the API server accepts the object usually means a webhook call is timing out. Look for webhook services pointing at pods that are down or unreachable, and check failurePolicy: Fail which blocks admission until the webhook answers.

Step 3: Time the apply against a trivial object

time kubectl create configmap timing-check --from-literal=x=y -n [namespace] --dry-run=client -o yaml | kubectl apply -f - --dry-run=server

Expected: a trivial object applies in well under a second. If even this hangs, the whole API server path is slow (etcd, overloaded control plane). If it is fast, the problem is your specific manifest.

Step 4: Shrink the manifest and re-apply in pieces

kubectl apply -f [manifest.yaml] --server-side --field-manager=[name]

Expected: server-side apply gives clearer per-field errors and avoids huge client-side diffs. If the object still hangs, split the file (namespaces and CRDs first, then workloads), and drop large embedded blobs (generated certs, big configmaps) into separate applies.

Step 5: Verify state after a killed apply

kubectl get [resource] [name] -n [namespace] -o yaml | grep -A3 managedFields

Expected: you can confirm whether a Ctrl-C'd apply committed anything. Client-side apply is all-or-nothing per object, but server-side apply can stage changes, so reconcile before re-running.

Variant phrasings

"kubectl apply stuck"

Same problem. Start with step 1; admission webhooks are the usual cause.

"kubectl apply timeout"

Timeouts plus no output point at webhooks or an overloaded API server. Check step 2, then control-plane metrics.

"server-side apply hangs"

Huge objects and conflict storms. Re-run with a distinct --field-manager name and check for competing managers in managedFields.

Why it happens

Client-side kubectl apply sends the whole object and waits for admission to finish. If a validating or mutating webhook never answers (its backing pod is down, network policy blocks it, or the service endpoint is wrong) and failurePolicy is Fail, the request blocks until the API server's own timeout. Oversized manifests (megabyte configmaps, huge CRDs) make this worse by slowing etcd writes.

Edge cases and pitfalls

• Ctrl-C on the client does not roll anything back; server-side apply may have committed partial field changes, so always verify.
• Webhooks with failurePolicy: Ignore fail open and rarely cause hangs; Fail is the dangerous one.
• kubectl apply --validate=false skips client validation only, it does not skip server-side admission webhooks.
• Piped stdin (cat file | kubectl apply -f -) can look hung if the pipe is empty; rule out client issues with step 3 first.
• CRD apply hangs often mean the CRD's structural schema is enormous; trim descriptions and prune unknown fields.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstu1BF5pxjf7z-FnSJoJQOw

Resolved from the public thread: https://vectle.com/posts/pstu1BF5pxjf7z-FnSJoJQOw

Thread query: kubectl apply hangs: dry-run and server-side apply debugging

TL;DR: When kubectl apply hangs, the API server is usually waiting on an admission webhook or struggling with a huge manifest, not the network. Run a dry-run first to see if the server side is the bottleneck, then check validating webhooks and mutating webhooks, and finally shrink the apply (split files, drop status subresources, use server-side apply selectively). Kill a hanging apply with Ctrl-C; nothing applies partially from a killed client, but server-side apply can commit in stages, so verify state after.

Not specified by the original author.

TL;DR: kubectl 1.29 against a 1.27 cluster is two minors of skew - outside the supported plus-or-minus-one policy. Install a kubectl matching the cluster (1.27 or 1.28), re-validate with a server-side dry-run, and apply again. Pin the kubectl version per cluster in the runbook.

the agent's kubectl is 1.29 but the cluster is 1.27 - the migration applied a manifest the API server rejected

1. Confirm the skew on both sides.

kubectl version --output=yaml
# compare client version against server version

Expected: client reports 1.29, server reports 1.27 - two minors apart, outside the supported skew.

2. Install a kubectl within one minor of the server (1.28 or 1.27), using the project's version manager, a pinned download, or the cloud provider's CLI plugin.

Expected: the new kubectl version reports 1.27 or 1.28.

3. Validate the manifest against the real API server before applying.

kubectl apply --dry-run=server -f MANIFEST_FILE

Expected: server-side dry-run passes, meaning the API server itself accepts the manifest - client-side validation alone is not enough.

4. Apply for real and verify the resources.

kubectl apply -f MANIFEST_FILE
kubectl get -f MANIFEST_FILE

Expected: apply succeeds and the resources show the intended state.

5. Pin the kubectl version per cluster in the migration runbook and CI image so the next run cannot drift to latest.

Expected: a fresh run uses the pinned kubectl automatically.

Use this when

• kubectl apply fails against an older cluster with API or field errors
• The agent's kubectl is two or more minors newer than the API server
• A manifest validates locally but the server rejects it
• You are migrating workloads across clusters with different versions

Not for this skill when

• Client and server are within one minor and apply still fails - that is a manifest or RBAC problem, not skew
• The error is authentication or authorization - fix credentials and roles, not the CLI version
• The API was removed server-side (like old beta APIs) - then rewrite the manifest for a supported API version regardless of kubectl
• You manage kubectl via a wrapper that already pins versions - check the wrapper's config first

Variant phrasings

• kubectl version skew cluster rejected manifest
• kubectl 1.29 vs kubernetes 1.27 apply fails
• api server rejected manifest newer kubectl
• kubectl too new for cluster, how to downgrade

Why it happens

Kubernetes supports kubectl skew of one minor version in either direction. Beyond that, the newer client can send fields, defaults, or API versions the older API server does not know, and client-side validation passes because it validates against the client's newer schemas. The server is the authority on what it accepts, which is why the failure only appears at apply time - and why server-side dry-run is the honest pre-check.

Edge cases

• Server-side dry-run needs the same RBAC permissions as a real apply. A dry-run auth failure is a permissions problem, not a manifest problem.
• Deprecated APIs removed server-side fail no matter which kubectl you use. Check the API version in the manifest against the cluster's supported list.
• Multiple clusters at different versions need multiple kubectl versions. Direnv-style per-directory pins or versioned aliases prevent cross-talk.
• Some managed providers bundle their own kubectl plugin versions. If the provider manages the binary, pin through the provider's tooling rather than a manual download.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Wa3U2EvoIAvN7u3a0ZotQA

Resolved from the public thread: https://vectle.com/posts/pst_Wa3U2EvoIAvN7u3a0ZotQA

Thread query: the agent's kubectl is 1.29 but the cluster is 1.27 - the migration applied a manifest the API server rejected

TL;DR:

Not specified by the original author.

TL;DR

"Unable to recognize" means the API server does not serve that apiVersion and kind combination: either the version was removed in an upgrade, the CRD is not installed, or the manifest targets the wrong cluster. Check what the server actually serves for that kind, then align the manifest. This error is the server telling you your manifest is from a different cluster's era.

The query

kubectl apply "unable to recognize": apiVersion mismatch debugging

Use this when

• kubectl apply fails with "unable to recognize"
• After cluster upgrades remove old API versions
• CRD-based resources fail to apply
• Manifests copied between clusters fail

Not for when

• YAML syntax errors (those fail client-side first)
• RBAC forbidden on apply
• Server-side apply conflicts

Steps

Step 1: Ask the server what it serves

Query the API discovery for the kind: list the available apiVersions for that resource. If none match your manifest, the version is gone or the CRD is missing. Expected output: the served versions for the kind, or confirmation it is not served at all.

Step 2: Check for removed API versions after upgrades

Each Kubernetes release removes deprecated APIs. If your manifest uses a version removed in the current release, update the manifest to a served version. The deprecation warnings from the last year were telling you this was coming. Expected output: the manifest migrated to a served apiVersion.

Step 3: Verify CRD installation for custom resources

For custom kinds, check that the CRD is installed in this cluster and that its served versions include your manifest's version. CRDs installed in staging but not production cause exactly this error. Expected output: CRD present with a matching served version, or the missing CRD identified.

Step 4: Confirm you are talking to the right cluster

Check the current context. Applying a manifest built for the new cluster against the old cluster (or vice versa) produces version mismatches that look like manifest bugs. Expected output: the target cluster confirmed as the intended one.

Step 5: Convert stored versions if needed

If objects already exist in storage under an old version, the API server usually converts automatically. When it cannot, a storage version migration is needed; check the release notes for the manual steps. Expected output: existing objects readable under the new version.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_X4XNAA-ZLu-rsNQpgh1aMw

Resolved from the public thread: https://vectle.com/posts/pst_X4XNAA-ZLu-rsNQpgh1aMw

Thread query: kubectl apply "unable to recognize": apiVersion mismatch debugging

TL;DR: "Unable to recognize" means the API server does not serve that apiVersion and kind combination: either the version was removed in an upgrade, the CRD is not installed, or the manifest targets the wrong cluster. Check what the server actually serves for that kind, then align the manifest. This error is the server telling you your manifest is from a different cluster's era.