Pods

Updated on 2025-07-09 GMT+08:00

View PDF

Video Tutorial

Overview of Pods

Pods are the smallest unit that you can create or deploy in Kubernetes. Each pod comprises one or more containers, shared storage (volumes), a unique IP address, and container runtime policies.

Pods can be used in either of the following ways:

A pod runs a single container. This is the most common scenario in Kubernetes. In this case, a pod can be thought of as a container, although Kubernetes manages the pod rather than the container itself.
A pod runs multiple tightly coupled containers that need to share resources. In this case, the pod includes a main container and several sidecar containers, as shown in Figure 1. For example, the main container might be a web server providing file services from a fixed directory, while sidecar containers periodically download files to that directory.
Figure 1 A pod running multiple containers

In Kubernetes, you rarely create pods directly. Instead, controllers like Deployments and jobs create and manage them. These controllers typically use pod templates to create and manage pods, providing features like replica management, rolling upgrades, and self-healing.

Creating a Pod

Kubernetes resources can be described using YAML or JSON files. The following is an example YAML file that describes a pod named nginx. This pod contains a container named container-0 that uses the nginx:alpine image. The container requests 100m CPU and 200 MiB of memory.

apiVersion: v1                      # The Kubernetes API version
kind: Pod                           # The Kubernetes resource type
metadata:
  name: nginx                       # The pod name
spec:                               # The pod specification
  containers:
  - image: nginx:alpine             # The image nginx:alpine
    name: container-0               # The container name
    resources:                      # Requested resources for the container
      limits:
        cpu: 100m
        memory: 200Mi
      requests:
        cpu: 100m
        memory: 200Mi
  imagePullSecrets:                 # The secret used to pull the image, which must be default-secret on CCE
  - name: default-secret

The above example shows that a YAML file includes:

metadata: information such as name, label, and namespace
spec: the pod specification, including the container image and volumes used

When checking a Kubernetes resource, you will also find the status field. It shows the current status of the resource. This field is automatically managed by Kubernetes and does not need to be set during resource creation. This example covers the minimum required parameters. Others will be described later.

After defining the pod, you can create it using kubectl. Assuming the YAML file is named nginx.yaml, run the following command to create the pod, where -f indicates that the pod will be created from a file:

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

After creating the pod, run the kubectl get pods command to obtain its status.

$ kubectl get pods
NAME           READY   STATUS    RESTARTS   AGE
nginx          1/1     Running   0          40s

The command output shows that the nginx pod is in the Running state. The READY state of 1/1 indicates that the pod has one container and that the container is in the Ready state.

You can run the kubectl get command to retrieve information about a pod with different output formats. Use -o yaml to obtain the information in YAML format and -o json to obtain in JSON format.

$ kubectl get pod nginx -o yaml

You can also run the kubectl describe command to view detailed information about the pod.

$ kubectl describe pod nginx

Before deleting a pod, Kubernetes terminates all containers within it by sending a SIGTERM signal to the main process of each container. It then waits for a grace period (30s by default) for the containers to stop gracefully. If a container does not stop within this period, Kubernetes will send a SIGKILL signal to forcefully terminate it.

There are many ways to delete a pod. For example, you can delete a pod by name using the following command:

$ kubectl delete po nginx
pod "nginx" deleted

Delete multiple pods concurrently:

$ kubectl delete po pod1 pod2

Delete all pods concurrently:

$ kubectl delete po --all
pod "nginx" deleted

Delete pods by label (see Labels):

$ kubectl delete po -l app=nginx
pod "nginx" deleted

Environment Variables

You can use environment variables to configure the runtime environment of a container.

They add flexibility to application settings and allow you to customize settings when you create a container. These settings take effect when the container runs, eliminating the need to rebuild the container image.

The following shows an example, in which you only need to configure the environment variable spec.containers.env:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
    containers:
    - image: nginx:alpine
      name: container-0
      resources:
        limits:
          cpu: 100m
          memory: 200Mi
        requests:
          cpu: 100m
          memory: 200Mi
      env:                            # The environment variable
      - name: env_key
        value: env_value
    imagePullSecrets:
    - name: default-secret

Check the environment variables in the container. The value of the env_key environment variable is env_value.

$ kubectl exec -it nginx -- env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=nginx
TERM=xterm
env_key=env_value

Environment variables can also be defined using ConfigMaps or secrets. For details, see Referencing a ConfigMap as an Environment Variable or Referencing a Secret as an Environment Variable.

Container Startup Commands

Starting a container involves initiating its main process. You need to make some preparations before starting a main process. For example, before running a MySQL server, you may need to configure or initialize the environment. These preparatory steps can be handled by defining the ENTRYPOINT or CMD in a Dockerfile during image creation. For example, configuring ENTRYPOINT ["top", "-b"] in a Dockerfile ensures that CCE automatically performs the necessary preparations during container startup.

FROM ubuntu
ENTRYPOINT ["top", "-b"]

In practice, you can define the command and its arguments for a container in a pod by setting the containers.command field. This field is a list, where the first element is the command, and subsequent elements are arguments.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - image: nginx:alpine
    name: container-0
    resources:
      limits:
        cpu: 100m
        memory: 200Mi
      requests:
        cpu: 100m
        memory: 200Mi
    command:                     # The startup command
    - top
    - "-b"
  imagePullSecrets:
   - name: default-secret

Container Lifecycle

Kubernetes provides lifecycle hooks that allow containers to run custom operations at specific points in their lifecycle. For example, you can create a hook to perform an operation before a container is stopped. The available lifecycle hooks are as follows:

postStart: triggered immediately after a container starts
preStop: triggered immediately before a container stops

To use these hooks, simply configure the lifecycle.postStart or lifecycle.preStop parameter for a pod. The following shows an example:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - image: nginx:alpine
    name: container-0
    resources:
      limits:
        cpu: 100m
        memory: 200Mi
      requests:
        cpu: 100m
        memory: 200Mi
    lifecycle:
      postStart:                 # Post-start processing
        exec:
          command:
          - "/postStart.sh"
      preStop:                   # Pre-stop processing
        exec:
          command:
          - "/preStop.sh"
  imagePullSecrets:
   - name: default-secret