How the Kubernetes API Works

Introduction

The Kubernetes API serves as the foundation for the entire Kubernetes platform. It's a RESTful API that allows users, components, and external systems to interact with the cluster. Understanding how this API works is essential for anyone working with Kubernetes, especially when troubleshooting issues or extending functionality.

API Server: The Gateway to Kubernetes

At the heart of the Kubernetes control plane is the API Server. This component:

• Validates and processes RESTful requests
• Serves as the frontend for the Kubernetes control plane
• Is the only component that directly communicates with the etcd datastore
• Implements a watch mechanism for resources

Request Flow Through the API

When you run a command like kubectl apply -f deployment.yaml, a REST request flows through several layers:

1. Authentication: Determines who is making the request
   • Client certificates
   • Bearer tokens
   • OpenID Connect tokens
   • Service account tokens
   • Webhook token authentication
2. Authorization: Determines what the requester can do
   • RBAC (Role-Based Access Control)
   • ABAC (Attribute-Based Access Control)
   • Node authorization
   • Webhook mode
3. Admission Control: Intercepts requests after authentication and authorization
   • Mutating admission controllers: Can modify the request
   • Validating admission controllers: Can only validate (accept/reject)
4. Schema Validation: Ensures request payload matches the API schema
5. Object Versioning: Handles API versioning (e.g., v1, v1beta1)
6. Resource Storage: API Server writes validated object to etcd

┌─────────┐    ┌───────────────┐    ┌─────────────┐    ┌──────────────┐    ┌─────────┐
│ Request │───►│Authentication │───►│Authorization│───►│ Admission    │───►│  etcd   │
└─────────┘    └───────────────┘    └─────────────┘    │ Controllers  │    └─────────┘
                                                       └──────────────┘

API Resources and Groups

Kubernetes organizes its API in terms of:

• API Groups: Collections of related functionality (e.g., apps, batch, networking.k8s.io)
• API Resources: Specific types within groups (e.g., deployments, jobs, ingresses)
• API Versions: Evolution stages (e.g., v1, v1beta1, v2alpha1)

Each resource is accessed via a URL path like:

/apis/{group}/{version}/namespaces/{namespace}/{resource}/{name}

Core resources use a legacy URL format:

/api/v1/namespaces/{namespace}/{resource}/{name}

The Controller Pattern

Kubernetes follows a declarative model where you describe the desired state rather than imperative commands. This is implemented through controllers:

1. Control Loop: Controllers continuously watch the API server for changes
2. Reconciliation: Controllers compare desired state with actual state
3. Action: Controllers take actions to make actual state match desired state

┌─────────────────┐
│ Desired State   │
│ (in etcd)       │
└────────┬────────┘
         │
         │ Watch
         ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Controller   │───►│ Compare Desired │───►│   Take Action   │
│                 │    │ vs Actual       │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         ▲                                             │
         │                                             │
         └─────────────────────────────────────────────┘
                          Reconcile

This pattern ensures the system continuously works toward the desired state, making Kubernetes self-healing and resilient.

Watch Mechanism

The API server supports efficient state monitoring through a watch mechanism:

# Example of using kubectl to watch pod changes
kubectl get pods --watch

Under the hood, this opens a persistent connection to the API server, which streams resource changes. This is more efficient than polling and forms the foundation of how controllers operate.

API Extensions

Kubernetes allows extending its API in three primary ways:

1. Custom Resources and CRDs (Custom Resource Definitions)
   • Define new resource types without writing server code
   • Example: kubectl apply -f custom-resource-definition.yaml
2. API Aggregation
   • Register additional API servers
   • More complex but provides greater flexibility
   • Used for APIs that need custom business logic
3. Admission Webhooks
   • Intercept requests to the API server
   • Mutate or validate resources before persistence
   • Perfect for enforcing custom policies

Practical Example: Request Flow for Pod Creation

Let's walk through what happens when you create a Pod:

1. You run kubectl create -f pod.yaml
2. kubectl converts the YAML to JSON and sends a POST request
3. API server authenticates your request using configured mechanisms
4. API server authorizes the request against RBAC policies
5. Request passes through admission controllers:
   • PodSecurityPolicy (if enabled)
   • LimitRanger (to apply resource constraints)
   • Others like ServiceAccount or custom webhooks
6. API server validates the Pod schema
7. API server stores the Pod object in etcd
8. The scheduler (watching for unassigned Pods) assigns it to a node
9. The kubelet on that node (watching for assigned Pods) creates the containers

Conclusion

The Kubernetes API is a sophisticated system designed with extensibility, security, and consistency in mind. Its layered architecture of authentication, authorization, and admission control provides security while allowing for significant customization.

Understanding the API's inner workings helps in troubleshooting, extending Kubernetes with custom resources, and appreciating the elegant design principles that make Kubernetes a powerful orchestration platform.

In future TechBites, we'll explore specific components of this API in more detail, including practical examples of extending Kubernetes through CRDs and admission webhooks.