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.

$ kubectl run sise --image=nginx:latest --port=8080
kubectl run --generator=deployment/apps.v1beta1 is DEPRECATED and will be removed in a future version. Use kubectl create instead.
deployment.apps/sise created

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:

$ kubectl get pods
NAME                      READY     STATUS    RESTARTS   AGE
nginx-6867b5b964-599ln    1/1       Running   0          1m

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:

# Descriptor conforms to version v1 of Kubernetes API
# The type of resource you are creating (Deployment, pod, ...etc).
# Description of your resource
# The actual objects and their properties that you want to create

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

apiVersion: v1               
kind: Pod                    
  name: mynginx         
  - image: nginx:latest       
	name: mynginx              
	- containerPort: 8080    
	  protocol: TCP

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.

$ kubectl create -f pod-mynginx.yaml
pod/mynginx created

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

$ kubectl get pods
NAME                                READY   STATUS             RESTARTS   AGE
mynginx                             1       Running            1          20s

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.

$ kubectl version
Client Version: version.Info{Major:"1", Minor:"12", GitVersion:"v1.12.1", GitCommit:"4ed3216f3ec431b140b1d899130a69fc671678f4", GitTreeState:"clean", BuildDate:"2018-10-05T16:46:06Z", GoVersion:"go1.10.4", Compiler:"gc", Platform:"linux/amd64"}
Server Version: version.Info{Major:"1", Minor:"10", GitVersion:"v1.10.0", GitCommit:"fc32d2f3698e36b93322a3465f63a14e9f0eaead", GitTreeState:"clean", BuildDate:"2018-03-26T16:44:10Z", GoVersion:"go1.9.3", Compiler:"gc", Platform:"linux/amd64"}

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.

$ cat web-deploy.yaml

# ====== Nginx Web Deployment
apiVersion: apps/v1beta1
kind: Deployment
  name: deployment-sample
  minReadySeconds: 5
  replicas: 3
  revisionHistoryLimit: 12
      role: web
      maxSurge: 2
      maxUnavailable: 2
    type: RollingUpdate
      name: web
        app: web
        role: frontend
        version: v1
      - name: frontend
        image: nginx:latest
$ kubectl apply -f web-deploy.yaml
deployment.apps/deployment-sample created
$ kubectl get deploy
deployment-sample   3         3         3            3           29s

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 explain pod
KIND:     Pod

	 Pod is a collection of containers that can run on a host. This resource is
	 created by clients and scheduled onto hosts.

   apiVersion   <string>
	 APIVersion defines the versioned schema of this representation of an
	 object. Servers should convert recognized schemas to the latest internal
	 value, and may reject unrecognized values. More info:

   kind <string>
	 Kind is a string value representing the REST resource this object
	 represents. Servers may infer this from the endpoint the client submits
	 requests to. Cannot be updated. In CamelCase. More info:

   metadata     <Object>
	 Standard object's metadata. More info:

   spec <Object>
	 Specification of the desired behavior of the pod. More info:

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:

	$ kubectl explain pod.spec
	RESOURCE: spec <Object>

		Specification of the desired behavior of the pod...
		podSpec is a description of a pod.

	   hostPID   <boolean>
		 Use the host's pid namespace. Optional: Default to false.

	   volumes   <[]Object>
		 List of volumes that can be mounted by containers belonging to the

	   Containers  <[]Object> -required-
		 List of containers belonging to the pod. Containers cannot currently
		 Be added or removed. There must be at least one container in a pod.
		 Cannot be updated. More info:

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.

	$ kubectl explain pod.spec.containers

	KIND:     Pod

	RESOURCE: containers <[]Object>

		 List of containers belonging to the pod. Containers cannot currently be
		 added or removed. There must be at least one container in a Pod. Cannot be

		 A single application container that you want to run within a pod.

	   args <[]string>
		 Arguments to the entrypoint. The docker image's CMD is used if this is not
		 provided. Variable references $(VAR_NAME) are expanded using the
		 container's environment...
	  image        <string>
		 Docker image name. More info: This field is
		 optional to allow higher level config management to default or override
		 container images in workload controllers like Deployments and StatefulSets.

	  name <string> -required-
		 Name of the container specified as a DNS_LABEL. Each container in a pod
		 must have a unique name (DNS_LABEL). Cannot be updated.

	   ports        <[]Object>
		 List of ports to expose from the container. Exposing a port here gives the
		 system additional information about the network connections a container
		 uses, but is primarily informational. Not specifying a port here DOES NOT
		 prevent that port from being exposed. Any port which is listening on the
		 default "" address inside a container will be accessible from the
		 network. Cannot be updated.

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

$ cat pod-websrv.yaml

apiVersion: v1
kind: Pod
  name: httpd
  - name: web-server
    image: httpd:latest
    - name:
      containerPort: 80
      hostPort: 80
$ kubectl apply -f pod-websrv.yaml
pod/httpd created
$ kubectl get pods
NAME            READY   STATUS             RESTARTS   AGE
httpd           1       Running            1          30s


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.

Leave a Comment

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