Pods

Pods are the smallest deployable units of computing that you can create and manage in Kubernetes.

APod (as in a pod of whales or pea pod) is a group of one or morecontainers, with shared storage and network resources, and a specification for how to run the containers. A Pod's contents are always co-located andco-scheduled, and run in a shared context. A Pod models anapplication-specific "logical host": it contains one or more applicationcontainers which are relatively tightly coupled.In non-cloud contexts, applications executed on the same physical or virtual machine are analogous to cloud applications executed on the same logical host.

As well as application containers, a Pod can containinit containers that runduring Pod startup. You can also injectephemeral containersfor debugging a running Pod.

What is a Pod?

The shared context of a Pod is a set of Linux namespaces, cgroups, andpotentially other facets of isolation - the same things that isolate acontainer. Within a Pod's context, the individual applications may havefurther sub-isolations applied.

A Pod is similar to a set of containers with shared namespaces and shared filesystem volumes.

Pods in a Kubernetes cluster are used in two main ways:

• Pods that run a single container. The "one-container-per-Pod" model is themost common Kubernetes use case; in this case, you can think of a Pod as awrapper around a single container; Kubernetes manages Pods rather than managingthe containers directly.

• Pods that run multiple containers that need to work together. A Pod canencapsulate an application composed ofmultiple co-located containers that aretightly coupled and need to share resources. These co-located containersform a single cohesive unit.

  Grouping multiple co-located and co-managed containers in a single Pod is arelatively advanced use case. You should use this pattern only in specificinstances in which your containers are tightly coupled.

  You don't need to run multiple containers to provide replication (for resilienceor capacity); if you need multiple replicas, seeWorkload management.

Using Pods

The following is an example of a Pod which consists of a container running the imagenginx:1.14.2.

pods/simple-pod.yaml

apiVersion:v1kind:Podmetadata:name:nginxspec:containers:-name:nginximage:nginx:1.14.2ports:-containerPort:80

To create the Pod shown above, run the following command:

kubectl apply -f https://k8s.io/examples/pods/simple-pod.yaml

Pods are generally not created directly and are created using workload resources.SeeWorking with Pods for more information on how Pods are usedwith workload resources.

Workload resources for managing pods

Usually you don't need to create Pods directly, even singleton Pods. Instead, create them using workload resources such asDeployment orJob.If your Pods need to track state, consider theStatefulSet resource.

Each Pod is meant to run a single instance of a given application. If you want toscale your application horizontally (to provide more overall resources by runningmore instances), you should use multiple Pods, one for each instance. InKubernetes, this is typically referred to asreplication.Replicated Pods are usually created and managed as a group by a workload resourceand itscontroller.

SeePods and controllers for more information on howKubernetes uses workload resources, and their controllers, to implement applicationscaling and auto-healing.

Pods natively provide two kinds of shared resources for their constituent containers:networking andstorage.

Working with Pods

You'll rarely create individual Pods directly in Kubernetes—even singleton Pods. Thisis because Pods are designed as relatively ephemeral, disposable entities. Whena Pod gets created (directly by you, or indirectly by acontroller), the new Pod isscheduled to run on aNode in your cluster.The Pod remains on that node until the Pod finishes execution, the Pod object is deleted,the Pod isevicted for lack of resources, or the node fails.

The name of a Pod must be a validDNS subdomainvalue, but this can produce unexpected results for the Pod hostname. For best compatibility,the name should follow the more restrictive rules for aDNS label.

Pod OS

You should set the.spec.os.name field to eitherwindows orlinux to indicate the OS onwhich you want the pod to run. These two are the only operating systems supported for now byKubernetes. In the future, this list may be expanded.

In Kubernetes v1.34, the value of.spec.os.name does not affecthow thekube-schedulerpicks a node for the Pod to run on. In any cluster where there is more than one operating system forrunning nodes, you should set thekubernetes.io/oslabel correctly on each node, and define pods with anodeSelector based on the operating systemlabel. The kube-scheduler assigns your pod to a node based on other criteria and may or may notsucceed in picking a suitable node placement where the node OS is right for the containers in that Pod.ThePod security standards also use thisfield to avoid enforcing policies that aren't relevant to the operating system.

Pods and controllers

You can use workload resources to create and manage multiple Pods for you. A controllerfor the resource handles replication and rollout and automatic healing in case ofPod failure. For example, if a Node fails, a controller notices that Pods on thatNode have stopped working and creates a replacement Pod. The scheduler places thereplacement Pod onto a healthy Node.

Here are some examples of workload resources that manage one or more Pods:

• Deployment
• StatefulSet
• DaemonSet

Pod templates

Controllers forworkload resources create Podsfrom apod template and manage those Pods on your behalf.

PodTemplates are specifications for creating Pods, and are included in workload resources such asDeployments,Jobs, andDaemonSets.

Each controller for a workload resource uses thePodTemplate inside the workloadobject to make actual Pods. ThePodTemplate is part of the desired state of whateverworkload resource you used to run your app.

When you create a Pod, you can includeenvironment variablesin the Pod template for the containers that run in the Pod.

The sample below is a manifest for a simple Job with atemplate that starts onecontainer. The container in that Pod prints a message then pauses.

apiVersion:batch/v1kind:Jobmetadata:name:hellospec:template:# This is the pod templatespec:containers:-name:helloimage:busybox:1.28command:['sh','-c','echo "Hello, Kubernetes!" && sleep 3600']restartPolicy:OnFailure# The pod template ends here

Modifying the pod template or switching to a new pod template has no direct effecton the Pods that already exist. If you change the pod template for a workloadresource, that resource needs to create replacement Pods that use the updated template.

For example, the StatefulSet controller ensures that the running Pods match the currentpod template for each StatefulSet object. If you edit the StatefulSet to change its podtemplate, the StatefulSet starts to create new Pods based on the updated template.Eventually, all of the old Pods are replaced with new Pods, and the update is complete.

Each workload resource implements its own rules for handling changes to the Pod template.If you want to read more about StatefulSet specifically, readUpdate strategy in the StatefulSet Basics tutorial.

On Nodes, thekubelet does notdirectly observe or manage any of the details around pod templates and updates; thosedetails are abstracted away. That abstraction and separation of concerns simplifiessystem semantics, and makes it feasible to extend the cluster's behavior withoutchanging existing code.

Pod update and replacement

As mentioned in the previous section, when the Pod template for a workloadresource is changed, the controller creates new Pods based on the updatedtemplate instead of updating or patching the existing Pods.

Kubernetes doesn't prevent you from managing Pods directly. It is possible toupdate some fields of a running Pod, in place. However, Pod update operationslikepatch, andreplacehave some limitations:

• Most of the metadata about a Pod is immutable. For example, you cannotchange thenamespace,name,uid, orcreationTimestamp fields.

• If themetadata.deletionTimestamp is set, no new entry can be added to themetadata.finalizers list.

• Pod updates may not change fields other thanspec.containers[*].image,spec.initContainers[*].image,spec.activeDeadlineSeconds,spec.terminationGracePeriodSeconds,spec.tolerations orspec.schedulingGates. Forspec.tolerations, you can only add new entries.

• When updating thespec.activeDeadlineSeconds field, two types of updatesare allowed:

  1. setting the unassigned field to a positive number;
  2. updating the field from a positive number to a smaller, non-negativenumber.

Pod subresources

The above update rules apply to regular pod updates, but other pod fields can be updated throughsubresources.

• Resize: Theresize subresource allows container resources (spec.containers[*].resources) to be updated.SeeResize Container Resources for more details.
• Ephemeral Containers: TheephemeralContainers subresource allowsephemeral containersto be added to a Pod.SeeEphemeral Containers for more details.
• Status: Thestatus subresource allows the pod status to be updated.This is typically only used by the Kubelet and other system controllers.
• Binding: Thebinding subresource allows setting the pod'sspec.nodeName via aBinding request.This is typically only used by thescheduler.

Pod generation

• Themetadata.generation field is unique. It will be automatically set by thesystem such that new pods have ametadata.generation of 1, and every update tomutable fields in the pod's spec will increment themetadata.generation by 1.

• observedGeneration is a field that is captured in thestatus section of the Podobject. If the feature gatePodObservedGenerationTracking is set, the Kubelet will setstatus.observedGenerationto track the pod state to the current pod status. The pod'sstatus.observedGeneration will reflect themetadata.generation of the pod at the point that the pod status is being reported.

Different status fields may either be associated with themetadata.generation of the current sync loop, or with themetadata.generation of the previous sync loop. The key distinction is whether a change in thespec is reflecteddirectly in thestatus or is an indirect result of a running process.

Direct Status Updates

For status fields where the allocated spec is directly reflected, theobservedGeneration willbe associated with the currentmetadata.generation (Generation N).

This behavior applies to:

• Resize Status: The status of a resource resize operation.
• Allocated Resources: The resources allocated to the Pod after a resize.
• Ephemeral Containers: When a new ephemeral container is added, and it is inWaiting state.

Indirect Status Updates

For status fields that are an indirect result of running the spec, theobservedGeneration will be associatedwith themetadata.generation of the previous sync loop (Generation N-1).

This behavior applies to:

• Container Image: TheContainerStatus.ImageID reflects the image from the previous generation until the new imageis pulled and the container is updated.
• Actual Resources: During an in-progress resize, the actual resources in use still belong to the previous generation'srequest.
• Container state: During an in-progress resize, with require restart policy reflects the previous generation'srequest.
• activeDeadlineSeconds &terminationGracePeriodSeconds &deletionTimestamp: The effects of these fields on thePod's status are a result of the previously observed specification.

Resource sharing and communication

Pods enable data sharing and communication among their constituentcontainers.

Storage in Pods

A Pod can specify a set of shared storagevolumes. All containersin the Pod can access the shared volumes, allowing those containers toshare data. Volumes also allow persistent data in a Pod to survivein case one of the containers within needs to be restarted. SeeStorage for more information on howKubernetes implements shared storage and makes it available to Pods.

Pod networking

Each Pod is assigned a unique IP address for each address family. Everycontainer in a Pod shares the network namespace, including the IP address andnetwork ports. Inside a Pod (andonly then), the containers that belong to the Podcan communicate with one another usinglocalhost. When containers in a Pod communicatewith entitiesoutside the Pod,they must coordinate how they use the shared network resources (such as ports).Within a Pod, containers share an IP address and port space, andcan find each other vialocalhost. The containers in a Pod can also communicatewith each other using standard inter-process communications like SystemV semaphoresor POSIX shared memory. Containers in different Pods have distinct IP addressesand can not communicate by OS-level IPC without special configuration.Containers that want to interact with a container running in a different Pod canuse IP networking to communicate.

Containers within the Pod see the system hostname as being the same as the configuredname for the Pod. There's more about this in thenetworkingsection.

Pod security settings

To set security constraints on Pods and containers, you use thesecurityContext field in the Pod specification. This field gives yougranular control over what a Pod or individual containers can do. For example:

• Drop specific Linux capabilities to avoid the impact of a CVE.
• Force all processes in the Pod to run as a non-root user or as a specificuser or group ID.
• Set a specific seccomp profile.
• Set Windows security options, such as whether containers run as HostProcess.

• To learn about kernel-level security constraints that you can use,seeLinux kernel security constraints for Pods and containers.
• To learn more about the Pod security context, seeConfigure a Security Context for a Pod or Container.

Static Pods

Static Pods are managed directly by the kubelet daemon on a specific node,without theAPI serverobserving them.Whereas most Pods are managed by the control plane (for example, aDeployment), for staticPods, the kubelet directly supervises each static Pod (and restarts it if it fails).

Static Pods are always bound to oneKubelet on a specific node.The main use for static Pods is to run a self-hosted control plane: in other words,using the kubelet to supervise the individualcontrol plane components.

The kubelet automatically tries to create amirror Podon the Kubernetes API server for each static Pod.This means that the Pods running on a node are visible on the API server,but cannot be controlled from there. See the guideCreate static Podsfor more information.

Pods with multiple containers

Pods are designed to support multiple cooperating processes (as containers) that forma cohesive unit of service. The containers in a Pod are automatically co-located andco-scheduled on the same physical or virtual machine in the cluster. The containerscan share resources and dependencies, communicate with one another, and coordinatewhen and how they are terminated.

Pods in a Kubernetes cluster are used in two main ways:

• Pods that run a single container. The "one-container-per-Pod" model is themost common Kubernetes use case; in this case, you can think of a Pod as awrapper around a single container; Kubernetes manages Pods rather than managingthe containers directly.
• Pods that run multiple containers that need to work together. A Pod canencapsulate an application composed ofmultiple co-located containers that aretightly coupled and need to share resources. These co-located containersform a single cohesive unit of service—for example, one container serving datastored in a shared volume to the public, while a separatesidecar containerrefreshes or updates those files.The Pod wraps these containers, storage resources, and an ephemeral networkidentity together as a single unit.

For example, you might have a container thatacts as a web server for files in a shared volume, and a separatesidecar containerthat updates those files from a remote source, as in the following diagram:

Some Pods haveinit containersas well asapp containers.By default, init containers run and complete before the app containers are started.

You can also havesidecar containersthat provide auxiliary services to the main application Pod (for example: a service mesh).

Enabled by default, theSidecarContainersfeature gateallows you to specifyrestartPolicy: Always for init containers.Setting theAlways restart policy ensures that the containers where you set it aretreated assidecars that are kept running during the entire lifetime of the Pod.Containers that you explicitly define as sidecar containersstart up before the main application Pod and remain running until the Pod isshut down.

Container probes

Aprobe is a diagnostic performed periodically by the kubelet on a container.To perform a diagnostic, the kubelet can invoke different actions:

• ExecAction (performed with the help of the container runtime)
• TCPSocketAction (checked directly by the kubelet)
• HTTPGetAction (checked directly by the kubelet)

You can read more aboutprobesin the Pod Lifecycle documentation.

What's next

• Learn about thelifecycle of a Pod.
• Learn aboutRuntimeClass and how you can use it toconfigure different Pods with different container runtime configurations.
• Read aboutPodDisruptionBudgetand how you can use it to manage application availability during disruptions.
• Pod is a top-level resource in the Kubernetes REST API.ThePodobject definition describes the object in detail.
• The Distributed System Toolkit: Patterns for Composite Containers explains common layouts for Pods with more than one container.
• Read aboutPod topology spread constraints

To understand the context for why Kubernetes wraps a common Pod API in other resources(such asStatefulSets orDeployments),you can read about the prior art, including:

• Aurora
• Borg
• Marathon
• Omega
• Tupperware.