A quest to understand Kubernetes API Server

Introduction

Laymen explanation

If you used Kubernetes, you might have query about working of k8s commands.

• Do you know what happens when you fire kubectl cluster-info command?

• Who responds to this and provides the output?

• K8s command can be fired from your laptop as well whereas cluster seats in cloud. Who handles this remote request.

This document helps in this regard.

Technical explanation

The API server implements a RESTful API over HTTP, performs all API operations, and is responsible for storing API objects into a persistent storage backend. Below picture depicts that it is middleman between other components.(Kubelet, kubectl, controller, schedular)

Points to Note

• For all of its complexity, from the standpoint of management, the Kubernetes API server is actually relatively simple to manage. Because all of the API server’s persistent state is stored in a database that is external to the API server, the server itself is stateless and can be replicated to handle request load and for fault tolerance.

• Although the primary use for the API is servicing individual client requests, before API requests can be processed, the client must know how to make an API request. Ultimately, the API server is an HTTP server—thus, every API request is an HTTP request. But the characteristics of those HTTP requests must be described so that the client and server know how to communicate.

Request Management

The main purpose of the API server in Kubernetes is to receive and process API calls in the form of HTTP requests. These requests are either from other components in the Kubernetes system or they are end-user requests. In either event, they are all processed by the Kubernetes API server in the same manner.

API Paths

Every request to the API server follows a RESTful API pattern where the request is defined by the HTTP path of the request. All Kubernetes requests begin with the prefix /api/ (the core APIs) or /apis/ (APIs grouped by API group).

Here are the components of the two different paths for namespaced resource types:

• /api/v1/namespaces/<namespace-name>/<resource-type-name>/<resource-name>

• /apis/<api-group>/<api-version>/namespaces/<namespace-name>/<resource-type-name>/<resource-name>

Here are the components of the two different paths for non-namespaced resource types:

• /api/v1/<resource-type-name>/<resource-name>

• /apis/<api-group>/<api-version>/<resource-type-name>/<resource-name>

Watch API

watch indicates that you can establish a watch for the resource. A watch is a long-running operation that provides notifications about changes to the object.

When a user establishes a watch connection to the API server by adding the query parameter ?watch=true to some API server request, the API server switches into watch mode, and it leaves the connection between client and server open.

API deprecation

An API becomes generally available (e.g., v1). General availability (GA) indicates that the API is stable. These APIs come with both a guarantee of backward compatability and a deprecation guarantee. After an API is marked as scheduled for removal, Kubernetes retains the API for at least three releases or one year, whichever comes first. Deprecation is also fairly unlikely. APIs are deprecated only after a superior alternative has been developed.

API for Container log

A client makes a request to get the logs for a Pod by appending /logs to the end of the path for a particular Pod (e.g., /api/v1/namespaces/default/pods/some-pod/logs) and then specifying the container name as an HTTP query parameter and an HTTP GET request.

If the client requests that the logs be tailed (by specifying the follow query parameter), the HTTP response is kept open by the API server and new logs are written to the HTTP response as they are received from the kubelet via the API server.