容器与云原生 / 系统课时
API 对象与声明式管理
API 对象与声明式管理
Kubernetes 的核心不是“远程执行一条命令”,而是把期望状态写成 API 对象交给集群持续维护。本节用一个 Deployment 看清资源对象、spec、status、控制循环和声明式配置之间的关系。
学习目标
- 识别 Kubernetes API 对象中描述身份、期望状态和实际状态的关键字段。
- 解释控制器如何通过控制循环把实际状态逼近期望状态。
- 使用声明式 YAML 创建资源,并理解重复执行
kubectl apply的含义。
从 API 对象看 Kubernetes
Kubernetes 中的 Pod、Deployment、Service 等资源,都通过 API Server 以对象形式读写。一个典型对象包含 apiVersion、kind、metadata 和 spec;集群运行后,控制面还会维护 status 等实际状态信息。
spec 主要表达“我希望它变成什么样”,例如副本数、容器镜像和端口;status 主要表达“现在实际是什么样”。用户通常修改期望状态,而不是直接伪造实际状态。
期望状态如何变成实际状态
当对象被提交给 API Server 后,控制器会持续观察资源。它把 spec 中的期望状态与集群当前状态比较,如果发现偏差,就创建、更新或删除下游对象;随后新的状态再次被观察,直到偏差消失。

这就是控制循环的本质:一次提交并不等于一次性任务。例如某个 Pod 意外退出,只要 Deployment 的期望副本数仍是 2,相关控制器就会继续尝试恢复到 2 个可用副本。
用声明式配置提交期望状态
下面定义一个包含两个副本的 Deployment。把内容保存为 deployment.yaml。
apiVersion: apps/v1
kind: Deployment
metadata:
name: demo-web
spec:
replicas: 2
selector:
matchLabels:
app: demo-web
template:
metadata:
labels:
app: demo-web
spec:
containers:
- name: nginx
image: nginx:1.27-alpine这份配置的生效行为是:集群维护一个名为 demo-web 的 Deployment,并尝试保持两个符合模板的 Pod。可以用下面的命令提交并读取期望副本数。
kubectl apply -f deployment.yaml
kubectl get deployment demo-web -o custom-columns=NAME:.metadata.name,DESIRED:.spec.replicas --no-headers预期输出
deployment.apps/demo-web created
demo-web 2首次创建时通常显示 created;再次执行同一份配置时可能显示 unchanged,修改 YAML 后则可能显示 configured。这正是 apply 的声明式语义:提交“现在应该是什么”,而不是要求系统机械重复一组步骤。
声明式管理的关键边界
声明式配置适合进入版本控制,因为 YAML 可以审查、比较和回滚;集群则负责持续协调实际状态。它不意味着所有字段都由用户维护,也不意味着资源会瞬间就绪。镜像拉取、调度、健康检查失败都可能让 status 暂时落后于 spec。
掌握 API 对象后,阅读 Kubernetes 配置时应先找 kind 和 spec,再结合 status 判断控制循环是否已经把现实推进到期望状态。