apiVersion field is the first line of every manifest. While it may seem like a static piece of boilerplate, it is actually the most important instruction you give to the API server. It defines the schema, the validation rules, and the stability of the resource are about to create.
Kubernetes organizes its thousands of parameters into API Groups. The apiVersion string tells the cluster which "folder" and "version" of the API to look in.
There are two distinct patterns for these values:
1. The Core Group
These are the foundational objects of Kubernetes. Because they have existed since the beginning, they do not belong to a named group.
Format: v1
Resources: Pod, Service, Namespace, Node, ConfigMap, Secret.
Example:
YAML
apiVersion: v1
kind: Service
2. Named Groups
As Kubernetes evolved, new functionality was added via specialized groups. These follow a "Group/Version" structure.
Format: group.k8s.io/version
Resources: Deployments, Ingress, CronJobs.
Example:
YAML
apiVersion: apps/v1
kind: Deployment
The Stability Lifecycle
Version Stability Description
v1alpha1 Experimental May contain bugs. Can be dropped in future releases without warning.
v1beta1 Prerelease Feature-complete and tested. Safe for non-critical environments.
v1 Stable Production-ready.
Many resources have migrated from "Beta" to "Stable" over the last few years. Here is the current standard mapping for common resources:
Workloads: apps/v1 (Deployment, StatefulSet, DaemonSet)
Batch: batch/v1 (Job, CronJob)
Networking: networking.k8s.io/v1 (Ingress, NetworkPolicy)
RBAC: rbac.authorization.k8s.io/v1 (Role, ClusterRole)
# See all resources and their associated API versions
kubectl api-resources
# List all enabled API versions on the server
kubectl api-versions