Understanding K8s API : Part 1

If you’re interested in the inner workings of Kubernetes, contributing to the K8s Project and how to debug it, understanding K8s API is really helpful.

Familiarity with Go is an advantage but not a hard requirement to follow along.

Introducing the API Server

On a conceptual level, Kubernetes is made up of a bunch of nodes with different roles. The control plane on the master node(s) consists of the API Server, the Controller Manager and Scheduler(s). The API Server is the central management entity and the only component that directly talks with the distributed storage component etcd. It provides the following core functionality:

• Serves the Kubernetes API, used cluster-internally by the worker nodes as well as externally by kubectl

• Proxies cluster components such as the Kubernetes UI

• Allows the manipulation of the state of objects, for example pods and services

• Persists the state of objects in a distributed storage (etcd)

Key Components of the API Server

• Filters:

  • The request lifecycle starts with filters.

  • Filters ensure various checks and augmentations happen before requests are processed.

  • Examples:

    • Authentication: Validates the identity of the client.

    • Authorization: Checks whether the client has permissions.

    • Audit: Logs what actions were taken.

    • CORS: Handles cross-origin requests.

• MUX (HTTP Routing):

  • MUX (short for Multiplexer) is essentially a router in the Kubernetes API server.

  • It routes requests to specific handlers based on URL patterns.

• API Groups and Resources:

  • API Groups logically organize related resources.

    • Example: batch is a group for job-related resources.

  • Resources represent system entities (like pods, jobs, etc.) sent as JSON via HTTP.

  • Group, Version, and Resource (GVR) uniquely identify any Kubernetes entity.

Understanding API Path

• API Group is a collection of Kinds that are logically related. For example, all batch objects like Job or ScheduledJob are in the batch API Group.

• Version. Each API Group can exist in multiple versions. For example, a group first appears as v1alpha1 and is then promoted to v1beta1 and finally graduates to v1.

• Resource is the representation of a system entity sent or retrieved as JSON via HTTP; can be exposed as an individual resource (such as .../namespaces/default) or collections of resources (like .../jobs).

Request Routing Flow

Let's understand the process step by step:

1. Incoming HTTP Request:

   • Example: GET /apis/batch/v1/jobs

   • The API server receives the request.

2. MUX Intercepts:

   • The MUX intercepts the request and compares the URL path and method against its routing table.

3. Matching Route:

   • The MUX finds the route /apis/batch/v1/jobs in its routing table.

   • It identifies that this route is associated with the jobs handler.

     

4. Call Handler:

   • The MUX invokes the appropriate handler function, passing the HTTP request and a context object.

   • The handler performs the necessary operations (e.g., retrieving jobs data from etcd or creating a new job).

5. Response:

   • The handler constructs the HTTP response (e.g., a list of jobs in JSON format) and sends it back to the client.