Kubernetes is a popular open-source container orchestration platform that helps to automate the deployment, scaling, and management of containerized applications. It provides a rich set of features and capabilities that enable users to run their applications in a highly available and scalable manner. At the heart of Kubernetes is its API (Application Programming Interface), which serves as the primary mechanism for managing and interacting with Kubernetes clusters.

In this blog post, we'll take a closer look at the Kubernetes API and how it works, its architecture, and some of the most important concepts that you should know to work with it.

Related Articles

What is the Kubernetes API?

The Kubernetes API is a RESTful API that exposes a set of resources and operations that allow you to manage and interact with Kubernetes clusters. It serves as the central control plane for Kubernetes, and all interactions with the system happen through this API. The Kubernetes API is designed to be extensible, which means that you can add your own custom resources and controllers to extend the functionality of Kubernetes to meet your specific requirements.

Kubernetes API uses a declarative model of configuration, which means that you declare the desired state of your application, and Kubernetes takes care of the rest. You specify the desired state of your application in the form of a YAML or JSON file, and then you submit it to Kubernetes via the API. Kubernetes then takes that configuration, compares it to the current state of the cluster, and makes any necessary changes to bring the cluster into the desired state.

How does the Kubernetes API work?

The Kubernetes API is built on top of a distributed key-value store called etcd. Etcd is a high-performance and highly available data store that provides a reliable and consistent way to store and retrieve data across a Kubernetes cluster. All state information about a Kubernetes cluster is stored in etcd, including information about pods, services, deployments, and nodes.

When you interact with the Kubernetes API, you're essentially interacting with etcd. When you make a request to the API, Kubernetes processes the request and sends the relevant data to etcd, which stores it in its distributed key-value store. When you retrieve data from the API, Kubernetes retrieves the data from etcd and returns it to you.

The Kubernetes API is designed to be highly scalable and available. The API server, which is the component that exposes the API, can be run in a highly available configuration with multiple replicas for increased availability. The API server is stateless, which means that it doesn't store any data locally. Instead, it retrieves data from etcd and returns it to the client. This architecture makes it easy to scale the API server horizontally by adding more replicas as needed.

Kubernetes API Architecture

The Kubernetes API is composed of several components that work together to provide a seamless and extensible API for managing Kubernetes clusters. Let's take a look at each of these components in more detail.

API Server

The API server is the primary component of the Kubernetes API. It serves as the entry point for all interactions with the API. The API server exposes the API endpoints and handles authentication and authorization of requests. It's responsible for validating and processing requests and sending the relevant data to etcd for storage.

etcd

Etcd is a distributed key-value store that serves as the primary data store for Kubernetes clusters. All state information about a cluster is stored in etcd, including information about pods, services, deployments, and nodes. Etcd is highly available and provides a reliable and consistent way to store and retrieve data across a Kubernetes cluster.

kubelet

The kubelet is the primary agent that runs on each node in a Kubernetes cluster. It's responsible for managing the lifecycle of containers on the node and ensuring that the containers are running as intended. The kubelet communicates with the API server to get the desired state of the containers and then takes the necessary actions to bring the containers into that state.

kubectl

Kubectl is a command-line tool that you can use to interact with the Kubernetes API. It allows you to perform operations such as creating, updating, and deleting Kubernetes resources. Kubectl communicates with the API server to perform these operations.

Controllers

Controllers are responsible for ensuring that the current state of the cluster matches the desired state. There are several built-in controllers in Kubernetes, including the ReplicationController, ReplicaSet, Deployment, and StatefulSet controllers. You can also create your own custom controllers to manage your own resources.

Key Concepts of the Kubernetes API

To work effectively with the Kubernetes API, you need to understand some key concepts. Let's take a closer look at some of the most important concepts that you should know.

Resources

In Kubernetes, a resource is an object that represents a part of your application, such as a pod, service, deployment, or node. You can interact with these resources through the Kubernetes API.

API Versions

The Kubernetes API is versioned, and each version exposes a different set of resources and operations. When you interact with the API, you specify the API version that you want to use.

Namespaces

Namespaces are a way to partition resources within a Kubernetes cluster. They allow you to organize your resources and provide a level of isolation between different parts of your application.

Labels and Selectors

Labels are key-value pairs that you can attach to Kubernetes resources to help you organize and manage them. Selectors are used to filter resources based on their labels.

Controllers and Operators

Controllers and operators are responsible for ensuring that the current state of the cluster matches the desired state. Controllers are built-in to Kubernetes and manage built-in resources like pods, services, and deployments. Operators are custom controllers that you can create to manage your own resources.

API Usage

Because the kubernetes control plane is powered by APIs, you have a nearly infinite number of ways to access it and perform actions against the API. The examples below will simply be retrieving all pods from a namespace named example.

Kubectl Example

Below is an example of utilizing the kubectl client:

$ kubectl get pods --namespace=example

This command uses the get subcommand to retrieve a list of all pods in the specified namespace. The --namespace flag is used to specify the namespace to retrieve pods from.

When you run this command, kubectl will communicate with the Kubernetes API server to retrieve the list of pods in the specified namespace. The output will include the name, status, and other details for each pod.

Golang Example

Below is an example of API access using Golang:

package main

import (
	"context"
	"fmt"
	"os"

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/rest"
)

func main() {
	// create a new Kubernetes client using the default configuration
	config, err := rest.InClusterConfig()
	if err != nil {
		fmt.Println("Failed to create Kubernetes client config:", err)
		os.Exit(1)
	}
	clientset, err := kubernetes.NewForConfig(config)
	if err != nil {
		fmt.Println("Failed to create Kubernetes clientset:", err)
		os.Exit(1)
	}

	// specify the [namespace](/topics/devops/learn/technology/kubernetes/namespace-part-1/) to retrieve pods from
	namespace := "example"

	// retrieve the list of pods in the namespace
	podList, err := clientset.CoreV1().Pods(namespace).List(context.Background(), metav1.ListOptions{})
	if err != nil {
		fmt.Println("Failed to retrieve pods:", err)
		os.Exit(1)
	}

	// print out the names of each pod
	fmt.Printf("Pods in namespace %s:\n", namespace)
	for _, [pod](/topics/devops/learn/technology/kubernetes/how-to-create-pod/) := range podList.Items {
		fmt.Println(pod.Name)
	}
}

In this example, we first create a new Kubernetes client using the default configuration for the current cluster. We then use the clientset to retrieve a list of all pods in the specified namespace using the List method of the CoreV1().Pods() resource. Finally, we loop through the list of pods and print out the name of each one.

Note that in order to run this example, you'll need to have a running Kubernetes cluster and the necessary GoLang dependencies installed. You'll also need to have the appropriate Kubernetes RBAC permissions to access the specified namespace.

Conclusion

The Kubernetes API is a critical component of Kubernetes, serving as the primary mechanism for managing and interacting with Kubernetes clusters. It provides a declarative model of configuration that allows you to specify the desired state of your application and leave the rest to Kubernetes. The Kubernetes API is highly scalable and available, built on top of a distributed key-value store called etcd. To work effectively with the Kubernetes API, you need to understand key concepts such as resources, API versions, namespaces, labels and selectors, and controllers and operators.

We hope that this blog post has provided you with a good understanding of what the Kubernetes API is and how it works. If you're new to Kubernetes, we encourage you to continue exploring the API and its capabilities to learn more about this powerful platform for container orchestration.