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 thenginx.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.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
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.
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.
To see an example of how to Create a deployment:
- Click Deployment v1
- Click Write Operations
- Click Create
- Click kubectl request example button
- Click kubectl response example button.
The payoff is that you get the keys to the Kubernetes kingdom. The following illustration shows both the request and the response.
The kubectl create -f command is shows too.
The fields for the Kubernetes object
To see the object’s fields, click on Deployment v1 apps. (You may need to click the Example button to hide the previous example code.)
Each field is documented. Click DeploymentSpec to see the fields that you can provide in the spec part of Deployment object.
In this example, you can see how to set the number of replicas and what the default value is.
You can continue to see each of the objects that are nested to see how to read, write and get status of each of the Kubernetes objects.
Next steps
- Read the Kubectl book for details of managing objects by Kubectl
- Review the kubectl Cheat Sheet
References
- For a complete list of kubectl operations, see Overview of kubectl.