kubectl apply says a Deployment in version v1 cannot be handled
error when creating "deployment.yaml": Deployment in version "v1" cannot be handled as a DeploymentShort answer
A Deployment does not live in the core v1 API group. It lives in apps/v1. Manifests that say v1, extensions/v1beta1, apps/v1beta1 or apps/v1beta2 are rejected. Change apiVersion to apps/v1, add a spec.selector that matches the pod template labels, and keep kubectl within one minor version of the cluster.
Fix it fast
1Find out which cause you have
Look at the first two lines of the manifest, then compare the kubectl version with the cluster's.
head -n 3 deployment.yaml kubectl version2Match what you see, then jump to its fix
- 1
The first line of the file reads apiVersion: v1 above kind: DeploymentapiVersion is v1 but the kind is DeploymentFix - 2
apiVersion is extensions/v1beta1, apps/v1beta1 or apps/v1beta2, often in an old tutorial or Helm chartThe manifest still uses a beta API group that was removedFix - 3
kubectl version shows a client and server that differ by more than one minor release, and the manifest is already apps/v1kubectl is too far from the cluster versionFix
- 1
What does the error look like?
error when creating "deployment.yaml": Deployment in version "v1" cannot be handled as a Deployment
Cause 1 of 3
apiVersion is v1 but the kind is Deployment
1Check
The Kubernetes Deployment page uses apiVersion apps/v1 with kind Deployment. Core v1 is for objects such as Pod and Service.
head -n 2 deployment.yaml2Fix
Change the group and version. A Deployment also needs a selector that matches the labels in the pod template.
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: nginx:1.273Verify
Apply the file and list the Deployment.
kubectl apply -f deployment.yaml
kubectl get deployment webConfirmed by kubernetes.io
Cause 2 of 3
The manifest still uses a beta API group that was removed
1Check
Kubernetes stopped serving those Deployment versions in v1.16. apps/v1 is the replacement.
grep -rn "apiVersion: extensions/v1beta1\|apiVersion: apps/v1beta" .2Fix
Move to apps/v1. In that version spec.selector is required and cannot be changed after creation, so reuse the existing template labels. If you have many old files, the kubectl convert plugin can rewrite one (it is not installed by default) and may pick defaults you would not choose.
kubectl convert -f ./my-deployment.yaml --output-version apps/v13Verify
Review the converted file, then apply it.
kubectl apply -f ./my-deployment.yamlConfirmed by kubernetes.io
Cause 3 of 3
kubectl is too far from the cluster version
1Check
Kubernetes supports kubectl within one minor version, older or newer, of kube-apiserver. Outside that range the client is not covered by the policy.
kubectl version2Fix
Install a kubectl release inside that range by following the official install guide for your operating system, then repeat the apply.
# after installing a matching release
kubectl version --client3Verify
Client and server versions are within one minor of each other, and the apply succeeds.
kubectl version
kubectl apply -f deployment.yamlConfirmed by kubernetes.io
How do I stop it coming back?
- Start new manifests from the current Deployment page, not from a tutorial of unknown age.
- Search charts and old repositories for beta apiVersions before you upgrade a cluster.
- Pin the kubectl version in CI to the cluster's minor version.
- Run kubectl explain deployment when unsure which fields exist.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Argo CD behind an nginx Ingress loops with too many redirects
307 Temporary Redirect on every request to the Argo CD host
The browser and Argo CD disagree about who handles TLS.
3 causes, each with a fixServers
A cert-manager Certificate stays at READY False with Let's Encrypt
Issuing certificate as Secret does not exist
A Certificate that stays not ready is waiting on a chain: Issuer, CertificateRequest, Order, Challenge.
3 causes, each with a fixServers
Kubernetes in Docker Desktop will not start or stays on starting
kubectl shows no contexts, or errors against the docker-desktop context
When the Docker Desktop cluster hangs on starting, the usual causes are too few resources, a broken cluster state, or the kubeadm provisioner failing.
4 causes, each with a fixServers
EKS managed node group ends in Create failed because nodes never joined
NodeCreationFailure
Nodes that do not register within 15 minutes cause NodeCreationFailure and a Create failed status.
4 causes, each with a fixServers
An Elasticsearch pod keeps restarting with Back-off restarting failed container
CrashLoopBackOff
Back-off restarting failed container only says the container keeps dying.
3 causes, each with a fixServers
helm install fails: must either provide a name or specify --generate-name
Error: must either provide a name or specify --generate-name
helm install expects a release name followed by a chart.
3 causes, each with a fix