Skip to content

Documentation change for container restart rules #51467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 6, 2025
Merged

Documentation change for container restart rules #51467

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 118 additions & 1 deletion content/en/docs/concepts/workloads/pods/pod-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,26 @@ To investigate the root cause of a `CrashLoopBackOff` issue, a user can:
application code. Running this container image locally or in a development
environment can help diagnose application specific issues.

### Container restart policy {#restart-policy}
### Container restarts {#restart-policy}

When a container in your Pod stops, or experiences failure, Kubernetes can restart it.
A restart isn't always appropriate; for example,
{{< glossary_tooltip text="init containers" term_id="init-container" >}} run only once,
during Pod startup.
<!-- TODO reword when ContainerRestartRules graduates -->
You can configure restarts as a policy that applies to all Pods, or using container-level configuration (for example: when you define a
{{< glossary_tooltip text="sidecar container" term_id="sidecar-container" >}}).
Comment on lines +246 to +247
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can configure restarts as a policy that applies to all Pods, or using container-level configuration (for example: when you define a
{{< glossary_tooltip text="sidecar container" term_id="sidecar-container" >}}).
You can configure restarts as a policy that applies to all Pods, or using container-level configuration
(for example: when you define a {{< glossary_tooltip text="sidecar container" term_id="sidecar-container" >}}).


#### Container restarts and resilience {#container-restart-resilience}

The Kubernetes project recommends following cloud-native principles, including resilient
design that accounts for unannounced or arbitrary restarts. You can achieve this either
by failing the Pod and relying on automatic
[replacement](/docs/concepts/workloads/controllers/), or you can design for container-level resilience.
Either approach helps to ensure that your overall workload remains available despite
partial failure.

#### Pod-level container restart policy

The `spec` of a Pod has a `restartPolicy` field with possible values Always, OnFailure,
and Never. The default value is Always.
Expand All @@ -262,6 +281,104 @@ problems, the kubelet resets the restart backoff timer for that container.
[Sidecar containers and Pod lifecycle](/docs/concepts/workloads/pods/sidecar-containers/#sidecar-containers-and-pod-lifecycle)
explains the behaviour of `init containers` when specify `restartpolicy` field on it.

#### Individual container restart policy and rules {#container-restart-rules}

{{< feature-state
feature_gate_name="ContainerRestartRules" >}}
Comment on lines +286 to +287
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{{< feature-state
feature_gate_name="ContainerRestartRules" >}}
{{< feature-state feature_gate_name="ContainerRestartRules" >}}

Put the shortcode onto a single line.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally yes


If your cluster has the feature gate `ContainerRestartRules` enabled, you can specify
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We really recommend hyperlinking the phrase "feature gates" to the list of feature gates.

`restartPolicy` and `restartPolicyRules` on _inidividual containers_ to override the Pod
restart policy. Container restart policy and rules applies to {{< glossary_tooltip text="app containers" term_id="app-container" >}}
in the Pod and to regular [init containers](/docs/concepts/workloads/pods/init-containers/).

A Kubernetes-native [sidecar container](/docs/concepts/workloads/pods/sidecar-containers/)
has its container-level `restartPolicy` set to `Always`, and does not support `restartPolicyRules`.

The container restarts will follow the same exponential backoff as pod restart policy described above.
Supported container restart policies:

* `Always`: Automatically restarts the container after any termination.
* `OnFailure`: Only restarts the container if it exits with an error (non-zero exit status).
* `Never`: Does not automatically restart the terminated container.

Additionally, _individual containers_ can specify `restartPolicyRules`. If the `restartPolicyRules`
field is specified, then container `restartPolicy` **must** also be specified. The `restartPolicyRules`
define a list of rules to apply on container exit. Each rule will consist of a condition
and an action. The supported condition is `exitCodes`, which compares the exit code of the container
with a list of given values. The supported action is `Restart`, which means the container will be
restarted. The rules will be evaluated in order. On the first match, the action will be applied.
If none of the rules’ conditions matched, Kubernetes fallback to container’s configured
`restartPolicy`.

For example, a Pod with OnFailure restart policy that have a `try-once` container. This allows
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example, a Pod with OnFailure restart policy that have a `try-once` container. This allows
For example, a Pod with `OnFailure` restart policy that have a `try-once` container. This allows

Pod to only restart certain containers:

```yaml
apiVersion: v1
kind: Pod
metadata:
name: on-failure-pod
spec:
restartPolicy: OnFailure
containers:
- name: try-once-container # This container will run only once because the restartPolicy is Never.
image: docker.io/library/busybox:1.28
command: ['sh', '-c', 'echo "Only running once" && sleep 10 && exit 1']
restartPolicy: Never
- name: on-failure-container # This container will be restarted on failure.
image: docker.io/library/busybox:1.28
command: ['sh', '-c', 'echo "Keep restarting" && sleep 1800 && exit 1']
```

A Pod with Always restart policy with an init container that only execute once. If the init
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A Pod with Always restart policy with an init container that only execute once. If the init
A Pod with `Always` restart policy with an init container that only execute once. If the init

Use a consistent style for those values

container fails, the Pod fails. This alllows the Pod to fail if the initialiaztion failed,
but also keep running once the initialization succeeds:

```yaml
apiVersion: v1
kind: Pod
metadata:
name: fail-pod-if-init-fails
spec:
restartPolicy: Always
initContainers:
- name: init-once # This init container will only try once. If it fails, the pod will fail.
image: docker.io/library/busybox:1.28
command: ['sh', '-c', 'echo "Failing initialization" && sleep 10 && exit 1']
restartPolicy: Never
containers:
- name: main-container # This container will always be restarted once initialization succeeds.
image: docker.io/library/busybox:1.28
command: ['sh', '-c', 'sleep 1800 && exit 0']
```

A Pod with Never restart policy with a container that ignores and restarts on specific exit codes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A Pod with Never restart policy with a container that ignores and restarts on specific exit codes.
A Pod with `Never` restart policy with a container that ignores and restarts on specific exit codes.

This is useful to differentiate between restartable errors and non-restartable errors:

```yaml
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this example is very synthetic. I do now know if it is useful to include, it looks more like a developer documentation, not the end user documentation.

I would suggest to add a few "real life" examples where those overrides will be useful.

  • OnFailure Pod with the try-once container (that has an override Never).
  • OnFailure Pod that has override treating subset of codes as "failures" and other exit code are ignored
  • Always Pod with the Init container that will only execute once and if failed, Pod is failed
  • Never Pod with the override on a container to ignore and restart on specific exit code

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about a Pod with a true sidecar and a "lazy init" container that runs to completion during app container startup, writing out a config that the app container hot reloads when available?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added some suggested examples. Let me know would these be enough.

apiVersion: v1
kind: Pod
metadata:
name: restart-on-exit-codes
spec:
restartPolicy: Never
containers:
- name: restart-on-exit-codes
image: docker.io/library/busybox:1.28
command: ['sh', '-c', 'sleep 60 && exit 0']
restartPolicy: Never # Container restart policy must be specified if rules are specified
restartPolicyRules: # Only restart the container if it exits with code 42
- action: Restart
exitCodes:
operator: In
values: [42]
```

Restart rules can be used for many more advanced lifecycle management scenarios. Note, restart rules
are affected by the same inconsistencies as the regular restart policy. Kubelet restarts, container
runtime garbage collection, intermitted connectivity issues with the control plane may cause the state
loss and containers may be re-run even when you expect a container not to be restarted.

### Reduced container restart delay

{{< feature-state
Expand Down
14 changes: 14 additions & 0 deletions ...s/reference/command-line-tools-reference/feature-gates/ContainerRestartRules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
title: ContainerRestartRules
content_type: feature_gate
_build:
list: never
render: false

stages:
- stage: alpha
defaultValue: false
fromVersion: "1.34"
---
Enables the ability to configure container-level restart policy and restart rules.
See [Container Restart Policy and Rules](/docs/concepts/workloads/pods/pod-lifecycle/#container-restart-rules) for more details.