Merge pull request #30710 from sftim/20211201_improve_probe_documentation

Improve documentation for container probes

Author: k8s-ci-robot

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
-  is considered successful if the command exits with a status code of 0.
+### 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:
 
-* [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.
+`exec`
+: Executes a specified command inside the container. The diagnostic
+  is considered successful if the command exits with a status code of 0.
 
-* [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.
+`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/).
+
+`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.
 
-The kubelet can optionally perform and react to three kinds of probes on running
-containers:
+`Failure`
+: The container failed the diagnostic.
+
+`Unknown`
+: The diagnostic failed (no action should be taken, and the kubelet
+  will make further checks).
 
-* `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`.
+### Types of probe
 
-* `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`.
+The kubelet can optionally perform and react to three kinds of probes on running
+containers:
 
-* `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`.
+`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`.
+
+`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.

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.
 
-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.
-
+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 probes has not failed:
+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 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)