kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revise Pod lifecycle page 

Reword Pod readiness section
- “Pod Ready++” is stable, so word the documentation accordingly.
- In the documentation, call this “Pod readiness”
- Related tweaks

Reword Pod lifetime section
- mention StatefulSet
- omit mentioning ReplicationController as it's deprecated
- reword to suggest that the list of workload resources is non-exhaustive
and use glossary tooltips as well.
This commit is contained in:
Tim Bannister 2019-12-23 12:50:53 +00:00 committed by bryan
parent ec17b4a4a9
commit fe24a953d0
1 changed files with 46 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
content/en/docs/concepts/workloads/pods/pod-lifecycle.md
View File

@ -181,7 +181,7 @@ Once Pod is assigned to a node by scheduler, kubelet starts creating containers
... ...
State: Waiting State: Waiting
Reason: ErrImagePull Reason: ErrImagePull
... ...
``` ```
* `Running`: Indicates that the container is executing without issues. The `postStart` hook (if any) is executed prior to the container entering a Running state. This state also displays the time when the container entered Running state. * `Running`: Indicates that the container is executing without issues. The `postStart` hook (if any) is executed prior to the container entering a Running state. This state also displays the time when the container entered Running state.
@ -205,31 +205,34 @@ Once Pod is assigned to a node by scheduler, kubelet starts creating containers
... ...
``` ```
## Pod readiness gate ## Pod readiness {#pod-readiness-gate}
{{< feature-state for_k8s_version="v1.14" state="stable" >}} {{< feature-state for_k8s_version="v1.14" state="stable" >}}
In order to add extensibility to Pod readiness by enabling the injection of Your application can inject extra feedback or signals into PodStatus:
extra feedback or signals into `PodStatus`, Kubernetes 1.11 introduced a _Pod readiness_. To use this, set `readinessGates` in the PodSpec to specify
feature named [Pod ready++](https://github.com/kubernetes/enhancements/blob/master/keps/sig-network/0007-pod-ready%2B%2B.md). a list of additional conditions that the kubelet evaluates for Pod readiness.
You can use the new field `ReadinessGate` in the `PodSpec` to specify additional
conditions to be evaluated for Pod readiness. If Kubernetes cannot find such a Readiness gates are determined by the current state of `status.condition`
fields for the Pod. If Kubernetes cannot find such a
condition in the `status.conditions` field of a Pod, the status of the condition condition in the `status.conditions` field of a Pod, the status of the condition
is default to "`False`". Below is an example: is defaulted to "`False`". Below is an example:
Here is an example:
```yaml ```yaml
Kind: Pod kind: Pod
... ...
spec: spec:
readinessGates: readinessGates:
- conditionType: "www.example.com/feature-1" - conditionType: "www.example.com/feature-1"
status: status:
conditions: conditions:
- type: Ready # this is a builtin PodCondition - type: Ready # a built in PodCondition
status: "False" status: "False"
lastProbeTime: null lastProbeTime: null
lastTransitionTime: 2018-01-01T00:00:00Z lastTransitionTime: 2018-01-01T00:00:00Z
- type: "www.example.com/feature-1" # an extra PodCondition - type: "www.example.com/feature-1" # an extra PodCondition
status: "False" status: "False"
lastProbeTime: null lastProbeTime: null
lastTransitionTime: 2018-01-01T00:00:00Z lastTransitionTime: 2018-01-01T00:00:00Z
@ -239,19 +242,26 @@ status:
... ...
``` ```
The new Pod conditions must comply with Kubernetes [label key format](/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). The Pod conditions you add must have names that meet the Kubernetes [label key format](/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set).
Since the `kubectl patch` command still doesn't support patching object status,
the new Pod conditions have to be injected through the `PATCH` action using
one of the [KubeClient libraries](/docs/reference/using-api/client-libraries/).
With the introduction of new Pod conditions, a Pod is evaluated to be ready **only**
when both the following statements are true: ### Status for Pod readiness {#pod-readiness-status}
The `kubectl patch` command does not support patching object status.
To set these `status.conditions` for the pod, applications and
{{< glossary_tooltip term_id="operator-pattern" text="operators">}} should use
the `PATCH` action.
You can use a [Kubernetes client library](/docs/reference/using-api/client-libraries/) to
write code that sets custom Pod conditions for Pod readiness.
For a Pod that uses custom conditions, that Pod is evaluated to be ready **only**
when both the following statements apply:
* All containers in the Pod are ready. * All containers in the Pod are ready.
* All conditions specified in `ReadinessGates` are "`True`". * All conditions specified in `ReadinessGates` are `True`.
To facilitate this change to Pod readiness evaluation, a new Pod condition When a Pod's containers are Ready but at least one custom condition is missing or
`ContainersReady` is introduced to capture the old Pod `Ready` condition. `False`, the kubelet sets the Pod's condition to `ContainersReady`.
## Restart policy ## Restart policy
@ -268,32 +278,31 @@ once bound to a node, a Pod will never be rebound to another node.
## Pod lifetime ## Pod lifetime
In general, Pods remain until a human or controller process explicitly removes them. In general, Pods remain until a human or
{{< glossary_tooltip term_id="controller" text="controller" >}} process
explicitly removes them.
The control plane cleans up terminated Pods (with a phase of `Succeeded` or The control plane cleans up terminated Pods (with a phase of `Succeeded` or
`Failed`), when the number of Pods exceeds the configured threshold `Failed`), when the number of Pods exceeds the configured threshold
(determined by `terminated-pod-gc-threshold` in the kube-controller-manager). (determined by `terminated-pod-gc-threshold` in the kube-controller-manager).
This avoids a resource leak as Pods are created and terminated over time. This avoids a resource leak as Pods are created and terminated over time.
Three types of controllers are available: There are different kinds of resources for creating Pods:
- Use a [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/) for Pods that are expected to terminate, - Use a {{< glossary_tooltip term_id="deployment" >}},
{{< glossary_tooltip term_id="replica-set" >}} or {{< glossary_tooltip term_id="statefulset" >}}
for Pods that are not expected to terminate, for example, web servers.
- Use a {{< glossary_tooltip term_id="job" >}}
for Pods that are expected to terminate once their work is complete;
for example, batch computations. Jobs are appropriate only for Pods with for example, batch computations. Jobs are appropriate only for Pods with
`restartPolicy` equal to OnFailure or Never. `restartPolicy` equal to OnFailure or Never.
- Use a [ReplicationController](/docs/concepts/workloads/controllers/replicationcontroller/), - Use a {{< glossary_tooltip term_id="daemonset" >}}
[ReplicaSet](/docs/concepts/workloads/controllers/replicaset/), or for Pods that need to run one per eligible node.
[Deployment](/docs/concepts/workloads/controllers/deployment/)
for Pods that are not expected to terminate, for example, web servers.
ReplicationControllers are appropriate only for Pods with a `restartPolicy` of
Always.
- Use a [DaemonSet](/docs/concepts/workloads/controllers/daemonset/) for Pods that need to run one per All workload resources contain a PodSpec. It is recommended to create the
machine, because they provide a machine-specific system service. appropriate workload resource and let the resource's controller create Pods
for you, rather than directly create Pods yourself.
All three types of controllers contain a PodTemplate. It
is recommended to create the appropriate controller and let
it create Pods, rather than directly create Pods yourself. That is because Pods
alone are not resilient to machine failures, but controllers are.
If a node dies or is disconnected from the rest of the cluster, Kubernetes If a node dies or is disconnected from the rest of the cluster, Kubernetes
applies a policy for setting the `phase` of all Pods on the lost node to Failed. applies a policy for setting the `phase` of all Pods on the lost node to Failed.