Table of Contents
Learn about Kubernetes client libraries in this article by Onur Yılmaz, a software engineer and a Certified Kubernetes Administrator (CKA) who works on Kubernetes and cloud management systems.
Kubernetes is an open source project that was released by Google in June, 2014. Google released the project as part of an effort to share their own infrastructure and technology advantage with the community at large.
Google launches 2 billion containers a week in their infrastructure and has been using container technology for over a decade. Originally, they were building a system named Borg, and now Omega, to schedule their vast quantities of workloads across their ever-expanding data center footprint. They took many of the lessons they learned over the years and rewrote their existing data center management tool for wide adoption by the rest of the world. The result was the Kubernetes open source project.
Kubernetes provides multiple options for creating applications with the Kubernetes API. These options include tools such as kubectl, helm, kops, and kubeadm; and client libraries, which are officially supported or community-maintained. This article will explore the official and community-maintained libraries and include detailed information and example applications.
Official Client Libraries
Applications that consume the Kubernetes REST API should implement API calls, including request and response types. Considering the rich set of Kubernetes resources provided, developing and maintaining API implementation becomes complex.
Fortunately, Kubernetes has a rich set of official client libraries that are implemented in various programming languages. Client libraries not only handle requests and responses but also authentication to the API server. Besides, most client libraries can discover and connect to the Kubernetes API server if it is running inside the cluster.
In this article, official Go and Python client libraries will be presented. The client repositories, documentation, how to install, and how to create simple applications that run inside and outside the clusters will be covered. You can find the complete code for this article at https://github.com/TrainingByPackt/Kubernetes-Design-Patterns-and-Extensions-eLearning/tree/master/Lesson02.
Go Client Library
Go, which is also of en referred to as Golang, is a programming language that was created by Google in 2009. The prominent features of Go are as follows:
- It is statically typed so that the compiler ensures object types and conversions are working
- It has memory safety with no development concerns
- It has garbage collection with a minimal overhead
- The structural typing of objects is based on their composition
- It has first-citizen concurrency handling with primitives such as go routines and channels
Go is a free, open source programming language that has compilers and environment tools. Go became popular within cloud-native applications because the aforementioned features are well-fitting to the requirements of scalable and reliable applications. Some of the most notable projects that use Go as their primary language are as follows:
- Docker
- Kubernetes
- Terraform
- OpenShift
- Consul
- Bitcoin Lightning Network
- InfluxDB
- CockroachDB
Repository
Kubernetes’ Go client, namely client-go, is part of the Kubernetes official project, which is available at https://github.com/kubernetes/client-go. It is the oldest and the most comprehensive client library. Kubernetes resource handlers of the client library are generated with the official source code generators from Kubernetes. In addition, client-go is widely used inside Kubernetes projects, such as kubectl, helm, and kops.
Documentation
The Go client repository consists of the following packages and respective focus areas:
- kubernetes: Clientset to access the Kubernetes API
- discovery: Discover APIs supported by the Kubernetes API server
- dynamic: Dynamic client to perform generic API access
- transport: Authentication and connection start
- The Go client follows the official documentation style of the Go language and it is available at https://godoc.org/k8s.io/client-go.
Installation
In the Go language, its toolset provides the go get command as a standard way of downloading and installing packages with their dependencies. This command downloads the default branch and the latest changes from source control version providers. However, specific versions of the Kubernetes client are designed to work with particular versions of dependencies. Therefore, the standard go get command is not usable. Instead, dependency management solutions proposed for Go should be used to work with client-go reliably.
In other words, the required version of client-go should be decided and then the dependency manager downloads it with the corresponding dependencies. This concept of handling dependencies is called vendoring. Accordingly, dependency managers collect the dependency libraries and put them in the vendor folder.
For a Go application that uses the client-go library, all related libraries and their dependencies should be collected under the vendor folder for reliable and repeatable builds.
The Kubernetes Go client supports multiple dependency management tools, such as dep, godeps, and glide. In addition, the required steps for casual users who do not want to use any dependency management tools are provided in the official documentation of client-go: https://github.com/kubernetes/client-go/blob/master/INSTALL.md.
Creating Configuration
The Go client library provides the necessary functionalities to connect to the Kubernetes API server. It is easy to create the configuration so that you can communicate outside and inside the cluster. You can do so with the following code snippets:
|
1 2 3 4 |
// Create configuration outside the cluster config, err = clientcmd.BuildConfigFromFlags("", kubeconfigPath) // Create configuration inside the cluster config, err = rest.InClusterConfig() |
Creating Clientset
Clientset contains the clients for each group of resources and provides access to them. With its redacted version, as shown in the following code, it can be seen that every group of resources have their clients implemented in the client library:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
type Clientset struct { ... appsV1 *appsv1.AppsV1Client ... batchV1 *batchv1.BatchV1Client coreV1 *corev1.CoreV1Client eventsV1beta1 *eventsv1beta1.EventsV1beta1Client networkingV1 *networkingv1.NetworkingV1Client rbacV1 *rbacv1.RbacV1Client storageV1beta1 *storagev1beta1.StorageV1beta1Client storageV1 *storagev1.StorageV1Client } |
Using the configuration from the previous step, clientset can be created with the following code snippet:
|
1 2 3 4 |
// Create clientset from configuration clientset, err := kubernetes.NewForConfig(config) |
Making API Calls
After creating the configuration and clientset, API calls can finally be carried out. All Kubernetes resources can be listed, updated, created, or deleted using the clients in the provided clientset. Some examples are shown in the following code snippet:
|
1 2 3 4 5 6 7 8 9 |
// Request all pods from all namespaces pods, err := clientset.CoreV1().Pods(v1.NamespaceAll).List(metav1.ListOptions{}) // Get deployment packt from the default namespace deployments, err := clientset.AppsV1().Deployments(v1.NamespaceDefault).Get("packt", metav1.GetOptions{}) // Delete statefulset test from namespace packt clientset.AppsV1().StatefulSets("packt").Delete("test", &metav1.DeleteOptions{}) |
Code snippets are provided for the configuration, client creation, and making API calls using the Kubernetes Go client in the previous sections. The complete application code is provided in go/main.go, bringing together all snippets at https://goo.gl/wJBjG5.
You can note the following points in the main.go file:
- In the main function that was started at line 19, all variables are defined, and the command-line arguments are parsed at line 30.
- Configuration is created from kubeconfig, and as a fallback method, it is created by in-cluster methods between lines 33 and 42.
- Clientset is created at line 45.
- Between lines 51 and 65, an indefinite loop is defined with 10 seconds of sleep at the end of iterations.
- At every iteration of this loop, pods from all namespaces are requested at line 53. The response is printed to the console between lines 58 and 62.
In the following example, an application combining all code snippets in the previous sections is built and run. It shows you how to build a Go application and use it outside the cluster. Although the application seems straightforward, the flow and codebase create a foundation for complex automation requirements.
To Use the Kubernetes Go Client outside the Cluster
In this section, you’ll learn to build and run a Go application, consuming Kubernetes Go client and connecting the application outside the cluster. Go applications are built using go toolset commands such as go build. However, this requires the installation of Go locally. In this example, you’ll use the official Docker image of the Go language without any installation on the local machine:
- Create a cross-platform build using the official Docker container using the following command:
1234cd gomake build - Start the application using the executable created in Step 1 and the kubeconfig file location:
123./client --kubeconfig=$HOME/.kube/configYou will see the following output:
Activity: Using the Kubernetes Go Client inside the Cluster
Scenario
You are assigned the task of deploying a Go application that lists all of the pods in Kubernetes. Besides this, the application will run inside the cluster and receive information about its cluster.
Aim
To run an application that consumes the Go client library inside the Kubernetes cluster.
Prerequisites
- Use the Docker image onuryilmaz/k8s-client-example:go image, which contains the executable from the previous example.
- Deploy the application and check the logs to see whether it is working as expected.
Steps for Completion
- Create a deployment with the Docker image of the example client from the previous example.
- Wait until the pod is running.
- Get the logs of the deployment pod.
With this command, the logs of the pod are retrieved with a subcommand. In the subcommand, all pods are retrieved with the selector label of run equal to go-client, and the name of the first pod is gathered. Logs should indicate the client itself, in addition to other pods in the cluster:
- Run the following command for cleanup:
123kubectl delete deployment go-client
Python Client Library
Python is a high-level and general-purpose programming language that was first released in 1990. It is one of the most popular open source programming languages, used in various areas, including machine learning, data processing, web development, and scripting. The essential feature of Python is that the language is interpreted with dynamic type checking. Python owes its popularity to its clear programming style and focuses on code readability. In modern cloud-native environments, Python is mostly used for infrastructure and automation. In addition to its popularity and widespread usage, Kubernetes has an official client library that’s implemented in Python.
Repository
The Kubernetes Python client is part of the official client repository and is available at https://github.com/kubernetes-client/python.
The Python client is an OpenAPI compliant client, which means that Swagger tools generate resource definitions. The client library is still in progress, and its capabilities should be checked from the repository before using them in production. The Python client, like every other Kubernetes client, attempts to support a set of predefined functionalities, and it is classified as "Silver" according to its coverage.
The OpenAPI is a specification for describing RESTful APIs. Using the OpenAPI specification, it is possible to create an implementation for clients and services, including all of the corresponding operations. Swagger is the tooling ecosystem for developing APIs, which is defined in OpenAPI. Swagger provides both open source and commercial tools to create applications for the provided specification.
Installation
There are two ways of installing the client library so that you can create a development environment. The first way is to download the source code and build:
|
1 2 3 4 5 6 |
$ git clone --recursive https://github.com/kubernetes-client/ python.git $ cd python $ python setup.py install |
The second way is to download the package from the Python Package Index using a package manager such as pip:
|
1 2 3 |
$ pip install kubernetes |
Client Usage
In the previous section, a Go application that lists all the pods were developed. The same functionality as the previous application is performed in Python in this section. With the clean code and readability philosophy of Python, the same functionality is handled in around ten lines of code, as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
from kubernetes import client, config import time config.load_incluster_config() v1 = client.CoreV1Api() while True: ret = v1.list_pod_for_all_namespaces(watch=False) print('There are {:d} pods in the cluster:'.format(len(ret.items))) for i in ret.items: print('{:s}/{:s}'.format((i.metadata.namespace, i.metadata.name)) time.sleep(10) |
These are the critical points to mention about the preceding code snippet:
- In line 3, the in-cluster configuration, and in line 5, the client for the corev1 API is created
- Starting in line 8, an infinite loop starts with a sleep of 10 seconds at each iteration
- In line 9, all pods are requested from the v1 client and the response is parsed and written to the console
Packaging
The Python application should run inside a container, like all services running on Kubernetes. Thus, the client library defined in this section is packaged with the following Dockerfile. This container definition enables the application to run its isolated environment with its dependencies:
|
1 2 3 4 5 6 |
FROM python:3 RUN pip install kubernetes ADD . /client.py CMD ["python", "./client.py"] |
Refer to the complete code at https://goo.gl/z78SKr.
The following are remarks about the preceding code:
- The container has the basis of Python supporting version 3
- The Kubernetes Python client library is installed using pip in line 3
- The client application is copied into the container in line 5 and started in line 7
In the following section, the code snippets presented for Python are utilized to work in a Kubernetes cluster. The complete code is packaged as a Docker container with its dependencies. With this container, the application is deployed to Kubernetes in an isolated way, which follows microservice architecture.
Using the Kubernetes Python Client inside the Cluster
In this section, you’ll deploy a Python application that lists all of the pods and consumes the Python client library inside Kubernetes. Besides this, the application will run inside the cluster and gather information about its cluster.
Before starting with the implementation, you need to use the Docker image onuryilmaz/k8s-client-example:python, which was built using the Dockerfile in the last section. You also need to deploy the application as a deployment and check the logs to see whether it is working as expected. Begin by implementing the following steps:
- Create a deployment with the Docker image of the example client:
123kubectl run python-client -it --image=onuryilmaz/k8sclient-example:pythonWith this command, a deployment with the name python-client will be created with the Docker image onuryilmaz/k8s-client-example:python in an interactive mode so that logs will be printed to the console.
Logs should indicate the client itself, in addition to other pods in the cluster:
- Run the following command for cleanup:
123kubectl delete deployment python-client
Other Official Client Libraries
Official client libraries also include some additional programming languages:
- Java: https://github.com/kubernetes-client/java
- .NET: https://github.com/kubernetes-client/csharp
- JavaScript: https://github.com/kubernetes-client/javascript
For the capabilities and hurdles of these libraries, you should check their corresponding repositories since they are all still in the development phase.
If you found this article interesting, you can explore Kubernetes Design Patterns and Extensions to see how services running in Kubernetes can leverage the platform’s security features. Kubernetes Design Patterns and Extensions can help you master the art of container management with Kubernetes and study robust container orchestration to ensure that your container-based applications sail into production without hiccups.
