Getting the most out of Kubernetes API Reference Docs

When it comes to managing a Kubernetes cluster and creating Kubernetes resources, you can either use the simple command line tool like kubectl or create manifest files in JSON or YAML.

While The first method is easier and faster to get your resources up and running, it only allows you to configure a limited set of properties. In a production environment, where you need more control and granularity on the objects you are creating on your Kubernetes cluster, you’ll want to go ahead with the manifest files method.

Let’s get a better idea about these two methods, then see how to use Kubernetes API reference documentation to simply the way creating and managing Kubenetes resources.

Creating Kubernetes Resources using kubectl run

Here is how simple it is to create a resource (a deployment in this example) in Kubernetes using kubectl run.

The command above launches a pod using the container image nginx:latest and expose an HTTP API on port 8080.

Once Kubernetes downloads the image from a trusted registry (Docker Hub by default, but you can configure other registries), you’ll be able to see that the pod running:

Creating Kubernetes Resources using Manifest Files

The other method for creating resources in Kubernetes is creating a JSON or YAML manifest that contains all the properties and specifications of your object ( It a can be a deployment, replica set, pod or service), then run it using kubectl create or kubectl apply.

Basically, the mandatory settings in the YAML file for creating or managing a resource are as follow:

For instance, for creating a pod, a basic YAML manifest file looks like this:

The v1 is to mention that we’re using version 1 of the Kubernetes API. The type of resource (kind) you’re describing here is a pod, with the name mynginx. The pod consists of a single container based on the nginx:latest image. You’ve also given a name to the container (mynginx) and indicated that it’s listening on port 8080.

After some time, you’ll have the pod up and running.

Getting the most out of Kubernetes API Reference Docs

As mentioned earlier, in a production environment, you’ll end up most probably writing your own manifest files than running simple kubectl commands to create your Kubernetes resources. This of course, has many benefits: control, flexibility, version control, …etc.

However, it can be a daunting task to create a JSON or YAML file from scratch, especially if you recently started to learn Kubernetes. And this why knowing how to read Kubernetes documentation and help might save your day.

When preparing a manifest, you can either turn to the Kubernetes reference documentation at to see which attributes are supported by each API object, or you can use the kubectl explain command.

Using Kubernetes Online API Reference Docs

The Kubernetes documentation a has section that contains references to all objects and properties that can be created in a Kubernetes cluser environement. You can go there by clicking on this Reference link in the Kubernetes Documentation web page.

Once there, click on the Kubernetes API version you are using, I’ll go ahead with version 1.12.

If you’re not sure which Kubernetes you are managing, run kubectl version and check the Server Version section.

The Kubernetes API Reference Overview and there you have it! A detailed source of information for any object you want to create in Kubernetes and a guide on how to write its corresponding YAML file.

For instance, Let’s suppose you want to create a simple YAML descriptor for a pod. All you have to do is to click on Pod v1 core batch link on the API OVERVIEW pane.

And you’ll have the main parts to be used to compose your file (apiVersion, kind, metadata, and spec), along with their description.

You can display a basic example by clicking on the kubectl example link.

To get further details about the specs, click on the PodSpec link to display the objects and properties that go under this section.

By only browsing the Kubernetes references help page back and forth and copying the objects needed, I was able to create a sample deployment manifest file (An nginx pod with 3 replicas) and run it in a matter of minutes.

You don’t have to memorize the role of all the properties that can used. You can read the description of each one of them in the reference docs while creating your file, then decide whether they’re needed or not.

Using Kubectl explain

Another method to get useful and detailed help for creating Kubernetes resources is to use the kubectl explain command. For example, when creating a pod manifest from scratch, you can start by asking kubectl to explain pods

Kubectl prints out the explanation of the object and lists the attributes the object can contain. You can then drill deeper to find out more about each attribute. For example, you can examine the spec attribute like this:

Following the same principle, you can go as deeper as you want by displaying any child object. For example, from above command, we could see that container description need to be under spec, but how about the way to write containers specifications inside the spec section.

With the help of the above commands, you would be able to start with a basic (to advanced) YAML manifest file as below


Knowing how to read Kubernetes help and API reference is very important to create and manage Kubernetes resources effectively and easily. So taking the necessary time to browse the help will save your time.

In fact, the four parts described previously (apiVersion, kind, metadata, spec) show the typical structure of a Kubernetes API object. Consequently, all other objects have the same anatomy. This makes understanding new objects (deployment, replica set, service, …etc) relatively easy.

Find this post interesting. Share it!

Leave a Comment

Your email address will not be published. Required fields are marked *