外观
05 - 提交 YAML 后发生了什么:Kubernetes 声明式 API 与控制循环
摘要
Deployment 明明声明了 3 个副本,为什么只有 2 个可用?提交 YAML 只是告诉 Kubernetes 你想要什么,控制器还要持续检查实际状态并推动后续工作。本文先解释期望状态与控制循环,再介绍变化感知和重试机制,最后通过一个最小 Deployment 实验观察资源如何逐级生成。
1. 场景:YAML 没写错,为什么一直不生效
考虑这样一个扩容场景:工程师把 Deployment 的 replicas 从 2 改成 3,kubectl apply 返回成功,但十分钟后仍只有两个可用 Pod。重复 apply、重新登录集群都没有变化。
继续检查才发现:第三个 Pod 已经创建,却因为没有节点满足资源请求而 Pending。API Server 已成功接受期望状态,Deployment 和 ReplicaSet 的控制器也已推动第三个 Pod 的创建;卡住的是后续调度阶段。
kubectl apply 成功返回,表示 API 层面的提交成功,不表示业务已经可用。Deployment 是声明副本数量和 Pod 模板的工作负载对象;Pod 是 Kubernetes 调度的基本单位,其中可以运行一个或多个容器。
声明式 API 的基本模型是:你描述“应该有 3 个副本”,控制器(Controller)比较这个目标与当前状态,再采取动作缩小差异。这个反复观察、比较、调整的过程叫控制循环;实际状态达到目标叫收敛。如果节点资源不足,创建 Pod 的阶段可以完成,调度阶段却无法完成。收敛需要后续各阶段的条件都满足。
2. 一次 apply 的完整链路
图表将在阅读到此处时加载…
图中合并展示了工作负载控制器的动作。具体分工是:Deployment Controller 创建或调整 ReplicaSet,ReplicaSet Controller 再维护 Pod 数量。ReplicaSet 是维持一组 Pod 副本数量的对象。Scheduler 为 Pod 选择节点,节点上的 Kubelet 再协调容器运行时启动容器。
API Server 是统一 API 入口,负责处理资源读写请求。各组件通过读写 API 对象协作,图中的先后关系表示工作依赖,不表示一次同步调用会等待所有阶段结束。
2.1 认证、授权和准入不是一回事
- Authentication:确认调用者是谁;
- Authorization:确认该身份能否执行动作;
- Admission Control:对象通过授权后,对内容进行修改或校验。
Mutating Admission 可以修改对象,Validating Admission 则校验对象是否符合规则。Webhook 是 API Server 调用的外部准入服务。Forbidden 常见于授权失败,但准入拒绝也可能表现为禁止操作;应结合错误正文判断拒绝发生在哪一层,不能只凭错误名称认定是权限问题。
2.2 etcd 保存的是 API 状态
etcd 是分布式键值存储,保存 Kubernetes 资源的持久状态,不直接保存容器文件、应用日志或镜像内容。普通用户应通过 API Server 访问资源,而不是绕过它直接修改 etcd。直接写 etcd 会跳过校验、准入和控制语义,属于高风险操作。
3. 声明式的关键:Spec、Status 与 Conditions
以 Deployment 为例,下面是字段示意,不是可直接提交的完整 YAML:
yaml
spec:
replicas: 3
status:
replicas: 3
readyReplicas: 2
availableReplicas: 2spec 表达期望,status 表达负责组件观察到的状态。这里期望有 3 个副本,观察到的副本数也是 3,但就绪和可用副本都只有 2;“Pod 已创建”与“Pod 已可用”是两件事。就绪(Ready)表示满足就绪条件,可用(Available)还要符合 Deployment 的可用性要求,例如配置的最短就绪时间。
状态更新是异步的,刚提交变更时,status 可能尚未反映新目标。不同资源的状态字段和更新者也不同,不能把所有状态都理解成 Kubelet 写入。
Conditions(状态条件)描述某个方面是否满足条件,并携带原因、消息和时间等信息。Deployment 的 Available、Progressing 分别描述可用性和发布进度,Pod 的 PodScheduled 描述调度状态;它们属于不同资源。
判断长期不收敛时,可以查看以下信息。命令假设目标 Deployment 名为 order-api,Pod 标签为 app=order-api,且当前 Namespace(命名空间,用于划分资源范围)正确:
bash
kubectl get deployment order-api -o yaml
kubectl describe deployment order-api
kubectl get pod -l app=order-api -o wide重点不是寻找一个万能字段,而是确定差异第一次出现在哪一级对象:Deployment、ReplicaSet、Pod、Container,还是外部依赖。
4. List-Watch:控制器如何感知变化
控制器需要知道对象何时变化,但频繁拉取全量数据会增加 API Server 的负担。List-Watch 把“获取初始状态”和“接收后续变化”分开:
- List 获取某类资源当前快照;
- 记录列表返回的
resourceVersion; - 从该版本开始 Watch 后续事件;
- Watch 中断后尝试恢复;如果版本过旧、无法继续观察,就重新 List 建立快照。
resourceVersion 用于表达 API 存储中的对象版本和观察起点,不应当作跨对象、跨集群的业务序列号。它的具体比较和一致性语义依 Kubernetes API 约定,应用不应自行发明数值排序规则。
图表将在阅读到此处时加载…
4.1 Informer 不只是事件回调
Informer 是客户端中维护资源本地缓存、分发变化通知的机制,通常组合了 List-Watch、本地 Cache(缓存)、事件分发和重连。控制器应把事件看成“某对象可能需要重新检查”的提示。
通知可能重复,队列中的工作可能合并,控制器也可能重启。因此,Reconcile(调谐,即比较状态并采取调整动作)应根据当前观察到的状态计算结果,而不是依赖逐条回放事件。缓存也可能暂时落后于 API 状态,后续观察和重试仍是控制循环的一部分。
4.2 Workqueue 为什么要去重和限速
Workqueue 是控制器等待处理工作的队列。Key 是待检查对象的标识,通常由命名空间和名称组成。同一对象短时间变化多次时,队列可以按 Key 合并工作;处理失败后,可通过限速队列按退避策略重新入队,也就是等待一段时间再尝试。这能减少重复工作,并缓解瞬时错误带来的请求压力。
5. Reconcile:把控制器写成幂等函数
下面的 Go 风格伪代码展示调谐的基本结构。本节代码省略了类型定义、API 客户端和错误处理细节,用于说明逻辑,不能直接编译运行:
go
func Reconcile(key NamespacedName) error {
desired := readSpec(key)
actual := observeActualState(key)
if alreadyConverged(desired, actual) {
return nil
}
return moveOneStepTowardDesired(desired, actual)
}幂等意味着相同状态下重复执行不会不断制造额外副作用。例如,“确保存在一个子资源”应先检查它是否存在,再决定创建。Owner Reference(属主引用)记录子资源与所属对象的关系,稳定名称则便于重复查找;每次创建随机名称的新资源会让重试变成重复创建。
反例:每次调谐都发外部消息
go
func Reconcile(req Request) error {
sendEmail("resource changed")
return nil
}Watch 重连、进程重启或失败重试都可能重复发送。
正例:用状态记录可恢复进度
go
func Reconcile(req Request) error {
obj := get(req)
if obj.Status.NotificationSent {
return nil
}
if err := sendWithIdempotencyKey(string(obj.UID)); err != nil {
return err
}
return patchStatusNotificationSent(obj)
}NotificationSent 是示例自定义资源的状态字段,UID 是对象实例的唯一标识。幂等键让外部服务识别重复请求;这里按 UID 去重表达的是“同一个对象实例只发送一次”,不是每次修改都发送一次。
这仍存在“外部发送成功、Status 写入失败”的窗口:控制器重试时会再次调用外部服务,因此外部系统必须支持并使用幂等键去重。仅在 Kubernetes 状态中记录发送成功,不能保证外部操作只执行一次。
6. 最小实验:观察对象逐级生成
实验需要可访问的 Kubernetes 测试集群和 kubectl,以及当前测试 Namespace 内资源的读写权限。所有命令都作用于当前 Namespace,应先确认它专用于实验,且没有其他使用 app=detached 的 Pod。节点资源和镜像拉取条件需要满足,才能观察到两个副本就绪。下面命令使用 Bash 风格的续行。
将以下内容保存为 reconcile-demo.yaml,创建 Deployment:
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: reconcile-demo
spec:
replicas: 2
selector:
matchLabels:
app: reconcile-demo
template:
metadata:
labels:
app: reconcile-demo
spec:
containers:
- name: web
image: nginx:1.27-alpine
ports:
- containerPort: 80bash
kubectl apply -f reconcile-demo.yaml
kubectl get deployment,replicaset,pod -l app=reconcile-demo \
--show-labels预期观察:Deployment 驱动 ReplicaSet 生成,ReplicaSet 再创建两个 Pod。控制循环异步执行,刚提交后可能尚未看到全部资源。YAML 的 Deployment 顶层没有设置 app=reconcile-demo 标签,因此上述带标签筛选的查询主要用于观察 ReplicaSet 和 Pod;查看 Deployment 可按名称查询 reconcile-demo。
检查返回 YAML 中的 metadata.ownerReferences,观察 ReplicaSet 与 Deployment、Pod 与 ReplicaSet 的所属关系:
bash
kubectl get rs -l app=reconcile-demo -o yaml
kubectl get pod -l app=reconcile-demo -o yaml从查询结果中选取一个实验 Pod,将下方名称占位符替换为它的完整名称,再手工删除。-w 表示持续观察变化,观察完成后可用 Ctrl+C 退出:
bash
kubectl delete pod reconcile-demo-请替换为实际名称
kubectl get pod -l app=reconcile-demo -w预期观察:ReplicaSet Controller 创建新的 Pod 补足副本;这是一个新对象,不是恢复被删除的同一个 Pod。待副本补齐后,再将 POD_NAME 替换为一个当前实验 Pod 的名称,修改它的 Label(标签,即资源上的键值标记):
bash
kubectl label pod POD_NAME app=detached --overwrite
kubectl get pods --show-labelsSelector(选择器)用于匹配标签。预期观察:修改后的 Pod 不再匹配 ReplicaSet 的选择器,控制器会创建匹配的 Pod 补足副本;被改标签的 Pod 仍可能存在。这个实验展示了标签匹配对副本维护的影响;实际成员管理还涉及属主关系,不能仅凭标签就认定任意 Pod 都属于某个 ReplicaSet。
清理实验资源。第二条命令会删除当前 Namespace 中所有带 app=detached 标签的 Pod,因此只能在前述隔离条件下使用:
bash
kubectl delete deployment reconcile-demo
kubectl delete pod -l app=detached --ignore-not-found7. 乐观并发:为什么更新会 Conflict
乐观并发是指读对象时不先加锁,提交更新时再检查对象是否已被别人修改。对于携带 resourceVersion 的对象更新,API Server 可以检测过期版本并拒绝更新。以下数字只是版本变化示意,不代表版本一定连续递增:
text
客户端 A、B 都读取版本 10
A 更新成功,对象变成版本 11
B 按旧版本 10 提交,被拒绝 Conflict正确处理通常是重新读取最新对象、重新计算修改并有限重试,而不是移除版本检查覆盖他人字段。
Server-Side Apply(服务端应用)由 API Server 跟踪哪些字段由哪个管理者维护,并处理字段所有权冲突。这与“按过期对象版本提交更新”是两种不同的冲突来源。其行为与 Kubernetes 版本和客户端参数有关,生产自动化应固定工具版本并测试变更。
8. 线上排障:状态为什么没有收敛
先比较 API 中的期望与状态,再沿下级对象查找第一处未完成的工作。已经生成 Pod 时,先看 spec.nodeName 判断是否已绑定节点;Pending 不一定表示尚未调度,也可能是调度后容器尚未准备好。
图表将在阅读到此处时加载…
图中,亲和性和污点是节点选择约束,PVC 是持久卷声明,可能影响调度或存储挂载;Runtime 是容器运行时,CNI 是容器网络接口,Probe 是健康探测。Pod Ready 也不能单独证明业务请求正常,还要检查 Service(服务访问入口)及应用依赖。
Events 是 Kubernetes 记录的平台事件,可帮助解释创建、调度和启动失败,但不是永久审计日志,可能有保留期限、聚合和限流。排障时应及时收集,故障复盘不能只依赖事后 kubectl get events。
9. 容易踩的坑
9.1 重复 apply 代替定位
如果对象已持久化,重复提交相同 Spec 不会解决调度、拉镜像或 Probe 问题。
9.2 把 Watch 当可靠消息队列
Watch 连接会中断,事件可能重复;消费者必须能重新 List 并按当前状态恢复。
9.3 控制器只处理“新增事件”
控制器重启后可能错过瞬时事件。Reconcile 应由当前状态推导动作。
9.4 Status 更新触发无限循环
如果控制器监听自身对象的状态变化,每次调谐都写入变化的 Status,就可能触发下一次调谐,形成无意义循环。写入前应比较状态是否真正改变,避免仅更新时间戳;具体是否重新入队还取决于事件过滤逻辑。
9.5 Finalizer 永远不删除
Finalizer(终结器)是对象上的清理标记。删除带有 Finalizer 的对象时,API 会先标记删除请求,等待负责组件完成清理并移除标记,再完成删除。控制器异常或外部系统永久失败,可能让对象长期处于 Terminating(正在终止)状态,因此需要设计有界重试、人工恢复和幂等清理。清理未完成时直接移除标记,可能遗留外部资源。
10. 总结
Kubernetes 的 apply 只提交期望状态,真正结果由多个控制循环异步推进并通过 Status 反馈。
可以带走的三个核心要点:
- API Server、Controller、Scheduler、Kubelet 各负责不同阶段,成功写入 API 不等于工作负载已经可用。
- List-Watch 和 Informer 提供变化感知,但事件不是唯一真相;Reconcile 必须依据当前状态且保持幂等。
- 状态不收敛时要沿 Deployment → ReplicaSet → Pod → Container 分层找第一处差异。
下一篇:Pod 一直 Pending:Scheduler 如何选择节点。