From 8a0f330654ed500520f4c34e145668dcff1ede24 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Wed, 1 Dec 2021 23:50:18 +0000 Subject: [PATCH] Improve documentation for container probes - mention gRPC probes in concept page - revise explanation of gRPC probes in task page - general tidying --- .../concepts/workloads/pods/pod-lifecycle.md | 106 +++++++++++------- ...igure-liveness-readiness-startup-probes.md | 62 +++++----- 2 files changed, 101 insertions(+), 67 deletions(-) diff --git a/content/en/docs/concepts/workloads/pods/pod-lifecycle.md b/content/en/docs/concepts/workloads/pods/pod-lifecycle.md index 75e4a0ba34..5d75bba37d 100644 --- a/content/en/docs/concepts/workloads/pods/pod-lifecycle.md +++ b/content/en/docs/concepts/workloads/pods/pod-lifecycle.md @@ -233,57 +233,87 @@ When a Pod's containers are Ready but at least one custom condition is missing o ## Container probes -A [Probe](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#probe-v1-core) is a diagnostic +A _probe_ is a diagnostic performed periodically by the [kubelet](/docs/reference/command-line-tools-reference/kubelet/) -on a Container. To perform a diagnostic, -the kubelet calls a -[Handler](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#handler-v1-core) implemented by -the container. There are three types of handlers: +on a container. To perform a diagnostic, +the kubelet either executes code within the container, or makes +a network request. -* [ExecAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#execaction-v1-core): - Executes a specified command inside the container. The diagnostic +### Check mechanisms {#probe-check-methods} + +There are four different ways to check a container using a probe. +Each probe must define exactly one of these four mechanisms: + +`exec` +: Executes a specified command inside the container. The diagnostic is considered successful if the command exits with a status code of 0. -* [TCPSocketAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#tcpsocketaction-v1-core): - Performs a TCP check against the Pod's IP address on - a specified port. The diagnostic is considered successful if the port is open. +`grpc` +: Performs a remote procedure call using [gRPC](https://grpc.io/). + The target should implement + [gRPC health checks](https://grpc.io/grpc/core/md_doc_health-checking.html). + The diagnostic is considered successful if the `status` + of the response is `SERVING`. + gRPC probes are an alpha feature and are only available if you + enable the `GRPCContainerProbe` + [feature gate](/docs/reference/command-line-tools-reference/feature-gates/). -* [HTTPGetAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#httpgetaction-v1-core): - Performs an HTTP `GET` request against the Pod's IP - address on a specified port and path. The diagnostic is considered successful - if the response has a status code greater than or equal to 200 and less than 400. +`httpGet` +: Performs an HTTP `GET` request against the Pod's IP + address on a specified port and path. The diagnostic is + considered successful if the response has a status code + greater than or equal to 200 and less than 400. + +`tcpSocket` +: Performs a TCP check against the Pod's IP address on + a specified port. The diagnostic is considered successful if + the port is open. If the remote system (the container) closes + the connection immediately after it opens, this counts as healthy. + +### Probe outcome Each probe has one of three results: -* `Success`: The container passed the diagnostic. -* `Failure`: The container failed the diagnostic. -* `Unknown`: The diagnostic failed, so no action should be taken. +`Success` +: The container passed the diagnostic. + +`Failure` +: The container failed the diagnostic. + +`Unknown` +: The diagnostic failed (no action should be taken, and the kubelet + will make further checks). + +### Types of probe The kubelet can optionally perform and react to three kinds of probes on running containers: -* `livenessProbe`: Indicates whether the container is running. If - the liveness 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 liveness probe, the default state is `Success`. +`livenessProbe` +: Indicates whether the container is running. If + the liveness 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 liveness probe, the default state is `Success`. -* `readinessProbe`: Indicates whether the container is ready to respond to requests. - If the readiness probe fails, the endpoints controller removes the Pod's IP - address from the endpoints of all Services that match the Pod. The default - state of readiness before the initial delay is `Failure`. If a Container does - not provide a readiness probe, the default state is `Success`. +`readinessProbe` +: Indicates whether the container is ready to respond to requests. + If the readiness probe fails, the endpoints controller removes the Pod's IP + address from the endpoints of all Services that match the Pod. The default + state of readiness before the initial delay is `Failure`. If a container does + not provide a readiness probe, the default state is `Success`. -* `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`. +`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`. For more information about how to set up a liveness, readiness, or startup probe, see [Configure Liveness, Readiness and Startup Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). -### When should you use a liveness probe? +#### When should you use a liveness probe? {{< feature-state for_k8s_version="v1.0" state="stable" >}} @@ -295,7 +325,7 @@ 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? +#### When should you use a readiness probe? {{< feature-state for_k8s_version="v1.0" state="stable" >}} @@ -329,7 +359,7 @@ The Pod remains in the unready state while it waits for the containers in the Po to stop. {{< /note >}} -### When should you use a startup probe? +#### When should you use a startup probe? {{< feature-state for_k8s_version="v1.20" state="stable" >}} @@ -451,13 +481,13 @@ This avoids a resource leak as Pods are created and terminated over time. ## {{% heading "whatsnext" %}} * Get hands-on experience - [attaching handlers to Container lifecycle events](/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/). + [attaching handlers to container lifecycle events](/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/). * Get hands-on experience [configuring Liveness, Readiness and Startup Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). * Learn more about [container lifecycle hooks](/docs/concepts/containers/container-lifecycle-hooks/). -* For detailed information about Pod / Container status in the API, see [PodStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podstatus-v1-core) -and -[ContainerStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerstatus-v1-core). +* For detailed information about Pod and container status in the API, see + the API reference documentation covering + [`.status`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodStatus) for Pod. diff --git a/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md b/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md index 2ef2b1368c..1553787301 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md +++ b/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md @@ -226,51 +226,56 @@ kubectl describe pod goproxy If your application implements [gRPC Health Checking Protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md), kubelet can be configured to use it for application liveness checks. +You must enable the `GRPCContainerProbe` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +in order to configure checks that rely on gRPC. + +Here is an example manifest: {{< codenew file="pods/probe/grpc-liveness.yaml">}} To use a gRPC probe, `port` must be configured. If the health endpoint is configured -on a non-default service, `service` must be configured. +on a non-default service, you must also specify the `service`. {{< note >}} Unlike HTTP and TCP probes, named ports cannot be used and custom host cannot be configured. {{< /note >}} -Configuration problems (e.g. incorrect port and service, unimplemented health checking protocol) +Configuration problems (for example: incorrect port and service, unimplemented health checking protocol) are considered a probe failure, similar to HTTP and TCP probes. +To try the gRPC liveness check, create a Pod using the command below. +In the example below, the etcd pod is configured to use gRPC liveness probe. + +```shell +kubectl apply -f https://k8s.io/examples/pods/probe/content/en/examples/pods/probe/grpc-liveness.yaml +``` + +After 15 seconds, view Pod events to verify that the liveness check has not failed: + +```shell +kubectl describe pod etcd-with-grpc +``` + Before Kubernetes 1.23, gRPC health probes were often implemented using [grpc-health-probe](https://github.com/grpc-ecosystem/grpc-health-probe/), as described in the blog post [Health checking gRPC servers on Kubernetes](/blog/2018/10/01/health-checking-grpc-servers-on-kubernetes/). The built-in gRPC probes behavior is similar to one implemented by grpc-health-probe. When migrating from grpc-health-probe to built-in probes, remember the following differences: -- Built-in probes will run against pod IP, unlike grpc-health-probe that often runs against `127.0.0.1`. - Be sure to configure your gRPC endpoint to listen for pod IP address. -- Built-in probes do not currently support any authentication parameters (like `-tls`). -- There are no error codes in built-in probes. All errors are considered as probe failures. -- If `ExecProbeTimeout` feature gate is set to `false`, grpc-health-probe will NOT - respect `timeoutSeconds` setting (which defaults to 1s), - while built-in probe will fail on timeout. - -To try the gRPC liveness check, create a Pod using the command below. -In the example below, etcd pod is configured to use gRPC liveness probe. - - -```shell -kubectl apply -f https://k8s.io/examples/pods/probe/content/en/examples/pods/probe/grpc-liveness.yaml -``` - -After 15 seconds, view Pod events to verify that the liveness probes has not failed: - -```shell -kubectl describe pod etcd-with-grpc -``` +- Built-in probes run against the pod IP address, unlike grpc-health-probe that often runs against `127.0.0.1`. + Be sure to configure your gRPC endpoint to listen on the Pod's IP address. +- Built-in probes do not support any authentication parameters (like `-tls`). +- There are no error codes for built-in probes. All errors are considered as probe failures. +- If `ExecProbeTimeout` feature gate is set to `false`, grpc-health-probe does **not** respect the `timeoutSeconds` setting (which defaults to 1s), + while built-in probe would fail on timeout. ## Use a named port You can use a named -[ContainerPort](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerport-v1-core) -for HTTP and TCP probes. Note, gRPC probe does not support named port. +[`port`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#ports) +for HTTP and TCP probes. (gRPC probes do not support named ports). + +For example: ```yaml ports: @@ -533,12 +538,11 @@ It will be rejected by the API server. ## {{% heading "whatsnext" %}} - * Learn more about [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). You can also read the API references for: -* [Pod](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core) -* [Container](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#container-v1-core) -* [Probe](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#probe-v1-core) +* [Pod](/docs/reference/kubernetes-api/workload-resources/pod-v1/), and specifically: + * [container(s)](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container) + * [probe(s)](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Probe)