Improve docs for Pods
- Add glossary entry for sidecar container - Revise glossary entry for init container to match - Revise the Pod concept overview - Reorder pages in that section
This commit is contained in:
Tim Bannister
parent
df0e89f8de
commit
2b4b4b4e66
|
|
@ -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.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
<!--intentionally repeats some text from earlier in the page, with more detail -->
|
||||
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:
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ reviewers:
|
|||
- davidopp
|
||||
title: Disruptions
|
||||
content_type: concept
|
||||
weight: 60
|
||||
weight: 70
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ reviewers:
|
|||
- yujuhong
|
||||
title: Ephemeral Containers
|
||||
content_type: concept
|
||||
weight: 80
|
||||
weight: 60
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
|
|
|||
|
|
@ -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:
|
|||
<!--more-->
|
||||
|
||||
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/).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<!--more-->
|
||||
|
||||
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.
|
||||
Loading…
Reference in New Issue