容器与云原生 / 系统课时
编写 Pod 清单
编写 Pod 清单
Pod 清单把期望状态提交给 Kubernetes API Server。本节从最小 YAML 开始,说明 apiVersion、kind、metadata、spec 与 status 的职责,并创建一个可验证运行的 Pod。
学习目标
- 正确填写 Pod 清单的核心字段并理解它们的职责边界
- 用 YAML 定义容器镜像、名称和端口等期望状态
- 使用 kubectl 创建 Pod,并从运行状态验证清单是否生效
读懂 Pod 对象的字段边界
apiVersion 表示对象使用的 API 版本,Pod 属于核心 API,通常写为 v1;kind 固定写 Pod。metadata 保存名称、标签等标识信息,spec 描述用户期望的运行方式,例如容器列表、镜像和端口。
status 与前四项不同。它由 Kubernetes 控制面和 kubelet 持续维护,用来记录当前阶段、Pod IP、容器状态等观测结果。编写清单时重点声明 metadata 与 spec,不要把运行中的 status 复制回期望配置。
编写最小可用清单
下面创建一个名为 web-demo 的 Pod,运行单个 Nginx 容器。保存为 pod.yaml。
apiVersion: v1
kind: Pod
metadata:
name: web-demo
labels:
app: web-demo
spec:
# spec 描述期望状态,status 不由用户在这里维护。
containers:
- name: nginx
image: nginx:1.27-alpine
# containerPort 记录容器监听端口,但不会自动创建 Service。
ports:
- containerPort: 80这个清单满足最小运行需求:Pod 有稳定名称,spec.containers 至少包含一个容器,并为容器指定镜像。标签 app: web-demo 不是 Pod 启动的必需项,但后续创建 Service、Deployment 或查询资源时通常会用它做选择条件。
创建并验证 Pod
在可用的 Kubernetes 集群中执行以下命令。kubectl wait 会等待 Pod 达到 Ready,避免刚创建就读取到暂时的 Pending 状态。
kubectl apply -f pod.yaml
kubectl wait --for=condition=Ready pod/web-demo --timeout=120s
kubectl get pod web-demo -o custom-columns=NAME:.metadata.name,PHASE:.status.phase,READY:.status.containerStatuses[0].ready预期输出
pod/web-demo created
pod/web-demo condition met
NAME PHASE READY
web-demo Running true如果目标命名空间已有同名 Pod,第一行可能显示 configured 或 unchanged。镜像拉取速度也会影响 Ready 时间,因此超时不一定表示 YAML 语法错误,需要继续查看 Pod 事件和容器状态。
区分声明内容与运行结果
创建完成后,API Server 保存 metadata 和 spec,调度器选择节点,kubelet 再根据 spec 创建容器。与此同时,系统不断更新 status。因此同一份清单可以保持不变,而 status.phase 会经历 Pending、Running 等变化。
这也是声明式配置的关键:清单表达“我要什么”,状态表达“现在是什么”。当两者不一致时,Kubernetes 控制器和节点组件会持续尝试把实际状态推向期望状态。
处理常见清单错误
若 apiVersion 或 kind 写错,API Server 可能无法找到对应资源类型;若字段层级错位或缩进错误,kubectl 会在解析或服务端校验阶段报错。遇到这类问题,先检查 YAML 结构,再确认字段是否属于 Pod 的 spec。
如果 Pod 一直不是 Ready,问题通常已经从“清单语法”进入“运行状态”阶段,例如镜像无法拉取、容器启动失败或节点资源不足。此时应查看 kubectl describe pod web-demo 的 Events 和容器状态,而不是继续修改 apiVersion、kind 这类已经通过校验的字段。
一份合格的 Pod 清单应保持期望状态最小且明确:对象身份放在 metadata,运行要求放在 spec,由集群维护 status。创建后再用实际状态验证,能快速区分“清单写错”与“运行环境出错”两类问题。