From 762bd879ac83759af03aae9ec3157d67b4d4eb23 Mon Sep 17 00:00:00 2001 From: Matthias Bertschy Date: Fri, 6 Sep 2019 22:37:20 +0200 Subject: [PATCH] Add docs related to KEP #950 (startupProbe) (#15714) --- .../concepts/workloads/pods/pod-lifecycle.md | 23 +++++++++- .../feature-gates.md | 2 + .../configure-liveness-readiness-probes.md | 46 +++++++++++++++++++ 3 files changed, 69 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/workloads/pods/pod-lifecycle.md b/content/en/docs/concepts/workloads/pods/pod-lifecycle.md index 26b8e40d84..59f945e641 100644 --- a/content/en/docs/concepts/workloads/pods/pod-lifecycle.md +++ b/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/). diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 99b5721522..4965ddcc4b 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/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. diff --git a/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md b/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md index fc9f9c3473..5e9238a778 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md +++ b/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.