Document the Pod Ready++ feature (#9180)

Closes: #9107
Xref: kubernetes/kubernetes#64057

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

@@ -56,9 +56,19 @@ Here are the possible values for `phase`:
 A Pod has a PodStatus, which has an array of
 [PodConditions](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podcondition-v1-core). Each element
 of the PodCondition array has a `type` field and a `status` field. The `type`
-field is a string, with possible values PodScheduled, Ready, Initialized, and
-Unschedulable. The `status` field is a string, with possible values True, False,
-and Unknown.
+field is a string with the following possible values:
+
+* `PodScheduled`: the Pod has been scheduled to a node;
+* `Ready`: the Pod is able to serve requests and should be added to the load
+  balancing pools of all matching Services;
+* `Initialized`: all [init containers](/docs/concepts/workloads/pods/init-containers)
+  have started successfully;
+* `Unschedulable`: the scheduler cannot schedule the Pod right now, for example
+  due to lacking of resources or other constraints;
+* `ContainersReady`: all containers in the Pod are ready.
+
+The `status` field is a string, with possible values "`True`", "`False`", and
+"`Unknown`".
 
 ## Container probes
 
@@ -130,7 +140,8 @@ puts itself into an unready state regardless of whether the readiness probe exis
 The Pod remains in the unready state while it waits for the Containers in the Pod
 to stop.
 
-For more information about how to set up a liveness or readiness probe, see [Configure Liveness and Readiness Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/).
+For more information about how to set up a liveness or readiness probe, see
+[Configure Liveness and Readiness Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/).
 
 ## Pod and Container status
 
@@ -141,6 +152,58 @@ and
 Note that the information reported as Pod status depends on the current
 [ContainerState](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerstatus-v1-core).
 
+## Pod readiness gate
+
+{{< feature-state for_k8s_version="v1.11" state="alpha" >}}
+
+In order to add extensibility to Pod readiness by enabling the injection of
+extra feedbacks or signals into `PodStatus`, Kubernetes 1.11 introduced a
+feature named [Pod ready++](https://github.com/kubernetes/community/blob/master/keps/sig-network/0007-pod-ready%2B%2B.md).
+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
+condition in the `status.conditions` field of a Pod, the status of the condition 
+is default to "`False`". Below is an example:
+
+```yaml
+Kind: Pod
+...
+spec:
+  readinessGates:
+    - conditionType: "www.example.com/feature-1"
+status:
+  conditions:
+    - type: Ready  # this is a builtin PodCondition
+      status: "True"
+      lastProbeTime: null
+      lastTransitionTime: 2018-01-01T00:00:00Z
+    - type: "www.example.com/feature-1"   # an extra PodCondition
+      status: "False"
+      lastProbeTIme: null
+      lastTransitionTime: 2018-01-01T00:00:00Z
+  containerStatuses:
+    - containerID: docker://abcd...
+      ready: true
+...
+```
+
+The new Pod conditions must comply with 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-librarie/).
+
+With the introduction of new Pod conditions, a Pod is evaluated to be ready **only**
+when both the following statements are true:
+
+* All containers in the Pod are ready.
+* All conditions specified in `ReadinessGates` are "`True`".
+
+To facilitate this change to Pod readiness evaluation, a new Pod condition
+`ContainersReady` is introduced to capture the old Pod `Ready` condition.
+
+As an alpha feature, the "Pod Ready++" feature has to be explicitly enabled by
+setting the `PodReadinessGates` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+to True.
+
 ## Restart policy
 
 A PodSpec has a `restartPolicy` field with possible values Always, OnFailure,
@@ -154,7 +217,6 @@ minutes of successful execution. As discussed in the
 once bound to a node, a Pod will never be rebound to another node.
 
 
-
 ## Pod lifetime
 
 In general, Pods do not disappear until someone destroys them. This might be a

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -74,6 +74,7 @@ different Kubernetes components.
 | `PersistentLocalVolumes` | `false` | Alpha | 1.7 | 1.9 |
 | `PersistentLocalVolumes` | `true` | Beta | 1.10 | |
 | `PodPriority` | `false` | Alpha | 1.8 | |
+| `PodReadinessGates` | `false` | Alpha | 1.11 | |
 | `PodShareProcessNamespace` | `false` | Alpha | 1.10 | |
 | `PVCProtection` | `false` | Alpha | 1.9 | 1.9 |
 | `ReadOnlyAPIDataVolumes` | `true` | Deprecated | 1.10 | |
@@ -195,6 +196,9 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `PersistentLocalVolumes`: Enable the usage of `local` volume type in Pods.
   Pod affinity has to be specified if requesting a `local` volume.
 - `PodPriority`: Enable the descheduling and preemption of Pods based on their [priorities](/docs/concepts/configuration/pod-priority-preemption/).
+- `PodReadinessGates`: Enable the setting of `PodReadinessGate` field for extending
+  Pod readiness evaluation.
+  For more details, please see [Pod readiness gate](/docs/concepts/workloads/pods/pod-lifecycle/#pod-readiness-gate).
 - `PVCProtection`: Enable the prevention of a PersistentVolumeClaim (PVC) from
   being deleted when it is still used by any Pod.
   More details can be found [here](/docs/tasks/administer-cluster/pvc-protection/).