From 8a44573309593190fbace6036f5e04499d334acd Mon Sep 17 00:00:00 2001 From: Matthias Bertschy Date: Thu, 29 Jun 2023 07:41:59 +0200 Subject: [PATCH] adding Sidecar Containers alpha feature Signed-off-by: Matthias Bertschy --- .../en/docs/concepts/workloads/pods/_index.md | 14 ++++++- .../workloads/pods/init-containers.md | 42 ++++++++++++++++++- .../feature-gates.md | 8 +++- .../application/deployment-sidecar.yaml | 34 +++++++++++++++ .../examples/application/job/job-sidecar.yaml | 26 ++++++++++++ 5 files changed, 120 insertions(+), 4 deletions(-) create mode 100644 content/en/examples/application/deployment-sidecar.yaml create mode 100644 content/en/examples/application/job/job-sidecar.yaml diff --git a/content/en/docs/concepts/workloads/pods/_index.md b/content/en/docs/concepts/workloads/pods/_index.md index e9fba178e2cdd..19f2564c30ee5 100644 --- a/content/en/docs/concepts/workloads/pods/_index.md +++ b/content/en/docs/concepts/workloads/pods/_index.md @@ -112,7 +112,17 @@ 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" >}}. Init containers run and complete before the app containers are started. +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.28" state="alpha" >}} + +Enabling the [SidecarContainers feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +allows specifying a restartPolicy=Always to init containers, making sure they 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). @@ -366,4 +376,4 @@ To understand the context for why Kubernetes wraps a common Pod API in other res * [Borg](https://research.google.com/pubs/pub43438.html) * [Marathon](https://mesosphere.github.io/marathon/docs/rest-api.html) * [Omega](https://research.google/pubs/pub41684/) -* [Tupperware](https://engineering.fb.com/data-center-engineering/tupperware/). +* [Tupperware](https://engineering.fb.com/data-center-engineering/tupperware/). \ No newline at end of file diff --git a/content/en/docs/concepts/workloads/pods/init-containers.md b/content/en/docs/concepts/workloads/pods/init-containers.md index c7e0707e881a5..0f3f085e83226 100644 --- a/content/en/docs/concepts/workloads/pods/init-containers.md +++ b/content/en/docs/concepts/workloads/pods/init-containers.md @@ -289,7 +289,46 @@ The Pod which is already running correctly would be killed by `activeDeadlineSec The name of each app and init container in a Pod must be unique; a validation error is thrown for any container sharing a name with another. -### Resources +#### API for sidecar containers + +{{< feature-state for_k8s_version="v1.28" state="alpha" >}} + +Starting with Kubernetes 1.28 in alpha, a feature gate named `SidecarContainers` +allows to specify a `restartPolicy` for init containers which is independent of +the Pod and other init containers. Container [probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe) +can also be added to control their lifecycle. + +If an init container is created with its `restartPolicy` set to `Always`, it will +start and remain running during the entire life of the Pod, which is useful for +running supporting services separated from the main application containers. + +If a `readinessProbe` is specified for this init container, its result will be used +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. + +The only difference is that they are not required to complete before the next +init container starts, so a next init container will start after the current +container has been marked as `started` as a result of its `startupProbe`. + +This feature can be used to implement the sidecar container pattern in a more +robust way, as the kubelet always restarts a sidecar container if it fails. + +Here's an example of a Deployment with two containers, one of which is a sidecar: + +{{% codenew language="yaml" file="application/deployment-sidecar.yaml" %}} + +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. + +Here's an example of a Job with two containers, one of which is a sidecar: + +{{% codenew language="yaml" file="application/job/job-sidecar.yaml" %}} + +#### Resource sharing within containers Given the ordering and execution for init containers, the following rules for resource usage apply: @@ -335,3 +374,4 @@ Kubernetes, consult the documentation for the version you are using. * Learn how to [debug init containers](/docs/tasks/debug/debug-application/debug-init-containers/) * Read about an overview of [kubelet](/docs/reference/command-line-tools-reference/kubelet/) and [kubectl](/docs/reference/kubectl/) * Learn about the [types of probes](/docs/concepts/workloads/pods/pod-lifecycle/#types-of-probe): liveness, readiness, startup probe. +* \ No newline at end of file diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index be6ea04ceef80..7a67737a2b71e 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -192,6 +192,7 @@ For a reference to old feature gates that are removed, please refer to | `SecurityContextDeny` | `false` | Alpha | 1.27 | | | `ServiceNodePortStaticSubrange` | `false` | Alpha | 1.27 | 1.27 | | `ServiceNodePortStaticSubrange` | `true` | Beta | 1.28 | | +| `SidecarContainers` | `false` | Alpha | 1.28 | | | `SizeMemoryBackedVolumes` | `false` | Alpha | 1.20 | 1.21 | | `SizeMemoryBackedVolumes` | `true` | Beta | 1.22 | | | `StableLoadBalancerNodeGet` | `true` | Beta | 1.27 | | @@ -701,6 +702,11 @@ Each feature gate is designed for enabling/disabling a specific feature: risk of collision. See [Avoiding collisions](/docs/concepts/services-networking/service/#avoiding-collisions) for more details. +- `SidecarContainers`: Allow setting the `restartPolicy` of an init container to + `Always` so that the container becomes a sidecar container (restartable init containers). + See + [Sidecar containers and restartPolicy](/docs/concepts/workloads/pods/init-containers/#sidecar-containers-and-restartpolicy) + for more details. - `SizeMemoryBackedVolumes`: Enable kubelets to determine the size limit for memory-backed volumes (mainly `emptyDir` volumes). - `StableLoadBalancerNodeGet`: Enables less load balancer re-configurations by @@ -749,4 +755,4 @@ Each feature gate is designed for enabling/disabling a specific feature: feature, you will also need to enable any associated API resources. For example, to enable a particular resource like `storage.k8s.io/v1beta1/csistoragecapacities`, set `--runtime-config=storage.k8s.io/v1beta1/csistoragecapacities`. - See [API Versioning](/docs/reference/using-api/#api-versioning) for more details on the command line flags. + See [API Versioning](/docs/reference/using-api/#api-versioning) for more details on the command line flags. \ No newline at end of file diff --git a/content/en/examples/application/deployment-sidecar.yaml b/content/en/examples/application/deployment-sidecar.yaml new file mode 100644 index 0000000000000..ae958c5b740ca --- /dev/null +++ b/content/en/examples/application/deployment-sidecar.yaml @@ -0,0 +1,34 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp + labels: + app: myapp +spec: + replicas: 1 + selector: + matchLabels: + app: myapp + template: + metadata: + labels: + app: myapp + spec: + containers: + - name: myapp + image: alpine:latest + command: ['sh', '-c', 'echo "logging" > /opt/logs.txt'] + volumeMounts: + - name: data + mountPath: /opt + initContainers: + - name: logshipper + image: alpine:latest + restartPolicy: Always + command: ['sh', '-c', 'tail /opt/logs.txt'] + volumeMounts: + - name: data + mountPath: /opt + volumes: + - name: data + emptyDir: {} \ No newline at end of file diff --git a/content/en/examples/application/job/job-sidecar.yaml b/content/en/examples/application/job/job-sidecar.yaml new file mode 100644 index 0000000000000..c5518cb061fee --- /dev/null +++ b/content/en/examples/application/job/job-sidecar.yaml @@ -0,0 +1,26 @@ +apiVersion: batch/v1 +kind: Job +metadata: + name: myjob +spec: + template: + spec: + containers: + - name: myjob + image: alpine:latest + command: ['sh', '-c', 'echo "logging" > /opt/logs.txt'] + volumeMounts: + - name: data + mountPath: /opt + initContainers: + - name: logshipper + image: alpine:latest + restartPolicy: Always + command: ['sh', '-c', 'tail /opt/logs.txt'] + volumeMounts: + - name: data + mountPath: /opt + restartPolicy: Never + volumes: + - name: data + emptyDir: {} \ No newline at end of file