Introduction

The error Deployment in version "v1" cannot be handled as a Deployment usually means the manifest says kind: Deployment but uses the wrong API group. Kubernetes validates resources by both kind and apiVersion, so kind alone is not enough.

Why v1 Is Wrong for Deployment

v1 is the core API group used for resources such as Pod, Service, and ConfigMap. A Deployment belongs to the apps API group, so the manifest must use apiVersion: apps/v1.

This is wrong:

1apiVersion: v1
2kind: Deployment
3metadata:
4  name: myapp
5spec:
6  replicas: 2

Kubernetes sees kind: Deployment paired with the core v1 group and rejects it because that resource does not exist there.

Use the Correct Deployment Shape

A valid minimal deployment needs more than the right API version. It also needs a selector that matches the pod template labels.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: myapp
5spec:
6  replicas: 2
7  selector:
8    matchLabels:
9      app: myapp
10  template:
11    metadata:
12      labels:
13        app: myapp
14    spec:
15      containers:
16        - name: myapp
17          image: nginx:1.25
18          ports:
19            - containerPort: 80

The important fixes are:

• 'apiVersion: apps/v1'
• 'kind: Deployment'
• matching selector.matchLabels and template.metadata.labels

Without those pieces, even a manifest with the right API group may still fail validation.

Validate Before Applying

A fast way to catch manifest problems is dry-run validation.

kubectl apply --dry-run=client -f deployment.yaml

You can also ask the cluster to validate server-side:

kubectl apply --dry-run=server -f deployment.yaml

This is especially useful when you are learning Kubernetes resource kinds and API groups, because YAML indentation errors and schema errors often appear together.

Understand the Pattern Behind the Error

This error is not unique to Deployments. It is a general Kubernetes pattern: every resource kind belongs to a specific API group and version.

Examples:

• 'Service often uses v1'
• 'Deployment uses apps/v1'
• 'Ingress uses a different API group again'

So when you create a manifest, the pair of values must make sense together. If the kind and version do not match the Kubernetes schema, the API server rejects the object before creation.

If you are unsure which fields a resource requires, kubectl explain deployment is a useful companion. It shows the schema Kubernetes expects, which makes it much easier to distinguish a version problem from a missing selector or a malformed pod template.

One more detail trips people up: a Deployment under apps/v1 is expected to manage a ReplicaSet-backed pod template, so the template.spec section must look like a pod spec, not like a service or top-level deployment field list. Once you remember that relationship, the manifest becomes easier to reason about during debugging and review. That mental model is often what turns the error from confusing to obvious quite quickly in practice.

Common Pitfalls

• Using apiVersion: v1 by habit for every Kubernetes resource.
• Forgetting that Deployment belongs to the apps API group.
• Fixing the API version but forgetting the required selector and matching labels.
• Assuming YAML syntax is the only thing to validate when the real issue is schema mismatch.
• Copying old manifests from outdated tutorials without checking the current API version.

Summary

• 'Deployment is not part of the core v1 API group.'
• Use apiVersion: apps/v1 together with kind: Deployment.
• Make sure the selector and pod-template labels match.
• Use dry-run validation to catch API-version and schema problems before applying the manifest.