Take the Kubernetes API for a Spin

Datetime:2016-08-23 03:16:31          Topic: Kubernetes           Share

At the heart of Kubernetes is an application programming interface (API). In fact, everything and anything in the platform is treated as an API object. Tasks such as the creation and deletion of pods, services, and replica sets are all translated into appropriate REST API calls.

This article discovers the hidden gems of Kubernetes API along with a detailed walkthrough. To get more from this tutorial, you are advised to spin up a cluster for yourself.

Architecture & Background

One of the key components of Kubernetes control plane is the API server. It is responsible for dealing with the REST operations while providing the front-end to the cluster’s shared state through which all other components interact. Every operation that involves changing the state of a Kubernetes objects such as a Pod goes through the API server.

Kubectl , the command line interface to Kubernetes, is a simple yet powerful client of this API.

The lesser known fact is that there are multiple client libraries available for the Kubernetes API. While the Go client is the official one, there are 3rd party clients for Node.js, PHP, Python, and Java available on Github .

In a typical Kubernetes cluster, the API is exposed on port 443, which can be accessed through a TLS connection. The self-signed certificate, which is generated during the cluster creation or configuration, is available at $USER/.kube/config on the user’s machine. But the access to the API server can be simplified through the proxy, which we will configure in the tutorial.

The API server performs authentication, authorization, and admission control of clients. Refer to Kubernetes API documentation for more details.

Setting up the Cluster

There are three ways to get the Kubernetes cluster up and running:

  1. Minikube – This is the simplest way to get a Kubernetes cluster on your Mac or Windows machine. Follow the instructions mentioned on the GitHub page .
  2. Vagrant Multi-Node – If you want to go beyond the basics to get a sense of the real Kubernetes cluster, clone the CoreOS Kubernetes repo and fire the vagrant up The folks at CoreOS does a great job of maintaining the repo along with the step-by-step guide .
  3. Google Container Engine – This is by far the simplest way to gain access to a full-blown Kubernetes cluster. Sign up with Google Cloud Platform, download the Cloud SDK and spin up the mighty powerful GKE cluster .

The entire script for this tutorial is also available on GitHub .

Verifying the Installation

Once you have access to a running cluster, verify that everything is intact by running the following commands:

kubectl cluster-info

kubectl component-status

If you see a similar output, the Kubernetes cluster is in perfect shape. We are all set to explore the API.

Configuring the Proxy

The easiest way to access Kubernetes API is to configure a proxy. Luckily, kubectl comes with an option to configure it.

Open a new terminal window and run the following command to create the proxy.

kubectl proxy --port=8000

Through this proxy session, any request sent to localhost:8000 will be forwarded to the Kubernetes API server.

Now that we are all set, let’s go ahead and make our first API call. But before that, let’s explore the Swagger UI.

Accessing and Invoking the API

Visit http://localhost:8000/swagger-ui/ from the browser to access Swagger. This may not be available if you are using Minikube.

Expanding the /api/v1 section will show us all the available endpoints.

Let’s now use cURL to play with the API.

curl http://localhost:8000/api

Let’s have some more fun playing with the API. To make things readable, install jq , the versatile JSON command line parser.

One of the most commonly used commands is kubectl get nodes , which returns the following output.

The equivalent curl command to get all the nodes is pretty straight forward. Jq is used for making the output prettier and human readable.

curl -s http://localhost:8000/api/v1/nodes | jq '.items[] .metadata.labels'

If you like, you can also use Postman to explore Kubernetes API.

Let’s take this to the next level by creating a pod through the API.

Creating a Pod and Service from the API

First, let’s define a pod. The below command will create a simple NGINX pod.

cat > nginx-pod.json <<EOF
     "kind": "Pod",
     "apiVersion": "v1",
         "name": "nginx",
         "namespace": "default",
         "labels": {
             "name": "nginx"
     "spec": {
         "containers": [{
             "name": "nginx",
             "image": "nginx",
             "ports": [{"containerPort": 80}],
             "resources": {
                 "limits": {
                     "memory": "128Mi",
                     "cpu": "500m"

We will then create a service definition to expose the NGINX pod that was just scheduled.

cat > nginx-service.json <<EOF
 "kind": "Service",
 "apiVersion": "v1",
 "metadata": {
 "name": "nginx-service",
 "namespace": "default",
 "labels": {"name": "nginx"}
 "spec": {
 "ports": [{"port": 80}],
 "selector": {"name": "nginx"}

The next step is to create the pod object by invoking the following command.

curl -s http://localhost:8000/api/v1/namespaces/default/pods \
-XPOST -H 'Content-Type: application/json' \
-d@nginx-pod.json \
| jq '.status'

We filtered the cURL output only to show the status. In a few seconds, the NGINX image will be downloaded and scheduled in one of the nodes.

With the NGINX pod in place, let’s also create a service. This process is very similar to the creation of the pod.

curl -s http://localhost:8000/api/v1/namespaces/default/services \

-XPOST -H 'Content-Type: application/json' \

-d@nginx-service.json \

| jq '.spec.clusterIP'

Let’s make sure that both the objects are created. We will use kubectl to list the pods and services.

kubectl get pods

kubectl get svc

Finally, let’s access the Nginx service through the proxy.

curl http://localhost:8000/v1/proxy/namespaces/default/services/nginx-service/

Time to clean up by deleting the pod and the service that we created.

curl http://localhost:8000/api/v1/namespaces/default/services/nginx-service -XDELETE
curl http://localhost:8000/api/v1/namespaces/default/pods/nginx -XDELETE


Kubernetes is one of the most extensible container orchestration engines available today. Powered by Google’s decades of experience in managing massive infrastructure, it brings web-scale computing to masses. The API-first approach makes Kubernetes programmable and extensible. As we have seen in the walkthrough, it is easy to get started with the API. Any task that can be performed through the dashboard or kubectl client is exposed as an API.

If you want to get started with Kubernetes, please do register for the free webinar that I am co-hosting, on Monday, August 29. We will show you how to setup your development environment, and deploy your first application.

Feature image via Pixabay.

About List