Kubernetes Primitives

Kubernetes primitives are the basic building blocks anchored in the Kubernetes architecture for creating and operating an application on the platform. Even as a beginner to Kubernetes, you might have heard of the terms Pod, Deployment, and Service — all of those terms are Kubernetes primitives. Apart from the ones mentioned, there are many more that serve a dedicated purpose in the Kubernetes architecture.

To draw an analogy think back to concepts of object-oriented programming (OOP). In object-oriented programming languages, a class defines the blueprint of a real-world functionality, its properties and behavior. A Kubernetes primitive is the equivalent of a class. The instance of a class in object-oriented programming is an object, managing its own state with the ability to communicate with other parts of the system. Whenever you create a Kubernetes object, you produce such an instance.

For example, a Pod in Kubernetes is the class of which there can be many instances with their own identity. Every Kubernetes object has a system-generated unique identifier (also known as UID) to clearly distinguish between the entities of a system. Later, we’ll have look at the properties of a Kubernetes object. Figure 2-1 illustrates the relationship between a Kubernetes primitive and an object.

Figure 2-1. Kubernetes object identity

Each and every Kubernetes primitive follows a general structure which you can observe if you have a deeper look at a manifest of an objects, as shown in Figure 2-2. The primary markup language used for a Kubernetes manifest is YAML.

Figure 2-2. Kubernetes resource structure

Let’s discuss each section and its relevance within the Kubernetes system.

API version

The Kubernetes API version defines the structure of a primitive and uses it to validate the correctness of the data. The API version serves a similar purpose as XML schemas to a XML document or JSON schema to JSON document. The version usually undergoes a maturity process e.g. from alpha to beta to final. Sometimes you see different prefixes separated by a slash e.g. apps. You can list the API versions compatible with your cluster version by running the command kubectl api-versions.

Kind

The kind defines the type of primitive e.g. a Pod or a Service. It ultimately answers the question “What type of object are we dealing with here?”.

Metadata

Metadata describes higher-level information about the object e.g. its name, what namespace it lives in or whether it defines labels and annotations? This section also defines the UID I mentioned earlier, the object’s identity.

Spec

The specification or short “spec” describes the desired state. How should this object look like after is has been created? For example, how to decide which image to run in the container or which environment variables to set.

Status

The status describes the actual state of an object. The Kubernetes scheduler constantly tries to transition a Kubernetes object from the desired state into the actual state. The object has not be materialized yet if the YAML status shows the value {}.

With this basic structure in mind, let’s have a look at how to create a Kubernetes object with the help of kubectl.

Using kubectl to Interact with the Kubernetes Cluster

Kubectl is the primary tool to interact with the Kubernetes clusters from the command line. The CKAD exam is exclusively focused on the use of kubectl. Therefore, it’s paramount to understand the ins and outs of kubectl and practice its use heavily.

In this section, I want to provide you with a very brief overview on its typical usage pattern. Let’s start by looking at the syntax for running commands first. A kubectl execution consists of a command, a resource type, a resource name and optional command line flags.

$ kubectl [command] [TYPE] [NAME] [flags]

The command specifies the operation, you are planning to run. Typical commands are create, get, describe, or delete. Next, you’ll need to provide the resource type you are working on either as full resource type or its short form. For example, you could work on a service here or use the short form svc. The name of the resource identifies the user-facing object identifier, effectively the value of metadata.name in the YAML representation. Be aware that the object name is not the same as the UID. The UID is an auto-generated, Kubernetes-internal object reference which you usually don’t have to interact with. The name of an object has to be unique across all objects of the same resource type within in a namespace. Finally, you can provide zero to many command line flags to describe additional configuration behavior. The --port flag to expose of a Pod’s container port is a typical example of a command line flag.

Figure 2-3 shows a full kubectl command in action.

Figure 2-3. Kubectl usage pattern

In the course of this book, we’ll explore the kubectl commands that make you the most productive during the CKAD exam. There are many more, however, and they usually go beyond the ones you’d use as application developer on a day-to-day basis. Next up, we’ll have a deeper look at the create command, the imperative way to create a Kubernetes object. Moreover, we’ll compare the imperative object creation approach with the declarative approach.

Object Management

You can create objects in a Kubernetes cluster in two ways, imperatively or declaratively. The following sections will describe each approach including their benefits, drawbacks and use cases.

$ kubectl run frontend --image=nginx --port=80
pod/frontend created

$ vim pod.yaml
$ kubectl create -f pod.yaml
pod/frontend created

$ kubectl run frontend --image=nginx --port=80 
  -o yaml --dry-run=client > pod.yaml
$ vim pod.yaml
$ kubectl create -f pod.yaml
pod/frontend created
$ kubectl describe pod frontend
Name:         frontend
Namespace:    default
Priority:     0
...

$ kubectl delete pod frontend
pod "frontend" deleted
$ kubectl delete -f pod.yaml
pod "frontend" deleted

$ kubectl edit pod frontend

$ kubectl replace -f pod.yaml

$ kubectl apply -f pod.yaml
pod/frontend configured

Understanding Pods

The most important primitive in the Kubernetes API is the Pod. A Pod lets you run an application inside of a container represented by a Docker image. In practice, you will often encounter a one to one mapping between a Pod and a container, however, there are use cases we’ll discuss in a later chapter that benefit from running more than a single container.

In addition to just running a container, a Pod can consume other services like a persistent storage, configuration data and much more. Therefore, think of a Pod as a wrapper for running containers including the mediator functionality with other Kubernetes objects.

Before jumping deeper into the coverage of a Pod, let’s first explore the role Docker plays in the Kubernetes ecosystem.

Containerization with Docker

Kubernetes is a container orchistrator that uses a container runtime to instantiate containers inside of Pods. By default, this container runtime is Docker. While it is not strictly necessary to understand Docker as a whole for the exam, you should at least be familiar with its basics. In this section, we’ll talk about Docker’s foundational concepts and commands. It is safe to skip this section if you are already familiar with Docker.

Basic Docker Concepts

A container packages an application into a single unit of software including its runtime environment and configuration. This unit of software usually includes the operating system, the application’s source code or the binary, its dependencies and other system tools deemed necessary. The declared goal of a container is to decouple the runtime environment from the application to avoid the “works on my machine” problem.

The process of bundling an application into a container is commonly-referred to as “containerization”. Containerization works based on instructions defined in a so-called Dockerfile. The Dockerfile explicitly spells out what needs to happen when the software is built. The result of the operation is a image. The image is usually published to a registry for consumption by other stakeholders. Docker Hub is the primary registry for Docker images available for public use. Figure 2-4 illustrates the concepts in the context of containerizing an application.

Figure 2-4. Containerization Process

To summarize, the Dockerfile is a blueprint of how the software should be built, the image is the artifact produced by the process, and the container is an running instance of the image serving the application. Let’s have a look at a more concrete example.

FROM openjdk:11-jre-slim
WORKDIR /app
COPY target/java-hello-world-0.0.1.jar java-hello-world.jar
ENTRYPOINT ["java", "-jar", "/app/java-hello-world.jar"]
EXPOSE 8080

$ docker build -t java-hello-world:1.0.0 .
Sending build context to Docker daemon   8.32MB
Step 1/5 : FROM openjdk:11-jre-slim
 ---> 973c18dbf567
Step 2/5 : WORKDIR /app
 ---> Using cache
 ---> 31f9c5f2a019
Step 3/5 : COPY target/java-hello-world-0.0.1.jar java-hello-world.jar
 ---> Using cache
 ---> 6a1deee17e9d
Step 4/5 : ENTRYPOINT ["java", "-jar", "/app/java-hello-world.jar"]
 ---> Using cache
 ---> 52a91ca70d86
Step 5/5 : EXPOSE 8080
 ---> Using cache
 ---> 3e9c22451a17
Successfully built 3e9c22451a17
Successfully tagged java-hello-world:1.0.0

$ docker images
REPOSITORY         TAG           IMAGE ID       CREATED              SIZE
java-hello-world   1.0.0         3e9c22451a17   About a minute ago   213MB
openjdk            11-jre-slim   973c18dbf567   20 hours ago         204MB

$ docker run -d -p 8080:8080 java-hello-world:1.0.0
b0ee04accf078ea7c73cfe3be0f9d1ac6a099ac4e0e903773bc6bf6258acbb66

$ curl localhost:8080
Hello World!

$ docker login --username=bmuschko
Password: *****
WARNING! Your password will be stored unencrypted in /Users/bmuschko/
.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded
$ docker tag java-hello-world:1.0.0 bmuschko/java-hello-world:1.0.0
$ docker push bmuschko/java-hello-world:1.0.0
The push refers to repository [docker.io/bmuschko/java-hello-world]
be6f48684f94: Pushed
ff3b0a3f736e: Pushed
a346421f0657: Mounted from library/openjdk
cab8f1f311d9: Mounted from library/openjdk
0a71386e5425: Mounted from library/openjdk
ffc9b21953f4: Mounted from library/openjdk
1.0.0: digest: sha256:aafd2ab53ba3ff66fe66d7ffc118c7a8ea993472132d1bdf417a 
62e212f3dcfd size: 1578

Creating Pods

In this chapter, we will only look at the creation of a Pod running a single container. Jump right over to the chapter 4, “Multi-container Pods”, if you want to learn more about Pods that run more than one container. That chapter explains applicable design patterns and how to interact with individual containers using kubectl.

The Pod defintion needs to state an image for every container. Upon creating the Pod object, imperatively or declaratively, the Kublet will check if the image already exists locally. If the image doesn’t exist yet, the Kublet will download it from a registry. By default the registry is Docker Hub. As soon as the image exists on the node, the container is instantiated and run. Figure 2-4 demonstrates the execution flow on a high-level.

Figure 2-5. Kubelet interation with Docker images

The run command is the central entry point for creating Pods imperatively. Let’s talk about its usage and the most important command line options you should memorize and practice. Say you wanted to run a Hazelcast instance inside of a Pod. The container should use the latest Hazelcast image, expose port 5701, and define an environment variable. In addition, we’ll also want to assign two labels to the Pod. The following command combines of this information and does not require any further editing of the live object.

$ kubectl run hazelcast --image=hazelcast/hazelcast --port=5701 
  --env="DNS_DOMAIN=cluster" --labels="app=hazelcast,env=prod"

The run command offers a wealth of command line options. Execute the kubectl run --help or refer to the Kubernetes documentation for a broad overview. For the CKAD exam, you will not need to understand each and every command. Table 2-1 lists the most commonly-used options.

Some developers are more used to the creation of Pods from a YAML manifest. Probably you are already accustomed to the declarative approach because you are using it at work. You can express the same configuration for the Hazelcast Pod by opening the editor, copying a Pod YAML code snippet from the Kubernetes online documentation and modifying it to your needs. Example 2-2 shows the Pod manifest saved in the file pod.yaml.

apiVersion: v1
kind: Pod
metadata:
  name: hazelcast
  labels:
    app: hazelcast
    env: prod
spec:
  containers:
  - env:
    - name: DNS_DOMAIN
      value: cluster
    image: hazelcast/hazelcast
    name: hazelcast
    ports:
    - containerPort: 5701

Creating the Pod from the manifest is straightforward. Simply use the create or apply command.

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

Listing Pods

Now that you created a Pod, you can further inspect its runtime information. The kubectl command offers a command for listing all Pods running in the cluster: get pods. The following command renders the Pod named hazelcast:

$ kubectl get pods
NAME        READY   STATUS    RESTARTS   AGE
hazelcast   1/1     Running   0          17s

Real-world Kubernetes clusters can run hundreds of Pods at the same time. If you know the name of the Pod of interest, its often times easier to query by name. We’d still only see a single Pod.

$ kubectl get pods hazelcast
NAME        READY   STATUS    RESTARTS   AGE
hazelcast   1/1     Running   0          17s

Pod Lifecycle Phases

It’s absolutely possible that the status of the Pod doesn’t show a Running status right away when listing the Pods. It usually takes a couple of seconds to retrieve the image and start the container. Upon Pod creation, the object goes through several lifecycle phases, as shown in Figure 2-6.

Figure 2-6. Pod Lifecycle Phases

Understanding the implications of each phase is important as it gives you an idea about the operational status of a Pod. For example, during the exam you may be asked to identify a Pod with an issue and further debug the object. Table 2-1 describes all Pod lifecycle phases.

Rendering Pod Details

The rendered table produced by the get command provides high-level information about a Pod. But what if you needed to have a deeper look at the details? The describe command can help.

$ kubectl describe pods hazelcast
Name:               hazelcast
Namespace:          default
Priority:           0
PriorityClassName:  <none>
Node:               docker-desktop/192.168.65.3
Start Time:         Wed, 20 May 2020 19:35:47 -0600
Labels:             app=hazelcast
                    env=prod
Annotations:        <none>
Status:             Running
IP:                 10.1.0.41
Containers:
  ...
Events:
  ...

The terminal output contains the metadata information of a Pod, the containers it runs and the event log, such as failures when the Pod was scheduled. The example output above has been condensed to just show the metadata section. You can expect the output to be very lengthy.

There’s a way to be more specific about the information you want to render. You can combine the describe command with a Unix grep command. Say you wanted to identify the image for running in the container.

$ kubectl describe pods hazelcast | grep Image:
    Image:          hazelcast/hazelcast

Accessing Logs of a Pod

As application developers, we know very well what to expect in the log files produced by the application we implemented. Runtime failures may occur when operating an application in a container. The logs command downloads the log output of a container. The output below indicates that the Hazelcast server started up successfully.

$ kubectl logs pod/hazelcast
...
May 25, 2020 3:36:26 PM com.hazelcast.core.LifecycleService
INFO: [10.1.0.46]:5701 [dev] [4.0.1] [10.1.0.46]:5701 is STARTED

It’s very likely that more log entries will be produced as soon as the container receives traffic from end users. You can stream the logs with the command line option -f. This option is helpful if you want to see logs in real-time.

Kubernetes tries to restart a container under certain conditions, such as if the image cannot be resolved on the first try. Upon a container restart, you will not have access to the logs of the previous container anymore; the logs command only renders the logs for the current container. However, you can still get back to the logs of the previous container by adding the -p command line option. You may want to use the option to identify the root cause that triggered a container restart.

Executing a Command in Container

There are situation that require you to log into the container and explore the file system. Maybe you want to inspect the configuration of your application or debug the current state of your application. You can use the exec command to open a shell in the container to explore it interactively, as shown below.

$ kubectl exec -it hazelcast -- /bin/sh
# ...

Notice that you do not have to provide the resource type. This command only works for a Pod. The two dashes (--) separate the exec command and its options from the command you want to run inside of the container.

It’s also possible to just execute a single command inside of a container. Say you wanted to render the environment variables available to containers without having to be logged in. Just remove the interactive flag -it and provide the relevant command after the two dashes.

$ kubectl exec hazelcast -- env
...
DNS_DOMAIN=cluster

Deleting a Pod

Sooner or later you will want to delete a Pod. During the exam, you may be asked to remove a Pod. Or possibly, you made a configuration mistake and want to start the question from scratch.

$ kubectl delete pod hazelcast
pod "hazelcast" deleted

Keep in mind that Kubernetes tries to delete a Pod gracefully. This means that the Pod will try to finish active requests to the Pod to avoid unnecessary disruption to the end user. A graceful deletion operation can take anywhere from 5-30 seconds, time you don’t want to waste during the exam. See chapter 1 for more information on how to speed up the process.

An alternative way to delete a Pod is to point the delete command to the YAML manifest you used to create it. The behavior is the same.

$ kubectl delete -f pod.yaml
pod "hazelcast" deleted

Configuring Pods

The CKAD curriculum expects you to feel comfortable with editing YAML manifests either as files or as live object representations. In this section, I want to point you to some of the typical configuration scenarios you may face during the exam. Later chapters will deepen your knowledge by touching on other configuration aspects.

apiVersion: v1
kind: Pod
metadata:
  name: spring-boot-app
spec:
  containers:
  - image: bmuschko/spring-boot-app:1.5.3
    name: spring-boot-app
    env:
    - name: SPRING_PROFILES_ACTIVE
      value: prod
    - name: VERSION
      value: '1.5.3'

$ kubectl run mypod --image=busybox -o yaml --dry-run=client 
  > pod.yaml -- /bin/sh -c "while true; do date; sleep 10; done"

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: mypod
  name: mypod
spec:
  containers:
  - args:
    - /bin/sh
    - -c
    - while true; do date; sleep 10; done
    image: busybox
    name: mypod
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Never
status: {}

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: mypod
  name: mypod
spec:
  containers:
  - command: ["/bin/sh"]
    args: ["-c", "while true; do date; sleep 10; done"]
    image: busybox
    name: mypod
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Never
status: {}

$ kubectl create -f pod.yaml
pod/mypod created
$ kubectl logs pod/mypod -f
Fri May 29 00:49:06 UTC 2020
Fri May 29 00:49:16 UTC 2020
Fri May 29 00:49:26 UTC 2020
Fri May 29 00:49:36 UTC 2020
...

Summary

Kubernetes represents its functionality for deploying and operating a cloud-native application with the help of primitives. Each primitive follows a general structure: the API version, the kind, the metadata and the desired state of the resources, also called the spec. Upon creation or modification of the object, the Kubernetes scheduler automatically tries to ensure that the actual state of the object follows the defined specification. Every live object can be inspected, edited and deleted.

The portion “Core Concepts” of the curriculum puts a strong emphasis on the concept of a Pod. The Pod is a Kubernetes primitive responsible for running an application in a container. Kubernetes uses Docker as its default container runtime technology. A Pod can define one or many containers that use a container image. Upon its creation, the container image is resolved and used to bootstrap the application. Every Pod can be further customized with the relevant YAML configuration.

Kubectl acts as a CLI-based client for the interacting with the Kubernetes cluster. You can use its commands and flags to manage Kubernetes objects.

Exam Essentials

Understand how to manage Kubernetes objects

In Kubernetes, you can create objects with the imperative or declarative approach. The imperative approach is the most time-efficient way to create objects. For Pods, use the command kubectl run, for any other resource use the command kubectl create. Furthermore, practice editing live objects with kubectl edit and know how to delete them via kubectl delete.

Know how to interact with Pods

A Pod runs an application inside of a container. You can check on the status and the configuration of the Pod by inspecting the object with the kubectl get or kubectl describe commands. Make yourself familiar with the lifecycle phases of a Pod to be able to quickly diagnose error conditions. The command kubectl logs can be used to download the container log information without having to shell into the container. Use the command kubectl exec to further explore the container environment e.g. to check on processes or to examine files.

Advanced Pod configuration options

Sometimes you have to start with the YAML manifest of a Pod and then create the Pod declaratively. This could be the case if you wanted to provide environment variables to the container or declare a custom command. Practice different configuration options by copy-pasting relevant code snippets from the Kubernetes documentation.

Sample Exercises

1. Create a new Pod named nginx running the image nginx:1.17.10. Expose the container port 80. The Pod should live in the namespace named ckad.

2. Get the details of the Pod including its IP address.

3. Create a temporary Pod that uses the busybox image to execute a wget command inside of the container. The wget command should access the endpoint exposed by the nginx container. You should see the HTML response body rendered in the terminal.

4. Get the logs of the nginx container.

5. Add the environment variables DB_URL=postgresql://mydb:5432 and DB_USERNAME=admin to the nginx container.

6. Open a shell for the nginx container and inspect the contents of the current directory ls -l.

7. Create a YAML manifest for a Pod named loop that runs the busybox image in a container. The container should run the following command: for i in {1..10}; do echo "Welcome $i times"; done. Create the Pod from the YAML manifest. What’s the status of the Pod?

8. Edit the Pod named loop. Change the command to run in an endless loop. Each iteration should echo the current date.

9. Inspect the events and the status of the Pod loop.

10. Delete the namespace ckad and its Pods.

Answers to Sample Exercises

1. You can either use the imperative approach or the declarative approach. First, we’ll look at creating the namespace with the imperative approach.

   $ kubectl create namespace ckad

   Create the Pod.

   $ kubectl run nginx --image=nginx:1.17.10 --port=80 --namespace=ckad

   Alternatively, you can use the declarative approach. Create a new YAML file called ckad-namespace.yaml with the following contents:

   apiVersion: v1
   kind: Namespace
   metadata:
     name: ckad

   Create the namespace from the YAML file.

   $ kubectl create -f ckad-namespace.yaml

   Create a new YAML file called nginx-pod.yaml with the following contents:

   apiVersion: v1
   kind: Pod
   metadata:
     name: nginx
   spec:
     containers:
     - name: nginx
       image: nginx:1.17.10
       ports:
         - containerPort: 80

   Create the Pod from the YAML file.

   $ kubectl create -f nginx-pod.yaml --namespace=ckad

2. You can use the command line option -o wide to retrieve the IP address of the Pod.

   $ kubectl get pod nginx --namespace=ckad -o wide

   The same information is available if you query for the Pod details.

   $ kubectl describe pod nginx --namespace=ckad | grep IP:

3. You can use the command line option --rm and --it to start a temporary Pod.

   $ kubectl run busybox --image=busybox --rm -it -n ckad 
     -- wget -O- 10.1.0.66:80

4. To download the logs, use a simple logs command.

   $ kubectl logs nginx --namespace=ckad

5. Editing the live object is forbidden. You will receive an error message if you try to add the environment variables.

   $ kubectl edit pod nginx --namespace=ckad

   You will have to recreate the object with a modified YAML file, but first you’ll have to delete the existing object.

   $ kubectl delete pod nginx --namespace=ckad

   Edit the existing YAML file nginx-pod.yaml.

   apiVersion: v1
   kind: Pod
   metadata:
     name: nginx
   spec:
     containers:
     - name: nginx
       image: nginx:1.17.10
       ports:
         - containerPort: 80
       env:
         - name: DB_URL
           value: postgresql://mydb:5432
         - name: DB_USERNAME
           value: admin

   Apply the changes.

   $ kubectl create -f nginx-pod.yaml --namespace=ckad

6. Use the exec command to open interactive shell to the container.

   $ kubectl exec -it nginx --namespace=ckad  -- /bin/sh
   # ls -l

7. Combine the command line options -o yaml and --dry-run=client to write the generated YAML to a file. Make sure to escape the double-quote characters of the string rendered by the echo command.

   $ kubectl run loop --image=busybox -o yaml --dry-run=client 
     -- /bin/sh -c "for i in {1..10}; do echo "Welcome $i  times"; done" 
     > pod.yaml

   Create the Pod from the YAML file.

   $ kubectl create -f pod.yaml

   The status of the Pod will say Completed as the executed command in the container does not run in an infinite loop.

   $ kubectl get pod loop

8. The ontainer command cannot be changed for existing Pods. Delete the Pod so you can modify the manifest file and recreate the object.

   $ kubectl delete pod loop

   Change the YAML file content.

   apiVersion: v1
   kind: Pod
   metadata:
     creationTimestamp: null
     labels:
       run: loop
     name: loop
   spec:
     containers:
     - args:
       - /bin/sh
       - -c
       - while true; do date; sleep 10; done
       image: busybox
       name: loop
       resources: {}
     dnsPolicy: ClusterFirst
     restartPolicy: Never
   status: {}

   Create the Pod from the YAML file.

   $ kubectl create -f pod.yaml

9. You can describe the Pod events by grepping for the term.

   $ kubectl describe pod loop | grep -C 10 Events:

10. You can simply delete the namespace which will delete all objects within the namespace.

    $ kubectl delete namespace ckad