用 YAML 描述 Pod：清单结构详解

为什么把 Pod 写成 YAML#

上一章用 kubectl run 创建 Pod，快是快，但有几个致命缺点：命令里塞不下复杂的配置，没法版本管理，也没法复现。真实工作中，所有资源都写在 YAML 清单里，提交进 Git，用 `kubectl apply` 下发。

YAML 描述的是「期望状态」，而不是「操作步骤」。这正好对应第一章讲的声明式思路：你不说「先做什么再做什么」，只说「我要一个长这样的 Pod」，剩下的交给控制器。

这一章我们不引入新概念，只把上一章的 Pod 完整地写成 YAML，并学会读它、改它、验证它。

YAML 缩进规则：只有空格，没有 Tab#

YAML 用缩进来表达层级，规则只有三条，但踩坑的人最多：

1. 只能用空格，不能用 Tab。编辑器里 Tab 是不可见的，报错信息也往往只说「第几行有问题」，所以请把编辑器设成「Tab 转 2 空格」。
2. 同一层级缩进必须完全一致。两个空格是最常见的约定，本课程统一用两个空格。
3. 列表项用 `- ` 开头，它和上一行的键属于同一层级，所以 - 通常要比键多缩进两个空格。

一个最小例子：

spec:
  containers:
    - name: web
      image: nginx:1.27

containers 是键，它的值是一个列表；- name: web 是列表的第一项，image 和 name 是同一项里的两个字段，所以和 name 对齐。写错一个空格，name 就会变成 containers 的兄弟字段，语义完全不同。

清单的四段骨架与 status#

任何 Kubernetes 清单都长这样：

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  # 期望状态写在这里

还有第五段 status，它只出现在 `kubectl get -o yaml` 的输出里，绝对不要手写。status 是集群回写的事实：Pod IP、所在节点、容器是否就绪。如果你在清单里写了 status，apiserver 会直接忽略它——因为事实只能由集群产生。

整张清单的流向可以画成一张图，左边是你负责的，右边是集群负责的：

   你写进 Git 的清单（期望状态）
  ┌──────────────────────────────────┐        ┌────────────────────────────────┐
  │ apiVersion: v1                   │        │ status:                        │
  │ kind: Pod                        │        │   phase: Running               │
  │ metadata:                        │ ─────► │   podIP: 10.244.1.7            │
  │   name: web                      │ apply  │   hostIP: 172.18.0.2           │
  │   labels: {app: web}             │ ◄───── │   conditions: Ready=True       │
  │ spec:                            │ 控制器  │   containerStatuses: [...]     │
  │   containers: [web]              │        │                                │
  └──────────────────────────────────┘        └────────────────────────────────┘
                  ▲                                          ▲
                  └── 你负责写、提交、apply                   └── 你只负责读，写它没用

apiVersion + kind 决定「交给谁来处理这份清单」，metadata 回答「它是谁」，spec 回答「它该长什么样」，status 回答「它现在实际是什么样」。前四段你写，第五段集群写。

动手：写一个完整的 Pod 清单#

apiVersion: v1
kind: Pod
metadata:
  name: web
  namespace: demo
  labels:
    app: web
    tier: frontend
spec:
  containers:
    - name: web
      image: nginx:1.27
      ports:
        - name: http
          containerPort: 80
      env:
        - name: APP_ENV
          value: dev
        - name: LOG_LEVEL
          value: info
      resources:
        requests:
          cpu: 50m
          memory: 64Mi
        limits:
          cpu: 200m
          memory: 128Mi

kubectl create namespace demo

kubectl apply -f pod.yaml
kubectl get pod web -n demo
kubectl get pod web -n demo -o yaml

逐个看这些字段：

• ports 是一个列表，每一项里写 containerPort，还可以给端口起个 name（后面 Service 会引用这个名字）。containerPort 只是声明，不写也能跑，但写了更清晰。
• env 注入环境变量，每一项是 name + value。从 ConfigMap、Secret 注入的写法在第 9 章 ConfigMap 与 Secret。
• resources.requests 是调度依据：调度器只把 Pod 放到资源足够的节点上。limits 是运行上限：CPU 超了会被限流，内存超了会被杀掉（OOMKilled）。50m 表示 0.05 核。

改完清单再下发一次，就会看到 apply 帮你更新对象：

kubectl apply -f pod.yaml

用 kubectl explain 查字段#

YAML 字段记不住很正常，kubectl explain 把字段文档直接打到终端里，比翻网页快：

kubectl explain pod
kubectl explain pod.spec.containers
kubectl explain pod.spec.containers.resources --recursive

第一条列出 Pod 的顶层字段；第二条列出容器支持的所有字段（image、command、env、ports、volumeMounts 等）；加 --recursive 会展开到最深层级，输出比较长，适合配合 grep 找字段名。

下面这份「常用路径清单」值得先抄到自己的笔记里，路径就是资源名加点号加字段名：

任何一条路径都可以再往后接字段名，kubectl explain 会一直往下钻。报错里出现 unknown field 时，就用它反查正确拼写。

另一个技巧是让 kubectl 帮你生成骨架：

kubectl run tmp --image=nginx:1.27 --dry-run=client -o yaml

--dry-run=client 表示只在本地生成对象、不发给集群，把输出重定向到文件就是一个可用的模板。

labels 与 selector#

labels 是挂在对象上的键值对，本身不产生任何行为，它的作用是被选中。Service、Deployment、NetworkPolicy 都通过 selector 找目标对象，这是 Kubernetes 把资源「连接」起来的主要方式。

kubectl get pods -n demo --show-labels
kubectl get pods -n demo -l app=web
kubectl get pods -n demo -l 'tier in (frontend)'

• --show-labels 把标签显示出来，确认清单里的 labels 真的写进去了。
• -l app=web 是等值选择器，只返回标签匹配的 Pod。
• -l 'tier in (frontend)' 是集合选择器，支持 in、notin、exists。

给已有对象加标签也可以直接用命令：

kubectl label pod web -n demo env=dev

最关键的一点：下一章 Service 的 spec.selector 必须和 Pod 的 labels 精确匹配（键和值都要一致）。如果 Service 选不到后端，第一件事就是对比这两处的标签。标签写错时 Kubernetes 不会报错，只会静默地「找不到 Pod」，这是新手最难发现的坑之一。

多容器 Pod 与 sidecar#

Pod 里可以放多个容器，它们共享网络命名空间（同一个 IP，可以互相用 localhost 访问）和挂载的存储卷，但各自有独立的文件系统和进程空间。

最常见的模式叫 sidecar：主容器负责业务，辅助容器负责日志收集、指标暴露或流量代理。下面这个例子给 nginx 配了一个每 10 秒请求一次本地服务的探针容器：

apiVersion: v1
kind: Pod
metadata:
  name: web-with-sidecar
  namespace: demo
  labels:
    app: web
spec:
  containers:
    - name: web
      image: nginx:1.27
      ports:
        - containerPort: 80
    - name: probe
      image: busybox:1.36
      command:
        - sh
        - -c
        - "while true; do wget -q -O- http://localhost:80 >/dev/null; sleep 10; done"

注意 probe 容器里用的是 http://localhost:80，而不是 Pod 的 IP——因为两个容器共享网络命名空间。把上面的清单保存为 sidecar.yaml，下发后看 probe 容器的输出：

kubectl apply -f sidecar.yaml
kubectl logs web-with-sidecar -n demo -c probe

实际生产中，sidecar 更多是服务网格的数据面代理或日志采集器。这里只需要记住概念：同一 Pod 内的容器是「同生共死」的，它们一起被调度，也一起被销毁。

常见坑#

写清单时最容易撞到的几种情况，先对着这张表找：

小结#

• YAML 用空格缩进，列表项以 - 开头；混入 Tab 是最高频的语法错误。
• 清单的四段骨架是 apiVersion、kind、metadata、spec；status 由集群回写，不要手写。
• kubectl apply -f 下发、kubectl diff -f 预览变更、kubectl delete -f 删除，是清单工作流的三条主命令。
• labels 是被选择的一方，selector 是选择的一方，两者必须精确匹配。
• 一个 Pod 可以放多个共享网络与存储的容器，sidecar 是最常见的用法。

练习#

1. 把清单里的 image 改成 nginx:1.27-alpine，用 kubectl diff -f pod.yaml 看看差异，再 apply，最后用 kubectl get pod web -n demo -o jsonpath='{.spec.containers[0].image}' 确认。
2. 给 Pod 加一个 env 变量 GREETING=hello，apply 后 kubectl exec 进去执行 echo $GREETING 验证。
3. 故意把 containers 下面的缩进多写一个空格，观察报错信息，再改回来。

单个 Pod 显然不够用：它挂了不会自动重建，也没法滚动更新。下一章我们用 第 6 章 Deployment 来管理多个 Pod 副本。

相关章节：第 4 章 第一个 Pod 讲了怎么用命令快速起一个 Pod，速查表 里有本章命令的一页速览。