云原生 on 吾爱主机

Kubernetes 探针机制：Liveness / Readiness / Startup 原理与工程实践

Sun, 19 Jul 2026 00:00:00 +0800

上线后 Pod 进程还在、端口也开着，但线程死锁、缓存预热未完成、依赖库未就绪——这类“半死不活”状态，单靠进程退出码抓不住。Kubernetes 用 探针（Probe） 让 kubelet 周期性诊断容器，并据此决定：是否重启、是否继续接流量、是否允许启动阶段慢慢就绪。

本文基于 Kubernetes 官方概念文档 Liveness, Readiness, and Startup Probes、任务文档 Configure Liveness, Readiness and Startup Probes 与 Pod Lifecycle，把三类探针的职责边界、四种检查机制、默认参数、典型 YAML 与线上排错清单讲清楚，方便直接落地到业务 Deployment。

一、问题背景：进程存活 ≠ 服务可用

常见误区：

只看 Running：容器主进程没挂，业务已卡死在死锁或无限重试里。
把启动慢当成故障：JVM 冷启动、大配置加载、数据预热需要数分钟，却用过激 liveness 把容器反复杀掉，进入 CrashLoopBackOff。
就绪与存活混用：依赖短暂不可用时杀进程，反而放大级联故障。

官方定位很清晰：探针是 kubelet 对容器做的周期性诊断；根据结果，Kubernetes 可以重启不健康容器，或停止向未就绪容器发送流量。

二、三类探针：职责完全不同

探针	回答的问题	失败后果（概要）	生命周期
Startup	应用是否已经完成启动？	kubelet 杀死容器，按 Pod `restartPolicy` 处理	仅启动阶段；成功后不再执行
Liveness	容器是否仍活着、值得保留？	连续失败超过阈值后重启该容器	启动探针成功后（或无 startup 时）周期执行
Readiness	容器是否可以接流量？	从匹配 Service 的 EndpointSlice 中摘掉 Pod IP；不重启容器	整个生命周期周期执行

1. Startup：给慢启动留窗口

配置了 startupProbe 后，在它成功之前，不会执行 liveness / readiness，避免启动期误杀。

适合：首次初始化很慢、但稳态后希望 liveness 快速发现死锁的应用。官方建议：用与 liveness 相同的检查，但把 failureThreshold * periodSeconds 拉长到覆盖最坏启动时间。示例（30 × 10s = 300s）：

startupProbe:
 httpGet:
 path: /healthz
 port: 8080
 failureThreshold: 30
 periodSeconds: 10
livenessProbe:
 httpGet:
 path: /healthz
 port: 8080
 failureThreshold: 1
 periodSeconds: 10

启动探针一旦成功一次，liveness 接管；若 300s 内始终失败，容器被杀死并受 restartPolicy 约束。

2. Liveness：死锁与不可恢复故障的“硬重启”

典型用途：进程还在，但无法推进业务（死锁、事件循环卡死）。重启可能比挂着更可用。

官方提醒：liveness 必须表示不可恢复失败。配置过激会在高压时连环重启、请求失败、剩余 Pod 压力更大——级联故障。

若进程自己会在异常时崩溃退出，不一定需要 liveness；kubelet 会按 restartPolicy 处理退出。需要“探测失败就杀并重启”时，再配 liveness，且 restartPolicy 一般为 Always 或 OnFailure。

3. Readiness：接不接流量，而不是杀不杀进程

适用：加载大文件、预热缓存、建立连接、临时过载或依赖抖动——暂时不想接流量，但也不该被杀掉。

失败时，控制器从所有匹配 Service 的 EndpointSlice 中移除该 Pod IP，流量不再打到它。删除 Pod 做摘流时，EndpointSlice 条件也会更新，不一定非要 readiness 才能排空；readiness 更适合运行期的“维护摘流 / 依赖未就绪摘流”。

官方还提到一种模式：依赖后端时，liveness 只表示本进程健康，readiness 额外检查后端是否可用，避免把只能回错误的 Pod 继续挂在 Service 上。

三、四种检查机制

每个探针必须且只能配置一种机制：

机制	成功条件	适用场景
`exec`	容器内命令退出码 0	文件标志、本地 CLI 自检
`httpGet`	HTTP 状态码 ≥ 200 且 < 400	业务 `/healthz`、`/ready`
`tcpSocket`	端口可建立 TCP 连接（对端立刻关闭也算健康）	只关心端口是否监听
`grpc`	gRPC Health Checking 返回 `SERVING`	原生 gRPC 服务

要点：

HTTP：路径/端口/命名端口均可；v1.13 之后本地 HTTP 代理环境变量不影响 HTTP liveness。
TCP：端口通了就算成功，不验证应用协议是否正常。
gRPC：需实现官方 health 协议；探针打到 Pod IP/主机名；不支持认证参数；gRPC 不支持命名端口。
exec 开销：每次探测会创建/派生进程；高密度集群 + 短 periodSeconds 会抬高节点 CPU，优先考虑 HTTP/TCP/gRPC。

四、关键参数与默认值

字段	含义	默认（官方）	注意
`initialDelaySeconds`	容器启动后延迟多久开始探测	0	有 startup 时，liveness/readiness 的延迟从 startup 成功后再算
`periodSeconds`	探测间隔	10	最小 1；未 Ready 时 readiness 可能更密探测以尽快就绪
`timeoutSeconds`	单次超时	1	最小 1
`successThreshold`	失败后需连续成功几次才算恢复	1	liveness/startup 必须为 1
`failureThreshold`	连续失败几次判定整体失败	3	最小 1
`terminationGracePeriodSeconds`	探针触发关闭时的宽限期	继承 Pod 级（未设则 30s）	≥1.25 可在 liveness/startup 上覆盖；不能设在 readiness

失败后的行为差异：

startup / liveness：达到 failureThreshold → 视为不健康 → 重启该容器；kubelet 会尊重（探针级或 Pod 级）terminationGracePeriodSeconds。
readiness：失败 → 容器继续跑、探针继续做，但 Pod 的 Ready 条件为 false，从 Service 摘流。

未配置某类探针时，kubelet 对该类结果视为 Success；对 readiness，初始延迟结束前结果按 Failure 处理（避免过早接流）。

五、可落地的组合配置

apiVersion: v1
kind: Pod
metadata:
 name: probe-example
spec:
 terminationGracePeriodSeconds: 30
 containers:
 - name: app
 image: registry.k8s.io/e2e-test-images/agnhost:2.40
 ports:
 - name: http
 containerPort: 8080
 startupProbe:
 httpGet:
 path: /healthz
 port: http
 failureThreshold: 30
 periodSeconds: 10
 livenessProbe:
 httpGet:
 path: /healthz
 port: http
 periodSeconds: 10
 timeoutSeconds: 3
 failureThreshold: 3
 readinessProbe:
 httpGet:
 path: /ready
 port: http
 periodSeconds: 5
 failureThreshold: 3

工程约定建议：

/healthz（liveness）：只查本进程/关键本地资源，不要把下游超时算作“该死”。
/ready（readiness）：可查依赖、连接池、预热是否完成；失败只摘流。
慢启动：用 startupProbe 拉长启动窗口，而不是把 liveness 的 initialDelaySeconds 拉到数分钟还丢掉快速失败能力。
同路径不同阈值：官方常见模式是 readiness 与 liveness 可共用低成本 HTTP 端点，但 liveness 使用更高 failureThreshold，先摘流再硬杀。

官方 exec 示例可快速验证“失败 → 重启”链路：

kubectl apply -f https://k8s.io/examples/pods/probe/exec-liveness.yaml
kubectl describe pod liveness-exec
# 约 30s 后会出现 Liveness probe failed / Container ... will be restarted
kubectl get pod liveness-exec # RESTARTS 递增

HTTP / TCP / gRPC 示例清单同在官方 task 文档：

https://k8s.io/examples/pods/probe/http-liveness.yaml
https://k8s.io/examples/pods/probe/tcp-liveness-readiness.yaml
https://k8s.io/examples/pods/probe/grpc-liveness.yaml

六、常见坑与排查

现象	可能原因	处理思路
启动即 `CrashLoopBackOff`	liveness 在应用未就绪时过早失败	加 `startupProbe` 或合理 `initialDelaySeconds`
READY 长期 0/1	readiness 过严或依赖一直失败	`kubectl describe` 看 Unhealthy；区分依赖故障 vs 端点写错
高压时批量重启	liveness 把“忙/慢”当“死”	收紧 liveness 语义；用 readiness 摘流 + HPA/限流
节点 CPU 被探针打高	大量 `exec` + 短周期	改 HTTP/TCP/gRPC，增大 `periodSeconds`
探针失败但业务浏览器可访问	探针打容器网络命名空间路径/端口与外部不一致	确认 `port`/`host`、命名端口、监听 `0.0.0.0`
gRPC 探针总失败	未实现 health 协议或只监听 localhost	按官方 gRPC health 检查协议暴露，监听 Pod IP 可达地址
重启过猛、优雅退出不够	宽限期过短	Pod 级或 liveness 探针级 `terminationGracePeriodSeconds`（≥1.25）

排错命令：

kubectl describe pod <pod> # Events: Unhealthy / Killing
kubectl get pod <pod> -o wide
kubectl logs <pod> --previous # 被重启前的日志
kubectl get endpointslices -l kubernetes.io/service-name=<svc>

describe 中典型事件类似：Liveness probe failed: ...，随后 Container ... failed liveness probe, will be restarted。

七、选型速查

场景	推荐
进程自己会崩	可不配 liveness，依赖 `restartPolicy`
可能死锁但不退出	liveness（轻量、本地）
启动慢（分钟级）	startup + 稳态 liveness
预热/依赖未齐不想接流量	readiness
维护窗口主动摘流	readiness 独立端点返回失败
仅端口监听即可	`tcpSocket`（认知其浅）
标准 HTTP API	`httpGet` 200–399
gRPC 微服务	实现 health 协议 + `grpc` 探针

八、总结

Startup 管“能不能开始正经跑”，失败会杀容器；成功前挡住 liveness/readiness。
Liveness 管“还值不值得活着”，失败会重启——语义必须严格，防止级联重启。
Readiness 管“能不能接流量”，失败只摘 EndpointSlice，不重启。
机制选 httpGet / tcpSocket / grpc / exec 时，优先低开销网络探针；exec 要注意节点开销。
调参抓住：periodSeconds、failureThreshold、timeoutSeconds 与 startup 窗口 failureThreshold × periodSeconds。

把三类探针当成三个独立控制面来设计端点与阈值，比“抄一段 YAML 三个探针同路径同阈值”更接近生产稳态。

参考资料

Kubernetes 官方概念文档：Liveness, Readiness, and Startup Probes
Kubernetes 官方任务文档：Configure Liveness, Readiness and Startup Probes
Kubernetes 官方概念文档：Pod Lifecycle（Container probes）
Kubernetes API 参考：Probe / Container（Pod v1）
gRPC Health Checking 协议：grpc/grpc health-checking.md

Kubernetes 1.36.2 补丁升级实战：DRA、CSI 与控制面稳定性检查清单

Sat, 11 Jul 2026 09:03:43 +0800

Kubernetes 1.36.2 是 1.36 分支的补丁版本，官方 GitHub Release 发布于 2026-06-12。它不是一个“炫技型”的大版本，而是非常适合平台团队纳入日常升级窗口的稳定性修复版本：其中包含 Dynamic Resource Allocation（DRA）调度路径、CSI 卷重新发布、Endpoint Controller、Secret 环境变量处理以及 kubeadm 证书 dry-run 等多个容易在生产环境放大的边界问题。

本文基于 Kubernetes 官方 Release、1.36 分支 CHANGELOG 与官方版本支持说明整理，面向正在运行 1.36.x、准备从 1.35/1.34 规划升级，或正在试点 GPU、DPU、RDMA 等设备资源编排能力的团队，给出一份可执行的升级与验证清单。

为什么这个补丁版本值得关注

Kubernetes 补丁版本通常不会引入破坏性 API 变化，但它会修复控制面和节点侧的真实缺陷。1.36.2 的重点可以概括为三类：

调度正确性：DRA 相关修复覆盖设备分区、共享计数器、多 allocatable 设备以及 ResourceClaim allocationMode: All 等场景。对于使用新资源模型管理 GPU、加速卡或其他专用设备的集群，这类问题可能导致 Pod 错误分配、长时间 Pending，甚至设备冲突。
存储与节点稳定性：kubelet 在 CSI requiresRepublish=true 周期性 NodePublishVolume 失败时，曾可能删除挂载目录并让 Pod 继续看到陈旧卷内容。该类问题不一定马上表现为 CrashLoop，却可能带来数据一致性和排障难度。
控制面兼容性：Endpoint Controller 处理早期未更新过 ipFamilies 字段的 Service 时可能 panic；另外还修复了 Secret 二进制非 UTF-8 数据作为环境变量来源时的回归问题。

与此同时，官方发布说明显示 Kubernetes 1.36.2 构建使用 Go 1.26.4。对自建发行包、二次编译或维护私有镜像仓库的团队来说，这意味着需要同步确认构建链、制品校验与 SBOM 记录。

核心修复解读

1. DRA 调度：从“能调度”到“调度正确”

Dynamic Resource Allocation 是 Kubernetes 近几个版本持续增强的资源建模能力，用于表达比传统 CPU/Memory 更复杂的设备资源。1.36.2 中有多项 DRA 修复：

修复在 SharedCounters 与多 allocatable 设备组合下，调度器可能把互斥设备分区分配给多个 Pod 的问题。
修复同时使用多节点 claim 与 per-node claim 的 Pod 可能卡在 Pending 的问题。
修复 ResourceClaim 使用 allocationMode: All 且选择消耗 shared counters 的设备时，kube-scheduler 可能 panic 的问题。

如果你的集群还没有启用 DRA，这些修复可能暂时没有直接影响；但如果你在做 AI 训练、推理平台、边缘设备管理或高性能网络设备调度，建议把 1.36.2 视为 1.36 分支的最低生产基线之一。

2. CSI republish：不要忽略“陈旧卷内容”

CHANGELOG 提到，kubelet 在处理 CSIDriver.spec.requiresRepublish=true 的周期性 NodePublishVolume 调用时，如果 republish 返回错误，曾可能删除 CSI mount directory，导致 Pod 继续持有陈旧卷内容，后续成功 republish 也无法自动修复。

这类问题的危险之处在于：应用容器未必马上退出，监控也未必能通过简单的 Pod 状态发现异常。对依赖 CSI 动态刷新凭据、配置或挂载状态的系统来说，升级后应该重点观察：

kubectl get csidriver -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.requiresRepublish}{"\n"}{end}'
kubectl get events -A --field-selector involvedObject.kind=Pod | grep -i 'NodePublishVolume\|MountVolume'

如果存在 requiresRepublish=true 的驱动，建议在灰度节点上执行挂载异常注入或至少复盘历史 kubelet 日志，确认升级前是否出现过 republish 失败后应用读到旧数据的迹象。

3. Endpoint Controller 与旧 Service 兼容性

1.36.2 修复了 Endpoint Controller 在处理 ipFamilies 为空的 Service 时可能 panic 的问题。官方说明将其描述为 pre-dual-stack services that were never spec-updated，也就是双栈能力引入前创建、之后长期未触碰规格字段的老 Service。

这对老集群很重要：很多生产集群中存在“创建多年但业务仍在使用”的 Service。升级前可以先做一次巡检：

kubectl get svc -A -o json | jq -r '
 .items[] | select((.spec.ipFamilies // []) | length == 0) |
 [.metadata.namespace, .metadata.name, .spec.clusterIP] | @tsv'

如果发现命中项，先在测试环境复现或通过无害字段更新触发默认值补齐，再安排控制面升级，会比升级窗口里临时定位 controller panic 更稳妥。

4. Secret 二进制环境变量回归

官方 CHANGELOG 还提到修复了 1.34+ 中一个回归：容器环境变量值来自 Secret API 对象且包含 binary non-UTF8 data 时的处理问题。虽然“二进制 Secret 直接进环境变量”不是推荐实践，但历史系统、第三方 Chart 或迁移遗留配置中并不少见。

建议升级前用以下思路排查：

kubectl get deploy,statefulset,daemonset -A -o yaml | grep -n "secretKeyRef" -C 3

对命中的工作负载，优先确认 Secret 内容是否应改为文件挂载、是否存在非 UTF-8 值，以及应用侧是否真的需要以环境变量方式读取。升级补丁可以修复回归，但配置治理仍应同步推进。

升级前检查清单

确认版本与支持窗口

Kubernetes 官方 Releases 页面说明，项目维护最近三个 minor release 分支；当前页面描述为 1.36、1.35、1.34。Kubernetes 1.19 及之后版本大约提供 1 年补丁支持。因此，1.36.2 对 1.36 用户是常规补丁升级，对更老分支则应结合版本偏斜策略规划跨 minor 升级。

kubectl version --short
kubectl get nodes -o wide
kubectl get --raw /version

如果控制面、kubelet、kubectl 或外部组件版本跨度较大，先阅读官方 version skew policy，再决定是否直接升级到 1.36.x。

备份 etcd 与关键配置

补丁升级也要按生产变更对待，至少完成：

ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-$(date +%F-%H%M).db \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/kubernetes/pki/etcd/ca.crt \
 --cert=/etc/kubernetes/pki/etcd/server.crt \
 --key=/etc/kubernetes/pki/etcd/server.key

kubectl get all,cm,secret,ingress,pvc -A -o yaml > /backup/k8s-resources-$(date +%F).yaml

托管 Kubernetes 也应在云厂商控制台确认升级回滚策略、节点池灰度能力与控制面维护窗口。

先升级测试集群或单个节点池

推荐顺序：

在测试集群升级控制面到 1.36.2。
升级一组低风险节点池。
验证 DRA、CSI、Service、Job、Secret 相关用例。
扩大到生产控制面与生产节点池。

对 kubeadm 集群，还应关注 1.36.2 修复的 kubeadm init phase certs --dry-run 复制现有 CA 文件问题。如果你的自动化流程依赖 dry-run 生成或校验证书，应在升级后重新跑一遍流水线。

升级后验证清单

升级完成后，不要只看 kubectl get nodes。建议至少执行：

kubectl get componentstatuses 2>/dev/null || true
kubectl get --raw='/readyz?verbose'
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
kubectl get events -A --sort-by=.lastTimestamp | tail -n 80
kubectl -n kube-system logs -l component=kube-scheduler --tail=200

重点观察：

kube-scheduler 是否仍出现 DRA ResourceClaim 相关 panic 或调度失败。
CSI 插件与 kubelet 日志中是否还有 NodePublishVolume 反复失败。
老 Service 是否触发 Endpoint/EndpointSlice 控制器异常。
使用 Secret 环境变量的 Pod 是否能正常启动。
suspended Job 修改 nodeSelector、tolerations、node affinity 等 scheduling directives 是否符合预期。

实践建议

未使用 DRA 的普通集群：可以按常规补丁窗口升级，但仍需完成 etcd 备份、控制面健康检查与节点池灰度。
使用 DRA 或设备插件的集群：建议优先升级测试环境，并围绕 ResourceClaim、共享计数器、多 allocatable 设备构造回归用例。
CSI 驱动复杂的集群：重点确认 requiresRepublish=true 驱动，升级后观察挂载内容刷新是否正常。
历史包袱较重的老集群：先巡检空 ipFamilies Service、Secret 环境变量与长期未更新的 workload spec，避免把老问题带进升级窗口。

总结

Kubernetes 1.36.2 的价值不在于新功能数量，而在于把 1.36 分支中几个高风险边界问题向前修掉：DRA 调度正确性、CSI republish 行为、Endpoint Controller 兼容性、Secret 二进制数据回归以及 kubeadm dry-run 证书流程。对于平台团队来说，最稳妥的做法是把它纳入一次小而完整的补丁升级：先备份，再灰度，最后用针对性清单验证关键路径。

如果你的集群已经在 1.36.x，建议优先评估 1.36.2；如果仍在 1.35/1.34，则应结合官方版本支持与版本偏斜策略制定 minor 升级计划，而不是只追补丁号。

参考资料

Kubernetes GitHub Release：https://github.com/kubernetes/kubernetes/releases/tag/v1.36.2
Kubernetes 1.36 CHANGELOG：https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.36.md
Kubernetes 官方 Releases 与支持分支说明：https://kubernetes.io/releases/

etcd 3.7.0 正式发布：Kubernetes 控制面的升级、备份与兼容性检查清单

Thu, 09 Jul 2026 09:06:19 +0800

etcd 是 Kubernetes 控制面的关键依赖：API Server 的对象状态、Leader 选举、租约与 watch 通知，最终都要落到这个分布式键值存储上。2026 年 7 月 8 日，etcd 项目发布了 v3.7.0。它不是一个只改版本号的小更新：官方发布说明明确要求升级前阅读 v3.7 升级指南，CHANGELOG 中同时包含安全修复、依赖升级、v2 相关能力移除、clientv3 行为变化以及运维工具改动。

这篇文章基于 etcd 官方 Release、CHANGELOG、v3.7 升级文档，以及 Kubernetes 官方 etcd 运维文档整理成一份实践清单。它不是复制某一篇公告，而是面向真实生产环境回答三个问题：是否应该升级、升级前要检查什么、如果你运行的是 Kubernetes 集群该如何降低风险。

这次发布最值得关注的变化

1. 安全修复与依赖升级

v3.7.0 的正式版 CHANGELOG 提到两个服务端修复：当配置 --listen-client-http-urls 时，gRPC listener 上的 CRL enforcement bypass 问题得到修复；同时修复了带 bearer 前缀 token 的 websocket 认证问题。依赖层面，官方二进制使用 Go 1.26.5 编译，并将 golang.org/x/crypto 升级到 v0.52.0，以处理多项 CVE。

对运维团队来说，这意味着 v3.7.0 不应只被看成“新功能版本”。如果你的 etcd 暴露在严格证书校验、客户端证书吊销列表、或经过网关/WebSocket 访问的场景中，安全修复本身就值得排期评估。

2. v2 时代彻底退出

v3.7 升级文档说明，v2 store 已在 v3.7 中完全移除：--enable-v2、--experimental-enable-v2v3、v2 discovery service、client/v2 包以及 v2 snapshot 文件加载都不再存在。CHANGELOG 也把移除 v2 discovery、client/v2、v2 request/apply 等列为 v3.7.0-rc.0 的 breaking changes。

如果你的集群已经稳定运行在 3.6，并且历史上没有保留 v2 数据，这通常不是阻塞项；但如果某些遗留脚本仍依赖 v2 API，或者你还保留了旧版本快照恢复流程，就必须在升级前完成迁移与演练。

3. clientv3 创建连接不再阻塞

CHANGELOG 写明：clientv3 创建 etcd client 变为 non-blocking，etcd 不再遵循已废弃的 grpc.WithBlock dial option。过去一些程序会假设 clientv3.New(...) 返回成功就代表连接已建立；升级依赖后，这类程序需要改为显式执行健康检查、超时控制或首次请求重试。

一个更稳妥的模式是：创建 client 后立即用带超时的上下文调用 Status 或 EndpointHealth，把“创建对象成功”和“后端可达”拆开处理。

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
_, err := cli.Status(ctx, "https://127.0.0.1:2379")
if err != nil {
 return fmt.Errorf("etcd endpoint not ready: %w", err)
}

4. 命令行工具与可观测性变化

v3.7 系列整理了 etcdctl 命令，使帮助输出更简洁；etcdutl 为所有命令增加 timeout flag，用于等待数据库文件锁时避免无限等待。监控方面，CHANGELOG 提到新增 etcd_server_request_duration_seconds，以及多项 watch send loop 相关指标。对于依赖 Prometheus 告警的集群，升级后应同步检查 dashboard 和 recording rules，避免因为指标新增、命名差异或告警阈值不适配导致误报或漏报。

生产升级前的硬性检查

官方 v3.7 升级文档给出了两个基础前提：运行中的集群必须已经是 v3.6.11 或更高版本；etcd 只支持一次升级一个 minor 版本。如果你还在 3.5 或更早版本，应先升级到 3.6，再从 3.6 升级到 3.7。

升级前建议执行以下检查：

# 1. 检查所有成员版本与健康状态
ETCDCTL_API=3 etcdctl \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/kubernetes/pki/etcd/ca.crt \
 --cert=/etc/kubernetes/pki/etcd/server.crt \
 --key=/etc/kubernetes/pki/etcd/server.key \
 endpoint status --cluster -w table

ETCDCTL_API=3 etcdctl \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/kubernetes/pki/etcd/ca.crt \
 --cert=/etc/kubernetes/pki/etcd/server.crt \
 --key=/etc/kubernetes/pki/etcd/server.key \
 endpoint health --cluster

# 2. 创建快照，保留到升级窗口结束后
ETCDCTL_API=3 etcdctl \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/kubernetes/pki/etcd/ca.crt \
 --cert=/etc/kubernetes/pki/etcd/server.crt \
 --key=/etc/kubernetes/pki/etcd/server.key \
 snapshot save /backup/etcd-$(date +%F-%H%M).db

# 3. 校验快照状态
etcdutl snapshot status /backup/etcd-YYYY-MM-DD-HHMM.db -w table

Kubernetes 官方文档也强调了 etcdctl 与 etcdutl 的分工：etcdctl 主要用于通过网络管理集群、键值和健康状态；etcdutl 更偏向直接操作数据文件，例如快照恢复、碎片整理、迁移与一致性验证。不要把两者混用成一个“万能命令”。

日常维护也要一起复盘

升级窗口是复盘 etcd 维护策略的好时机。官方维护文档指出，etcd 需要周期性维护以保持可靠性；如果 keyspace 历史没有及时压缩，后端数据库没有碎片整理，空间配额触发后集群会进入只接受读取和删除的受限维护模式。

建议把下面三件事纳入升级后的运维基线：

# 自动压缩：保留最近 1 小时历史（示例，需按业务 watch/回放需求调整）
etcd --auto-compaction-mode=periodic --auto-compaction-retention=1h

# 手动压缩到某个 revision 后，再对成员做 defrag
ETCDCTL_API=3 etcdctl compact <revision>
ETCDCTL_API=3 etcdctl defrag --cluster

# 关注 DB Size、leader 切换、请求延迟、watch 延迟等指标
# 结合新增的 etcd_server_request_duration_seconds 更新 Prometheus 告警

升级风险清单

遗留 v2 依赖：检查脚本、SDK、旧控制器和快照恢复流程，不要等升级后才发现 client/v2 或 v2 snapshot 不可用。
客户端连接假设：如果业务代码使用 clientv3，确认是否依赖 grpc.WithBlock 带来的阻塞语义。
快照不可恢复：只保存快照不够，至少要在隔离环境验证一次恢复流程。
混合版本时间过长：滚动升级可以混合版本运行，但不应长期停留在混合状态。
Kubernetes 兼容性：控制面组件、发行版、kubeadm 与 etcd 版本必须一起评估。

总结

etcd 3.7.0 的关键词是“安全修复、v2 清理、客户端语义调整、运维工具增强”。对于新集群，它让技术债更少；对于老集群，它会暴露历史遗留依赖。真正稳妥的升级不是简单替换二进制，而是先确认版本链路、备份可恢复、客户端行为可接受、监控和维护策略同步更新。只要把这些检查前置，v3.6 到 v3.7 的滚动升级可以成为一次相对可控的控制面基础设施升级。

参考资料

etcd 官方 Release：https://github.com/etcd-io/etcd/releases/tag/v3.7.0
etcd 官方 CHANGELOG 3.7：https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.7.md
etcd 官方 v3.7 升级指南：https://etcd.io/docs/v3.7/upgrades/upgrade_3_7/
etcd 官方维护文档：https://etcd.io/docs/v3.7/op-guide/maintenance/
Kubernetes 官方 etcd 管理文档：https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/

Headlamp Cluster API 插件发布：把多集群生命周期管理搬进 Kubernetes UI

Tue, 07 Jul 2026 09:06:20 +0800

6 月下旬 Kubernetes 官方博客介绍了 Headlamp Cluster API 插件：它把 Cluster API（CAPI）的集群、机器、控制平面和拓扑关系搬到 Headlamp 的图形界面里。对平台工程团队来说，这不是“再做一个 Kubernetes Dashboard”，而是把原本需要在多个 kubectl 命令、YAML、OwnerReference 和 Condition 之间来回切换的多集群排障流程，整理成更接近日常运维视角的可视化工作台。

本文基于 Kubernetes 官方博客、Cluster API 官方文档、Headlamp 插件文档以及插件仓库 README 做多源核验，整理它解决的问题、核心能力、落地前的检查项，以及团队应该如何把它纳入现有的多集群运维流程。

背景：Cluster API 强在声明式，弱在人工排障体验

Cluster API 是 Kubernetes SIG Cluster Lifecycle 下的项目，目标是用 Kubernetes 风格的 API 和控制器来管理 Kubernetes 集群生命周期。简单说，平台团队可以把“创建集群、升级控制面、扩缩容节点、替换机器模板”等动作表达成 Kubernetes 资源，让管理集群里的控制器去持续调谐。

典型资源包括：

Cluster：描述一个工作负载集群；
Machine、MachineSet、MachineDeployment：描述节点及其副本关系；
KubeadmControlPlane：描述基于 kubeadm 的控制平面；
KubeadmConfig：描述节点初始化或加入集群的 bootstrap 配置；
各云厂商或虚拟化平台的 Infrastructure Provider 资源。

这种模式的优点是自动化和可复现，但真实排障时仍然会遇到几个痛点：

关系链长：一个集群问题可能同时涉及 Cluster、ControlPlane、MachineDeployment、MachineSet、Machine、BootstrapConfig、InfrastructureMachine 等资源。
状态分散：健康度通常藏在 status.conditions、副本数字、事件、Provider 资源状态中。
命令切换频繁：排查时经常要反复执行 kubectl get、kubectl describe、kubectl get -o yaml，再靠人工拼 OwnerReference。
新成员学习成本高：不了解 CAPI 资源层级的人，很难快速判断“是控制面问题、节点问题、模板问题，还是 Provider 问题”。

Headlamp Cluster API 插件瞄准的正是这个体验层缺口。

这次插件带来了什么

根据 Kubernetes 官方博客和插件 README，这个插件会在 Headlamp 中新增一个专门的 Cluster API 区域，并围绕 CAPI 资源提供列表页、详情页、仪表盘和关系图。

1. 集群总览与健康仪表盘

插件提供集中化的 Cluster API Dashboard，用于汇总：

Cluster、Machine、MachineDeployment、MachinePool、MachineSet、ControlPlane 的状态；
控制面与工作节点副本数；
Provider、配置模板、资源健康情况；
当前存在的 Condition 异常与修复提示。

对平台团队来说，仪表盘的价值不是取代告警系统，而是把“告警之后进入问题现场”的第一屏做得更清楚。过去你可能需要先列出所有资源，再逐层查看；现在可以先从 Dashboard 判断故障落在哪个层级。

2. Machine 体系的可视化

插件为 MachineDeployment、MachineSet、Machine 和 MachinePool 提供专门视图，展示副本、版本、Owner 关系、Provider ID、Condition 等信息。

这对节点扩缩容和滚动升级尤其有用。例如：

kubectl get machinedeployments.cluster.x-k8s.io -A
kubectl get machines.cluster.x-k8s.io -A
kubectl describe machine <machine-name> -n <namespace>

这些命令仍然是自动化和深度排障的基础，但图形界面能更快暴露：哪个 MachineDeployment 没有达到期望副本数，哪些 Machine 没 Ready，资源之间的归属关系是否符合预期。

3. 直接从 UI 扩缩容

官方博客提到，插件支持对 MachineDeployments 和 MachineSets 执行 Scale 操作。也就是说，日常节点池扩缩容可以在 Headlamp 中完成，而不必每次手写 kubectl scale 或修改 YAML。

但这里要注意两点：

如果集群是 ClusterClass / topology 管理的，扩缩容入口可能应当在更高层级，而不是直接改底层 MachineSet；
UI 操作必须受 RBAC 控制，生产环境应限制谁能调整节点池规模。

建议团队把 UI 操作视为“人工运维入口”，而不是绕过 GitOps 的捷径。如果集群资源已经由 GitOps 管理，仍应优先从 Git 仓库修改声明式配置，Headlamp 用于观察和紧急诊断。

4. KubeadmConfig 结构化查看

在 CAPI 排障中，bootstrap 配置经常决定节点能不能正确加入集群。插件提供了对 KubeadmConfig 的结构化视图，可以查看文件、kubelet 参数、join/init 设置等内容。

这比直接阅读大段 YAML 更适合快速排查：

kubelet 参数是否和集群版本匹配；
bootstrap 文件是否缺失；
join 配置是否指向正确控制面；
是否存在模板更新但 Machine 未滚动的情况。

不过，结构化 UI 只能提升阅读效率，不能代替对敏感字段的权限治理。涉及 kubeconfig、证书、Token 的资源仍要按最小权限原则配置访问范围。

5. Map View：把 OwnerReference 变成关系图

CAPI 的核心难点之一是资源关系。Headlamp 的 Map View 可以显示 Cluster、ControlPlane、Worker 等资源之间的关系，让平台工程师不必手工追踪 OwnerReference。

在以下场景中，关系图特别有价值：

新集群创建卡住，需要定位卡在基础设施、控制面还是工作节点；
节点池升级后副本数异常，需要确认 MachineDeployment → MachineSet → Machine 的链路；
Provider 资源健康但 CAPI 资源未 Ready，需要确认引用关系是否断裂；
新成员学习 CAPI 架构，需要直观看到对象层级。

落地前的检查清单

如果你已经在用 Cluster API，可以按下面顺序评估是否引入该插件。

1. 确认 CAPI CRD 存在

kubectl get crd | grep cluster.x-k8s.io
kubectl get clusters.cluster.x-k8s.io -A
kubectl get machines.cluster.x-k8s.io -A

如果这些资源不存在，说明当前集群并不是 CAPI 管理集群，安装插件也看不到核心数据。

2. 确认 Headlamp 部署方式

Headlamp 可以以桌面应用、集群内服务或其他方式运行。对于生产环境，建议优先明确：

访问入口是否经过认证；
是否使用 OIDC 或企业身份系统；
ServiceAccount 是否按角色区分；
是否允许跨命名空间查看 CAPI 资源。

Headlamp 插件机制允许扩展侧边栏、资源详情页、仪表盘和业务逻辑，因此插件能力越强，越需要认真审计安装来源与权限边界。

3. 按 RBAC 分层授权

不要把所有 Headlamp 用户都绑定成 cluster-admin。可以按角色拆分：

角色	建议权限
观察者	只读查看 Cluster、Machine、Condition、事件
平台运维	可扩缩容 MachineDeployment / MachineSet
平台管理员	可安装插件、调整 Provider、执行升级相关动作

只读用户可以先验证 UI 的可观察性价值；有写权限的操作应纳入审计。

4. 与 GitOps 流程约定边界

如果 CAPI 资源由 Argo CD、Flux 或内部平台生成，UI 修改可能被下一次 GitOps 同步覆盖。建议明确三条规则：

常规变更走 Git；
UI 只用于观察、诊断和经过授权的紧急操作；
紧急操作后必须回写 Git，避免实际状态和声明状态长期漂移。

一个实用排障流程示例

假设某个工作负载集群扩容后节点迟迟未 Ready，可以这样组合使用 UI 与 CLI。

先在 Headlamp 的 Cluster API Dashboard 查看该 Cluster 是否有异常 Condition，确认问题集中在 worker 侧还是 control plane 侧。接着打开 MachineDeployment，检查期望副本与当前副本是否一致，再进入相关 MachineSet 和 Machine 页面查看具体状态。

如果 UI 显示某台 Machine 卡在 bootstrap 或 infrastructure 阶段，再回到 CLI 做深挖：

kubectl describe machine <machine-name> -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp
kubectl get kubeadmconfig -n <namespace> -o yaml
kubectl get <provider-machine-resource> -n <namespace> -o yaml

这样做的好处是：先用 UI 缩小范围，再用 CLI 获取完整细节。排障路径会比一开始就从所有 YAML 中搜索更短。

对平台工程团队的影响

这类插件的意义不只是“好看”。它反映了 Kubernetes 平台工程的一个趋势：底层仍然保持声明式 API 和控制器模式，上层则需要更贴近人类操作习惯的可视化、关系图和上下文导航。

对团队来说，可以预期三类收益：

降低 CAPI 学习成本：新成员更容易理解 Cluster、Machine、ControlPlane 的关系；
缩短人工排障路径：状态聚合和 Map View 能减少重复命令；
提升操作一致性：常见动作如扩缩容被封装在界面中，减少手写 YAML 出错。

同时，也要警惕两类风险：

权限放大：可视化工具一旦具备写操作，就必须严控 RBAC；
流程分叉：UI 操作和 GitOps 声明式配置可能产生漂移，需要制度约束。

总结

Headlamp Cluster API 插件把 CAPI 的资源层级、健康状态、扩缩容动作和拓扑关系集中到 Kubernetes UI 中，适合已经使用 Cluster API 的平台团队试用。它不会替代 kubectl、GitOps 或告警系统，但能成为告警之后的第一诊断入口，让多集群生命周期管理从“读 YAML 拼关系”逐步走向“看状态、看关系、再深入验证”。

如果你的团队正在推进 CAPI、多云集群或自助式集群交付，建议先在测试环境启用该插件，以只读方式验证 Dashboard、资源详情页和 Map View 的价值，再逐步开放扩缩容等写操作。

参考资料

Kubernetes 官方博客：Introducing the Cluster API plugin for Headlamp（2026-06-25） https://kubernetes.io/blog/2026/06/25/headlamp-cluster-api-plugin/
Cluster API 官方文档：Introduction https://cluster-api.sigs.k8s.io/introduction
Headlamp 官方文档：Plugins https://headlamp.dev/docs/latest/development/plugins/
Headlamp 插件仓库：Cluster API Plugin README https://github.com/headlamp-k8s/plugins/blob/main/cluster-api/README.md

K3s 轻量级 Kubernetes 实战：安装、配置与生产部署

Thu, 25 Jun 2026 17:00:00 +0000

前言

K3s 是 Rancher（现为 SUSE 旗下）开源的轻量级 Kubernetes 发行版。它将 K8s 打包为一个不到 100MB 的二进制文件，资源占用极低，专为边缘计算、IoT、CI/CD 和资源受限环境设计。K3s 完全兼容标准 K8s API，是学习和部署 K8s 的绝佳选择。当前最新版本为 v1.36.2+k3s1（2026 年 6 月），内置 Kubernetes v1.36.2、Traefik v3.7.4、containerd v2.3.2。

1. K3s vs K8s 对比

对比项	K8s (kubeadm)	K3s
二进制大小	~1GB+	< 100MB
最低内存	2GB+	512MB
最低 CPU	2 核	1 核
默认存储	etcd	SQLite（可选 etcd/MySQL/PostgreSQL）
网络插件	Calico/Flannel 等	Flannel（内置）
Ingress	需单独安装	Traefik（内置）
安装时间	10-30 分钟	< 5 分钟
组件数量	多个独立组件	单一二进制
适用场景	大规模生产	边缘/IoT/轻量/学习
API 兼容性	100%	100% 完全兼容

2. 安装 K3s

2.1 Server 节点安装

# 最简安装（国内加速）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

# 使用阿里云镜像
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 INSTALL_K3S_MIRROR=cn \
 K3S_TOKEN=mytoken \
 INSTALL_K3S_EXEC="--docker" \
 sh -

# 指定版本安装
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 INSTALL_K3S_MIRROR=cn \
 INSTALL_K3S_VERSION=v1.28.4+k3s2 \
 sh -

# 使用外部数据库（高可用）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 K3S_DATASTORE_ENDPOINT="mysql://user:pass@tcp(mysql-host:3306)/k3s" \
 sh -

2.2 Agent 节点加入

# 获取 Server 节点的 token
cat /var/lib/rancher/k3s/server/node-token

# Agent 节点安装
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 K3S_URL=https://server-ip:6443 \
 K3S_TOKEN=<node-token> \
 INSTALL_K3S_MIRROR=cn \
 sh -

2.3 验证安装

# 查看节点状态
kubectl get nodes

# 查看所有 Pod
kubectl get pods -A

# 查看 K3s 版本
k3s --version

# 查看 K3s 服务状态
systemctl status k3s
systemctl status k3s-agent

2.4 配置 kubectl

# Server 节点的 kubeconfig
cat /etc/rancher/k3s/k3s.yaml

# 复制到本地
mkdir -p ~/.kube
scp root@server-ip:/etc/rancher/k3s/k3s.yaml ~/.kube/config
chmod 600 ~/.kube/config

# 修改 server 地址（把 127.0.0.1 改为实际 IP）
sed -i 's/127.0.0.1/server-ip/g' ~/.kube/config

# 验证
kubectl get nodes

3. 安装选项

3.1 Server 安装参数

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 INSTALL_K3S_MIRROR=cn \
 INSTALL_K3S_EXEC="server" \
 sh -s - \
 --write-kubeconfig-mode 644 \  # kubeconfig 文件权限
 --disable traefik \  # 禁用内置 Traefik
 --disable servicelb \  # 禁用内置 ServiceLB
 --datastore-endpoint "..." \  # 外部数据库
 --tls-san "my-k3s.example.com" \  # 额外的 TLS SAN
 --node-label "env=production" \  # 节点标签
 --node-taint "key=value:NoSchedule" \ # 节点污点
 --docker # 使用 Docker 而非 containerd

3.2 常用环境变量

# 安装脚本环境变量
INSTALL_K3S_MIRROR=cn # 使用国内镜像
INSTALL_K3S_VERSION=v1.28.4+k3s2 # 指定版本
INSTALL_K3S_EXEC="server" # server 或 agent
K3S_TOKEN=mytoken # 集群 token
K3S_URL=https://server:6443 # Agent 连接 Server 的地址
INSTALL_K3S_SKIP_START=true # 只安装不启动
INSTALL_K3S_SKIP_DOWNLOAD=true # 使用本地二进制

# K3s 运行时环境变量
K3S_KUBECONFIG_MODE=644
K3S_TOKEN=mytoken
K3S_DATASTORE_ENDPOINT=mysql://...

4. 卸载与重装

# 卸载 Server
/usr/local/bin/k3s-uninstall.sh

# 卸载 Agent
/usr/local/bin/k3s-agent-uninstall.sh

# 清理残留
rm -rf /etc/rancher/k3s
rm -rf /var/lib/rancher/k3s
rm -rf /var/lib/rancher/k3s/server/manifests

5. 高可用部署

5.1 架构方案

┌──────────────────────────────────────────┐
│ Load Balancer │
│ (nginx/haproxy/cloud LB) │
└────────┬────────────┬────────────┬───────┘
 │ │ │
 ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
 │ Server 1│ │ Server 2│ │ Server 3│
 │ (etcd) │ │ (etcd) │ │ (etcd) │
 └─────────┘ └─────────┘ └─────────┘
 │ │ │
 ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
 │ Agent 1 │ │ Agent 2 │ │ Agent 3 │
 └─────────┘ └─────────┘ └─────────┘

5.2 使用嵌入式 etcd（推荐）

# 第一个 Server 节点（初始化集群）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 INSTALL_K3S_MIRROR=cn \
 INSTALL_K3S_EXEC="server --cluster-init" \
 sh -

# 后续 Server 节点（加入集群）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 K3S_TOKEN=<token> \
 INSTALL_K3S_MIRROR=cn \
 INSTALL_K3S_EXEC="server --server https://first-server-ip:6443" \
 sh -

# 查看 etcd 状态
k3s etcd-snapshot list

5.3 使用外部数据库

# 使用 MySQL
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 K3S_DATASTORE_ENDPOINT="mysql://k3s:password@tcp(mysql-host:3306)/k3s" \
 sh -

# 使用 PostgreSQL
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 K3S_DATASTORE_ENDPOINT="postgres://k3s:password@postgres-host:5432/k3s?sslmode=disable" \
 sh -

6. 网络配置

6.1 Flannel 配置

# 查看 Flannel 网络
ip addr show flannel.1

# 自定义 Pod CIDR
k3s server --cluster-cidr=10.42.0.0/16 --service-cidr=10.43.0.0/16

# 使用其他后端（vxlan/host-gw/wireguard）
k3s server --flannel-backend=host-gw

6.2 替换 Flannel 为 Calico

# 安装时禁用 Flannel
k3s server --flannel-backend=none --disable-network-policy

# 安装 Calico
kubectl apply -f https://projectcalico.docs.tigera.io/manifests/calico.yaml

6.3 ServiceLB（内置负载均衡）

# K3s 内置 ServiceLB（原 klipper-lb）
# 创建 LoadBalancer 类型的 Service 会自动分配 IP

# 查看 ServiceLB 状态
kubectl get pods -n kube-system | grep svclb

# 禁用 ServiceLB（使用 MetalLB 等替代）
k3s server --disable servicelb

7. 存储配置

7.1 本地路径存储（默认）

# K3s 默认提供 local-path StorageClass
kubectl get storageclass

# 使用默认 StorageClass
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: my-pvc
spec:
 accessModes:
 - ReadWriteOnce
 storageClassName: local-path
 resources:
 requests:
 storage: 1Gi

# 自定义本地路径
k3s server --default-local-storage-path=/data/k3s-storage

7.2 NFS 存储

# 安装 NFS CSI Driver
helm repo add csi-driver-nfs https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/charts
helm install csi-driver-nfs csi-driver-nfs/csi-driver-nfs --namespace kube-system

# 创建 StorageClass
cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: nfs-csi
provisioner: nfs.csi.k8s.io
parameters:
 server: nfs-server-ip
 share: /exported/path
reclaimPolicy: Retain
volumeBindingMode: Immediate
EOF

8. Ingress 配置

8.1 Traefik（内置）

# K3s 默认安装 Traefik 作为 Ingress Controller
kubectl get pods -n kube-system | grep traefik

# 查看 Traefik IngressClass
kubectl get ingressclass

# 使用 Traefik Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: myapp-ingress
 annotations:
 traefik.ingress.kubernetes.io/router.entrypoints: web
spec:
 rules:
 - host: app.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: myapp-svc
 port:
 number: 80

8.2 禁用 Traefik，使用 Nginx Ingress

# 安装时禁用 Traefik
k3s server --disable traefik

# 安装 Nginx Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.0/deploy/static/provider/baremetal/deploy.yaml

9. Helm 集成

# 安装 Helm（K3s 已内置 HelmChart CRD）
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 使用 HelmChart 自定义资源部署
cat <<EOF | kubectl apply -f -
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
 name: prometheus
 namespace: kube-system
spec:
 chart: prometheus
 repo: https://prometheus-community.github.io/helm-charts
 set:
 server.global.scrape_interval: 15s
EOF

10. 日常运维命令

# 查看集群状态
kubectl get nodes -o wide
kubectl get pods -A
kubectl top nodes
kubectl top pods -A

# K3s 特有命令
k3s --help
k3s check-config # 检查系统配置
k3s certificate # 管理证书
k3s etcd-snapshot save # 备份 etcd
k3s etcd-snapshot restore # 恢复 etcd

# 查看 K3s 日志
journalctl -u k3s -f
journalctl -u k3s-agent -f

# 重启 K3s
systemctl restart k3s # Server 节点
systemctl restart k3s-agent # Agent 节点

# 更新 K3s
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
 INSTALL_K3S_MIRROR=cn \
 INSTALL_K3S_VERSION=v1.29.0+k3s1 \
 sh -

11. 与 K8s 的差异点

差异	K3s	K8s
默认容器运行时	containerd	containerd
默认 CNI	Flannel	无（需手动安装）
默认 Ingress	Traefik	无（需手动安装）
默认存储	local-path	无（需手动配置）
默认 LB	ServiceLB	无（需 MetalLB 等）
etcd 备份	k3s etcd-snapshot	etcdctl snapshot
配置文件	/etc/rancher/k3s/config.yaml	各组件独立配置

12. 适用场景

场景	推荐度	说明
本地学习 K8s	⭐⭐⭐⭐⭐	安装简单，资源占用低
边缘计算	⭐⭐⭐⭐⭐	专为边缘设计
IoT 设备管理	⭐⭐⭐⭐⭐	ARM 支持好
CI/CD 环境	⭐⭐⭐⭐	快速创建销毁
小型生产环境	⭐⭐⭐⭐	足够稳定
大规模生产	⭐⭐⭐	建议用完整 K8s 或托管服务
桌面开发	⭐⭐⭐⭐⭐	Docker Desktop K8s 的替代

总结

K3s 核心优势：

轻量 — 单一二进制，< 100MB，512MB 内存即可运行
简单 — 一条命令安装，< 5 分钟上手
完整 — 100% 兼容 K8s API，内置 Traefik/Flannel/ServiceLB
安全 — 自动轮换证书，CIS 加固
多数据库 — 支持 SQLite/etcd/MySQL/PostgreSQL
ARM 支持 — 原生支持 ARM64，适合树莓派等设备

如果你是 K8s 新手，或者需要在边缘设备、小型服务器上运行 K8s，K3s 是最佳选择。

Kubernetes (K8s) 完全指南：架构、核心概念与实战命令

Thu, 25 Jun 2026 16:30:00 +0000

前言

Kubernetes（简称 K8s）是 Google 开源的容器编排平台，已成为云原生领域的事实标准。当前最新版本为 v1.36（2026 年发布）。它能自动化容器化应用的部署、扩缩容和管理。无论是微服务架构、CI/CD 流水线，还是混合云部署，K8s 都是核心基础设施。

1. 架构概述

1.1 整体架构

┌─────────────────────────────────────────────────────┐
│ Control Plane │
│ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │
│ │ API │ │Scheduler │ │Controller│ │ etcd │ │
│ │ Server │ │ │ │ Manager │ │ │ │
│ └──────────┘ └──────────┘ └────────┘ └──────────┘ │
└─────────────────────────────────────────────────────┘
 │
 ┌───────────┼───────────┐
 ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Worker 1 │ │ Worker 2 │ │ Worker 3 │
│ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │
│ │ kubelet │ │ │ │ kubelet │ │ │ │ kubelet │ │
│ ├──────────┤ │ │ ├──────────┤ │ │ ├──────────┤ │
│ │kube-proxy│ │ │ │kube-proxy│ │ │ │kube-proxy│ │
│ ├──────────┤ │ │ ├──────────┤ │ │ ├──────────┤ │
│ │Container │ │ │ │Container │ │ │ │Container │ │
│ │ Runtime │ │ │ │ Runtime │ │ │ │ Runtime │ │
│ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │
└──────────────┘ └──────────────┘ └──────────────┘

1.2 Control Plane 组件

组件	作用
API Server	集群的统一入口，所有操作通过 REST API 进行
etcd	分布式键值存储，保存集群的所有状态数据
Scheduler	监听未调度的 Pod，根据资源/亲和性等分配到合适的节点
Controller Manager	运行各种控制器（Deployment、ReplicaSet、Node 等），确保实际状态与期望状态一致

1.3 Worker Node 组件

组件	作用
kubelet	每个节点上的代理，管理 Pod 生命周期，汇报节点状态
kube-proxy	网络代理，实现 Service 的负载均衡和网络规则
Container Runtime	容器运行时（containerd、CRI-O 等）

2. 核心概念

2.1 Pod

Pod 是 K8s 最小的部署单元，包含一个或多个容器。

# pod.yaml
apiVersion: v1
kind: Pod
metadata:
 name: my-pod
 labels:
 app: myapp
 version: v1
spec:
 containers:
 - name: nginx
 image: nginx:1.25
 ports:
 - containerPort: 80
 resources:
 requests:
 cpu: "100m"
 memory: "128Mi"
 limits:
 cpu: "500m"
 memory: "256Mi"
 livenessProbe:
 httpGet:
 path: /healthz
 port: 80
 initialDelaySeconds: 10
 periodSeconds: 5
 readinessProbe:
 httpGet:
 path: /ready
 port: 80
 initialDelaySeconds: 5
 periodSeconds: 3
 - name: sidecar
 image: busybox
 command: ["sh", "-c", "while true; do echo hello; sleep 10; done"]

2.2 Deployment

Deployment 管理 ReplicaSet，实现应用的声明式更新。

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: myapp
 namespace: default
spec:
 replicas: 3
 selector:
 matchLabels:
 app: myapp
 strategy:
 type: RollingUpdate
 rollingUpdate:
 maxSurge: 1 # 滚动更新时最多多出 1 个 Pod
 maxUnavailable: 0 # 更新时不允许不可用
 template:
 metadata:
 labels:
 app: myapp
 spec:
 containers:
 - name: myapp
 image: myapp:1.0
 ports:
 - containerPort: 8080
 env:
 - name: DB_HOST
 valueFrom:
 configMapKeyRef:
 name: myconfig
 key: db_host
 - name: DB_PASSWORD
 valueFrom:
 secretKeyRef:
 name: mysecret
 key: db_password
 resources:
 requests:
 cpu: "250m"
 memory: "256Mi"
 limits:
 cpu: "1"
 memory: "512Mi"

2.3 Service

Service 为 Pod 提供稳定的网络访问入口。

# ClusterIP（集群内部访问）
apiVersion: v1
kind: Service
metadata:
 name: myapp-svc
spec:
 type: ClusterIP
 selector:
 app: myapp
 ports:
 - port: 80
 targetPort: 8080
 protocol: TCP

---
# NodePort（外部通过节点端口访问）
apiVersion: v1
kind: Service
metadata:
 name: myapp-nodeport
spec:
 type: NodePort
 selector:
 app: myapp
 ports:
 - port: 80
 targetPort: 8080
 nodePort: 30080 # 外部通过 <NodeIP>:30080 访问

---
# LoadBalancer（云厂商负载均衡）
apiVersion: v1
kind: Service
metadata:
 name: myapp-lb
spec:
 type: LoadBalancer
 selector:
 app: myapp
 ports:
 - port: 80
 targetPort: 8080

2.4 Ingress

Ingress 管理外部对集群服务的 HTTP/HTTPS 访问。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: myapp-ingress
 annotations:
 nginx.ingress.kubernetes.io/rewrite-target: /
 cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
 ingressClassName: nginx
 tls:
 - hosts:
 - app.example.com
 secretName: app-tls
 rules:
 - host: app.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: myapp-svc
 port:
 number: 80
 - path: /api
 pathType: Prefix
 backend:
 service:
 name: api-svc
 port:
 number: 8080

2.5 ConfigMap 和 Secret

# ConfigMap - 存储配置数据
apiVersion: v1
kind: ConfigMap
metadata:
 name: myconfig
data:
 db_host: "mysql.default.svc.cluster.local"
 db_port: "3306"
 app.properties: |
 server.port=8080
 logging.level=INFO

---
# Secret - 存储敏感数据（base64 编码）
apiVersion: v1
kind: Secret
metadata:
 name: mysecret
type: Opaque
data:
 db_password: cGFzc3dvcmQxMjM=  # echo -n 'password123' | base64
 api_key: c2VjcmV0a2V5

2.6 其他核心资源

# StatefulSet - 有状态应用（数据库、消息队列）
apiVersion: apps/v1
kind: StatefulSet
metadata:
 name: mysql
spec:
 serviceName: "mysql"
 replicas: 3
 selector:
 matchLabels:
 app: mysql
 template:
 metadata:
 labels:
 app: mysql
 spec:
 containers:
 - name: mysql
 image: mysql:8.0
 volumeMounts:
 - name: data
 mountPath: /var/lib/mysql
 volumeClaimTemplates:
 - metadata:
 name: data
 spec:
 accessModes: ["ReadWriteOnce"]
 resources:
 requests:
 storage: 10Gi

---
# DaemonSet - 每个节点运行一个 Pod
apiVersion: apps/v1
kind: DaemonSet
metadata:
 name: log-agent
spec:
 selector:
 matchLabels:
 app: log-agent
 template:
 metadata:
 labels:
 app: log-agent
 spec:
 containers:
 - name: fluentd
 image: fluentd:latest

---
# CronJob - 定时任务
apiVersion: batch/v1
kind: CronJob
metadata:
 name: backup
spec:
 schedule: "0 2 * * *" # 每天凌晨 2 点
 jobTemplate:
 spec:
 template:
 spec:
 containers:
 - name: backup
 image: backup-tool:latest
 command: ["/bin/sh", "-c", "run-backup.sh"]
 restartPolicy: OnFailure

3. 常用 kubectl 命令

3.1 集群信息

# 集群信息
kubectl cluster-info
kubectl get nodes
kubectl get nodes -o wide # 详细信息
kubectl describe node <node-name>

# 查看所有资源
kubectl get all -A # 所有命名空间
kubectl get all -n kube-system # 指定命名空间

3.2 资源管理

# 创建资源
kubectl apply -f deployment.yaml
kubectl create namespace my-ns
kubectl create configmap myconfig --from-file=config.properties
kubectl create secret generic mysecret --from-literal=password=123

# 查看资源
kubectl get pods
kubectl get pods -o wide # 显示 IP 和节点
kubectl get pods --show-labels # 显示标签
kubectl get pods -l app=myapp # 按标签过滤
kubectl get pods -A # 所有命名空间
kubectl get pods -w # 实时监听变化
kubectl get pods --field-selector=status.phase=Running

kubectl get svc
kubectl get deploy
kubectl get ingress
kubectl get configmap
kubectl get secret
kubectl get pvc # 持久卷声明
kubectl get events --sort-by='.lastTimestamp'

# 查看详情
kubectl describe pod <pod-name>
kubectl describe svc <svc-name>
kubectl describe node <node-name>

# 删除资源
kubectl delete pod <pod-name>
kubectl delete -f deployment.yaml
kubectl delete pods --all # 删除所有 Pod
kubectl delete pods --all -n my-ns

3.3 部署与更新

# 滚动更新
kubectl set image deployment/myapp myapp=myapp:2.0
kubectl apply -f deployment.yaml # 声明式更新

# 查看更新状态
kubectl rollout status deployment/myapp
kubectl rollout history deployment/myapp

# 回滚
kubectl rollout undo deployment/myapp # 回到上一个版本
kubectl rollout undo deployment/myapp --to-revision=2 # 回到指定版本

# 扩缩容
kubectl scale deployment/myapp --replicas=5
kubectl autoscale deployment/myapp --min=3 --max=10 --cpu-percent=80

3.4 调试与日志

# 查看日志
kubectl logs <pod-name>
kubectl logs <pod-name> -f # 实时追踪
kubectl logs <pod-name> --tail=100 # 最后 100 行
kubectl logs <pod-name> -c <container> # 多容器 Pod 指定容器
kubectl logs -l app=myapp # 按标签查看日志
kubectl logs --previous # 查看上次崩溃的日志

# 进入容器
kubectl exec -it <pod-name> -- /bin/bash
kubectl exec -it <pod-name> -c <container> -- /bin/sh

# 端口转发
kubectl port-forward <pod-name> 8080:80
kubectl port-forward svc/myapp-svc 8080:80

# 文件复制
kubectl cp <pod-name>:/path/file ./file
kubectl cp ./file <pod-name>:/path/file

# 查看 Pod 事件
kubectl get events --field-selector involvedObject.name=<pod-name>

# 调试 Pod（临时容器）
kubectl debug <pod-name> -it --image=busybox

3.5 命名空间管理

kubectl get namespaces
kubectl create namespace dev
kubectl config set-context --current --namespace=dev # 切换默认命名空间
kubectl delete namespace dev

4. 网络模型

4.1 Service 类型对比

类型	访问范围	使用场景
ClusterIP	集群内部	微服务间通信（默认）
NodePort	外部通过节点IP:Port	开发测试
LoadBalancer	云厂商 LB	生产环境
ExternalName	DNS CNAME	引用外部服务

4.2 网络策略

# 只允许同命名空间中 label 为 role=frontend 的 Pod 访问
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
 name: allow-frontend
 namespace: production
spec:
 podSelector:
 matchLabels:
 app: backend
 policyTypes:
 - Ingress
 ingress:
 - from:
 - podSelector:
 matchLabels:
 role: frontend
 ports:
 - port: 8080

5. 存储

5.1 PersistentVolume 与 PVC

# PersistentVolume
apiVersion: v1
kind: PersistentVolume
metadata:
 name: my-pv
spec:
 capacity:
 storage: 10Gi
 accessModes:
 - ReadWriteOnce
 storageClassName: standard
 hostPath:
 path: /data/pv

---
# PersistentVolumeClaim
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: my-pvc
spec:
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 5Gi
 storageClassName: standard

---
# 在 Pod 中使用
spec:
 containers:
 - name: app
 volumeMounts:
 - name: data
 mountPath: /data
 volumes:
 - name: data
 persistentVolumeClaim:
 claimName: my-pvc

5.2 StorageClass（动态供给）

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: fast
provisioner: kubernetes.io/aws-ebs
parameters:
 type: gp3
 iopsPerGB: "10"
reclaimPolicy: Retain
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

6. RBAC 权限管理

# 创建角色
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
 namespace: dev
 name: pod-reader
rules:
 - apiGroups: [""]
 resources: ["pods", "pods/log"]
 verbs: ["get", "list", "watch"]
 - apiGroups: ["apps"]
 resources: ["deployments"]
 verbs: ["get", "list"]

---
# 绑定角色到用户
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
 name: read-pods
 namespace: dev
subjects:
 - kind: User
 name: developer
 apiGroup: rbac.authorization.k8s.io
roleRef:
 kind: Role
 name: pod-reader
 apiGroup: rbac.authorization.k8s.io

7. 集群搭建方式

方式	适用场景	复杂度
minikube	本地学习开发	⭐
kind	CI/CD 测试	⭐⭐
kubeadm	生产部署	⭐⭐⭐
k3s	边缘/IoT/轻量	⭐⭐
托管服务	EKS/AKS/GKE	⭐⭐

8. 生产最佳实践

资源限制 — 始终设置 requests 和 limits
健康检查 — 配置 livenessProbe 和 readinessProbe
副本数 — 至少 2 个副本保证高可用
滚动更新 — 设置合理的 maxSurge 和 maxUnavailable
命名空间隔离 — 按环境（dev/staging/prod）分命名空间
网络策略 — 限制 Pod 间不必要的通信
RBAC — 最小权限原则
监控告警 — Prometheus + Grafana
日志收集 — EFK/Loki 栈
备份 etcd — 定期备份集群状态

总结

K8s 核心知识点：

架构 — Control Plane + Worker Node
Pod — 最小部署单元
Deployment — 无状态应用管理，滚动更新
Service — 为 Pod 提供稳定访问入口
Ingress — HTTP/HTTPS 路由
ConfigMap/Secret — 配置与敏感数据管理
StatefulSet — 有状态应用
PV/PVC — 持久化存储
RBAC — 权限控制
kubectl — 集群操作的核心命令

云原生 on 吾爱主机

Kubernetes 探针机制：Liveness / Readiness / Startup 原理与工程实践

一、问题背景：进程存活 ≠ 服务可用

二、三类探针：职责完全不同

1. Startup：给慢启动留窗口

2. Liveness：死锁与不可恢复故障的“硬重启”

3. Readiness：接不接流量，而不是杀不杀进程

三、四种检查机制

四、关键参数与默认值

五、可落地的组合配置

六、常见坑与排查

七、选型速查

八、总结

参考资料

Kubernetes 1.36.2 补丁升级实战：DRA、CSI 与控制面稳定性检查清单

为什么这个补丁版本值得关注

核心修复解读

1. DRA 调度：从“能调度”到“调度正确”

2. CSI republish：不要忽略“陈旧卷内容”

3. Endpoint Controller 与旧 Service 兼容性

4. Secret 二进制环境变量回归

升级前检查清单

确认版本与支持窗口

备份 etcd 与关键配置

先升级测试集群或单个节点池

升级后验证清单

实践建议

总结

参考资料

etcd 3.7.0 正式发布：Kubernetes 控制面的升级、备份与兼容性检查清单

这次发布最值得关注的变化

1. 安全修复与依赖升级

2. v2 时代彻底退出

3. clientv3 创建连接不再阻塞

4. 命令行工具与可观测性变化

生产升级前的硬性检查

推荐的滚动升级节奏

日常维护也要一起复盘

升级风险清单

总结

参考资料

Headlamp Cluster API 插件发布：把多集群生命周期管理搬进 Kubernetes UI

背景：Cluster API 强在声明式，弱在人工排障体验

这次插件带来了什么

1. 集群总览与健康仪表盘

2. Machine 体系的可视化

3. 直接从 UI 扩缩容

4. KubeadmConfig 结构化查看

5. Map View：把 OwnerReference 变成关系图

落地前的检查清单

1. 确认 CAPI CRD 存在

2. 确认 Headlamp 部署方式

3. 按 RBAC 分层授权

4. 与 GitOps 流程约定边界

一个实用排障流程示例

对平台工程团队的影响

总结

参考资料

K3s 轻量级 Kubernetes 实战：安装、配置与生产部署

前言

1. K3s vs K8s 对比

2. 安装 K3s

2.1 Server 节点安装

2.2 Agent 节点加入

2.3 验证安装

2.4 配置 kubectl

3. 安装选项

3.1 Server 安装参数

3.2 常用环境变量

4. 卸载与重装

5. 高可用部署

5.1 架构方案

5.2 使用嵌入式 etcd（推荐）

5.3 使用外部数据库

6. 网络配置

6.1 Flannel 配置

6.2 替换 Flannel 为 Calico

6.3 ServiceLB（内置负载均衡）

7. 存储配置

7.1 本地路径存储（默认）