Add docs related to KEP #950 (startupProbe) (#15714)

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

@@ -101,7 +101,7 @@ Each probe has one of three results:
 * Failure: The Container failed the diagnostic.
 * Unknown: The diagnostic failed, so no action should be taken.
 
-The kubelet can optionally perform and react to two kinds of probes on running
+The kubelet can optionally perform and react to three kinds of probes on running
 Containers:
 
 * `livenessProbe`: Indicates whether the Container is running. If
@@ -115,7 +115,15 @@ Containers:
    state of readiness before the initial delay is `Failure`. If a Container does
    not provide a readiness probe, the default state is `Success`.
 
-### When should you use liveness or readiness probes?
+* `startupProbe`: Indicates whether the application within the Container is started.
+   All other probes are disabled if a startup probe is provided, until it succeeds.
+   If the startup probe fails, the kubelet kills the Container, and the Container
+   is subjected to its [restart policy](#restart-policy). If a Container does not
+   provide a startup probe, the default state is `Success`.
+
+### When should you use a liveness probe?
+
+{{< feature-state for_k8s_version="v1.0" state="stable" >}}
 
 If the process in your Container is able to crash on its own whenever it
 encounters an issue or becomes unhealthy, you do not necessarily need a liveness
@@ -125,6 +133,10 @@ with the Pod's `restartPolicy`.
 If you'd like your Container to be killed and restarted if a probe fails, then
 specify a liveness probe, and specify a `restartPolicy` of Always or OnFailure.
 
+### When should you use a readiness probe?
+
+{{< feature-state for_k8s_version="v1.0" state="stable" >}}
+
 If you'd like to start sending traffic to a Pod only when a probe succeeds,
 specify a readiness probe. In this case, the readiness probe might be the same
 as the liveness probe, but the existence of the readiness probe in the spec means
@@ -142,6 +154,13 @@ 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.
 
+### When should you use a startup probe?
+
+{{< feature-state for_k8s_version="v1.16" state="alpha" >}}
+
+If your Container usually starts in more than `initialDelaySeconds + failureThreshold × periodSeconds`, you should specify a startup probe that checks the same endpoint as the liveness probe. The default for `periodSeconds` is 30s.
+You should then set its `failureThreshold` high enough to allow the Container to start, without changing the default values of the liveness probe. This helps to protect against deadlocks.
+
 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/).
 

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

@@ -151,6 +151,7 @@ different Kubernetes components.
 | `ServerSideApply` | `false` | Alpha | 1.14 | |
 | `ServiceLoadBalancerFinalizer` | `false` | Alpha | 1.15 | |
 | `ServiceNodeExclusion` | `false` | Alpha | 1.8 | |
+| `StartupProbe` | `false` | Alpha | 1.16 | |
 | `StorageObjectInUseProtection` | `true` | Beta | 1.10 | 1.10 |
 | `StorageObjectInUseProtection` | `true` | GA | 1.11 | |
 | `StorageVersionHash` | `false` | Alpha | 1.14 | 1.14 |
@@ -337,6 +338,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `ServiceLoadBalancerFinalizer`: Enable finalizer protection for Service load balancers.
 - `ServiceNodeExclusion`: Enable the exclusion of nodes from load balancers created by a cloud provider.
   A node is eligible for exclusion if annotated with "`alpha.service-controller.kubernetes.io/exclude-balancer`" key.
+- `StartupProbe`: Enable the [startup](/docs/concepts/workloads/pods/pod-lifecycle/#when-should-you-use-a-startup-probe) probe in the kubelet.
 - `StorageObjectInUseProtection`: Postpone the deletion of PersistentVolume or
   PersistentVolumeClaim objects if they are still being used.
 - `StorageVersionHash`: Allow apiservers to expose the storage version hash in the discovery.

content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md

@@ -19,6 +19,12 @@ accepting traffic. A Pod is considered ready when all of its Containers are read
 One use of this signal is to control which Pods are used as backends for Services.
 When a Pod is not ready, it is removed from Service load balancers.
 
+The kubelet uses startup probes to know when a Container application has started.
+If such a probe is configured, it disables liveness and readiness checks until
+it succeeds, making sure those probes don't interfere with the application startup.
+This can be used to adopt liveness checks on slow starting containers, avoiding them
+getting killed by the kubelet before they are up and running.
+
 {{% /capture %}}
 
 {{% capture prerequisites %}}
@@ -231,6 +237,46 @@ livenessProbe:
     port: liveness-port
 ```
 
+## Protect slow starting containers with startup probes {#define-startup-probes}
+
+Sometimes, you have to deal with legacy applications that might require
+an additional startup time on their first initialization.
+In such cases, it can be tricky to setup liveness probe parameters without
+compromising the fast response to deadlocks that motivated such a probe.
+The trick is to setup a startup probe with the same command, HTTP or TCP
+check, with a `failureThreshold * periodSeconds` long enough to cover the
+worse case startup time.
+
+So, the previous example would become:
+
+```yaml
+ports:
+- name: liveness-port
+  containerPort: 8080
+  hostPort: 8080
+
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: liveness-port
+  failureThreshold: 1
+  periodSeconds: 10
+
+startupProbe:
+  httpGet:
+    path: /healthz
+    port: liveness-port
+  failureThreshold: 30
+  periodSeconds: 10
+```
+
+Thanks to the startup probe, the application will have a maximum of 5 minutes
+(30 * 10 = 300s) to finish its startup.
+Once the startup probe has succeeded once, the liveness probe takes over to
+provide a fast response to container deadlocks.
+If the startup probe never succeeds, the container is killed after 300s and
+subject to the pod's `restartPolicy`.
+
 ## Define readiness probes
 
 Sometimes, applications are temporarily unable to serve traffic.