Kubernetes Pod in a Nutshell

What are Kubernetes Pods?

A Kubernetes Pod is the smallest deployable unit that can be managed in Kubernetes and is the building block of Kubernetes applications. A Pod includes one or more application containers and a specification for how to run the containers. Containers in a Pod share storage and network resources.

While most Pods only have on container, there are use cases that a Pod needs multiple containers. When a Pod has more than one containers, these containers are tightly coupled and work together closely to achieve a desired function or provide a service.

A Pod can be created from a YAML or JSON file. Below is an example of a Pod with one container:

apiVersion: apps/v1
kind: Pod
metadata:
  name: your_pod_name
spec:
  containers:
  - name: your_app_name
    image: container_images_repo.your-company.com/your_app_name:v1
    resources:
      requests:
        memory: "512Mi"
        cpu: "500m"
      limits:
        memory: "1Gi"
        cpu: "1000m"
  restartPolicy: OnFailure

A Pod with two containers:

apiVersion: apps/v1
kind: Pod
metadata:
  name: your_pod_name
spec:
  containers:
  - name: your_app_name
    image: container_images_repo.your-company.com/your_app_name:v1
    resources:
      requests:
        ephemeral-storage: "1Gi"
      limits:
        ephemeral-storage: "2Gi"
  - name: logging-sidecar
    image: container_images_repo.your-company.com/logging-sidecar:v2
    resources:
      requests:
        ephemeral-storage: "2Gi"
      limits:
        ephemeral-storage: "4Gi"
  restartPolicy: OnFailure

Save the content above to a file your_pod.yaml and run command below to create a Pod in a namespace. If a namespace is not provided, the Pod is created in the default namespace.

kubectl create -f ./your_pod.yaml -n your_target_namespace

To check your newly created Pod status:

kubectl get your_pod_name -n your_target_namespace

To view the detail of the Pod:

kubectl describe your_pod_name -n your_target_namespace

To delete a Pod:

kubectl delete your_pod_name -n your_target_namespace

Kubernetes does not support stop/pause the current state of a Pod and resume it later on.

Besides app containers, a Pod can also have one or more init containers that run at the Pod startup time. When there are multiple init containers, Kubernetes runs the Pod’s init containers sequentially in the order they are defined in the Pod’s spec. All the init containers must complete before app containers start.

Below is an example of Pod with init container:

apiVersion: apps/v1
kind: Pod
metadata:
  name: your_pod_name
spec:
  containers:
  - name: your_app_name
    image: container_images_repo.your-company.com/your_app_name:v1
    volumeMounts:
      - name: workdir
        mountPath: /usr/share/work-dir
  # These containers are run during pod initialization
  initContainers:
  - name: your_init_app
    image: container_images_repo.your-company.com/your_init_app:v1
    volumeMounts:
    - name: workdir
      mountPath: /work-dir
  volumes:
  - name: workdir
    emptyDir: {}

Kubernetes Pods are ephemeral and not permanent resources. When a Pod is created, a unique ID is assigned to it and it’s scheduled to run on a node in your cluster. The Pod remains on the node until the Pod is deleted or evicted or the node itself fails.

Even though you can create a Pod directly in Kubernetes, it’s better to let controllers for workload resources, such as Deployments, to create and manage the Pods from a pod template for you. Below is a template example for Deployment.

Pods have four lifecycle phases:

Pending: The Pod has been accepted by the Kubernetes cluster, but one or more of the containers are not set up yet and not ready to run.

Running: The Pod is bound to a node in the cluster and all of its containers have been created. At least one container is running, or is in the process of starting or restarting.

Succeeded: All containers in the Pod have been terminated in success and cannot be restarted.

Failed: All containers in the Pod have been terminated and at least one container has non-zero return status.