whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #30710 from sftim/20211201_improve_probe_documentation

Browse Source 
Improve documentation for container probes
This commit is contained in:
Kubernetes Prow Robot
2021-12-03 06:08:27 -08:00
committed by GitHub
parent 3baac6dde3 8a0f330654
commit 4f193feffe
2 changed files with 101 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/workloads/pods/pod-lifecycle.md
+60 -30
View File
@@ -233,57 +233,87 @@ When a Pod's containers are Ready but at least one custom condition is missing o
## Container probes ## 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 performed periodically by the
[kubelet](/docs/reference/command-line-tools-reference/kubelet/) [kubelet](/docs/reference/command-line-tools-reference/kubelet/)
on a Container. To perform a diagnostic, on a container. To perform a diagnostic,
the kubelet calls a the kubelet either executes code within the container, or makes
[Handler](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#handler-v1-core) implemented by a network request.
the container. There are three types of handlers:
* [ExecAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#execaction-v1-core): ### Check mechanisms {#probe-check-methods}
Executes a specified command inside the container. The diagnostic
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. is considered successful if the command exits with a status code of 0.
* [TCPSocketAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#tcpsocketaction-v1-core): `grpc`
Performs a TCP check against the Pod's IP address on : Performs a remote procedure call using [gRPC](https://grpc.io/).
a specified port. The diagnostic is considered successful if the port is open. 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): `httpGet`
Performs an HTTP `GET` request against the Pod's IP : Performs an HTTP `GET` request against the Pod's IP
address on a specified port and path. The diagnostic is considered successful address on a specified port and path. The diagnostic is
if the response has a status code greater than or equal to 200 and less than 400. 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: Each probe has one of three results:
* `Success`: The container passed the diagnostic. `Success`
* `Failure`: The container failed the diagnostic. : The container passed the diagnostic.
* `Unknown`: The diagnostic failed, so no action should be taken.
`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 The kubelet can optionally perform and react to three kinds of probes on running
containers: containers:
* `livenessProbe`: Indicates whether the container is running. If `livenessProbe`
: Indicates whether the container is running. If
the liveness probe fails, the kubelet kills the container, and the container 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 is subjected to its [restart policy](#restart-policy). If a container does not
provide a liveness probe, the default state is `Success`. provide a liveness probe, the default state is `Success`.
* `readinessProbe`: Indicates whether the container is ready to respond to requests. `readinessProbe`
: Indicates whether the container is ready to respond to requests.
If the readiness probe fails, the endpoints controller removes the Pod's IP 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 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 state of readiness before the initial delay is `Failure`. If a container does
not provide a readiness probe, the default state is `Success`. not provide a readiness probe, the default state is `Success`.
* `startupProbe`: Indicates whether the application within the container is started. `startupProbe`
: Indicates whether the application within the container is started.
All other probes are disabled if a startup probe is provided, until it succeeds. 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 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 is subjected to its [restart policy](#restart-policy). If a container does not
provide a startup probe, the default state is `Success`. provide a startup probe, the default state is `Success`.
For more information about how to set up a liveness, readiness, or startup probe, 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/). 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" >}} {{< 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 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. 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" >}} {{< 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. to stop.
{{< /note >}} {{< /note >}}
### When should you use a startup probe? #### When should you use a startup probe?
{{< feature-state for_k8s_version="v1.20" state="stable" >}} {{< 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" %}} ## {{% heading "whatsnext" %}}
* Get hands-on experience * 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 * Get hands-on experience
[configuring Liveness, Readiness and Startup Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). [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/). * 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) * For detailed information about Pod and container status in the API, see
and the API reference documentation covering
[ContainerStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerstatus-v1-core). [`.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
+33 -29
View File
@@ -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), 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. 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">}} {{< codenew file="pods/probe/grpc-liveness.yaml">}}
To use a gRPC probe, `port` must be configured. If the health endpoint is configured 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 >}} {{< note >}}
Unlike HTTP and TCP probes, named ports cannot be used and custom host cannot be configured. Unlike HTTP and TCP probes, named ports cannot be used and custom host cannot be configured.
{{< /note >}} {{< /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. 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/), 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/). 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. 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: 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`. - 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 for pod IP address. Be sure to configure your gRPC endpoint to listen on the Pod's IP address.
- Built-in probes do not currently support any authentication parameters (like `-tls`). - Built-in probes do not support any authentication parameters (like `-tls`).
- There are no error codes in built-in probes. All errors are considered as probe failures. - 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 will NOT - If `ExecProbeTimeout` feature gate is set to `false`, grpc-health-probe does **not** respect the `timeoutSeconds` setting (which defaults to 1s),
respect `timeoutSeconds` setting (which defaults to 1s), while built-in probe would fail on timeout.
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
```
## Use a named port ## Use a named port
You can use a named You can use a named
[ContainerPort](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerport-v1-core) [`port`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#ports)
for HTTP and TCP probes. Note, gRPC probe does not support named port. for HTTP and TCP probes. (gRPC probes do not support named ports).
For example:
```yaml ```yaml
ports: ports:
@@ -533,12 +538,11 @@ It will be rejected by the API server.
## {{% heading "whatsnext" %}} ## {{% heading "whatsnext" %}}
* Learn more about * Learn more about
[Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes).
You can also read the API references for: You can also read the API references for:
* [Pod](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core) * [Pod](/docs/reference/kubernetes-api/workload-resources/pod-v1/), and specifically:
* [Container](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#container-v1-core) * [container(s)](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container)
* [Probe](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#probe-v1-core) * [probe(s)](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Probe)