02-02-pod.md

Lesson 2 - Create your first pod

The first Kubernetes object that you will create is a pod. A pod is the smallest unit of deployment in a Kubernetes cluster. Pods typically contain a single container, although very closely related containers might be deployed in a single pod when a context needs to be shared. In all the examples you will see in this course, they will be single-container pods.

All Kubernetes objects follow more or less the same syntax. You start by specifying the api version to use and the kind of object, then you add in some metadata. And you finish with the spec of the object.

To create your first pod, you can start by creating a new file. You can call it pod.yaml and you can put this YAML file along with all the others you will write in a folder called k8s. In this file, you will need to specify the Kubernetes API version to use, which will be version 1 and the kind of object you want to create. In this case, it will be a Pod.

apiVersion: v1
kind: Pod

Next, you need to add some metadata. You will need to give your new object a name. Kubernetes objects are usually grouped based on labels. For now, we will ignore the labels but it’s good to know that this is where they usually go.

metadata:
  name: hello

And finally, we add the spec version. Spec will change for every Kubernetes object. In the case of this example, you will tell Kubernetes to use a single container. You need to specify a name for this container, which is hello. Then you tell Kubernetes which container image to use. You can use a base image here or a custom image that you have built using a docker build command. For this first pod, the base image alpine is used. Finally, you can override the entry point that is specified in a base image by adding a command array. In this case, you will tell the container to echo a Hello World and then sleep 30 seconds. Once it’s done, the container will automatically stop running.

spec:
  containers:
  - name: hello
    image: alpine
    command: ["sh", "-c", "echo Hello World && sleep 30"]

Your final pod.yaml file should look like this

apiVersion: apps/v1
kind: Pod
metadata:
  name: hello
spec:
  containers:
  - name: hello
    image: alpine
    command: ["sh", "-c", "echo Hello World && sleep 30"]

Once you apply this file to your Kubernetes cluster, it will download the container image if needed, and then run the specified command. Once this command is executed, the container will automatically shut down and it will consider it’s just terminated. You can apply this file to your cluster by using the apply command with a -f flag and the name of the file to apply to your cluster.

kubectl apply -f pod.yaml

This will create your first pod. Kubernetes will start the container you specified and execute the command in the YAML file. It is actually very similar to what you did in some of the first lessons on containers. Kubernetes uses a container runtime behind the scenes to start this container and execute the echo command. You can see the output of your container by using kubectl logs followed by the name of the container. This should output the line "Hello World".

kubectl logs hello

Kubernetes does more than just running the containers though. You can see all the objects that you have in your cluster with the get command. If you want to see everything, you can use the get command with the all parameter.

kubectl get all

This will list all the objects in your cluster. You should see an object named pod/hello. There is also an object named service/kubernetes. That is the Kubernetes API but you can ignore that one for now. If you want to see only one type of object, you can change the all for an object kind, like pods in this case.

kubectl get pods

Back to the pod, you will see how many pods are ready, what is the status, how many restarts and the age of the pod. If you wait a few seconds and try the command again, you might notice some changes in the status or the restarts. If you want to monitor a pod in real-time, you can use the -w flag.

kubectl get -w pods

Now that your pods are being monitored in real-time, you will see some changes. The pod should go from "Running" to "Completed". This is because the pod stops running after the sleep command we passed it in the YAML file. The main difference between running a pod in Kubernetes is that the pod will automatically be restarted. The platform will always try to keep this pod alive. This is why you should see another line that specified the pod is running again and that the number of restarts was incremented. At some point, you might also see a CrashLoopBackOff status. This is because Kubernetes noticed that this container stops just a few seconds after it started and it gives you an error message. If you want to know more about why a container is crashing, you can use the logs as we did previously or use the describe command. You will need to specify the type of resource you want details for (a pod in this case) followed by the name of the resource.

kubectl describe pod hello

This pod only runs a single command and then gets restarted automatically when it’s done, but most of the time, you will want to run a pod that stays up and running. You can test this out with an empty Nginx server. If you start from the pod.yaml you created earlier, you can change the image name to nginx and remove the command line.

...
spec:
  containers:
  - name: hello
    image: nginx:1.17

This will create a pod that is running the base image of nginx. Because you can’t have two pods with the same name on a given cluster, you will need to delete your pod with the delete command and then apply this new file. Delete takes the type of resource followed by the resource name as arguments.

kubectl delete pod hello
kubectl apply -f ./pod.yaml

If you run a get command again, you will see that you have a pod called hello but this time, the pod should stay up and running.

Should you want to log into a pod, this is very similar to what you did with containers. You can use the exec command with the -it flags to open up a command in interactive mode.

kubectl exec -it hello -- /bin/bash

From within your container, you can test if the nginx service is running with the command

service nginx status

Which should tell you that it is running. To exit the container, use the exit command.

exit

As you can see, pods are very similar to the containers we had earlier. The main difference being that a pod can have more than one container. Now that you are done with this single pod, you can remove it with the command delete.

kubectl delete pod hello

To verify that the pod was deleted. you can run a get all command again and you should only see the Kubernetes API service.

kubectl get all

Now all of this worked but you would never actually manually create a single pod in a Kubernetes cluster. In reality, you would use a deployment that would be in charge of managing those pods.