K8s Pod 详解：从 yaml 字段到常用命令与生产排错实战

K8s 系列写到这里第三篇终于轮到 Pod 了。前面两篇把集群架构和环境搭好之后不少读者会陷入一个尴尬期命令能敲了但面对一份 yaml 还是习惯“照着模板改个名字”不知道每个字段到底是什么意思更不知道为什么有时候 Pod 起来又退了、有时候一直 Pending。这篇我就专门把 Pod 这个对象从头到尾掰开讲一遍重点放在 yaml 详解和常用命令上配合完整实战和排错实录。不管你刚学 K8s还是用了挺久但对细节模棱两可建议都读一遍很多困惑会在这里对上答案。1. Pod 到底是什么K8s 里最小的调度单位1.1 为什么 K8s 不直接调度容器刚开始学 K8s 的人最常问的一个问题就是K8s 明明是容器编排平台为什么不直接以容器为调度单位非要再包一层 Pod答案要从多容器协作说起。假设你现在要跑一个 nginx顺便在旁边挂一个收集日志的 filebeat。这两个容器有明确的依赖关系同一个应用、共享同一份日志文件、网络要互通。如果 K8s 只调度容器调度器就得想办法表达“这俩容器必须一起跑、一起调度、共享资源”这个模型会非常别扭。更麻烦的是单个容器崩溃重启后 IP 会变调度器无法把“这么多容器”组织成“一个应用实例”来管理。Pod 就是用来解决这个问题的。Pod 把一组需要紧密协作的容器打包成一个整体K8s 调度、部署、伸缩、健康检查都以 Pod 为单位。换句话说容器是执行进程的Pod 是描述“一组进程如何在一起工作”的。1.2 Pod 与容器的关系一个“宿舍”里的室友用一句话记Pod 就是容器们的“宿舍”。住在同一个宿舍里的室友共享同一根网线网络命名空间所以同一个 Pod 里的容器可以通过 localhost 直接访问彼此同时大家共用一块公共区域存储卷读写的文件互相可见。Pod 是这个宿舍的单位你给这个宿舍分配多少资源CPU、内存里面每个容器怎么分配由你在 yaml 里描述。这里有个细节值得注意每个 Pod 背后其实有个常驻的“宿舍管理员”容器叫 pause 容器也叫 infra container。它的职责只有一个持有整个 Pod 的网络命名空间保证整个 Pod 的生命周期内网络环境稳定。即使业务容器重启了pause 容器一直在Pod 的 IP 就不变。这也是为什么 Pod 重启容器时 IP 不换、端口不换——对调用方来说服务地址始终稳定。1.3 多容器 Pod 的典型场景以 Sidecar 为例既然 Pod 支持多个容器那什么样的容器才适合放进同一个 Pod判断标准很朴素如果它们必须被当成一个整体来调度和伸缩就放一起如果两个服务可以各自扩容、各自发布、独立对外暴露那就应该拆成两个 Pod甚至两个 Deployment。最常见的多容器场景是 Sidecar 模式。比如日志采集器主容器跑业务应用旁挂一个 filebeat/fluentd 容器共享日志目录自动采集上报。配置同步器主容器启动前由 sidecar 负责从配置中心拉取最新配置写入共享卷。服务网格代理业务只监听 127.0.0.1由同一个 Pod 里的 Envoy 代理接管流量。这些 sidecar 流量不大但跟主容器强绑定拆开反而增加复杂度放一起由 Pod 统一管理是最合理的。2. 手把手拆解 Pod 的 yaml核心字段逐行讲透2.1 yaml 基础语法缩进、冒号、数组与引号写 K8s 清单绕不开 yaml所以先花两分钟把 yaml 语法里最容易踩的坑说清楚。第一缩进必须用两个空格不能用 Tab。尤其用 vim 写文件时Tab 键显示的宽度会骗人看着像对齐了kubectl apply 一跑就报错。我建议写 yaml 前先执行:set expandtabvim 里设置 Tab 展开为空格或者干脆用 VS Code 加 YAML 插件写错了会有波浪线提示。第二冒号后面必须跟一个空格name: nginx是对的name:nginx解析会出问题。另外注意 yaml 里没有逗号不要从 JSON 习惯里把逗号带进来。第三布尔值和数字。true、false、1、3.14这种不加引号没问题但字符串如果包含特殊字符比如冒号、井号开头、数字开头尽量加引号包裹省得解析时出幺蛾子。例如环境变量的值TZ: Asia/Shanghai我就建议加引号。一个实用技巧拿不准字段怎么写的时候kubectl explain是你最好的老师。比如输入kubectl explain pod.spec.containers它会直接打印该字段的说明、类型和示例比翻网页快得多。2.2 顶层字段apiVersion、kind、metadata 怎么填每个 K8s 资源 yaml 都有固定的三个顶层字段apiVersion、kind、metadata。apiVersion表示 API 版本。Pod 属于核心 API 组用v1如果你写 Deployment那就是apps/v1。写错版本最常见的结果是 apply 时直接报错。kind是资源类型这里就是Pod。metadata是元数据里面最核心的是name和namespace。name在同一个命名空间内必须唯一只能包含小写字母、数字、中划线和点。namespace不写就是default。另外metadata里还可以挂labels和annotations这俩一字之差用途完全不同labels是 K8s 的“标签”供选择器筛选用比如 Service 根据app: nginx找到对应 Podannotations是注解更像给对象写的说明文档K8s 内部一些工具也会用它传递配置但不用于筛选。2.3 spec 核心containers、resources、探针spec是描述“这个 Pod 该怎么做”的部分也是 yaml 里最重要的部分。下面拆几个核心字段containers必填的数组。每个容器都要有name和image。name在 Pod 内唯一image建议写具体的版本号比如nginx:1.27生产环境尽量避免latest它会让升级和回滚变不可控。imagePullPolicy镜像拉取策略。可选值Always、IfNotPresent、Never。默认逻辑是镜像 tag 是 latest 或不写 tag 时默认Always写了具体版本号时默认IfNotPresent。知道这点后你就明白为什么线上改成 latest 后每次 Pod 重启都会触发拉镜像。command和args这两个字段会覆盖 Dockerfile 里的 Entrypoint 和 CMD。如果 Dockerfile 里已经配好了启动命令这里通常不用写。ports声明容器监听的端口。注意它主要是“告知”作用不声明也不会封掉端口但写清楚对后续 Service 配置和可读性都有帮助。env环境变量列表。从 ConfigMap 或 Secret 注入也在这里配置。resources资源限制。分requests请求量和limits上限。调度器根据requests判断节点能不能放下这个 Pod运行时如果容器超过limits.memory会被 OOMKill。CPU 单位是m毫核100m等于 0.1 核内存单位常用Mi、Gi。这里补充一个应用实例如果想让 Pod 调用 GPU 资源在limits里声明nvidia.com/gpu: 1调度器会按扩展资源的方式处理。探针Probe也是spec里的关键配置分三种livenessProbe探活。探测失败达到阈值后kubelet 会按重启策略重启容器。readinessProbe就绪。探测失败时 Pod 不会从 Service 流量中移除也就是此时不应该接流量。startupProbe启动探针。适用于启动很慢的应用比如 Java 服务它会先于前两个探针运行防止应用还没起来就被 liveness 误杀。探针支持三种探测方式exec执行命令、httpGet请求 HTTP 接口、tcpSocket建立 TCP 连接。常用参数的表格我放后面。2.4 一个完整的 Pod yaml 示例把上面说的字段综合起来下面是一个带探针、资源限制、环境变量、存储卷的完整示例apiVersion: v1 kind: Pod metadata: name: nginx-demo namespace: default labels: app: nginx env: demo spec: restartPolicy: Always # 容器异常退出后总是重启 containers: - name: nginx image: nginx:1.27 imagePullPolicy: IfNotPresent ports: - name: http containerPort: 80 protocol: TCP env: - name: TZ value: Asia/Shanghai resources: requests: cpu: 100m memory: 128Mi limits: cpu: 500m memory: 256Mi volumeMounts: - name: html mountPath: /usr/share/nginx/html livenessProbe: httpGet: path: / port: 80 initialDelaySeconds: 10 # 容器启动后等 10 秒再探 periodSeconds: 10 # 每 10 秒探一次 timeoutSeconds: 3 failureThreshold: 3 # 连续失败 3 次判定为不健康 readinessProbe: httpGet: path: / port: 80 initialDelaySeconds: 5 periodSeconds: 5 failureThreshold: 3 volumes: - name: html hostPath: path: /data/nginx # 把节点目录挂载进容器这份 yaml 写完后执行kubectl apply -f nginx-pod.yaml一个 Pod 就创建好了。探索阶段我强烈建议你把这种带探针和资源限制的模板当成自己的底座别裸写。2.5 编写 yaml 的避坑技巧这些坑我是真金白银踩过的第一缩进错位是 yaml 报错最高频原因。遇到error converting YAML to JSON之类的报错先检查缩进。第二字段拼接错误。env和resources是containers下的子字段经常有人把它们写到spec层级导致 apply 通过但 Pod 起不来。用kubectl explain pod.spec.containers可以随时核验。第三不可变字段。比如metadata.name、nodeName、容器的name在创建后是不能修改的。如果 apply 时出现field is immutable报错说明当前 yaml 在你的集群里已经存在而且改了不允许改的字段。正确做法是确认变化需求必要时删除重建。第四不要手写所有字段。日常开发中很少从零写 yaml更高效的方式是用kubectl create deployment demo --imagenginx --dry-runclient -o yaml生成模板再在这个基础上改。3. Pod 常用命令实战覆盖日常操作的完整链路3.1 创建与更新apply 和 create 怎么选先明确一个原则日常操作里优先用kubectl apply -f pod.yaml少用kubectl create -f pod.yaml。create是命令式操作文件里描述的资源如果已经存在创建直接报错。而apply是声明式操作K8s 会计算当前实际状态和你提交的期望状态之间的差异然后执行变更。比如修改镜像版本后重新 applyPod 会自动更新。这也是 K8s 整个设计哲学的核心你只声明“最终要什么样”API Server 会帮你收敛到这个状态。如果你想快速临时跑个容器试试还可以用命令直接创建kubectl run nginx --imagenginx:1.27 --restartNever。这条命令本质上是帮你生成一个最新的裸 Pod yaml 然后创建调试场景很好用。3.2 查询与排查get / describe 组合用法部署完 Pod 后第一步通常是kubectl get pods。默认输出列是NAME READY STATUS RESTARTS AGEResponse 里的READY表示“多少个容器就绪 / 多少个容器总共”。几个常用参数-o wide额外显示 Pod 所在的节点 IP、节点名。-n指定命名空间比如-n kube-system。-A所有命名空间。-l按标签过滤比如-l appnginx。-w持续监听变化部署新 Pod 时配合它观察状态流转很直观。而kubectl describe pod name是排查问题时的第一命令。它会显示 Pod 的完整配置摘要、状态、事件Events。事件里通常带着问题线索拉镜像失败、磁盘不足、探针失败、调度失败全都会记录在里面。我自己的排错顺序一直是 describe 在先因为它话最全比一条条猜原因高效得多。3.3 日志与调试logs / exec / port-forward / cpkubectl logs查看日志最常用的参数-f持续跟踪日志输出类似tail -f。--tail200只看最近 200 行。--previous或简写-p当容器重启后查看上一次容器的日志。这在 CrashLoopBackOff 场景里几乎是救命指令因为当前容器还没启动完就崩了拿不到有效日志但上一次崩溃前的日志往往能说明原因。如果 Pod 里有多个容器kubectl logs pod -c container必须指定容器名否则命令会提示你哪个容器有日志。进入容器用kubectl exec -it pod -- /bin/sh。注意有些镜像里没有 bash比如部分精简版容器只有 sh写 bash 会直接报找不到命令。本地调试时kubectl port-forward pod/pod-name 8080:80可以把集群里的 Pod 端口映射到本地浏览器直接访问 localhost:8080 就行。这个命令不依赖 Service最轻量。复制文件用kubectl cpkubectl cp pod-name:pod内路径 本地路径用于把日志和配置文件从容器里拽出来非常实用。3.4 删除与清理优雅删除和强制删除kubectl delete pod pod-name默认走“优雅终止”流程向容器主进程发送 SIGTERM等宽限期默认 30 秒由terminationGracePeriodSeconds控制超时后再发 SIGKILL。这个机制是为了让应用有机会做清理操作比如保存状态、断开连接池。kubectl delete pod pod-name --force --grace-period0是强制删除直接跳过优雅终止。除非集群卡住无法响应否则我不建议日常使用。强制删容易让有状态应用丢数据也会绕过一些清理逻辑。还要记住一件事如果这个 Pod 是 Deployment 或 ReplicaSet 管理的你手动 delete 后控制器马上会创建一个新 Pod 顶上来只有裸 Pod没有控制器管理才是删了就没了。3.5 kubectl 常用命令速查表下面是我平时最常敲的一组直接收藏。操作命令示例说明创建/更新kubectl apply -f pod.yaml声明式推荐日常使用查看列表kubectl get pods -o wide显示 Pod 和所在节点查看详情kubectl describe pod nginx-demo排错第一命令查看完整配置kubectl get pod nginx-demo -o yaml看对象实际状态持续关注kubectl get pods -w实时观察变化看日志kubectl logs -f nginx-demo --tail100实时跟踪看上次日志kubectl logs nginx-demo --previous容器重启后查根因进入容器kubectl exec -it nginx-demo -- /bin/sh交互式 shell端口映射kubectl port-forward pod/nginx-demo 8080:80本地调试复制文件kubectl cp nginx-demo:/etc/nginx/nginx.conf ./容器文件拉取到本地原地修改kubectl edit pod nginx-demo直接编辑对象定义删除kubectl delete -f pod.yaml按文件删除4. 实战演练从零部署一个 Nginx Pod4.1 环境检查与准备动手前先确认集群可用。执行kubectl get nodes如果看到所有节点都处于Ready状态就可以继续了。再执行kubectl get pods -A确认 kube-system 命名空间下的核心组件比如 coredns没有异常避免后续 DNS 或者调度层面出现问题。如果你只是想找个环境练手单节点集群完全够用。之前有读者问单节点 K8s 上怎么跑微服务整套环境其实就是把多个 Deployment 陆续发布核心前提是这台节点能跑、够用本篇的 Pod 实验在单节点上没有任何区别。4.2 编写并应用 Pod yaml把前面示例保存为nginx-pod.yaml然后执行kubectl apply -f nginx-pod.yaml正常会返回pod/nginx-demo created。如果返回invalid或error多半是 yaml 格式问题先检查缩进和字段名。4.3 观察状态变化与事件然后是见证状态的时刻kubectl get pods -w你会看到 Pod 依次经历Pending-ContainerCreating-Running。这三个阶段很有代表性PendingPod 还没被调度到节点上调度器在找工作。卡在这一步基本是资源不足或节点选择条件不满足。ContainerCreating已经找到节点正在拉镜像、启动容器。RunningPod 已经运行但此时还要看READY列如果显示0/1说明 readinessProbe 还没通过。看到Running 1/1后再执行kubectl describe pod nginx-demoEvents 段会有拉镜像Pulling image、成功拉取Successfully pulled image、创建容器Created container、启动容器Started container这串记录。以后排错时你会发现事件链条就是人话版的目标状态收敛过程。4.4 本地访问与更新验证Pod 在集群内本地先通过端口转发访问kubectl port-forward pod/nginx-demo 8080:80另开终端执行curl http://localhost:8080能看到 nginx 默认欢迎页就说明整个链路通了。接着试试更新镜像版本。把 nginx-pod.yaml 里的image从nginx:1.27改成nginx:1.26再执行 apply。Pod 的 image 字段是可变的apply 后 K8s 会重新拉取镜像并重建容器。这时再执行get pods -w能看到容器重启、重新变成 Running 的过程。注意裸 Pod 的更新在多数字段上是受限的这里演示的是个例外生产环境里这种“更新”通常由 Deployment 做滚动发布而不是直接改裸 Pod。4.5 清理环境实验结束后执行kubectl delete -f nginx-pod.yamlPod 会被优雅终止。你写过的这份 yaml 建议保留下一阶段学 Service 时还能拿来当后端。5. Pod 生命周期与控制器搞懂 Pod 的“从生到死”5.1 Pod 的 phase 与容器状态kubectl get pods看到的STATUS列主要对应 Pod 的 phase。官方定义有五种Pending、Running、Succeeded、Failed、Unknown。其中Running不代表业务进程一定健康它只是说容器在跑真正的健康度要看 readinessProbe 是否通过以及容器状态是Running还是Waiting、Terminated。如果你执行kubectl get pod nginx-demo -o yaml在status里能看到更细粒度的描述phase、podIP、startTime、conditions列表初始化的、就绪的、容器就绪的、Pod 调度的以及每个容器的state。这些原始数据是高级排错的重要抓手。5.2 restartPolicy 到底怎么生效spec.restartPolicy有Always、OnFailure、Never三个值默认是Always。很多人刚接触会困惑一个表现容器里的进程正常退出exit code 0为什么 Pod 还是把它拉起来了因为这个策略是“凡退出都要重启”不管退出码是不是 0。如果你想目睹“不重启”的行为可以把 restartPolicy 改成Never然后让容器跑一个sleep 5之类的短命令等它 normal exit 后 Pod 会进入Completed状态再也不会拉起。还要注意当 Pod 被 Deployment 管理时restartPolicy 只能设成Always。Job 这一类对象则可以用Never或OnFailure因为批处理任务天然希望“跑完就结束”。5.3 探针失败会发生什么探针是 K8s 对容器健康的“体检机制”失败后的行为分两种livenessProbe连续失败failureThreshold次kubelet 会杀掉容器并按 restartPolicy 重启。表现就是 Pod 还在但容器重启次数不断增加。readinessProbe连续失败Pod 会从 EndpointsService 的后端地址列表里被摘除也就是暂时没有流量打到它。我遇到过的一类典型案例是 Java 应用启动要 20-30 秒但 livenessProbe 的 initialDelaySeconds 配了 5 秒结果是应用刚启动到一半就被探针判定“死了”进入无休止的 CrashLoopBackOff。解决办法要么调大 initialDelaySeconds要么加 startupProbe给慢启动应用一个保护期。探针参数的核心取舍就是探测太勤容易误杀太疏又拉长了故障发现时间。5.4 为什么生产环境要交给控制器管理裸 Pod 可以理解为“没有老板的员工”它自己完不成自愈、滚动更新、优雅升级。生产环境里我们几乎不会直接创建裸 Pod而是通过 Deployment、StatefulSet、DaemonSet 这些控制器来管理。打个比方Pod 像一辆车Deployment 像车队调度系统车坏了它自动换一辆要升级它滚动替换流量大了它加车流量小了它减车。Deployment 通过spec.selector.matchLabels匹配你给 Pod 打的标签所以 labels 写错或漏写会导致控制器“管不到”你的 Pod。Deployment 的滚动更新能力也是很多微服务场景的基础比如你有一个 Java 微服务需要发布新版本Deployment 默认会先把新 Pod 起来、探活通过后把流量切过去再摘掉旧 Pod整个发布过程对客户端几乎无感。这也是不少项目能实现“不停服迁移”的底层机制。另外需要稳定网络标识和存储的比如数据库、中间件用 StatefulSet每个节点都要跑一个实例的比如日志采集用 DaemonSet。这些控制器以后都会单独展开你只要先记住它们都围绕 Pod 这个核心展开就够了。6. 生产环境 Pod 排错实录从报错到恢复6.1 Pending调度不上去怎么办Pod 一直停在Pending最典型的两个原因节点资源不足或者没有节点满足调度条件。排错靠 describe。如果事件里出现0/2 nodes are available: 2 Insufficient memory说明现在节点剩余内存满足不了 Pod 的 requests需要找台大机器或者调小内存请求。如果出现0/2 nodes are available: 2 node(s) didnt match node selector说明 Pod 里写了 nodeSelector但没有节点带对应标签。还有一种情况是 PVC 绑定失败。Pod 里声明了持久卷但对应 PVC 一直 Pending事件里会有waiting for a volume to be created这类提示。这时候去查kubectl get pvc看存储类是否配置正确、底层存储是否可用。6.2 ImagePullBackOff / ErrImagePull这是新手遇到最多的错误之一表现是 Pod 状态 ImagePullBackOff或者事件里出现 ErrImagePull。原因有几大类镜像地址拼写错误或 tag 不存在。比如nginx:1.99不存在拉取直接 404。私有仓库需要认证。事件里看到 401/403就在 Pod 的spec.imagePullSecrets里引用一个 docker-registry 类型的 Secret。镜像太大拉取超时。网络到镜像仓库不稳定。排查方法kubectl describe pod看事件的明文报错。修复手段依次排查核对镜像名、补 imagePullSecrets、配置镜像加速或自建仓库。这里多说一句生产环境建议把镜像放到公司内网镜像仓库既能规避公网网络抖动也能顺便做漏洞扫描比在应用容器里反复和内网环境斗智斗勇省心得多。6.3 CrashLoopBackOff应用反复重启Pod 创建成功但不断重启状态停在 CrashLoopBackOff。第一次看到这个名字的人可能会慌其实背后的逻辑很直白容器启动后立刻退出kubelet 按 restartPolicy 反复拉起退出的时间间隔不断拉大形成退避。第一步永远是看日志。注意如果容器快速重启kubectl logs pod可能拿到的是空日志这时加--previous看上一个实例的日志往往能找到真正的报错比如连不上数据库、端口被占、配置文件读不到。第二步看状态。如果kubectl describe的事件里出现OOMKilled说明是内存 limits 设太小进程被内核杀掉了调大 limits 或者检查是否存在内存泄漏。还要看是不是 livenessProbe 配置太激进误杀了还在启动期的容器。CrashLoopBackOff 的本质是容器进程活不下来K8s 层面能做的只是如实报告和反复重试所以根因定位必须回到应用侧。不要一看到反复重启就想着删 Pod删了也会重新创建问题依旧。6.4 failed to create pod sandbox运行时与 CNI 出问题这类报错在生产环境非常经典Pod 卡在ContainerCreating事件里出现类似failed to create pod sandbox: rpc error: code Unknown desc failed to create containerd task: ...问题的根因通常不在应用本身而在节点上的容器运行时containerd / cri-dockerd或者 CNI 网络插件。排查顺序建议先看节点状态kubectl get nodes确认节点是否 Ready。看磁盘空间在节点上执行df -h检查/和/var/lib/containerd是否被占满。日志和镜像长期不清理最容易在这里爆掉。看网络组件kubectl get pods -n kube-system确认 flannel/calico 或对应 CNI 的所有 Pod 都处于 Running。如果网络插件 Pod 异常新 Pod 创建 sandbox 时建不出 veth 对。看运行时日志在节点上journalctl -u kubelet搜报错内容对应的关键词。用crictl直接连容器运行时排查crictl ps -a查看沙箱状态crictl logs container-id拉取容器日志。在 Kubernetes 各版本逐渐移除 Docker 依赖后crictl几乎是节点侧排查的必备工具。我遇到过的一次典型情况是节点上/var/lib/containerd磁盘被日志撑满新 Pod 根本建不出 sandbox清理空间后 Pod 立刻创建成功。记住这类问题不是 yaml 能解决的要上节点看运行时。6.5 排错的“三板斧”与深入排查技巧把排错思路固定成一套流程遇到问题不会慌kubectl describe pod name看事件。kubectl logs name --previous看应用日志。kubectl get pod name -o yaml看 status 里的原始状态和条件。这三步解决不了再进入节点侧df -h、journalctl -u kubelet、crictl ps -a。别一上来就删 Pod删掉只会丢失现场。还可以用kubectl get events --sort-by.lastTimestamp拉取集群事件按时间排序看问题发生前后还伴随了哪些异常。这种方式在多个 Pod 同时异常时特别好用能帮你把“哪台节点先出问题”串起来。集群证书过期这类周期性问题不算常见但一旦发生现象往往是所有资源访问报错排查相对复杂这个主题适合单独写一篇这里就不展开了。最后再分享一个我自己早期的教训刚学 K8s 时习惯把 Pod 当作一个持久运行的“小虚拟机”进去装这装那后来才意识到 Pod 的哲学是“永续循环和声明式期望”容器里的一切都不是持久资产。理解了这点很多看似奇怪的行为容器重启、IP 不变、yaml 里改个字段整个重建就都顺理成章了。建议你手头常备kubectl explain多写多试多 deletePod 这点事很快就能摸透。下一篇文章我可以接着写它们怎么通过 Service 暴露给外部流量先把这篇里的 nginx-demo 留着到时候直接拿来当后端。