KCNA — The Kubernetes API
The Kubernetes API
The Kubernetes API is the central interface for the entire cluster. Every interaction — from kubectl commands to internal component communication — goes through the API server.
What Is the Kubernetes API?
The Kubernetes API is a RESTful HTTP API served by the kube-apiserver. It exposes every Kubernetes resource as an API endpoint.
| Aspect | Details |
|---|---|
| Type | RESTful HTTP API |
| Served by | kube-apiserver |
| Protocol | HTTPS (TLS encrypted) |
| Authentication | Certificates, tokens, or external identity providers |
| Authorization | RBAC (Role-Based Access Control) |
How the API Works
Everything Is a Resource
In Kubernetes, everything is represented as an API resource (sometimes called an “object”):
| Resource | API Group | Example Endpoint |
|---|---|---|
| Pod | core (v1) | /api/v1/namespaces/default/pods |
| Deployment | apps/v1 | /apis/apps/v1/namespaces/default/deployments |
| Service | core (v1) | /api/v1/namespaces/default/services |
| ConfigMap | core (v1) | /api/v1/namespaces/default/configmaps |
| Node | core (v1) | /api/v1/nodes |
CRUD Operations
Standard HTTP methods map to Kubernetes operations:
| HTTP Method | K8s Operation | kubectl Equivalent |
|---|---|---|
| POST | Create a resource | kubectl create |
| GET | Read a resource | kubectl get |
| PUT/PATCH | Update a resource | kubectl apply / kubectl edit |
| DELETE | Delete a resource | kubectl delete |
API Versioning
Kubernetes APIs go through maturity stages:
| Version Stage | Stability | Example | What It Means |
|---|---|---|---|
| Alpha (v1alpha1) | Unstable | batch/v1alpha1 |
May change or be removed. Disabled by default. |
| Beta (v1beta1) | Mostly stable | flowcontrol.apiserver.k8s.io/v1beta1 |
Well-tested but may have minor changes. |
| Stable (v1) | Fully stable | apps/v1 |
Production-ready. Won’t have breaking changes. |
Exam tip: When asked about API stability, remember: alpha → beta → stable. Only stable APIs are guaranteed backward-compatible.
API Groups
APIs are organized into groups:
| Group | Path | Resources |
|---|---|---|
| Core (legacy) | /api/v1 |
Pods, Services, ConfigMaps, Secrets, Nodes, Namespaces |
| apps | /apis/apps/v1 |
Deployments, StatefulSets, DaemonSets, ReplicaSets |
| batch | /apis/batch/v1 |
Jobs, CronJobs |
| networking.k8s.io | /apis/networking.k8s.io/v1 |
NetworkPolicies, Ingress |
| rbac.authorization.k8s.io | /apis/rbac.authorization.k8s.io/v1 |
Roles, ClusterRoles, RoleBindings |
How kubectl Communicates with the API
When you run a kubectl command:
kubectl get pods
│
▼
1. kubectl reads ~/.kube/config for cluster connection info
2. Sends HTTPS request to kube-apiserver:
GET /api/v1/namespaces/default/pods
3. API server authenticates the request (who are you?)
4. API server authorizes the request (are you allowed?)
5. API server fetches data from etcd
6. Returns JSON response to kubectl
7. kubectl formats and displays the output
Authentication, Authorization, and Admission
Every API request goes through three stages:
1. Authentication (“Who are you?”)
| Method | How It Works | Used By |
|---|---|---|
| X.509 Certificates | Client certificate signed by cluster CA | kubelets, admin users |
| Bearer Tokens | Token in Authorization header | Service accounts |
| OpenID Connect | External identity provider | Enterprise SSO integration |
2. Authorization (“Are you allowed?”)
| Mode | How It Works |
|---|---|
| RBAC | Role-based access control — most common. Roles define permissions, RoleBindings assign them to users. |
| ABAC | Attribute-based access control — less common |
| Webhook | External service decides |
3. Admission Control (“Should we allow this?”)
After authentication and authorization, admission controllers can:
- Mutate the request (e.g., inject a sidecar container)
- Validate the request (e.g., reject pods without resource limits)
- Deny the request (e.g., enforce security policies)
Request → Authentication → Authorization → Admission Control → etcd
│
Mutating → Validating
Watching for Changes
Kubernetes components use the watch mechanism to get real-time updates:
| Component | What It Watches |
|---|---|
| kube-scheduler | New pods with no node assignment |
| kube-controller-manager | Changes to deployments, replicasets, nodes, etc. |
| kubelet | Pods assigned to its node |
| kube-proxy | Changes to services and endpoints |
The watch mechanism is more efficient than polling — components get notified immediately when something changes.
Custom Resources and CRDs
Kubernetes is extensible. You can define your own resource types using Custom Resource Definitions (CRDs):
| Concept | What It Is |
|---|---|
| CRD | Defines a new resource type in the API (e.g., Certificate, VirtualService) |
| Custom Resource | An instance of a CRD |
| Operator | A controller that manages custom resources and automates complex operations |
Example: Cert-Manager defines a Certificate CRD. When you create a Certificate resource, the Cert-Manager operator automatically provisions a TLS certificate.
Exam note: Know that CRDs and operators exist and how they extend Kubernetes. You don’t need to know how to create them.
Key Takeaways for the Exam
- The Kubernetes API is a RESTful HTTP API served by kube-apiserver
- Every interaction with the cluster goes through the API — kubectl, kubelet, controllers, everything
- APIs are versioned: alpha → beta → stable
- Resources are grouped into API groups (core, apps, batch, networking, rbac)
- Every request passes through Authentication → Authorization → Admission Control
- RBAC is the standard authorization method
- CRDs allow extending the API with custom resource types
- Components use the watch mechanism for real-time updates
What’s Next?
Let’s explore how pods communicate with each other across the cluster.
