The API and kubectl
API groups and versions, object structure, declarative vs imperative management, everyday kubectl, RBAC basics, and which tool builds which kind of cluster.
Exam tasks: 1.2 (Administration: the Kubernetes API, kubectl, access control basics, cluster tooling)
The decision: how do you change the cluster (declare a file or issue a command), which API version and group does an object live in, and which tool fits the cluster you need?
Everything is an API call
- kubectl is just a client. It reads a kubeconfig (default
~/.kube/config) that lists clusters, users (credentials) and contexts (a cluster + user + default namespace). - Every request passes authentication, then authorization, then admission control, before the object is stored. A rejected request fails at one of these three stages.
API groups and versions
| Group | apiVersion you write | URL path | Examples |
|---|---|---|---|
| core (legacy, no name) | v1 | /api/v1 | Pod, Service, ConfigMap, Secret, Namespace, Node |
apps | apps/v1 | /apis/apps/v1 | Deployment, StatefulSet, DaemonSet, ReplicaSet |
batch | batch/v1 | /apis/batch/v1 | Job, CronJob |
networking.k8s.io | networking.k8s.io/v1 | /apis/networking.k8s.io/v1 | Ingress, NetworkPolicy |
rbac.authorization.k8s.io | rbac.authorization.k8s.io/v1 | /apis/rbac.authorization.k8s.io/v1 | Role, RoleBinding |
autoscaling | autoscaling/v2 | /apis/autoscaling/v2 | HorizontalPodAutoscaler |
- Versions mature as alpha (
v1alpha1: off by default, may vanish), beta (v1beta1: well tested; new beta APIs are also off by default), and stable (v1: kept for the long term). - Deprecated versions are removed after a published grace period, so old manifests can stop applying after an
upgrade.
kubectl api-resourcesandkubectl api-versionsshow what the server supports now.
Legacy: use apps/v1, autoscaling/v2, networking.k8s.io/v1 instead
Older examples use extensions/v1beta1 or apps/v1beta2 for Deployments, autoscaling/v2beta2 for the HPA,
and extensions/v1beta1 for Ingress. All of these have been removed; manifests using them are rejected.
Anatomy of an object
apiVersion: apps/v1 # group/version
kind: Deployment # type
metadata: # identity: name, namespace, labels, annotations
name: quotes-api
namespace: shop
labels:
app: quotes-api
spec: # desired state: you write this
replicas: 2
selector:
matchLabels:
app: quotes-api
template:
metadata:
labels:
app: quotes-api
spec:
containers:
- name: api
image: registry.example.com/quotes-api:2.4.1
# status: # observed state: controllers write this- spec is what you want; status is what the system reports. Controllers work to make status match spec.
kubectl explain deployment.spec.strategydocuments any field straight from the server.
Declarative vs imperative
| Style | Example | Good for |
|---|---|---|
| Imperative command | kubectl create deployment quotes-api --image=nginx --replicas=2 | Quick one-offs, generating YAML |
| Imperative object config | kubectl create -f quotes.yaml, kubectl replace -f | Files, but you choose the operation |
| Declarative | kubectl apply -f manifests/ | Version-controlled config, GitOps, repeatable changes |
- With
apply, you state the end result and Kubernetes works out create vs update. Re-running it is safe (idempotent), which is why CI/CD and GitOps tools use it. kubectl createfails if the object already exists;kubectl applyupdates it.--dry-run=client -o yamlturns any imperative command into a starter manifest.
Exam signal
"Desired state stored in files in Git and applied repeatedly" is declarative management with
kubectl apply. "Run a command that performs a specific action now" is imperative.
kubectl you should recognise
| Command | Does |
|---|---|
kubectl get pods -n shop -o wide | List, with node and IP |
kubectl describe pod quotes-api-7d9f | Details plus recent events |
kubectl logs quotes-api-7d9f -c api | Container logs (--previous for the last crash) |
kubectl exec -it quotes-api-7d9f -- sh | Shell inside a running container |
kubectl apply -f file.yaml / kubectl delete -f file.yaml | Declare / remove |
kubectl scale deployment quotes-api --replicas=5 | Change replica count |
kubectl rollout status / undo deployment/quotes-api | Follow or roll back a rollout |
kubectl config use-context staging | Switch cluster or user |
kubectl auth can-i delete pods -n shop | Check your own permissions |
RBAC in one table
| Object | Scope | Role |
|---|---|---|
| Role | One namespace | Lists allowed verbs (get, list, create...) on resources |
| ClusterRole | Cluster-wide | Same, plus cluster-scoped resources such as nodes |
| RoleBinding | One namespace | Grants a Role or ClusterRole to subjects in that namespace |
| ClusterRoleBinding | Cluster-wide | Grants a ClusterRole everywhere |
- Subjects are users, groups or ServiceAccounts. Kubernetes has no User object: humans come from certificates or an identity provider, while ServiceAccounts are real objects for workloads.
- RBAC is additive only. There are no deny rules; anything not granted is refused.
- Hands-on depth: CKA RBAC.
ClusterRole means cluster-wide access
A ClusterRole bound with a RoleBinding grants its permissions only inside that RoleBinding's namespace. The
binding decides the scope. This is the usual way to reuse one ClusterRole such as view across many
namespaces.
Tools for building clusters
| Tool | What it is | Pick it when |
|---|---|---|
| kubeadm | Official tool that bootstraps a conformant cluster on machines you provide (kubeadm init, kubeadm join) | You run your own nodes and want upstream Kubernetes |
| minikube | Local single-node (or small) cluster in a VM or container | Learning and local development |
| kind | Kubernetes in Docker: nodes are containers | Fast, disposable clusters for CI and testing |
| k3s | Lightweight certified distribution in one binary | Edge, IoT, small servers |
| Managed (EKS, GKE, AKS) | The provider runs the control plane | Production without operating the control plane |
kubeadm, kubelet, kubectl
Three different binaries. kubeadm sets up the cluster, kubelet runs on each node as the node agent, and kubectl is the client you type commands into. A question about "installing a cluster" never answers with kubectl.
Scenarios
Deployments live in the apps group at the stable v1 version. Plain v1 is the core group (Pods, Services,
ConfigMaps). extensions/v1beta1 was removed long ago. The core group has no name, so core/v1 isn't valid.
kubectl apply is declarative: it creates missing objects and updates existing ones, and can be run repeatedly.
create fails on objects that exist, replace fails on objects that don't, and kubectl run only starts a Pod
imperatively.
A RoleBinding limits whatever it grants to its own namespace, even when it references a ClusterRole. A
ClusterRoleBinding would grant Pod access in every namespace. system:masters is full admin. A Role in
kube-system can't be bound with a ClusterRoleBinding and is the wrong namespace anyway.
Further reading
Core objects
Pods, ReplicaSets, Deployments, StatefulSets, DaemonSets, Jobs and CronJobs, Services, ConfigMaps and Secrets, labels, annotations and namespaces, and how to tell look-alikes apart.
Scheduling
How kube-scheduler filters and scores nodes, and how resource requests, nodeSelector, node and Pod affinity, taints and tolerations, and priority steer where Pods land.