Best of 2018: Introduction to Using the Kubernetes REST API

As we close out 2018, we at Container Journal wanted to highlight the five most popular articles of the year. Following is the third in our weeklong series of the Best of 2018.

Kubernetes has taken the container orchestration space by storm. It’s created a vibrant ecosystem, and in 2017 451 Research found that 71 percent of respondents were using Kubernetes to manage their containers.

Many have found significant benefits in using a clustered container orchestration system. For example, Datadog recently found that “Kubernetes containers churn 8x faster than ECS containers.” While this is impressive, is there any way to extend the Kubernetes experience?

Using the programmatic Kubernetes REST API could prove useful for streamlining particular cluster management duties. For the sake of this walkthrough, we’ll analyze how to initiate sample actions on container clusters directly through the Kubernetes REST API, using curl as an HTTP client.

Setting Up Kubernetes REST API Access

At the heart of Kubernetes is an API; in fact, everything in Kubernetes is treated as an API object. You can translate the creation or deletion of pods, replica sets, services and other cluster management actions into REST API calls.

To access your clusters via the API you must first have a cluster (Duh). You can use Minikube to generate a cluster. Now, the `kubectl` CLI tool must be set up to communicate with it.

Since `kubectl` handles locating and authenticating to the API server, it’s recommended to run it in proxy mode for easier authentication and better security. Alternatively, you can also access the API using official client libraries in Go or Python, or other community maintained libraries.

You can initiate the proxy as follows:

““

$ kubectl proxy –port=8000

““

With this proxy in place, all calls to `localhost:8000` will be sent to the Kubernetes API Server.

 

How to Explore the API

To learn the API methods and parameters, you can explore the Kubernetes API reference here. Alternatively, they provide a raw 3.5 MB Open API Specification (fka Swagger) to describe all API processes. To make this human-readable, download the API Spots Google Chrome extension. This can be used to generate a GUI for clean, interactive API documentation.

A bit on Kubernetes API terminologies. Kubernetes API resources types are either “objects,” such as pods or namespaces, or are “virtual,” representing operations or services. They all have JSON schema representation. Another definition is “collections,” which are lists of resources type instances.

Retrieving Information on Pods and Resources

Let’s walk through a few sample API calls. A simple function would be to list all the pods in a particular namespace. This following `GET` call will do just that:

““

GET /api/v1/namespaces/test/pods

““

This will return a JSON object:

““

200 OK

Content-Type: application/json

{

“kind”: “PodList”,

“apiVersion”: “v1”,

“metadata”: {“resourceVersion”:”1001″},

“items”: […]

}

““

Having programmatic access to this metadata can aid in modeling the structure of a cluster. Notice the `resourceVersion` assignment? All Kubernetes objects are required to tap into “watch,” a notification feed that listens for changes in the underlying database, enabling clients to detect change (creates, deletes, or updates) and stay updated.

With that in mind, we could further this inspection by requesting notification of changes starting at a specific resource version. This test will return changes from resource “1001” onward.

““

GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=1001

““

What we get are small JSON objects per each resource. For example, if resourceVersion “1020” had been modified since the last update, we would see a response like this:

““

200 OK

Transfer-Encoding: chunked

Content-Type: application/json

{

“type”: “MODIFIED”,

“object”: {“kind”: “Pod”, “apiVersion”: “v1”, “metadata”: {“resourceVersion”: “1020”, …}, …}

}

““

Tips for Working with Large Clusters

When working with large clusters, you may want to consider putting limits on the response package. Thankfully, the Kubernetes API offers this sort of pagination.

To break responses into individual chunks, utilize the `limit` and `continue` parameters. For example, if you wanted to receive a group of only 300 pods at a time, tie a limit into the API request:

““

GET /api/v1/pods?limit=300

““

The JSON response would look something like:

““

200 OK

Content-Type: application/json

{

“kind”: “PodList”,

“apiVersion”: “v1”,

“metadata”: {

“resourceVersion”:”1020″,

“continue”: “ENCODED_CONTINUE_TOKEN”,

},

“items”: […] // returns pods 1-300

}

““

This option provides developer consumers the ability to customize calls to better fit their requirements.

As you can see above, the `continue` parameter outputs a token that can be used to request additional pods. To continue retrieving information, we’d insert that token as follows to continue to the next set of data:

““

GET /api/v1/pods?limit=300&continue=ENCODED_CONTINUE_TOKEN

““

Final Thoughts

We can learn a bit about how Kubernetes functions simply by perusing its API. Of course, simply retrieving data is the cusp of the multitude of API functionalities that can be performed. Using HTTP verbs (POST, PUT, PATCH, DELETE, GET), you can retrieve, edit and delete your resources and perform advanced functions on Kubernetes clusters.

Thankfully, the Kubernetes API has been designed to be flexible, with smart controls for detecting change. Having the ability to iteratively detect change using “watches,” and the ability to request lists allows other components “to effectively cache and synchronize the state of resources.”

We’ve only scratched the surface in this walkthrough. For additional resources, see the API reference. For power users considering editing the API Kubernetes comes packaged with, it’d a good idea to follow the API changes community board for said information.

Bill Doerrfeld

Bill Doerrfeld is a tech journalist and analyst. His beat is cloud technologies, specifically the web API economy. He began researching APIs as an Associate Editor at ProgrammableWeb, and since 2015 has been the Editor at Nordic APIs, a high-impact blog on API strategy for providers. He loves discovering new trends, interviewing key contributors, and researching new technology. He also gets out into the world to speak occasionally.

Bill Doerrfeld has 105 posts and counting. See all posts by Bill Doerrfeld