diff --git a/content/en/docs/concepts/workloads/pods/_index.md b/content/en/docs/concepts/workloads/pods/_index.md index 1132c38793..1ae8a7c7fe 100644 --- a/content/en/docs/concepts/workloads/pods/_index.md +++ b/content/en/docs/concepts/workloads/pods/_index.md @@ -19,10 +19,10 @@ containers 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 contain -[init containers](/docs/concepts/workloads/pods/init-containers/) that run +{{< glossary_tooltip text="init containers" term_id="init-container" >}} that run during Pod startup. You can also inject -[ephemeral containers](/docs/concepts/workloads/pods/ephemeral-containers/) -for debugging if your cluster offers this. +{{< glossary_tooltip text="ephemeral containers" term_id="ephemeral-container" >}} +for debugging a running Pod. @@ -39,6 +39,26 @@ further 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 the + most common Kubernetes use case; in this case, you can think of a Pod as a + wrapper around a single container; Kubernetes manages Pods rather than managing + the containers directly. +* **Pods that run multiple containers that need to work together**. A Pod can + encapsulate an application composed of + [multiple co-located containers](#how-pods-manage-multiple-containers) that are + tightly coupled and need to share resources. These co-located containers + form a single cohesive unit. + + Grouping multiple co-located and co-managed containers in a single Pod is a + relatively advanced use case. You should use this pattern only in specific + instances in which your containers are tightly coupled. + + You don't need to run multiple containers to provide replication (for resilience + or capacity); if you need multiple replicas, see + [Workload management](/docs/concepts/workloads/controllers/). + ## Using Pods The following is an example of a Pod which consists of a container running the image `nginx:1.14.2`. @@ -61,26 +81,6 @@ term_id="deployment" >}} or {{< glossary_tooltip text="Job" term_id="job" >}}. If your Pods need to track state, consider the {{< glossary_tooltip text="StatefulSet" term_id="statefulset" >}} resource. -Pods in a Kubernetes cluster are used in two main ways: - -* **Pods that run a single container**. The "one-container-per-Pod" model is the - most common Kubernetes use case; in this case, you can think of a Pod as a - wrapper around a single container; Kubernetes manages Pods rather than managing - the containers directly. -* **Pods that run multiple containers that need to work together**. A Pod can - encapsulate an application composed of multiple co-located containers that are - tightly coupled and need to share resources. These co-located containers - form a single cohesive unit of service—for example, one container serving data - stored in a shared volume to the public, while a separate _sidecar_ container - refreshes or updates those files. - The Pod wraps these containers, storage resources, and an ephemeral network - identity together as a single unit. - - {{< note >}} - Grouping multiple co-located and co-managed containers in a single Pod is a - relatively advanced use case. You should use this pattern only in specific - instances in which your containers are tightly coupled. - {{< /note >}} Each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (to provide more overall resources by running @@ -93,36 +93,10 @@ See [Pods and controllers](#pods-and-controllers) for more information on how Kubernetes uses workload resources, and their controllers, to implement application scaling and auto-healing. -### How Pods manage multiple containers - -Pods are designed to support multiple cooperating processes (as containers) that form -a cohesive unit of service. The containers in a Pod are automatically co-located and -co-scheduled on the same physical or virtual machine in the cluster. The containers -can share resources and dependencies, communicate with one another, and coordinate -when and how they are terminated. - -For example, you might have a container that -acts as a web server for files in a shared volume, and a separate "sidecar" container -that updates those files from a remote source, as in the following diagram: - -{{< figure src="/images/docs/pod.svg" alt="Pod creation diagram" class="diagram-medium" >}} - -Some Pods have {{< glossary_tooltip text="init containers" term_id="init-container" >}} -as well as {{< glossary_tooltip text="app containers" term_id="app-container" >}}. -By default, init containers run and complete before the app containers are started. - -{{< feature-state for_k8s_version="v1.29" state="beta" >}} - -Enabled by default, the `SidecarContainers` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) -allows you to specify `restartPolicy: Always` for init containers. -Setting the `Always` restart policy ensures that the init containers where you set it are -kept running during the entire lifetime of the Pod. -See [Sidecar containers and restartPolicy](/docs/concepts/workloads/pods/init-containers/#sidecar-containers-and-restartpolicy) -for more details. - Pods natively provide two kinds of shared resources for their constituent containers: [networking](#pod-networking) and [storage](#pod-storage). + ## Working with Pods You'll rarely create individual Pods directly in Kubernetes—even singleton Pods. This @@ -343,6 +317,57 @@ The `spec` of a static Pod cannot refer to other API objects {{< glossary_tooltip text="Secret" term_id="secret" >}}, etc). {{< /note >}} +## Pods with multiple containers {#how-pods-manage-multiple-containers} + +Pods are designed to support multiple cooperating processes (as containers) that form +a cohesive unit of service. The containers in a Pod are automatically co-located and +co-scheduled on the same physical or virtual machine in the cluster. The containers +can share resources and dependencies, communicate with one another, and coordinate +when 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 the + most common Kubernetes use case; in this case, you can think of a Pod as a + wrapper around a single container; Kubernetes manages Pods rather than managing + the containers directly. +* **Pods that run multiple containers that need to work together**. A Pod can + encapsulate an application composed of + multiple co-located containers that are + tightly coupled and need to share resources. These co-located containers + form a single cohesive unit of service—for example, one container serving data + stored in a shared volume to the public, while a separate + {{< glossary_tooltip text="sidecar container" term_id="sidecar-container" >}} + refreshes or updates those files. + The Pod wraps these containers, storage resources, and an ephemeral network + identity together as a single unit. + +For example, you might have a container that +acts as a web server for files in a shared volume, and a separate +[sidecar container](/docs/concepts/workloads/pods/sidecar-containers/) +that updates those files from a remote source, as in the following diagram: + +{{< figure src="/images/docs/pod.svg" alt="Pod creation diagram" class="diagram-medium" >}} + +Some Pods have {{< glossary_tooltip text="init containers" term_id="init-container" >}} +as well as {{< glossary_tooltip text="app containers" term_id="app-container" >}}. +By default, init containers run and complete before the app containers are started. + +You can also have [sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/) +that provide auxiliary services to the main application Pod (for example: a service mesh). + +{{< feature-state for_k8s_version="v1.29" state="beta" >}} + +Enabled by default, the `SidecarContainers` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +allows you to specify `restartPolicy: Always` for init containers. +Setting the `Always` restart policy ensures that the containers where you set it are +treated as _sidecars_ that are kept running during the entire lifetime of the Pod. +Containers that you explicitly define as sidecar containers +start up before the main application Pod and remain running until the Pod is +shut down. + + ## Container probes A _probe_ is a diagnostic performed periodically by the kubelet on a container. To perform a diagnostic, the kubelet can invoke different actions: diff --git a/content/en/docs/concepts/workloads/pods/disruptions.md b/content/en/docs/concepts/workloads/pods/disruptions.md index 1d2b33d55f..83befbe71d 100644 --- a/content/en/docs/concepts/workloads/pods/disruptions.md +++ b/content/en/docs/concepts/workloads/pods/disruptions.md @@ -5,7 +5,7 @@ reviewers: - davidopp title: Disruptions content_type: concept -weight: 60 +weight: 70 --- diff --git a/content/en/docs/concepts/workloads/pods/ephemeral-containers.md b/content/en/docs/concepts/workloads/pods/ephemeral-containers.md index dfd7c366c1..efdf0e1a0c 100644 --- a/content/en/docs/concepts/workloads/pods/ephemeral-containers.md +++ b/content/en/docs/concepts/workloads/pods/ephemeral-containers.md @@ -4,7 +4,7 @@ reviewers: - yujuhong title: Ephemeral Containers content_type: concept -weight: 80 +weight: 60 --- diff --git a/content/en/docs/reference/glossary/init-container.md b/content/en/docs/reference/glossary/init-container.md index a999042e30..dfb29b5b4b 100644 --- a/content/en/docs/reference/glossary/init-container.md +++ b/content/en/docs/reference/glossary/init-container.md @@ -5,7 +5,7 @@ date: 2018-04-12 full_link: short_description: > One or more initialization containers that must run to completion before any app containers run. - +full_link: /docs/concepts/workloads/pods/init-containers/ aka: tags: - fundamental @@ -15,3 +15,7 @@ tags: Initialization (init) containers are like regular app containers, with one difference: init containers must run to completion before any app containers can start. Init containers run in series: each init container must run to completion before the next init container begins. + +Unlike {{< glossary_tooltip text="sidecar containers" term_id="sidecar-container" >}}, init containers do not remain running after Pod startup. + +For more information, read [init containers](/docs/concepts/workloads/pods/init-containers/). diff --git a/content/en/docs/reference/glossary/sidecar-container.md b/content/en/docs/reference/glossary/sidecar-container.md new file mode 100644 index 0000000000..97faa10153 --- /dev/null +++ b/content/en/docs/reference/glossary/sidecar-container.md @@ -0,0 +1,20 @@ +--- +title: Sidecar Container +id: sidecar-container +date: 2018-04-12 +full_link: +short_description: > + An auxilliary container that stays running throughout the lifecycle of a Pod. +full_link: /docs/concepts/workloads/pods/sidecar-containers/ +tags: +- fundamental +--- + One or more {{< glossary_tooltip text="containers" term_id="container" >}} that are typically started before any app containers run. + + + +Sidecar containers are like regular app containers, but with a different purpose: the sidecar provides a Pod-local service to the main app container. +Unlike {{< glossary_tooltip text="init containers" term_id="init-container" >}}, sidecar containers +continue running after Pod startup. + +Read [Sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/) for more information.