API Server

Key points to know about API Server

• Runs on Master node

• The only component talks to etcd(The distributed storage component)

• Serves the K8S API both internally(from worker nodes) and externally(kubectl or endpoint)

• Proxies cluster components such as the K8S UI

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

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

K8S API

The K8S API is a HTTP API with JSON as its primary serialization schema, however it also supports Protocol Buffers, mainly for cluster-internal communication. For extensibility reasons K8s supports multiple API versions at different API paths, such as /api/v1 or /apis/extensions/v1beta1. Different API versions imply different levels of stability and support:

• Alpha level, for example v1alpha1 is disabled by default, support for a feature may be dropped at any time without notice and should only be used in short-lived testing clusters.

• Beta level, for example v2beta3, is enabled by default, means that the code is well tested but the semantics of objects may change in incompatible ways in a subsequent beta or stable release.

• Stable level, for example, v1 will appear in released software for many subsequent versions.

In K8s world, every object is represented by a REST endpoint, which means you could send curl command to get the info of the object.

• Run kubectl proxy --port=8080 in one terminal

• In another terminal, runcurl http://127.0.0.1:8080/api/v1/namespaces/<namespace>/pods to get the info on the pods. Or curl http://127.0.0.1:8080/api/v1/namespaces/<namespace>/pods/<pod_name>

You are supposed to get the same info by running kubectl command.

Terminology

Kind is the type of an entity. Each object has a field Kind which tells a client—such as kubectl that it represents, for example, a pod:

apiVersion: v1
kind: Pod
metadata:
  name: webserver
spec:
  containers:
  - name: nginx
    image: nginx:1.9
    ports:
    - containerPort: 80

There are three categories of Kinds:

• Objects represent a persistent entity in the system. An object may have multiple resources that clients can use to perform specific actions. Examples: Pod and Namespace.

• Lists are collections of resources of one or more kinds of entities. Lists have a limited set of common metadata. Examples: PodLists and NodeLists.

• Special purpose kinds are for example used for specific actions on objects and for non-persistent entities such as /binding or /status, discovery uses APIGroup and APIResource, error results use Status, etc.

API Group is a collection of Kinds that are logically related. For example, all batch objects like Job or CronJob 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. An object created in one version (e.g. v1beta1) can be retrieved in each of the supported versions (for example as v1). The API server does lossless conversion to return objects in the requested version.

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).

An API Group, a Version and a Resource (GVR) uniquely defines a HTTP path and also defines a kind (Kinds may not only exist in different versions, but also in different API Groups simultaneously)

Request flow and processing

Briefly there are three steps when a request comes:

• Filters: authentication, authorization, adding request metadata, etc

• Multiplexer: routes the request to respective handler

• Handler: handles the request, and delivers the requested object from storage

Filters: A filter needs to be registered in DefaultBuildHandlerChain() , (see config.go)

• WithRequestInfo() as defined in requestinfo.go attaches a RequestInfo to the context

• WithMaxInFlightLimit() as defined in maxinflight.go limits the number of in-flight requests

• WithTimeoutForNonLongRunningRequests() as defined in timeout.go times out non-long-running requests like most GET, PUT, POST, DELETE requests in contrast to long-running requests like watches and proxy requests

• WithPanicRecovery() as defined in wrap.go wraps an handler to recover and log panics

• WithCORS() as defined in cors.go provides a CORS implementation; CORS stands for Cross-Origin Resource Sharing and is a mechanism that allows JavaScript embedded in a HTML page to make XMLHttpRequests to a domain different from the one the JavaScript originated from.

• WithAuthentication() as defined in authentication.go tries to authenticate the given request as a user and stores the user info in the provided context. On success, the Authorization HTTP header is removed from the request.

• WithAudit() as defined in audit.go decorates the handler with audit logging information for all incoming requests The audit log entries contain infos such as source IP of the request, user invoking the operation, and namespace of the request.

• WithImpersonation() as defined in impersonation.go handles user impersonation, by checking requests that attempt to change the user (similar to sudo).

• WithAuthorization() as defined in authorization.go passes all authorized requests on to multiplexer which dispatched the request to the right handler, and returns a forbidden error otherwise.

Multiplexer: (see container.go)

Handlers: registered per API Group (see groupversion.go and installer.go) takes the HTTP request and context (like user, rights, etc.) and delivers the requested object from storage.

reference: https://blog.openshift.com/kubernetes-deep-dive-api-server-part-1/