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:
| Kind | apiVersion |
|---|---|
| Pod, Service, ConfigMap, Secret, PersistentVolume(Claim) | v1 |
| Deployment, StatefulSet, DaemonSet, ReplicaSet | apps/v1 |
| Job, CronJob | batch/v1 |
| Role, ClusterRole, RoleBinding, ClusterRoleBinding | rbac.authorization.k8s.io/v1 |
| NetworkPolicy, Ingress, IngressClass | networking.k8s.io/v1 |
| HorizontalPodAutoscaler | autoscaling/v2 |
| PodDisruptionBudget | policy/v1 |
| StorageClass, CSIDriver | storage.k8s.io/v1 |
| PriorityClass | scheduling.k8s.io/v1 |
| RuntimeClass | node.k8s.io/v1 |
| CertificateSigningRequest | certificates.k8s.io/v1 |
| EndpointSlice | discovery.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/v1for a Pod orv1for 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
statusfields 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.