The Kubernetes API is what makes a cluster tick. Every action inside your Kubernetes cluster goes through the API. The entire kubectl tool is essentially a wrapper around this API. When you run kubectl apply, you are sending a request that tells the control plane to create your resources. This request goes through the API, which then hands it over to the right internal services.
An API can be anything that’s used for programmatic communication. The Kubernetes API in particular is RESTful. As long as you’ve worked with another API beforehand, you won’t have to learn any new principles for communicating with it.
The Kubernetes API follows the traditional CRUD pattern, making it possible to focus more on what you can do with the API rather than spending time learning its structure. To make life even easier, there are many client libraries available if you want to integrate the API directly into your application.
Over the course of this article, you’ll get a feel for how you can interact with the Kubernetes API, how it can be used, and how you can secure the API once you start using it in production.
How important is the Kubernetes API?
Everything in Kubernetes revolves around the API. Without it, nothing would work. You may not realize it, but nearly everything you do when managing your cluster interacts with the API. Even when you’re not deep in the roots of your cluster, internal services are communicating with each other, making sure that your cluster is healthy.
You can think of Kubernetes as an all-encompassing service that consists of several microservices. There are multiple components that need to communicate with each other in order to carry out specific tasks. Rather than building a specific API purely for one purpose, the creators of Kubernetes decided to create a general API, making it easier for people to contribute and expand on their clusters. You can read more about the components of Kubernetes here.
Using the Kubernetes API
Depending on your use case, there are many different ways to interact with the Kubernetes API. Whether you’re developing an application that interacts with your cluster directly or you just want to check out what possibilities are available in the API, rest assured there’s an easy way to get started. Since you’re working with a REST API, your main concern is getting access and understanding the possibilities, rather than learning a new framework.
Let’s go over a few options of how you can get started.
Using Kubectl
The easiest way to get started with the Kubernetes API is by using kubectl. Run kubectl proxy --port=8080, and as long as the command is successful, you should be able to open your browser. Go to http://localhost:8080 and get a response, telling you what paths are available to be queried. You can also use curl http://localhost:8080.
You can also run kubectl get --raw /, and you should get the same response as you would using kubectl proxy --port=8080.
You can use kubectl get --raw / to get a list of different resources, too, for example, getting all pods by running kubectl get --raw /api/v1/pods.
There are two key differences compared to the normal kubectl get pods approach:
- The output is a JSON response, rather than a nicely formatted output.
- The API is not namespaced. When you run a “raw” command to get pods, you are getting all the pods in your cluster.
Using a client library
Using kubectl to interact with the API is a great way to familiarize yourself with it, but it’s not the best way to develop an application that interacts with the API. The official documentation provides great insight into what libraries are available and in what language. Some of these are officially supported by Kubernetes, and some are supported by the community.
Whatever use you may have for a library, you can find it on the list linked in the previous paragraph, and every library has examples of how it can be used. If you don’t find exactly what you need, there are great communities around these libraries where you can find help.
Using a Kubernetes operator
The way you interact with the Kubernetes API depends on what language you’re writing in. Most likely you’ll want to use a client library as mentioned in the previous section. Any application can use a client library and integrate with the API, but using it in an operator is unique.
Operators are typically meant for automating tasks or allowing third-party tools to be more deeply integrated with your cluster. One way to use an operator is to have applications deployed on demand. Kubernetes has many options integrated for how to deploy an application, but sometimes you have a special use case.
Consider that you have a web UI where developers can spin up their own pods to make sure that the changes they are making work before merging it into the codebase. In that case, you may want to have an operator react to an event and then spin up that application in a pod.
Knowing API groups
Knowing about API Groups is not necessary to work with the API, but it can help you get started.
Kubernetes exposes many different endpoints for you to query. With few exceptions, all endpoints related to Kubernetes resources are located on the apis/ endpoint. To make things more easily accessible, endpoints are divided up into subcategories. You may have noticed that you always need to write an apiVersion in your YAML files.
When you want to create a Deployment, write apiVersion: apps/v1. In this case, the API Group is apps. This makes the API easier to work with, but it also makes it easy for you to figure out the group you need to query, considering all you have to do is look at the apiVersion field of your YAML files.
Monitoring cluster health
Once you have access to the Kubernetes API, the possibilities are endless.
For example, you can monitor the health of your application. Develop and deploy an application to your cluster, and by sending requests to the API about the health of your cluster, you can report issues back to your team. You can do this through the API endpoints that Kubernetes exposes, like /healthz, /livez, and /readyz.
When you want to deploy your application, as long as it only queries your cluster, it’s fairly easy to get it set up. In many cases where you want to interact with the API, you’ll have to set up authentication and authorization. By default, Kubernetes creates a service account with very limited access and mounts it to all pods. This limited access is just enough that you can monitor your cluster.
Securing API access
Now that you know how to interact with the Kubernetes API, it’s time to also make sure that you do so securely. The first thing is to make sure that the API is not publicly available. You may think that setting up the needed users and the correct permissions is enough. That’s a great step in securing your cluster, but locking it down based on IP should come first.
There are tons of bots constantly looking for open Kubernetes APIs. This is why your first step should be to put the IPs you know your organization uses on an allow list. Once that’s done, you can start creating users and using Role-Based Access Control (RBAC) to delegate permissions. RBAC allows you to give very granular permissions so that your users won’t be able to make changes outside what is necessary.
Then there are cases where you don’t want to secure the access of users, but rather your application. It’s possible to use the default service account, but you also have the option to create your own. You should be creating a service account per application and assigning it only the permission it needs. This can be done through Roles and RoleBinding, either using the default Roles available in any Kubernetes cluster or by creating your own.
Conclusion
After reading this article you should have a good understanding of the Kubernetes API, and you’ve got a solid foundation now on which to build your expertise. You’ve learned how to use kubectl to test out the functionalities it provides. You’ve learned how you can integrate it into your applications, and you’ve learned how to make it secure.
From here you can start looking more into what role the API can play in your organization, what you can improve by using it, and form a better understanding of what the API offers. One thing to keep in mind is that while it’s simple on the surface, the Kubernetes API does cover quite a bit of ground. Follow the best practices here to get started, and once you’re comfortable, grow your knowledge from there.
If you're looking to build robust internal tools using APIs, scripts, queries, and more, then take a look at Airplane. With Airplane, you can build powerful workflows and UIs using SQL queries, REST API calls, Python scripts, Javascript functions, and more. When combined with Airplane Views, a React-based platform for building UIs, these scripts can function as admin panels, deployment dashboards, incident management centers, and more.
Sign up for a free account or book a demo and start building powerful internal tools within minutes.
