Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

kubectl apply says a Deployment in version v1 cannot be handled

Errorerror when creating "deployment.yaml": Deployment in version "v1" cannot be handled as a Deployment

Short 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.

  • Applies to Kubernetes 1.30-1.34, kubectl 1.30-1.34
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 version
  2. 2Match what you see, then jump to its fix

    1. 1The first line of the file reads apiVersion: v1 above kind: DeploymentapiVersion is v1 but the kind is DeploymentFix
    2. 2apiVersion 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. 3kubectl 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

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.yaml

2Fix

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.27

3Verify

Apply the file and list the Deployment.

kubectl apply -f deployment.yaml
kubectl get deployment web

Confirmed by kubernetes.io

Did this fix it?

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/v1

3Verify

Review the converted file, then apply it.

kubectl apply -f ./my-deployment.yaml

Confirmed by kubernetes.io

Did this fix it?

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 version

2Fix

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 --client

3Verify

Client and server versions are within one minor of each other, and the apply succeeds.

kubectl version
kubectl apply -f deployment.yaml

Confirmed by kubernetes.io

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.