【K8S学习之探针】详细了解就绪探针 readinessProbe 和存活探针 livenessProbe 的配置

参考

• Pod健康检查 · Kubernetes 学习笔记
• Kubernetes 就绪探针（Readiness Probe） - 人艰不拆_zmc - 博客园
• Kubernetes存活探针（Liveness Probe） - 人艰不拆_zmc - 博客园

Pod健康检查

Pod的健康状态由两类探针来检查：LivenessProbe和ReadinessProbe。

简单描述流程

┌─────────────┐
│  Pod 启动中 │
└─────┬───────┘
      │ readinessProbe
      ▼
┌──────────────┐
│ Ready = True │ ←─→ 接收流量、被 sidecar 调用
└──────────────┘
      │ livenessProbe
      ▼
   健康失败 → 自动重启容器

restartPolicy 直观对比

• 配置在 Pod 中，.spec 下

默认 restartPolicy 对照表

通用配置参数

常用的参数为timeoutSeconds、periodSeconds、periodSeconds，即接口超时时间，重试频率，重试次数三个值。

• initialDelaySeconds：启动容器后首次进行健康检查的等待时间，单位为秒，默认值为0。
• timeoutSeconds:健康检查接口超时响应的时间，默认为1秒，最小值为1秒。
• periodSeconds：重试的频率，默认值为10秒，即10秒重试一次，最小值是1秒，建议可以设置为3-5秒。
• failureThreshold：失败重试的次数，默认值为3，最小值为1。
• successThreshold：最小探测成功次数，默认值为1，一般不设置。

除了以上的通用参数外，livenessProbe和readinessProbe参数基本一致。以下以readinessProbe为例说明探针的使用方式。

探测方式

三种探测方式总览

建议

1️⃣ HTTP 探测（适合 Web 服务）

readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 3
  periodSeconds: 10
---
livenessProbe:
  httpGet:
    path: /live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 15

• Kubernetes 的 HTTP 探针 (httpGet) 不支持设置鉴权（如 Header、Token、Basic Auth 等），它只能发起一个非常基础的 无认证的 GET 请求
  • 支持的基本认证方式（有限）,可以手动加上 Basic Auth 或静态 Token，例如：

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
    host: 127.0.0.1
    scheme: HTTP
    httpHeaders:        # ✅ 仅支持自定义 Header（有限的鉴权）
    # 虽然可以配置 httpHeaders，但它仅支持添加固定值的请求头，不支持动态 Token、OAuth、JWT 等复杂认证机制。
      - name: X-Custom
        value: some-value
---
# 支持的基本认证方式（有限）
# 可以手动加上 Basic Auth 或静态 Token，例如：
# ⚠️ 注意：Kubernetes 不会自动加密或刷新 Token，不适合需要动态鉴权的系统。
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
    scheme: HTTP
    httpHeaders:
      - name: Authorization
        value: "Bearer your-static-token"

• 更复杂鉴权怎么办？

• 如果你的健康检查接口需要：

  • JWT 验证
  • OAuth 令牌
  • mTLS
  • Cookie 会话

  你有两个常见替代方案：

# 🔁 方案 1：增加一个 无鉴权的 /healthz 路由
# 让健康检查接口跳过鉴权，例如:
# 这是最推荐的方案，被广泛使用。
if req.URL.Path == "/healthz" {
    return 200
}
---
# 🛠️ 方案 2：用 Exec 或 Sidecar 转发带 Token 的请求
# 写一个 shell 脚本用 curl 加 Token：
# 或在容器里运行一个 sidecar 服务专门处理健康探测转发。
exec:
  command:
    - /bin/sh
    - -c
    - curl -H "Authorization: Bearer $MY_TOKEN" http://localhost:8080/secure-health

2️⃣ TCP 探测（适合没有健康接口的服务）

livenessProbe:
  tcpSocket:
    port: 3306
  initialDelaySeconds: 10
  periodSeconds: 20

这个探针只会判断 TCP 端口是否能连通，不判断服务逻辑是否正常。

3️⃣ Exec 探测（适合非 HTTP 应用，如 CSI 插件）

readinessProbe:
  exec:
    command:
      - /bin/sh
      - -c
      - 'test -S /csi/csi.sock'
  initialDelaySeconds: 5
  periodSeconds: 10

这类适合自定义协议、gRPC、检查 Unix socket 文件等场景。

详解

1. 探针类型

1. livenessProbe(存活探针)

• 表明容器是否正在运行。
• 如果存活探测失败，则 kubelet 会杀死容器，并且容器将受到其 重启策略的影响。
• 如果容器不提供存活探针，则默认状态为 Success。

2. readinessProbe(就绪探针)

• 表明容器是否可以正常接受请求。
• 如果就绪探测失败，端点控制器将从与 Pod 匹配的所有 Service 的端点中删除该 Pod 的 IP 地址。
• 初始延迟之前的就绪状态默认为 Failure。
• 如果容器不提供就绪探针，则默认状态为 Success。

2. 探针使用场景

• 如果容器异常可以自动崩溃，则不一定要使用探针，可以由Pod的restartPolicy执行重启操作。
• 存活探针适用于希望容器探测失败后被杀死并重新启动，需要指定restartPolicy 为 Always 或 OnFailure。
• 就绪探针适用于希望Pod在不能正常接收流量的时候被剔除，并且在就绪探针探测成功后才接收流量。

探针是kubelet对容器执行定期的诊断，主要通过调用容器配置的四类Handler实现：

Handler的类型：

• ExecAction：在容器内执行指定命令。如果命令退出时返回码为 0 则认为诊断成功。
• TCPSocketAction：对指定端口上的容器的 IP 地址进行 TCP 检查。如果端口打开，则诊断被认为是成功的。
• HTTPGetAction：对指定的端口和路径上的容器的 IP 地址执行 HTTP Get 请求。如果响应的状态码大于等于200 且小于 400，则诊断被认为是成功的。
• GRPCAction：调用GRPC接口来判断服务是否健康。 如果响应的状态是 “SERVING”，则认为诊断成功。

探测结果为以下三种之一：

• 成功：容器通过了诊断。
• 失败：容器未通过诊断。
• 未知：诊断失败，因此不会采取任何行动。

3. 探针的配置

探针配置在pod的container结构体下，livenessProbe和readinessProbe参数基本一致。

3.1. 探针通用参数

常用的参数为timeoutSeconds、periodSeconds、periodSeconds，即接口超时时间，重试频率，重试次数三个值。

• initialDelaySeconds：启动容器后首次进行健康检查的等待时间，单位为秒，默认值为0。
• timeoutSeconds:健康检查接口超时响应的时间，默认为1秒，最小值为1秒。
• periodSeconds：重试的频率，默认值为10秒，即10秒重试一次，最小值是1秒，建议可以设置为3-5秒。
• failureThreshold：失败重试的次数，默认值为3，最小值为1。
• successThreshold：最小探测成功次数，默认值为1，一般不设置。

除了以上的通用参数外，livenessProbe和readinessProbe参数基本一致。以下以readinessProbe为例说明探针的使用方式。

3.2. ReadinessProbe三种实现方式

3.2.1. HTTPGetAction

通过容器的IP地址、端口号及路径调用HTTP Get方法，如果响应的状态码大于等于200且小于等于400，则认为容器健康。

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-healthcheck
spec:
  restartPolicy: Always  # ⭐ 容器探针依赖此项自动重启，默认也是 Always 或 OnFailure
  containers:
  - name: nginx
    image: nginx
    ports:
    - containnerPort: 80
    readinessProbe:
      httpGet:
        path: /_status/healthz
        port: 80
        scheme: HTTP
      initialDelaySeconds: 1
      periodSeconds: 5
      timeoutSeconds: 5

3.2.2. TCPSocketAction

通过容器IP地址和端口号执行TCP检查，如果能够建立TCP连接，则表明容器健康。

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-healthcheck
spec:
  containers:
  - name: nginx
    image: nginx
    ports:
    - containnerPort: 80
    readinessProbe:
      tcpSocket:
        port: 80
      initialDelaySeconds: 1
      timeoutSeconds: 5

3.2.3. ExecAction

在一个容器内部执行一个命令，如果该命令状态返回值为0，则表明容器健康。

apiVersion: v1
kind: Pod
metadata:
  name: readiness-exec
spec:
  containers:
  - name: readiness
    image: tomcagcr.io/google_containers/busybox
    args:
    - /bin/sh
    - -c
    - echo ok > /tmp/health;sleep 10;rm -fr /tmp/health;sleep 600
    readinessreadinessProbe:
      exec:
        command:
        - cat
        - /tmp/health
      initialDelaySeconds: 1
      timeoutSeconds: 5

4. 探针相关源码

探针配置在pod的container结构体下：

    // 存活探针
    LivenessProbe *Probe `json:"livenessProbe,omitempty" protobuf:"bytes,10,opt,name=livenessProbe"`
    // 就绪探针
    ReadinessProbe *Probe `json:"readinessProbe,omitempty" protobuf:"bytes,11,opt,name=readinessProbe"`

4.1. Probe源码

type Probe struct {
    // The action taken to determine the health of a container
    ProbeHandler `json:",inline" protobuf:"bytes,1,opt,name=handler"`
    // Number of seconds after the container has started before liveness probes are initiated.
    // More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
    // +optional
    InitialDelaySeconds int32 `json:"initialDelaySeconds,omitempty" protobuf:"varint,2,opt,name=initialDelaySeconds"`
    // Number of seconds after which the probe times out.
    // Defaults to 1 second. Minimum value is 1.
    // More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
    // +optional
    TimeoutSeconds int32 `json:"timeoutSeconds,omitempty" protobuf:"varint,3,opt,name=timeoutSeconds"`
    // How often (in seconds) to perform the probe.
    // Default to 10 seconds. Minimum value is 1.
    // +optional
    PeriodSeconds int32 `json:"periodSeconds,omitempty" protobuf:"varint,4,opt,name=periodSeconds"`
    // Minimum consecutive successes for the probe to be considered successful after having failed.
    // Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1.
    // +optional
    SuccessThreshold int32 `json:"successThreshold,omitempty" protobuf:"varint,5,opt,name=successThreshold"`
    // Minimum consecutive failures for the probe to be considered failed after having succeeded.
    // Defaults to 3. Minimum value is 1.
    // +optional
    FailureThreshold int32 `json:"failureThreshold,omitempty" protobuf:"varint,6,opt,name=failureThreshold"`
    // Optional duration in seconds the pod needs to terminate gracefully upon probe failure.
    // The grace period is the duration in seconds after the processes running in the pod are sent
    // a termination signal and the time when the processes are forcibly halted with a kill signal.
    // Set this value longer than the expected cleanup time for your process.
    // If this value is nil, the pod's terminationGracePeriodSeconds will be used. Otherwise, this
    // value overrides the value provided by the pod spec.
    // Value must be non-negative integer. The value zero indicates stop immediately via
    // the kill signal (no opportunity to shut down).
    // This is a beta field and requires enabling ProbeTerminationGracePeriod feature gate.
    // Minimum value is 1. spec.terminationGracePeriodSeconds is used if unset.
    // +optional
    TerminationGracePeriodSeconds *int64 `json:"terminationGracePeriodSeconds,omitempty" protobuf:"varint,7,opt,name=terminationGracePeriodSeconds"`
}

4.2. ProbeHandler源码

// ProbeHandler defines a specific action that should be taken in a probe.
// One and only one of the fields must be specified.
type ProbeHandler struct {
    // Exec specifies the action to take.
    // +optional
    Exec *ExecAction `json:"exec,omitempty" protobuf:"bytes,1,opt,name=exec"`
    // HTTPGet specifies the http request to perform.
    // +optional
    HTTPGet *HTTPGetAction `json:"httpGet,omitempty" protobuf:"bytes,2,opt,name=httpGet"`
    // TCPSocket specifies an action involving a TCP port.
    // +optional
    TCPSocket *TCPSocketAction `json:"tcpSocket,omitempty" protobuf:"bytes,3,opt,name=tcpSocket"`

    // GRPC specifies an action involving a GRPC port.
    // This is a beta field and requires enabling GRPCContainerProbe feature gate.
    // +featureGate=GRPCContainerProbe
    // +optional
    GRPC *GRPCAction `json:"grpc,omitempty" protobuf:"bytes,4,opt,name=grpc"`
}

4.3. ProbeAction

4.3.1. HTTPGetAction

// HTTPHeader describes a custom header to be used in HTTP probes
type HTTPHeader struct {
    // The header field name
    Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
    // The header field value
    Value string `json:"value" protobuf:"bytes,2,opt,name=value"`
}

// HTTPGetAction describes an action based on HTTP Get requests.
type HTTPGetAction struct {
    // Path to access on the HTTP server.
    // +optional
    Path string `json:"path,omitempty" protobuf:"bytes,1,opt,name=path"`
    // Name or number of the port to access on the container.
    // Number must be in the range 1 to 65534. 
    // Name must be an IANA_SVC_NAME.
    Port intstr.IntOrString `json:"port" protobuf:"bytes,2,opt,name=port"`
    // Host name to connect to, defaults to the pod IP. You probably want to set
    // "Host" in httpHeaders instead.
    // +optional
    Host string `json:"host,omitempty" protobuf:"bytes,3,opt,name=host"`
    // Scheme to use for connecting to the host.
    // Defaults to HTTP.
    // +optional
    Scheme URIScheme `json:"scheme,omitempty" protobuf:"bytes,4,opt,name=scheme,casttype=URIScheme"`
    // Custom headers to set in the request. HTTP allows repeated headers.
    // +optional
    HTTPHeaders []HTTPHeader `json:"httpHeaders,omitempty" protobuf:"bytes,5,rep,name=httpHeaders"`
}

// URIScheme identifies the scheme used for connection to a host for Get actions
// +enum
type URIScheme string

const (
    // URISchemeHTTP means that the scheme used will be http://
    URISchemeHTTP URIScheme = "HTTP"
    // URISchemeHTTPS means that the scheme used will be https://
    URISchemeHTTPS URIScheme = "HTTPS"
)

4.3.2. TCPSocketAction

// TCPSocketAction describes an action based on opening a socket
type TCPSocketAction struct {
    // Number or name of the port to access on the container.
    // Number must be in the range 1 to 65534. 
    // Name must be an IANA_SVC_NAME.
    Port intstr.IntOrString `json:"port" protobuf:"bytes,1,opt,name=port"`
    // Optional: Host name to connect to, defaults to the pod IP.
    // +optional
    Host string `json:"host,omitempty" protobuf:"bytes,2,opt,name=host"`
}

4.3.3. ExecAction

// ExecAction describes a "run in container" action.
type ExecAction struct {
    // Command is the command line to execute inside the container, the working directory for the
    // command  is root ('/') in the container's filesystem. The command is simply exec'd, it is
    // not run inside a shell, so traditional shell instructions ('|', etc) won't work. To use
    // a shell, you need to explicitly call out to that shell.
    // Exit status of 0 is treated as live/healthy and non-zero is unhealthy.
    // +optional
    Command []string `json:"command,omitempty" protobuf:"bytes,1,rep,name=command"`
}

4.3.4. GRPCAction

type GRPCAction struct {
    // Port number of the gRPC service. Number must be in the range 1 to 65534. 
    Port int32 `json:"port" protobuf:"bytes,1,opt,name=port"`

    // Service is the name of the service to place in the gRPC HealthCheckRequest
    // (see https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
    //
    // If this is not specified, the default behavior is defined by gRPC.
    // +optional
    // +default=""
    Service *string `json:"service" protobuf:"bytes,2,opt,name=service"`
}

参考文章：

• https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/
• 配置存活、就绪和启动探针 | Kubernetes
• https://mp.weixin.qq.com/s/ApD8D0_UAPftUjw-0Txcyw
• 《Kubernetes权威指南》