Merge pull request #44800 from sftim/20240118_improve_sidecar_container_docs

Update docs around sidecar containers

Author: k8s-ci-robot

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

@@ -331,8 +331,10 @@ for resource usage apply:
 Quota and limits are applied based on the effective Pod request and
 limit.
 
-Pod level control groups (cgroups) are based on the effective Pod request and
-limit, the same as the scheduler.
+### Init containers and Linux cgroups {#cgroups}
+
+On Linux, resource allocations for Pod level control groups (cgroups) are based on the effective Pod
+request and limit, the same as the scheduler.
 
 {{< comment >}}
 This section also present under [sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/) page.

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

@@ -9,21 +9,43 @@ weight: 50
 
 Sidecar containers are the secondary containers that run along with the main
 application container within the same {{< glossary_tooltip text="Pod" term_id="pod" >}}.
-These containers are used to enhance or to extend the functionality of the main application
-container by providing additional services, or functionality such as logging, monitoring,
+These containers are used to enhance or to extend the functionality of the primary _app
+container_ by providing additional services, or functionality such as logging, monitoring,
 security, or data synchronization, without directly altering the primary application code.
 
+Typically, you only have one app container in a Pod. For example, if you have a web
+application that requires a local webserver, the local webserver is a sidecar and the
+web application itself is the app container.
+
 <!-- body -->
 
-## Enabling sidecar containers
+## Sidecar containers in Kubernetes {#pod-sidecar-containers}
+
+Kubernetes implements sidecar containers as a special case of
+[init containers](/docs/concepts/workloads/pods/init-containers/); sidecar containers remain
+running after Pod startup. This document uses the term _regular init containers_ to clearly
+refer to containers that only run during Pod startup.
+
+Provided that your cluster has the `SidecarContainers`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) enabled
+(the feature is active by default since Kubernetes v1.29), you can specify a `restartPolicy`
+for containers listed in a Pod's `initContainers` field.
+These restartable _sidecar_ containers are independent from other init containers and from
+the main application container(s) within the same pod.
+These can be started, stopped, or restarted without effecting the main application container
+and other init containers.
+
+You can also run a Pod with multiple containers that are not marked as init or sidecar
+containers. This is appropriate if the containers within the Pod are required for the
+Pod to work overall, but you don't need to control which containers start or stop first.
+You could also do this if you need to support older versions of Kubernetes that don't
+support a container-level `restartPolicy` field.
+
+### Example application {#sidecar-example}
+
+Here's an example of a Deployment with two containers, one of which is a sidecar:
 
-Enabled by default with Kubernetes 1.29, a
-[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) named
-`SidecarContainers` allows you to specify a `restartPolicy` for containers listed in a
-Pod's `initContainers` field. These restartable _sidecar_ containers are independent with
-other [init containers](/docs/concepts/workloads/pods/init-containers/) and main
-application container within the same pod. These can be started, stopped, or restarted
-without effecting the main application container and other init containers.
+{{% code_sample language="yaml" file="application/deployment-sidecar.yaml" %}}
 
 ## Sidecar containers and Pod lifecycle
 
@@ -35,8 +57,8 @@ If a `readinessProbe` is specified for this init container, its result will be u
 to determine the `ready` state of the Pod.
 
 Since these containers are defined as init containers, they benefit from the same
-ordering and sequential guarantees as other init containers, allowing them to
-be mixed with other init containers into complex Pod initialization flows.
+ordering and sequential guarantees as regular init containers, allowing you to mix
+sidecar containers with regular init containers for complex Pod initialization flows.
 
 Compared to regular init containers, sidecars defined within `initContainers` continue to
 run after they have started. This is important when there is more than one entry inside
@@ -46,30 +68,28 @@ next init container from the ordered `.spec.initContainers` list.
 That status either becomes true because there is a process running in the
 container and no startup probe defined, or as a result of its `startupProbe` succeeding.
 
-Here's an example of a Deployment with two containers, one of which is a sidecar:
-
-{{% code_sample language="yaml" file="application/deployment-sidecar.yaml" %}}
+### Jobs with sidecar containers
 
-This feature is also useful for running Jobs with sidecars, as the sidecar
-container will not prevent the Job from completing after the main container
-has finished.
+If you define a Job that uses sidecar using Kubernetes-style init containers,
+the sidecar container in each Pod does not prevent the Job from completing after the
+main container has finished.
 
 Here's an example of a Job with two containers, one of which is a sidecar:
 
 {{% code_sample language="yaml" file="application/job/job-sidecar.yaml" %}}
 
-## Differences from regular containers
+## Differences from application containers
 
-Sidecar containers run alongside regular containers in the same pod. However, they do not
+Sidecar containers run alongside _app containers_ in the same pod. However, they do not
 execute the primary application logic; instead, they provide supporting functionality to
 the main application.
 
 Sidecar containers have their own independent lifecycles. They can be started, stopped,
-and restarted independently of regular containers. This means you can update, scale, or
+and restarted independently of app containers. This means you can update, scale, or
 maintain sidecar containers without affecting the primary application.
 
 Sidecar containers share the same network and storage namespaces with the primary
-container This co-location allows them to interact closely and share resources.
+container. This co-location allows them to interact closely and share resources.
 
 ## Differences from init containers
 
@@ -112,8 +132,10 @@ for resource usage apply:
 Quota and limits are applied based on the effective Pod request and
 limit.
 
-Pod level control groups (cgroups) are based on the effective Pod request and
-limit, the same as the scheduler.
+### Sidecar containers and Linux cgroups {#cgroups}
+
+On Linux, resource allocations for Pod level control groups (cgroups) are based on the effective Pod
+request and limit, the same as the scheduler.
 
 ## {{% heading "whatsnext" %}}
 

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

@@ -283,7 +283,7 @@ pod usage is still within acceptable limits.
 The HorizontalPodAutoscaler API also supports a container metric source where the HPA can track the
 resource usage of individual containers across a set of Pods, in order to scale the target resource.
 This lets you configure scaling thresholds for the containers that matter most in a particular Pod.
-For example, if you have a web application and a logging sidecar, you can scale based on the resource
+For example, if you have a web application and a sidecar container that provides logging, you can scale based on the resource
 use of the web application, ignoring the sidecar container and its resource use.
 
 If you revise the target resource to have a new Pod specification with a different set of containers,