Kubernetes API

What is Kubernetes API?

The Api server in kubernetes is the hub of Kubernetes control, providing an HTTP API for end users, cluster components, and other components to connect. It enables querying and altering the status of Kubernetes API objects like Pods, Namespaces, ConfigMaps, and Events. The API can be accessed through command-line interfaces like kubectl or REST calls, allowing for efficient use of the system.

The REST API is the foundation of Kubernetes. All activities and interactions between components, as well as external user instructions, are REST API requests handled by the API Server. As a result, everything on the Kubernetes platform is handled as an API object, with its own entry in the API.

OpenAPI Specifications

OpenAPI, formerly Swagger, is a standard for creating and documenting APIs, defining RESTful APIs in a machine-readable style, making it easier for developers to understand and interact with them.

OpenAPI V2

OpenAPI v2 is utilized for designing and evaluating Kubernetes API resources, including Pods, Services, Deployments, and ConfigMaps, to ensure desired structure and format in API requests and answers.The Kubernetes API server provides an aggregated OpenAPI v2 standard through the /openapi/v2 endpoint.

Using request headers, you may provide the following response format:

Kubernetes uses a Protobuf-based serialization standard that is primarily meant for intra-cluster communication.

OpenAPI V3

The Kubernetes API offers easy access to API descriptions and version information via a discovery endpoint called /openapi/v3 within the Kubernetes cluster, providing a JSON document listing accessible API groups and versions.These group/versions are provided in the following format:

The API server improves client-side caching by creating immutable OpenAPI descriptions, setting HTTP caching headers, expiring to 1 year, and setting Cache-Control to immutable.

The Kubernetes API server provides an OpenAPI v3 standard each Kubernetes group version at the /openapi/v3/apis/<group>/<version>?hash=<hash> endpoint.

Accepted request headers are included in the table below:

Kubernetes API Discovery

Creating a local Kubernetes cluster

A local Docker-based Kubernetes cluster is required to send queries to an existing API server. The following configuration will create a cluster with one control plane node and two worker nodes:

To get the cluster up and running, use the following command:

API Discovery

In Kubernetes API, The cluster supports a list of all group versions through its /api and /apis endpoints. The list of resources supported by each group version is also promoted through /apis/<group>/<version> (for example: /apis/rbac.authorization.k8s.io/v1alpha1)To obtain a list of the resources a cluster may provide, kubectl uses these endpoints.

We can now send queries to the Kubernetes API server because we have a local cluster.

Run kubectl in proxy mode to expose an unauthenticated API server on localhost:8001, enabling the curl tool to easily investigate the server.

We can now find the API using the server. The /api prefix can be used to determine the simplest request.

An API object of type APIVersions is returned as the response.

This version will be useful in order to carry out our discovery.

Compared to the previous call, this one has received a far larger response. Specific resources are shown, along with their definitions.

Now we can use this strategy continuously. The API distinguishes between namespaced and non-namespaced resource paths. These namespaced resource type examples are provided:

And here are some examples of non-namespaced resource types.

The API server allows object alteration through POST or DELETE requests, and GET for retrieving information. The -v=6 extension provides more information about the REST call of the kubectl command.

Kubernetes API Groups and Versioning

API groups and versioning in Kubernetes manage revisions of the Kubernetes API, enabling new features, upgrades, and updates while maintaining compatibility with existing clients.

API Groups:

Kubernetes API groups organize and prevent conflicts by containing linked resources like Pods, Services, and ConfigMaps, each with its versioning system, allowing users to create custom resources.

API Versions:

API versions update Kubernetes' API, allowing control over new features and modifications to existing resources while maintaining client compatibility. Initial /api/v1 versions are suitable for communicating with Pods in clusters, but more recent versions like /api/v1beta1 or /api/v1beta2 may be needed for new features.

For example:

Utilize the apps/v1 API version within the "apps" group to create a simple Deployment YAML for a web application:

Adding a Custom Resource to an API Group:

Created using a Custom Resource Definition (CRD), MyCustomResource is part of the custom.example.com custom API group.

In these examples, the API group appears before the version in the apiVersion field. The resource versions (apps/v1, custom.example.com/v1) show which API iteration is being utilized.

Extension

Here we can see that we can extend the Kubernetes API with the aggregation layer, API server extensions, and custom resources.

Aggregation Layer

The aggregation layer in Kubernetes enables the creation of Kubernetes-style APIs within a cluster, enhancing its capabilities and programmatic performance, and can be done using Kubebuilder or Service Catalogue.

Custom Resources

Kubernetes resources are API objects, while custom resources are unique installations not found in every cluster. They can be activated or disabled through dynamic registration, and administrators can impact them independently. Custom resources can be accessed using kubectl.

Understanding Custom Controllers

Custom resources are structured data that can be fetched, with controllers describing their state as a declarative API. They can be deployed on any cluster, with documentation suggesting aggregation for declarative APIs.

API Aggregation Provides Greater Flexibility Than CRDs

CRDs are simpler to establish and require less code, but API aggregation offers more flexibility, including customization of data storage and versioning. Aggregated APIs offer functionality not found in CRDs, such as enabling endpoints to support HTTP verbs and protocol buffers, and extending beyond CRUD with logs or exec.