From 6f9a31a1fc7304ab0b2b8ae6b7e7f3a52a75aae4 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Tue, 22 Dec 2020 16:25:08 +0800 Subject: [PATCH] Update Pod overview This PR adds some clarifications about Pod update and Pod replacement, which can be pretty confusing to new users. --- .../en/docs/concepts/workloads/pods/_index.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/content/en/docs/concepts/workloads/pods/_index.md b/content/en/docs/concepts/workloads/pods/_index.md index 5bd954dcef..af548a79cb 100644 --- a/content/en/docs/concepts/workloads/pods/_index.md +++ b/content/en/docs/concepts/workloads/pods/_index.md @@ -191,6 +191,35 @@ details are abstracted away. That abstraction and separation of concerns simplif system semantics, and makes it feasible to extend the cluster's behavior without changing existing code. +## Pod update and replacement + +As mentioned in the previous section, when the Pod template for a workload +resource is changed, the controller creates new Pods based on the updated +template instead of updating or patching the existing Pods. + +Kubernetes doesn't prevent you from managing Pods directly. It is possible to +update some fields of a running Pod, in place. However, Pod update operations +like +[`patch`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#patch-pod-v1-core), and +[`replace`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#replace-pod-v1-core) +have some limitations: + +- Most of the metadata about a Pod is immutable. For example, you cannot + change the `namespace`, `name`, `uid`, or `creationTimestamp` fields; + the `generation` field is unique. It only accepts updates that increment the + field's current value. +- If the `metadata.deletionTimestamp` is set, no new entry can be added to the + `metadata.finalizers` list. +- Pod updates may not change fields other than `spec.containers[*].image`, + `spec.initContainers[*].image`, `spec.activeDeadlineSeconds` or + `spec.tolerations`. For `spec.tolerations`, you can only add new entries. +- When updating the `spec.activeDeadlineSeconds` field, two types of updates + are allowed: + + 1. setting the unassigned field to a positive number; + 1. updating the field from a positive number to a smaller, non-negative + number. + ## Resource sharing and communication Pods enable data sharing and communication among their constituent