Free to read · CKA · Cluster architecture and kubectl fluency

API objects, groups and versions

How the control plane and the nodes of a kubeadm cluster work together, how the API is organised, and the kubectl and exam habits that make every later module faster.

Lesson · 10 min. This module is free on this site. The rest of the course, the quizzes and the labs open with a free account.

Why this matters

Every task on the exam is, in the end, about creating or changing API objects. If you can read any object's structure from the cluster itself, you never need to remember a field name exactly. You look it up in seconds with kubectl explain.

Anatomy of an object

Every Kubernetes object has the same four top-level parts:

apiVersion: apps/v1          # API group and version
kind: Deployment             # the type
metadata:                    # identity: name, namespace, labels, annotations
  name: web
  namespace: shop
  labels:
    app: web
spec:                        # what you want
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: nginx
        image: nginx:1.27
status:                      # what exists; written by controllers, not by you
  readyReplicas: 3

You write spec. Controllers write status. When the two disagree, a controller is still working, or something is stopping it.

Groups, versions, kinds and resources

The API is split into groups. Each group has one or more versions, and each version serves some kinds. The lowercase plural name used in URLs and RBAC rules is the resource.

  • The core group has no name. Its objects use apiVersion: v1 (Pod, Service, ConfigMap, Secret, Namespace, Node, PersistentVolume).
  • Named groups appear before the slash: apps/v1, batch/v1, rbac.authorization.k8s.io/v1.

Use the cluster to check rather than guessing:

kubectl api-resources | head
kubectl api-resources --namespaced=false        # cluster-scoped kinds
kubectl api-resources --api-group=rbac.authorization.k8s.io
kubectl api-versions | grep autoscaling

The current versions you will type most often:

KindapiVersion
Pod, Service, ConfigMap, Secret, PersistentVolume(Claim)v1
Deployment, StatefulSet, DaemonSet, ReplicaSetapps/v1
Job, CronJobbatch/v1
Role, ClusterRole, RoleBinding, ClusterRoleBindingrbac.authorization.k8s.io/v1
NetworkPolicy, Ingress, IngressClassnetworking.k8s.io/v1
HorizontalPodAutoscalerautoscaling/v2
PodDisruptionBudgetpolicy/v1
StorageClass, CSIDriverstorage.k8s.io/v1
PriorityClassscheduling.k8s.io/v1
RuntimeClassnode.k8s.io/v1
CertificateSigningRequestcertificates.k8s.io/v1
EndpointSlicediscovery.k8s.io/v1
Gateway, HTTPRoute (Gateway API CRDs)gateway.networking.k8s.io/v1

Old beta versions such as extensions/v1beta1 or policy/v1beta1 are gone. If an old manifest fails with "no matches for kind", the version is the first thing to check.

kubectl explain: the built-in reference

kubectl explain reads the schema the API server publishes. It needs no browser tab, and it describes the version actually running, custom resources included.

kubectl explain deployment.spec.strategy
kubectl explain pod.spec.containers.resources
kubectl explain pod.spec --recursive | less
kubectl explain cronjob.spec.jobTemplate.spec.template.spec.restartPolicy

Each field shows its type and, often, the allowed values. This is usually faster than searching the docs for a single field name.

Namespaced and cluster-scoped

Most objects live in a namespace. Some do not: Nodes, PersistentVolumes, StorageClasses, ClusterRoles, ClusterRoleBindings, Namespaces themselves, CRDs, CSIDrivers, PriorityClasses, RuntimeClasses.

This matters for three reasons. A cluster-scoped object ignores -n. RBAC for cluster-scoped objects needs a ClusterRole bound with a ClusterRoleBinding. And deleting a namespace deletes everything namespaced inside it, but nothing cluster-scoped.

Labels, selectors and ownership

Labels are key-value pairs for grouping. Selectors pick objects by label. Services find pods, Deployments find their ReplicaSets and pods, and NetworkPolicies choose pods, all through selectors.

kubectl get pods -l app=web,tier!=cache
kubectl get pods -l 'env in (prod,staging)' --show-labels
kubectl label pod web-1 tier=frontend --overwrite

Annotations are also key-value pairs, but they are for tools and humans, not selection.

Controllers mark what they create with metadata.ownerReferences. A pod owned by a ReplicaSet, owned by a Deployment, forms a chain. Delete the Deployment and the garbage collector removes the chain. Delete just the pod and the ReplicaSet creates a new one. That is why "delete the pod to fix it" rarely works for long.

kubectl get pod web-7d9c6b-x2x4p -o jsonpath='{.metadata.ownerReferences[0].kind}{"\n"}'

Extending the API: CRDs

A CustomResourceDefinition adds a new kind to the API. Once it exists, kubectl get, explain, RBAC and labels all work for the new kind exactly as for built-in ones. An operator is a controller that watches those custom objects and acts on them.

kubectl get crd
kubectl explain widgets.spec            # works for custom kinds too
kubectl api-resources --api-group=demo.internal.local

A CRD defines a schema (openAPIV3Schema) so the API server can reject invalid objects, and it can add printer columns and a status subresource. The kubernetes.io page on CustomResourceDefinitions has a full example you can adapt in the exam.

Common mistakes

  • Writing apiVersion: apps/v1 for a Pod or v1 for a Deployment. The error message tells you, but it costs time.
  • Using the kind (NetworkPolicy) where a resource name (networkpolicies) is needed, for example in RBAC rules.
  • Setting status fields in a manifest and expecting them to stick.
  • Forgetting that the Deployment selector must match the pod template labels; the API rejects the object if they differ.

Exam angle

When you are unsure about a field, kubectl explain beats searching. When you are unsure about a version, kubectl api-resources beats guessing. Both read the real cluster, which is the one being graded.

Practise it

Work with custom kinds and their schemas in these labs:

Practise this on a real cluster in your account: C9, C31.

Official documentation