配置存活探针、就绪探针和启动探针

此页面展示了如何为容器配置存活探测、就绪探测和启动探测。

The kubelet 使用存活探测来了解何时重新启动容器。例如，存活探测可以捕获死锁，在这种情况下，应用程序正在运行，但无法取得进展。在这样的状态下重新启动容器可以帮助提高应用程序的可用性，尽管存在错误。

存活探测的常见模式是使用与就绪探测相同的低成本 HTTP 端点，但具有更高的失败阈值。这确保了在 pod 被强制杀死之前，它在一段时间内被观察为不就绪。

kubelet 使用就绪探测来了解容器何时准备好开始接受流量。当所有容器都就绪时，Pod 被认为就绪。此信号的一种用途是控制哪些 Pod 用作服务的后端。当 Pod 不就绪时，它将从服务负载均衡器中删除。

kubelet 使用启动探测来了解容器应用程序何时启动。如果配置了此类探测，则存活探测和就绪探测在它成功之前不会启动，确保这些探测不会干扰应用程序启动。这可以用于在启动缓慢的容器上采用存活检查，避免它们在启动并运行之前被 kubelet 杀死。

注意

存活探测是恢复应用程序故障的强大方法，但应谨慎使用。必须仔细配置存活探测，以确保它们确实指示不可恢复的应用程序故障，例如死锁。

注意

存活探测的错误实现会导致级联故障。这会导致容器在高负载下重新启动；由于应用程序的可扩展性降低，客户端请求失败；由于某些 pod 失败，剩余 pod 上的工作负载增加。了解就绪探测和存活探测之间的区别，以及何时将它们应用于您的应用程序。

开始之前

您需要拥有一个 Kubernetes 集群，并且 kubectl 命令行工具必须配置为与您的集群通信。建议在至少有两个节点的集群上运行本教程，这些节点不充当控制平面主机。如果您还没有集群，可以使用 minikube 创建一个，或者可以使用以下 Kubernetes 游乐场之一

定义存活命令

许多长时间运行的应用程序最终会过渡到损坏状态，并且除了重新启动之外无法恢复。Kubernetes 提供存活探测来检测和解决此类情况。

在本练习中，您将创建一个 Pod，该 Pod 运行基于 registry.k8s.io/busybox 镜像的容器。以下是 Pod 的配置文件

pods/probe/exec-liveness.yaml

apiVersion: v1
kind: Pod
metadata:
  labels:
    test: liveness
  name: liveness-exec
spec:
  containers:
  - name: liveness
    image: registry.k8s.io/busybox
    args:
    - /bin/sh
    - -c
    - touch /tmp/healthy; sleep 30; rm -f /tmp/healthy; sleep 600
    livenessProbe:
      exec:
        command:
        - cat
        - /tmp/healthy
      initialDelaySeconds: 5
      periodSeconds: 5

在配置文件中，您可以看到 Pod 只有一个 Container。periodSeconds 字段指定 kubelet 应该每 5 秒执行一次存活探测。initialDelaySeconds 字段告诉 kubelet 它应该等待 5 秒才能执行第一个探测。要执行探测，kubelet 会在目标容器中执行命令 cat /tmp/healthy。如果命令成功，它将返回 0，kubelet 将认为容器处于活动状态且运行良好。如果命令返回非零值，kubelet 将杀死容器并重新启动它。

当容器启动时，它会执行以下命令

/bin/sh -c "touch /tmp/healthy; sleep 30; rm -f /tmp/healthy; sleep 600"

在容器生命周期的前 30 秒内，存在一个 /tmp/healthy 文件。因此，在前 30 秒内，命令 cat /tmp/healthy 返回成功代码。30 秒后，cat /tmp/healthy 返回失败代码。

创建 Pod

kubectl apply -f https://k8s.io/examples/pods/probe/exec-liveness.yaml

在 30 秒内，查看 Pod 事件

kubectl describe pod liveness-exec

输出表明还没有存活探测失败

Type    Reason     Age   From               Message
----    ------     ----  ----               -------
Normal  Scheduled  11s   default-scheduler  Successfully assigned default/liveness-exec to node01
Normal  Pulling    9s    kubelet, node01    Pulling image "registry.k8s.io/busybox"
Normal  Pulled     7s    kubelet, node01    Successfully pulled image "registry.k8s.io/busybox"
Normal  Created    7s    kubelet, node01    Created container liveness
Normal  Started    7s    kubelet, node01    Started container liveness

35 秒后，再次查看 Pod 事件

kubectl describe pod liveness-exec

在输出的底部，有一些消息表明存活探测已失败，并且已杀死并重新创建了失败的容器。

Type     Reason     Age                From               Message
----     ------     ----               ----               -------
Normal   Scheduled  57s                default-scheduler  Successfully assigned default/liveness-exec to node01
Normal   Pulling    55s                kubelet, node01    Pulling image "registry.k8s.io/busybox"
Normal   Pulled     53s                kubelet, node01    Successfully pulled image "registry.k8s.io/busybox"
Normal   Created    53s                kubelet, node01    Created container liveness
Normal   Started    53s                kubelet, node01    Started container liveness
Warning  Unhealthy  10s (x3 over 20s)  kubelet, node01    Liveness probe failed: cat: can't open '/tmp/healthy': No such file or directory
Normal   Killing    10s                kubelet, node01    Container liveness failed liveness probe, will be restarted

再等待 30 秒，并验证容器是否已重新启动

kubectl get pod liveness-exec

输出显示 RESTARTS 已递增。请注意，RESTARTS 计数器会在失败的容器恢复到运行状态后立即递增

NAME            READY     STATUS    RESTARTS   AGE
liveness-exec   1/1       Running   1          1m

定义存活 HTTP 请求

另一种存活探测使用 HTTP GET 请求。以下是运行基于 registry.k8s.io/e2e-test-images/agnhost 镜像的容器的 Pod 的配置文件。

pods/probe/http-liveness.yaml

apiVersion: v1
kind: Pod
metadata:
  labels:
    test: liveness
  name: liveness-http
spec:
  containers:
  - name: liveness
    image: registry.k8s.io/e2e-test-images/agnhost:2.40
    args:
    - liveness
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
        httpHeaders:
        - name: Custom-Header
          value: Awesome
      initialDelaySeconds: 3
      periodSeconds: 3

在配置文件中，您可以看到 Pod 只有一个容器。periodSeconds 字段指定 kubelet 应该每 3 秒执行一次存活探测。initialDelaySeconds 字段告诉 kubelet 它应该等待 3 秒才能执行第一个探测。要执行探测，kubelet 会向在容器中运行并在端口 8080 上监听的服务器发送 HTTP GET 请求。如果服务器的 /healthz 路径的处理程序返回成功代码，kubelet 将认为容器处于活动状态且运行良好。如果处理程序返回失败代码，kubelet 将杀死容器并重新启动它。

任何大于或等于 200 且小于 400 的代码都表示成功。任何其他代码都表示失败。

您可以在 server.go 中看到服务器的源代码。

在容器处于活动状态的前 10 秒内，/healthz 处理程序返回状态 200。之后，处理程序返回状态 500。

http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
    duration := time.Now().Sub(started)
    if duration.Seconds() > 10 {
        w.WriteHeader(500)
        w.Write([]byte(fmt.Sprintf("error: %v", duration.Seconds())))
    } else {
        w.WriteHeader(200)
        w.Write([]byte("ok"))
    }
})

kubelet 在容器启动后 3 秒开始执行健康检查。因此，前几次健康检查将成功。但在 10 秒后，健康检查将失败，kubelet 将杀死并重新启动容器。

要尝试 HTTP 存活检查，请创建一个 Pod

kubectl apply -f https://k8s.io/examples/pods/probe/http-liveness.yaml

10 秒后，查看 Pod 事件以验证存活探测是否已失败以及容器是否已重新启动

kubectl describe pod liveness-http

在 v1.13 之后的版本中，本地 HTTP 代理环境变量设置不会影响 HTTP 存活探测。

定义 TCP 存活探测

第三种存活探测使用 TCP 套接字。使用此配置，kubelet 将尝试在指定端口上打开到您的容器的套接字。如果它可以建立连接，则容器被认为是健康的，如果它不能，则被认为是失败的。

pods/probe/tcp-liveness-readiness.yaml

apiVersion: v1
kind: Pod
metadata:
  name: goproxy
  labels:
    app: goproxy
spec:
  containers:
  - name: goproxy
    image: registry.k8s.io/goproxy:0.1
    ports:
    - containerPort: 8080
    readinessProbe:
      tcpSocket:
        port: 8080
      initialDelaySeconds: 15
      periodSeconds: 10
    livenessProbe:
      tcpSocket:
        port: 8080
      initialDelaySeconds: 15
      periodSeconds: 10

如您所见，TCP 检查的配置与 HTTP 检查非常相似。此示例同时使用就绪探测和存活探测。kubelet 将在容器启动后 15 秒发送第一个就绪探测。这将尝试连接到端口 8080 上的 goproxy 容器。如果探测成功，则 Pod 将被标记为就绪。kubelet 将继续每 10 秒运行一次此检查。

除了就绪探测之外，此配置还包括存活探测。kubelet 将在容器启动后 15 秒运行第一个存活探测。与就绪探测类似，这将尝试连接到端口 8080 上的 goproxy 容器。如果存活探测失败，则容器将被重新启动。

要尝试 TCP 存活检查，请创建一个 Pod

kubectl apply -f https://k8s.io/examples/pods/probe/tcp-liveness-readiness.yaml

15 秒后，查看 Pod 事件以验证存活探测

kubectl describe pod goproxy

定义 gRPC 存活探测

功能状态： Kubernetes v1.27 [稳定]

如果您的应用程序实现了 gRPC 健康检查协议，此示例展示了如何配置 Kubernetes 以将其用于应用程序存活检查。类似地，您可以配置就绪探测和启动探测。

以下是一个示例清单

pods/probe/grpc-liveness.yaml

apiVersion: v1
kind: Pod
metadata:
  name: etcd-with-grpc
spec:
  containers:
  - name: etcd
    image: registry.k8s.io/etcd:3.5.1-0
    command: [ "/usr/local/bin/etcd", "--data-dir",  "/var/lib/etcd", "--listen-client-urls", "http://0.0.0.0:2379", "--advertise-client-urls", "http://127.0.0.1:2379", "--log-level", "debug"]
    ports:
    - containerPort: 2379
    livenessProbe:
      grpc:
        port: 2379
      initialDelaySeconds: 10

要使用 gRPC 探测，必须配置 port。如果您想区分不同类型的探测和针对不同功能的探测，可以使用 service 字段。您可以将 service 设置为 liveness 值，并使您的 gRPC 健康检查端点对该请求的响应方式不同于将 service 设置为 readiness 时。这使您可以使用同一个端点进行不同类型的容器健康检查，而不是监听两个不同的端口。如果您想指定您自己的自定义服务名称并指定探测类型，Kubernetes 项目建议您使用将两者连接起来的名称。例如：myservice-liveness（使用 - 作为分隔符）。

注意

与 HTTP 或 TCP 探测不同，您不能通过名称指定健康检查端口，也不能配置自定义主机名。

配置问题（例如：端口或服务不正确、未实现健康检查协议）被视为探测失败，类似于 HTTP 和 TCP 探测。

要尝试 gRPC 存活检查，请使用以下命令创建一个 Pod。在以下示例中，etcd pod 配置为使用 gRPC 存活探测。

kubectl apply -f https://k8s.io/examples/pods/probe/grpc-liveness.yaml

15 秒后，查看 Pod 事件以验证存活检查是否未失败

kubectl describe pod etcd-with-grpc

使用 gRPC 探测时，需要注意一些技术细节

探测针对 pod IP 地址或其主机名运行。确保将您的 gRPC 端点配置为监听 Pod 的 IP 地址。
探测不支持任何身份验证参数（如 -tls）。
内置探针没有错误代码。所有错误都被视为探针故障。
如果ExecProbeTimeout特性门设置为false，grpc-health-probe将**不**遵守timeoutSeconds设置（默认为1秒），而内置探针将在超时时失败。

使用命名端口

您可以为 HTTP 和 TCP 探针使用命名端口。gRPC 探针不支持命名端口。

例如

ports:
- name: liveness-port
  containerPort: 8080

livenessProbe:
  httpGet:
    path: /healthz
    port: liveness-port

使用启动探针保护启动缓慢的容器

有时，您需要处理可能需要在第一次初始化时额外启动时间的遗留应用程序。在这种情况下，在不影响导致此类探针的死锁的快速响应的情况下设置存活探针参数可能很棘手。诀窍是使用相同的命令、HTTP 或 TCP 检查设置启动探针，并使用failureThreshold * periodSeconds足够长的时间来覆盖最坏情况下的启动时间。

因此，前面的示例将变为

ports:
- name: liveness-port
  containerPort: 8080

livenessProbe:
  httpGet:
    path: /healthz
    port: liveness-port
  failureThreshold: 1
  periodSeconds: 10

startupProbe:
  httpGet:
    path: /healthz
    port: liveness-port
  failureThreshold: 30
  periodSeconds: 10

由于启动探针，应用程序将有最多 5 分钟（30 * 10 = 300 秒）的时间完成启动。启动探针成功一次后，存活探针将接管，以提供对容器死锁的快速响应。如果启动探针从未成功，则容器将在 300 秒后被杀死，并受 Pod 的restartPolicy影响。

定义就绪探针

有时，应用程序暂时无法提供服务。例如，应用程序可能需要在启动时加载大型数据或配置文件，或者在启动后依赖外部服务。在这种情况下，您不希望杀死应用程序，但也不希望向其发送请求。Kubernetes 提供就绪探针来检测和缓解这些情况。具有报告其未就绪的容器的 Pod 不会通过 Kubernetes 服务接收流量。

注意

就绪探针在容器的整个生命周期内运行。

注意

就绪探针和存活探针的成功与否相互独立。如果您希望在执行就绪探针之前等待，则应使用initialDelaySeconds或startupProbe。

就绪探针的配置与存活探针类似。唯一的区别是您使用readinessProbe字段而不是livenessProbe字段。

readinessProbe:
  exec:
    command:
    - cat
    - /tmp/healthy
  initialDelaySeconds: 5
  periodSeconds: 5

HTTP 和 TCP 就绪探针的配置也与存活探针相同。

就绪探针和存活探针可以并行用于同一个容器。使用两者可以确保流量不会到达未准备好接收流量的容器，并且容器在失败时会重新启动。

配置探针

探针有许多字段，您可以使用它们来更精确地控制启动、存活和就绪检查的行为

initialDelaySeconds：容器启动后启动、存活或就绪探针启动之前的秒数。如果定义了启动探针，则存活和就绪探针延迟不会在启动探针成功之前开始。如果periodSeconds的值大于initialDelaySeconds，则initialDelaySeconds将被忽略。默认为 0 秒。最小值为 0。
periodSeconds：执行探针的频率（以秒为单位）。默认为 10 秒。最小值为 1。
timeoutSeconds：探针超时之前的秒数。默认为 1 秒。最小值为 1。
successThreshold：探针被认为成功后，连续成功的最小次数。默认为 1。对于存活和启动探针，必须为 1。最小值为 1。
failureThreshold：探针连续失败failureThreshold次后，Kubernetes 认为整体检查失败：容器未就绪/健康/存活。对于启动或存活探针，如果至少failureThreshold次探针失败，Kubernetes 将容器视为不健康，并触发对该特定容器的重启。kubelet 会遵守该容器的terminationGracePeriodSeconds设置。对于失败的就绪探针，kubelet 会继续运行失败检查的容器，并继续运行更多探针；由于检查失败，kubelet 会将 Pod 上的Ready条件设置为false。
terminationGracePeriodSeconds：配置 kubelet 在触发失败容器的关闭与强制容器运行时停止该容器之间等待的宽限期。默认情况下，将继承 Pod 级别的terminationGracePeriodSeconds值（如果未指定，则为 30 秒），最小值为 1。有关详细信息，请参阅探针级terminationGracePeriodSeconds。

注意

就绪探针的错误实现可能会导致容器中的进程数量不断增加，如果任其发展，会导致资源饥饿。

HTTP 探针

HTTP 探针有可以在httpGet上设置的附加字段

host：要连接到的主机名，默认为 Pod IP。您可能希望在httpHeaders中设置“Host”而不是它。
scheme：用于连接到主机的方案（HTTP 或 HTTPS）。默认为“HTTP”。
path：要访问的 HTTP 服务器上的路径。默认为“/”。
httpHeaders：要在请求中设置的自定义标头。HTTP 允许重复标头。
port：要访问的容器上的端口的名称或编号。数字必须在 1 到 65535 的范围内。

对于 HTTP 探针，kubelet 会向指定的端口和路径发送 HTTP 请求以执行检查。kubelet 会将探针发送到 Pod 的 IP 地址，除非地址被httpGet中的可选host字段覆盖。如果scheme字段设置为HTTPS，kubelet 会发送 HTTPS 请求，跳过证书验证。在大多数情况下，您不希望设置host字段。以下是一个您需要设置它的场景。假设容器侦听 127.0.0.1 并且 Pod 的hostNetwork字段为 true。那么httpGet下的host应该设置为 127.0.0.1。如果您的 Pod 依赖于虚拟主机，这可能是更常见的情况，您不应该使用host，而应该在httpHeaders中设置Host标头。

对于 HTTP 探针，kubelet 会除了强制的Host标头之外，还发送两个请求标头

User-Agent：默认值为kube-probe/1.30，其中1.30是 kubelet 的版本。
Accept：默认值为*/*。

您可以通过为探针定义httpHeaders来覆盖默认标头。例如

livenessProbe:
  httpGet:
    httpHeaders:
      - name: Accept
        value: application/json

startupProbe:
  httpGet:
    httpHeaders:
      - name: User-Agent
        value: MyUserAgent

您还可以通过将它们定义为空值来删除这两个标头。

livenessProbe:
  httpGet:
    httpHeaders:
      - name: Accept
        value: ""

startupProbe:
  httpGet:
    httpHeaders:
      - name: User-Agent
        value: ""

注意

当 kubelet 使用 HTTP 探测 Pod 时，它只会遵循重定向，如果重定向
是到同一主机。如果 kubelet 在探测过程中收到 11 个或更多个重定向，则探针被认为成功，并且会创建一个相关的事件

Events:
  Type     Reason        Age                     From               Message
  ----     ------        ----                    ----               -------
  Normal   Scheduled     29m                     default-scheduler  Successfully assigned default/httpbin-7b8bc9cb85-bjzwn to daocloud
  Normal   Pulling       29m                     kubelet            Pulling image "docker.io/kennethreitz/httpbin"
  Normal   Pulled        24m                     kubelet            Successfully pulled image "docker.io/kennethreitz/httpbin" in 5m12.402735213s
  Normal   Created       24m                     kubelet            Created container httpbin
  Normal   Started       24m                     kubelet            Started container httpbin
 Warning  ProbeWarning  4m11s (x1197 over 24m)  kubelet            Readiness probe warning: Probe terminated redirects

如果 kubelet 收到一个主机名与请求不同的重定向，则探针的结果将被视为成功，kubelet 会创建一个事件来报告重定向失败。

TCP 探针

对于 TCP 探针，kubelet 会在节点而不是 Pod 中建立探针连接，这意味着您不能在host参数中使用服务名称，因为 kubelet 无法解析它。

探针级`terminationGracePeriodSeconds`

特性状态： Kubernetes v1.28 [稳定]

在 1.25 及更高版本中，用户可以在探针规范中指定探针级terminationGracePeriodSeconds。当同时设置 Pod 级和探针级terminationGracePeriodSeconds时，kubelet 将使用探针级的值。

设置terminationGracePeriodSeconds时，请注意以下事项

如果 Pod 上存在探针级terminationGracePeriodSeconds字段，kubelet 始终会遵守该字段。
如果您有已存在的 Pod，其中设置了terminationGracePeriodSeconds字段，并且您不再希望使用每个探针的终止宽限期，则必须删除这些已存在的 Pod。

例如

spec:
  terminationGracePeriodSeconds: 3600  # pod-level
  containers:
  - name: test
    image: ...

    ports:
    - name: liveness-port
      containerPort: 8080

    livenessProbe:
      httpGet:
        path: /healthz
        port: liveness-port
      failureThreshold: 1
      periodSeconds: 60
      # Override pod-level terminationGracePeriodSeconds #
      terminationGracePeriodSeconds: 60

无法为就绪探针设置探针级terminationGracePeriodSeconds。它将被 API 服务器拒绝。

下一步

详细了解容器探针。

您还可以阅读 API 参考，了解

Pod，特别是
- 容器(s)
- 探针(s)

上次修改时间：2024 年 4 月 13 日下午 7:27 PST：更新 configure-liveness-readiness-startup-probes.md (2a6ec81df0)

配置存活探针、就绪探针和启动探针

注意

注意

开始之前

定义存活命令

定义存活 HTTP 请求

定义 TCP 存活探测

定义 gRPC 存活探测

注意

使用命名端口

使用启动探针保护启动缓慢的容器

定义就绪探针

注意

注意

配置探针

注意

HTTP 探针

注意

TCP 探针

探针级terminationGracePeriodSeconds

下一步

反馈

探针级`terminationGracePeriodSeconds`