k8s Pod YAML详解：从零看懂并手写最小Pod配置

Pod 基础与 YAML 结构

本教程共 65 篇 · 第 11 篇 · 更新于 2026-08-14 · 约 9 分钟阅读

KubernetesPodYAMLkubectl容器组

本节目标：学完你能看懂并手写一个最小 Pod 的 YAML，理解 metadata、spec、containers 这三层结构，并用 kubectl 把它跑起来。

很多人一上来就被 Kubernetes 的 YAML 吓退。其实 Pod 的 YAML 是最该先啃下来的骨头。它就像集装箱的装箱单，看懂一张，后面所有工作负载你都能举一反三。

11-1 什么是 Pod

Pod（容器组）是 Kubernetes 里最小、最基础的部署单元。你可以把它理解成一截”豌豆荚”。

豆荚里包着豆子。Pod 里包着一到多个容器。这些容器共享同一个网络地址、共享同一批存储卷，被调度到同一台节点上，一起生一起死。

Note

Kubernetes 直接管理的是 Pod，而不是里面的某个容器。你平时说”起一个容器”，在 k8s 里其实是”起一个 Pod，里面跑一个容器”。

大多数时候一个 Pod 只装一个容器，这叫”一个 Pod 一个容器”模型。它最常用，也最省心。Kubernetes 帮你管 Pod 的生死，不直接进到容器里指手画脚。

也有把多个紧耦合容器塞进一个 Pod 的情况，比如主程序和一个帮忙打日志的边车容器。这就好比一个厨师配一个帮厨，俩人得在同一个灶台干活。这种玩法我们放到第 13 章细讲。

11-2 一个最小 Pod 的 YAML

先看最精简、能跑起来的样子。下面的清单起一个跑着 Nginx 的 Pod。

apiVersion: v1
kind: Pod
metadata:
  name: nginx-demo
  labels:
    app: nginx
spec:
  containers:
  - name: nginx
    image: nginx:1.27
    ports:
    - containerPort: 80

这短短几行，其实分了三层。我拆开给你看。

apiVersion 和 kind 在最顶上，告诉 Kubernetes”我要创建什么”。这里就是 v1 版本的 Pod。

metadata 是”身份证”：叫什么名字、贴什么标签、属于哪个命名空间。

spec 是”期望状态”：你希望这个 Pod 长什么样。里面 containers 列出要跑的容器。

Tip

记不住字段名很正常。敲 kubectl explain pod.spec.containers 就能现场查字段说明，比翻文档快。

11-3 metadata：名字、标签、命名空间

metadata.name 是 Pod 的名字，在它所在的命名空间里必须唯一。名字得符合 DNS 子域名规则（RFC 1123）：小写字母、数字、短横线，还能带点，不能带下划线，最长 253 个字符。

metadata.labels 是一组键值对，像给 Pod 贴的便利贴。它本身不影响运行，但后面所有”按标签找 Pod”的操作都靠它。比如 Deployment 靠 app: nginx 这个标签认领自己的 Pod。

metadata:
  name: nginx-demo
  namespace: default
  labels:
    app: nginx
    tier: frontend

namespace 不写就落在 default。生产环境最好自己建命名空间，把不同项目隔开，免得名字撞车。

11-4 spec.containers：镜像、端口、命令

containers 是个列表，所以前面有个短横线。每个容器至少要写 name 和 image。

image 是镜像地址加标签。我建议永远写明确的版本号，别用 latest。latest 像个没封口的抽屉，你永远不知道里面装的是哪一版，出了事都难复现。

ports.containerPort 只是声明”容器监听 80”。它不真的开防火墙，纯粹是文档性质的提示。真正让外部能访问，是后面 Service 的事（第 25 章）。

spec:
  containers:
  - name: nginx
    image: nginx:1.27
    ports:
    - containerPort: 80
    command: ["nginx"]
    args: ["-g", "daemon off;"]

command 和 args 覆盖镜像里默认的启动命令。不写就用镜像自带的 ENTRYPOINT 和 CMD。

Warning

别在 Pod 里手写一堆容器来”扩容”。想多副本请交给 ReplicaSet 或 Deployment（第 17、18 章）。Pod 生来就是一次性的，节点一挂它就没了。

11-5 用 kubectl 创建并查看

把上面的 YAML 存成 pod.yaml，然后用声明式命令创建：

kubectl apply -f pod.yaml

创建后常用这几条命令看状态：

kubectl get pod nginx-demo
kubectl describe pod nginx-demo
kubectl logs nginx-demo

get 看一眼概要，describe 看详细事件和调度情况，logs 看容器打出的日志。这三个是排错三件套，后面会天天用。

想删掉它，用：

kubectl delete pod nginx-demo

11-6 几个容易踩的坑

新手经常在这些地方绊倒，我提前给你划个线。

一是 YAML 缩进。Kubernetes 用空格缩进表达层级，千万别用 Tab。缩进错了，apiserver 直接拒收，报一串看不懂的错。

二是 image 标签忘了拉取策略。镜像 tag 是 latest 或缺省时默认 Always（每次都拉）；带明确版本号时默认 IfNotPresent，本地有就用本地的。想每次都拉新镜像，可以加 imagePullPolicy: Always。

三是 Pod 跑起来又秒退。多半是容器命令写错，或镜像里程序启动就崩。这时候 kubectl logs 和 describe 里的 Events 就是你的救命稻草。

Tip

想快速生成一个 YAML 模板又不手写？用 kubectl run nginx --image=nginx:1.27 -o yaml --dry-run=client > pod.yaml。它会吐出一份标准模板，你照着改就行。

Pod 讲完了。它就是其它所有工作负载的”积木”。下一章我们看 Pod 从生到死会经历哪些状态。