Introduction

In Kubernetes YAML, kind tells Kubernetes what type of object the manifest describes. It answers the question "what am I creating or updating" before Kubernetes even looks at the object-specific fields under spec.

kind does not work alone. Kubernetes interprets it together with apiVersion. The pair tells the API server which schema and behavior to use.

kind and apiVersion Work Together

Here is a simple Deployment manifest:

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

In this example:

• 'apiVersion: apps/v1 selects the Deployment API group and version.'
• 'kind: Deployment says the object is a Deployment.'
• Kubernetes then validates the remaining fields against the Deployment schema.

If you change kind to Service, the expected spec changes completely.

Examples of Common kind Values

Different resource types use different kinds:

1apiVersion: v1
2kind: Service
3metadata:
4  name: web-service
5spec:
6  selector:
7    app: web-app
8  ports:
9    - port: 80
10      targetPort: 80

1apiVersion: v1
2kind: ConfigMap
3metadata:
4  name: app-config
5data:
6  LOG_LEVEL: info

Common values include Pod, Deployment, Service, ConfigMap, Secret, Job, and Ingress. Each one maps to a different Kubernetes resource type with its own rules.

Why kind Matters

Kubernetes is a large API, not a single object type. kind is how the system knows whether your YAML describes a workload, a network endpoint, configuration data, or something else entirely.

This also affects how controllers behave:

• A Deployment is reconciled by the Deployment controller.
• A Job is handled by the Job controller.
• A Service creates a stable virtual endpoint for matching pods.

So kind is not just a label. It determines the behavior attached to the object.

Custom Resources Also Use kind

The concept is not limited to built-in resources. Custom Resource Definitions add new kinds to the cluster.

1apiVersion: example.com/v1
2kind: BackupPolicy
3metadata:
4  name: nightly-backup
5spec:
6  schedule: "0 2 * * *"
7  retentionDays: 7

In that case, kind: BackupPolicy only works if the cluster already knows that custom resource definition.

This is one reason manifests are portable only within the set of APIs a cluster actually exposes. A valid custom kind in one cluster may be completely unknown in another.

Multi-Object Files

A single YAML file can contain multiple documents separated by ---. Each document still needs its own apiVersion, kind, and metadata.

1apiVersion: v1
2kind: Namespace
3metadata:
4  name: demo
5---
6apiVersion: v1
7kind: ServiceAccount
8metadata:
9  name: demo-sa
10  namespace: demo

Kubernetes reads each document independently.

Common Pitfalls

One common mistake is using the wrong apiVersion for a given kind. A manifest may look valid but still fail because that kind is not served in the selected API version.

Another issue is case sensitivity. Deployment and deployment are not the same. Kubernetes expects the exact kind name.

People also confuse the kind field in normal manifests with the separate local tool named kind, which is a Kubernetes-in-Docker project. They are unrelated except for the word.

Finally, changing kind without rewriting spec almost always breaks the manifest, because each resource type expects different fields.

When debugging, kubectl explain deployment or kubectl explain service is often the fastest way to see what a given kind expects in its schema.

Summary

• 'kind tells Kubernetes what type of object the YAML describes.'
• Kubernetes interprets kind together with apiVersion.
• Different kinds have different schemas, controllers, and runtime behavior.
• Custom resources introduce additional valid kind values.
• Every YAML document needs its own kind, even when several resources live in one file.