Kubernetes objects

In the Kubernetes cluster, the cluster state is managed by the kube-apiserver component and is persisted in the etcd cluster. The state is abstracted and modeled as a set of Kubernetes objects – these entities describe what containerized applications should be run, how they should be scheduled, and are the policies concerning restarting or scaling them. If there is anything you would like to achieve in your Kubernetes cluster, then you have to create or update Kubernetes objects. This type of model is called a declarative model – you declare your intent and Kubernetes is responsible for changing the current state of the cluster to the desired (intended) one. The declarative model and the idea of maintaining the desired state is what makes Kubernetes so powerful and easy to use.

The anatomy of each Kubernetes Object is exactly the same; it has two fields:

• Spec: This defines the desired state of the Object. This is where you define your requirements when creating or updating an Object.
• Status: This is provided by Kubernetes and describes the current state of the Object.

Working with Kubernetes objects always requires using the Kubernetes API. Most commonly, you will manage Kubernetes objects using the command-line interface (CLI) for Kubernetes, which comes as a kubectl binary. It is also possible to interact with the Kubernetes API directly using client libraries.

Now, let's take a quick look at how an example Kubernetes Object is structured. When interacting directly with the Kubernetes API, objects must be specified in JSON format. However, kubectl allows us to use YAML manifest files, which are translated into JSON when you perform operations. Using YAML manifest files is generally recommended and you can expect most of the examples that you find in the documentation to follow this convention. As an example, we will use a definition of a Pod that consists of a single nginx web server Linux container, stored in a file called nginx.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod-example
  labels:
    app: nginx-host
spec:
  containers:
  - name: nginx
    image: nginx:1.17
    ports:
    - containerPort: 80

The required parts in the manifest file are as follows:

• apiVersion: The version of the Kubernetes API being used for this Object.
• kind: The type of Kubernetes Object. In this case, this is Pod.
• metadata: Additional metadata for the Object.
• spec: The Object Spec. In the example specification, the nginx container uses the nginx:1.17 Docker image and exposes port 80. The Spec is different for every Kubernetes Object and has to follow the API documentation. For example, for Pod, you can find the API reference here: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#podspec-v1-core.

Creating the Pod is now as simple as running the following kubectl apply command:

kubectl apply -f nginx.yaml

If you would like to try out this command without a local Kubernetes cluster, we recommend using one for Kubernetes playground; for example, https://www.katacoda.com/courses/kubernetes/playground:

1. In the master window, run the following kubectl command, which will apply a manifest file hosted on GitHub:

kubectl apply -f https://raw.githubusercontent.com/PacktPublishing/Hands-On-Kubernetes-on-Windows/master/Chapter04/01_pod-example/nginx.yaml

2. After a few seconds, the Pod will be created and its STATUS should be Running:

master $ kubectl get pod -o wide
NAME                READY   STATUS    RESTARTS   AGE   IP          NODE     NOMINATED NODE   READINESS GATES
nginx-pod-example   1/1     Running   0          15s   10.40.0.1   node01   <none>           <none>

3. Use the curl command in the master window to get the Pod's IP (in this case, 10.40.0.1) to verify that the container is indeed running. You should see the raw contents of the default nginx web page:

curl http://10.40.0.1:80

Now, let's take a closer look at the Pod API Object.