Skip to content

Commit 9b9d765

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #43346 from T-Lakshmi/sidecar-container
Add a new concept page for Sidecar containers
2 parents 0c5cb41 + b23c499 commit 9b9d765

File tree

3 files changed

+180
-55
lines changed

3 files changed

+180
-55
lines changed

‎content/en/docs/concepts/workloads/pods/init-containers.md

Lines changed: 36 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ Init containers can contain utilities or setup scripts not present in an app ima
1414
You can specify init containers in the Pod specification alongside the `containers`
1515
array (which describes app containers).
1616

17+
In Kubernetes, a [sidecar container](/docs/concepts/workloads/pods/sidecar-containers/) is a container that
18+
starts before the main application container and _continues to run_. This document is about init containers:
19+
containers that run to completion during Pod initialization.
1720

1821
<!-- body -->
1922

@@ -48,14 +51,33 @@ including resource limits, [volumes](/docs/concepts/storage/volumes/), and secur
4851
resource requests and limits for an init container are handled differently,
4952
as documented in [Resource sharing within containers](#resource-sharing-within-containers).
5053

51-
Also, init containers do not support `lifecycle`, `livenessProbe`, `readinessProbe`, or
52-
`startupProbe` because they must run to completion before the Pod can be ready.
54+
Regular init containers (in other words: excluding sidecar containers) do not support the
55+
`lifecycle`, `livenessProbe`, `readinessProbe`, or `startupProbe` fields. Init containers
56+
must run to completion before the Pod can be ready; sidecar containers continue running
57+
during a Pod's lifetime, and _do_ support some probes. See [sidecar container](/docs/concepts/workloads/pods/sidecar-containers/)
58+
for further details about sidecar containers.
5359

5460
If you specify multiple init containers for a Pod, kubelet runs each init
5561
container sequentially. Each init container must succeed before the next can run.
5662
When all of the init containers have run to completion, kubelet initializes
5763
the application containers for the Pod and runs them as usual.
5864

65+
### Differences from sidecar containers
66+
67+
Init containers run and complete their tasks before the main application container starts.
68+
Unlike [sidecar containers](/docs/concepts/workloads/pods/sidecar-containers),
69+
init containers are not continuously running alongside the main containers.
70+
71+
Init containers run to completion sequentially, and the main container does not start
72+
until all the init containers have successfully completed.
73+
74+
init containers do not support `lifecycle`, `livenessProbe`, `readinessProbe`, or
75+
`startupProbe` whereas sidecar containers support all these [probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe) to control their lifecycle.
76+
77+
Init containers share the same resources (CPU, memory, network) with the main application
78+
containers but do not interact directly with them. They can, however, use shared volumes
79+
for data exchange.
80+
5981
## Using init containers
6082

6183
Because init containers have separate images from app containers, they
@@ -289,51 +311,9 @@ The Pod which is already running correctly would be killed by `activeDeadlineSec
289311
The name of each app and init container in a Pod must be unique; a
290312
validation error is thrown for any container sharing a name with another.
291313

292-
#### API for sidecar containers
293-
294-
{{< feature-state for_k8s_version="v1.28" state="alpha" >}}
295-
296-
Starting with Kubernetes 1.28 in alpha, a feature gate named `SidecarContainers`
297-
allows you to specify a `restartPolicy` for init containers which is independent of
298-
the Pod and other init containers. Container [probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe)
299-
can also be added to control their lifecycle.
300-
301-
If an init container is created with its `restartPolicy` set to `Always`, it will
302-
start and remain running during the entire life of the Pod, which is useful for
303-
running supporting services separated from the main application containers.
304-
305-
If a `readinessProbe` is specified for this init container, its result will be used
306-
to determine the `ready` state of the Pod.
307-
308-
Since these containers are defined as init containers, they benefit from the same
309-
ordering and sequential guarantees as other init containers, allowing them to
310-
be mixed with other init containers into complex Pod initialization flows.
311-
312-
Compared to regular init containers, sidecar-style init containers continue to
313-
run and the next init container can begin starting once the kubelet has set
314-
the `started` container status for the sidecar-style init container to true.
315-
That status either becomes true because there is a process running in the
316-
container and no startup probe defined, or
317-
as a result of its `startupProbe` succeeding.
318-
319-
This feature can be used to implement the sidecar container pattern in a more
320-
robust way, as the kubelet always restarts a sidecar container if it fails.
321-
322-
Here's an example of a Deployment with two containers, one of which is a sidecar:
323-
324-
{{% code_sample language="yaml" file="application/deployment-sidecar.yaml" %}}
325-
326-
This feature is also useful for running Jobs with sidecars, as the sidecar
327-
container will not prevent the Job from completing after the main container
328-
has finished.
329-
330-
Here's an example of a Job with two containers, one of which is a sidecar:
331-
332-
{{% code_sample language="yaml" file="application/job/job-sidecar.yaml" %}}
333-
334-
#### Resource sharing within containers
314+
### Resource sharing within containers
335315

336-
Given the ordering and execution for init containers, the following rules
316+
Given the order of execution for init, sidecar and app containers, the following rules
337317
for resource usage apply:
338318

339319
* The highest of any particular resource request or limit defined on all init
@@ -354,6 +334,10 @@ limit.
354334
Pod level control groups (cgroups) are based on the effective Pod request and
355335
limit, the same as the scheduler.
356336

337+
{{< comment >}}
338+
This section also present under [sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/) page.
339+
If you're editing this section, change both places.
340+
{{< /comment >}}
357341

358342
### Pod restart reasons
359343

@@ -373,7 +357,9 @@ Kubernetes, consult the documentation for the version you are using.
373357

374358
## {{% heading "whatsnext" %}}
375359

376-
* Read about [creating a Pod that has an init container](/docs/tasks/configure-pod-container/configure-pod-initialization/#create-a-pod-that-has-an-init-container)
377-
* Learn how to [debug init containers](/docs/tasks/debug/debug-application/debug-init-containers/)
378-
* Read about an overview of [kubelet](/docs/reference/command-line-tools-reference/kubelet/) and [kubectl](/docs/reference/kubectl/)
379-
* Learn about the [types of probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe): liveness, readiness, startup probe.
360+
Learn more about the following:
361+
* [Creating a Pod that has an init container](/docs/tasks/configure-pod-container/configure-pod-initialization/#create-a-pod-that-has-an-init-container).
362+
* [Debug init containers](/docs/tasks/debug/debug-application/debug-init-containers/).
363+
* Overview of [kubelet](/docs/reference/command-line-tools-reference/kubelet/) and [kubectl](/docs/reference/kubectl/).
364+
* [Types of probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe): liveness, readiness, startup probe.
365+
* [Sidecar containers](/docs/concepts/workloads/pods/sidecar-containers).

‎content/en/docs/concepts/workloads/pods/pod-lifecycle.md

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -150,11 +150,22 @@ the `Terminated` state.
150150
The `spec` of a Pod has a `restartPolicy` field with possible values Always, OnFailure,
151151
and Never. The default value is Always.
152152

153-
The `restartPolicy` applies to all containers in the Pod. `restartPolicy` only
154-
refers to restarts of the containers by the kubelet on the same node. After containers
155-
in a Pod exit, the kubelet restarts them with an exponential back-off delay (10s, 20s,
156-
40s, …), that is capped at five minutes. Once a container has executed for 10 minutes
157-
without any problems, the kubelet resets the restart backoff timer for that container.
153+
The `restartPolicy` for a Pod applies to {{< glossary_tooltip text="app containers" term_id="app-container" >}}
154+
in the Pod and to regular [init containers](/docs/concepts/workloads/pods/init-containers/).
155+
[Sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/)
156+
ignore the Pod-level `restartPolicy` field: in Kubernetes, a sidecar is defined as an
157+
entry inside `initContainers` that has its container-level `restartPolicy` set to `Always`.
158+
For init containers that exit with an error, the kubelet restarts the init container if
159+
the Pod level `restartPolicy` is either `OnFailure` or `Always`.
160+
161+
When the kubelet is handling container restarts according to the configured restart
162+
policy, that only applies to restarts that make replacement containers inside the
163+
same Pod and running on the same node. After containers in a Pod exit, the kubelet
164+
restarts them with an exponential back-off delay (10s, 20s,40s, …), that is capped at
165+
five minutes. Once a container has executed for 10 minutes without any problems, the
166+
kubelet resets the restart backoff timer for that container.
167+
[Sidecar containers and Pod lifecycle](/docs/concepts/workloads/pods/sidecar-containers/#sidecar-containers-and-pod-lifecycle)
168+
explains the behaviour of `init containers` when specify `restartpolicy` field on it.
158169

159170
## Pod conditions
160171

@@ -582,6 +593,8 @@ for more details.
582593

583594
* Learn more about [container lifecycle hooks](/docs/concepts/containers/container-lifecycle-hooks/).
584595

596+
* Learn more about [sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/).
597+
585598
* For detailed information about Pod and container status in the API, see
586599
the API reference documentation covering
587600
[`status`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodStatus) for Pod.

‎content/en/docs/concepts/workloads/pods/sidecar-containers.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: Sidecar Containers
3+
content_type: concept
4+
weight: 50
5+
---
6+
7+
<!-- overview -->
8+
{{< feature-state for_k8s_version="v1.28" state="alpha" >}}
9+
10+
Sidecar containers are the secondary containers that run along with the main
11+
application container within the same {{< glossary_tooltip text="Pod" term_id="pod" >}}.
12+
These containers are used to enhance or to extend the functionality of the main application
13+
container by providing additional services, or functionality such as logging, monitoring,
14+
security, or data synchronization, without directly altering the primary application code.
15+
16+
<!-- body -->
17+
18+
## Enabling sidecar containers
19+
20+
Starting with Kubernetes 1.28, a
21+
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) named
22+
`SidecarContainers` allows you to specify a `restartPolicy` for containers listed in a
23+
Pod's `initContainers` field. These restartable _sidecar_ containers are independent with
24+
other [init containers](/docs/concepts/workloads/pods/init-containers/) and main
25+
application container within the same pod. These can be started, stopped, or restarted
26+
without effecting the main application container and other init containers.
27+
28+
## Sidecar containers and Pod lifecycle
29+
30+
If an init container is created with its `restartPolicy` set to `Always`, it will
31+
start and remain running during the entire life of the Pod. This can be helpful for
32+
running supporting services separated from the main application containers.
33+
34+
If a `readinessProbe` is specified for this init container, its result will be used
35+
to determine the `ready` state of the Pod.
36+
37+
Since these containers are defined as init containers, they benefit from the same
38+
ordering and sequential guarantees as other init containers, allowing them to
39+
be mixed with other init containers into complex Pod initialization flows.
40+
41+
Compared to regular init containers, sidecars defined within `initContainers` continue to
42+
run after they have started. This is important when there is more than one entry inside
43+
`.spec.initContainers` for a Pod. After a sidecar-style init container is running (the kubelet
44+
has set the `started` status for that init container to true), the kubelet then starts the
45+
next init container from the ordered `.spec.initContainers` list.
46+
That status either becomes true because there is a process running in the
47+
container and no startup probe defined, or as a result of its `startupProbe` succeeding.
48+
49+
Here's an example of a Deployment with two containers, one of which is a sidecar:
50+
51+
{{% code_sample language="yaml" file="application/deployment-sidecar.yaml" %}}
52+
53+
This feature is also useful for running Jobs with sidecars, as the sidecar
54+
container will not prevent the Job from completing after the main container
55+
has finished.
56+
57+
Here's an example of a Job with two containers, one of which is a sidecar:
58+
59+
{{% code_sample language="yaml" file="application/job/job-sidecar.yaml" %}}
60+
By default, this feature is not available in Kubernetes. To avail this feature, you
61+
need to enable the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
62+
named `SidecarContainers`.
63+
64+
## Differences from regular containers
65+
66+
Sidecar containers run alongside regular containers in the same pod. However, they do not
67+
execute the primary application logic; instead, they provide supporting functionality to
68+
the main application.
69+
70+
Sidecar containers have their own independent lifecycles. They can be started, stopped,
71+
and restarted independently of regular containers. This means you can update, scale, or
72+
maintain sidecar containers without affecting the primary application.
73+
74+
Sidecar containers share the same network and storage namespaces with the primary
75+
container This co-location allows them to interact closely and share resources.
76+
77+
## Differences from init containers
78+
79+
Sidecar containers work alongside the main container, extending its functionality and
80+
providing additional services.
81+
82+
Sidecar containers run concurrently with the main application container. They are active
83+
throughout the lifecycle of the pod and can be started and stopped independently of the
84+
main container. Unlike [init containers](/docs/concepts/workloads/pods/init-containers/),
85+
sidecar containers support [probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe) to control their lifecycle.
86+
87+
These containers can interact directly with the main application containers, sharing
88+
the same network namespace, filesystem, and environment variables. They work closely
89+
together to provide additional functionality.
90+
91+
## Resource sharing within containers
92+
93+
{{< comment >}}
94+
This section is also present in the [init containers](/docs/concepts/workloads/pods/init-containers/) page.
95+
If you're editing this section, change both places.
96+
{{< /comment >}}
97+
98+
Given the order of execution for init, sidecar and app containers, the following rules
99+
for resource usage apply:
100+
101+
* The highest of any particular resource request or limit defined on all init
102+
containers is the *effective init request/limit*. If any resource has no
103+
resource limit specified this is considered as the highest limit.
104+
* The Pod's *effective request/limit* for a resource is the sum of
105+
[pod overhead](/docs/concepts/scheduling-eviction/pod-overhead/) and the higher of:
106+
* the sum of all non-init containers(app and sidecar containers) request/limit for a
107+
resource
108+
* the effective init request/limit for a resource
109+
* Scheduling is done based on effective requests/limits, which means
110+
init containers can reserve resources for initialization that are not used
111+
during the life of the Pod.
112+
* The QoS (quality of service) tier of the Pod's *effective QoS tier* is the
113+
QoS tier for all init, sidecar and app containers alike.
114+
115+
Quota and limits are applied based on the effective Pod request and
116+
limit.
117+
118+
Pod level control groups (cgroups) are based on the effective Pod request and
119+
limit, the same as the scheduler.
120+
121+
## {{% heading "whatsnext" %}}
122+
123+
* Read a blog post on [native sidecar containers](/blog/2023/08/25/native-sidecar-containers/).
124+
* Read about [creating a Pod that has an init container](/docs/tasks/configure-pod-container/configure-pod-initialization/#create-a-pod-that-has-an-init-container).
125+
* Learn about the [types of probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe): liveness, readiness, startup probe.
126+
* Learn about [pod overhead](/docs/concepts/scheduling-eviction/pod-overhead/).

0 commit comments

Comments
 (0)