Read and write Kubernetes objects using kubernetes.io API reference documentation

Once you have deployed your Kubernetes infrastructure, you have a control plane and a worker plane. You define how you want Kubernetes to manage your Kubernetes objects through tools that interact with the API. Kubernetes objects are all those persistent entities in the Kubernetes system, such as your Pods, Nodes, Services, Namespaces, ConfigMaps, Events.

Most operations can be performed through the kubectl command-line interface or other command-line tools, such as kubeadm, which in turn use the API.

kubectl is the command-line tool where you run most of the commands to manage the Kubernetes clusters. Use kubectl to deploy applications, inspect and manage cluster resources, and view logs.

In this post, learn how to use the Kubernetes documentation to discover the objects, how to figure out to describe the state you want for your Kubernetes objects. In particular, you will want to know the fields to use in your .yaml files and how to determine what the default values are. You will also learn the basic kubectl commands.

Interacting with Kubernetes objects

A Kubernetes object is a “record of intent” or the desired state of what you want your cluster to look like. Once you create the object, the Kubernetes system will constantly work to ensure that object exists.

Just about every object includes two nested object fields:

The object spec. When you create the object, this is the desired state.
The object status. When you query the object, this is the current state supplied and updated by the Kubernetes system and its components.

Ways to manage objects

The kubectl command-line tool supports several different ways to create and manage Kubernetes objects:

Imperative command lets you run directly on the live object. It is good for “quick and dirty” environments to do a one-off task on a cluster. You just run a kubectl command, such as kubectl create deployment nginx --image nginx, which runs an instance of the nginx container.
Imperative object where you provide the kubectl command for the operation (create, replace, etc.), optional flags and at least one file name. The file specified must contain a full definition of the object in YAML or JSON format. For example, kubectl create -f nginx.yaml creates the objects in the nginx.yaml file.
Declarative object configuration where you operate on a file locally, but you do not need to define the operations. Kubernetes will figure out what needs to be done, including create, update, and delete.

It is a best practice to manage Kubernetes using only one technique. Mixing and matching techniques for the same object results in undefined behavior.

For more information, see Kubernetes Object Management.

Object descriptions

You describe the object using yaml files when you use kubectl. (As a side note, kubectl converts the information to JSON when making the API request. But you will generally work with yaml.)

For example, the following yaml describes a sample Deployment object that deploys an nginx image.

	apiVersion: apps/v1 # for versions before 1.9.0 use apps/v1beta2
	kind: Deployment
	metadata:
	name: nginx-deployment
	spec:
	selector:
	matchLabels:
	app: nginx
	replicas: 2 # tells deployment to run 2 pods matching the template
	template:
	metadata:
	labels:
	app: nginx
	spec:
	containers:
	– name: nginx
	image: nginx:1.14.2
	ports:
	– containerPort: 80

view raw

ngnix.yaml

hosted with ❤ by GitHub

But how do you learn what should be in the Deployment object?

Kubernetes documentation

In this case, the Deployment object is defined in v1.18 API documentation. The documentation can change between versions. So the API calls (and the kubectl yaml files) need to match the version you are using. See Available Documentation Versions. Click on your version. Click Reference in the left panel. Scroll to see API Reference under Design Documents headline, the click your version number several times until you see the reference documentation.

Here are links for the current version as of the writing of this post:

The format is https://[versionnumber].docs.kubernetes.io/docs/reference/generated/kubernetes-api/[versionnumber]/. The version number includes the v[majorversion]-[minorversion].

Go to the link of the API you want, then click Deployment v1 apps to see the fields and descriptions and the list of operations you can perform, as shown in the following illustration.

k8s deployment docs

The various objects are in the left panel and the object description are on the right. You can get an example of the object yaml by clicking on Example button.

k8s deployment example