K8s核心YAML实战：Pod、Deployment、Service配置详解与避坑指南

1. 为什么每个运维人都绕不开 YAML 这道坎

刚接触容器编排那会儿，我最头疼的不是命令记不住，而是那一堆缩进严格的配置文件。少一个空格、多一个冒号，整个部署就卡在那里不动，报错信息还特别含糊。后来用多了才明白，YAML 不是简单的配置格式，它是整个集群的“施工图纸”——你写的每一行，最终都会变成集群里真实运行的容器、网络规则和调度策略。

这篇文章我想把 Pod、Deployment、Service 这三类最核心的 YAML 文件彻底讲透。它们分别对应三个最基本的问题：跑什么、跑几个、怎么访问。不管你是刚入门的开发，还是需要自己维护测试环境的运维，只要你在用容器编排平台，这三个对象就是你每天都要打交道的。我会从字段含义、参数取值、实际踩坑经验三个层面展开，尽量让你看完就能直接抄作业，而不是对着官方文档一行行猜。

先给个整体认知：Pod 是最小调度单元，Deployment 管 Pod 的副本和滚动更新，Service 给一组 Pod 提供稳定的访问入口。三者层层嵌套，YAML 写得好不好，直接决定了你的服务能不能稳定跑起来、能不能平滑升级、能不能被正确访问到。下面我按这个逻辑顺序，把每个对象的 YAML 掰开揉碎讲。

2. Pod 的 YAML 到底在描述什么

2.1 Pod 是最小单元，但它通常不单独用

很多人第一次写 YAML 就是写 Pod，写完kubectl apply一下，看到容器跑起来就以为学会了。但实际生产中，你几乎不会直接创建裸 Pod。原因很简单：裸 Pod 没有自愈能力，节点挂了它就没了，也不会自动重启或迁移。它更适合用来做临时调试、跑一次性任务，或者作为理解 Deployment 的基础。

不过理解 Pod 的 YAML 结构非常关键，因为 Deployment、StatefulSet、DaemonSet 这些控制器的模板部分，本质上就是在描述 Pod。你把 Pod 的字段搞清楚了，后面那些控制器就是加了一层“管理逻辑”而已。

一个最基础的 Pod YAML 长这样：

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

看起来简单，但每个字段都有讲究。apiVersion和kind决定了这个资源对象的类型，metadata里放名称和标签，spec才是真正的“规格说明”。标签这块我要多提一句：labels 是后续 Service 选中 Pod 的唯一依据，写错了标签，Service 就找不到后端，这是新手最常犯的错误之一。

2.2 容器字段里的那些关键参数

spec.containers是一个列表，意味着一个 Pod 里可以跑多个容器。这里有个经典模式叫Sidecar，比如一个容器跑主业务，另一个容器负责收集日志或做网络代理。它们共享同一个网络命名空间，所以可以用localhost互相通信，这是 Pod 多容器设计最大的价值。

镜像拉取策略imagePullPolicy有三个取值：Always、IfNotPresent、Never。默认情况下，如果镜像标签是latest，策略就是Always；如果是具体版本号，就是IfNotPresent。我个人的建议是永远不要用 latest 标签，因为每次拉取行为不一致，回滚的时候你根本不知道上一个版本是什么。用固定版本号，配合IfNotPresent，既稳定又省拉取时间。

资源限制这块也是重灾区。resources.requests是调度依据，resources.limits是硬上限。我见过太多人只写 limits 不写 requests，结果调度器不知道该怎么分配节点，Pod 要么起不来，要么被随机塞到资源紧张的节点上。正确的做法是两个都写，而且 requests 要略低于 limits，给突发流量留一点缓冲。

resources: requests: memory: "128Mi" cpu: "100m" limits: memory: "256Mi" cpu: "500m"

这里的100m表示 0.1 个 CPU 核心，Mi是二进制兆字节。内存单位千万别写成M，虽然有些场景能识别，但Mi才是标准写法，避免歧义。

2.3 探针配置决定 Pod 的“健康判定”

探针是我认为 Pod YAML 里最值得花时间研究的字段。它分三种：livenessProbe、readinessProbe、startupProbe。很多人只配一个 liveness，结果服务启动慢的时候被反复重启，陷入死循环。

• livenessProbe：判断容器是否活着，失败就重启容器。
• readinessProbe：判断容器是否准备好接收流量，失败就从 Service 后端摘除。
• startupProbe：判断容器是否启动完成，成功之前不执行其他探针。

对于启动慢的应用，一定要配 startupProbe，把failureThreshold设大一点，比如 30 次，每次间隔 10 秒，给足 5 分钟启动时间。启动成功后，liveness 和 readiness 才开始工作。这样就不会出现“服务还在初始化就被判定死亡”的尴尬情况。

探针的检查方式也有三种：httpGet、tcpSocket、exec。HTTP 接口最常用，但要注意路径不能是需要认证的接口，否则永远返回 401，探针一直失败。TCP 适合数据库这类没有 HTTP 接口的服务。exec 最灵活，但每次执行都会产生进程开销，频率别设太高。

提示：探针的initialDelaySeconds不要设得太小，尤其是 Java 应用，类加载就要几十秒。我一般会先设 30 秒起步，观察日志后再调整。

3. Deployment：让 Pod 真正具备生产可用性

3.1 Deployment 解决了裸 Pod 的哪些致命问题

裸 Pod 最大的问题是没有副本管理、没有自愈、没有滚动更新。Deployment 的出现就是为了解决这三个问题。它通过 ReplicaSet 来管理 Pod 副本数，通过控制器循环不断对比“期望状态”和“实际状态”，一旦发现 Pod 数量不对，就自动创建或删除，直到两者一致。

这意味着你声明replicas: 3，Deployment 就会保证任何时候都有 3 个 Pod 在跑。某个节点挂了，它会在其他节点上重新拉起 Pod。你要升级镜像，它支持滚动更新，一个一个替换，保证服务不中断。你要回滚，一条命令就能回到上一个版本。这些能力在生产环境里是刚需，所以Deployment 才是无状态服务最常用的控制器。

3.2 Deployment YAML 的骨架与关键字段

一个典型的 Deployment YAML 结构如下：

apiVersion: apps/v1 kind: Deployment metadata: name: demo-deployment labels: app: demo spec: replicas: 3 selector: matchLabels: app: demo strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 maxUnavailable: 0 template: metadata: labels: app: demo spec: containers: - name: demo-container image: nginx:1.25 ports: - containerPort: 80

这里有几个字段需要重点解释。selector.matchLabels必须和template.metadata.labels匹配，否则 Deployment 不知道要管理哪些 Pod。这个匹配关系是强制的，写错了直接报错。strategy定义更新策略，RollingUpdate是默认值，也是推荐值。maxSurge表示更新过程中最多可以超出期望副本数的 Pod 数量，maxUnavailable表示最多可以有多少个 Pod 不可用。

我一般会把maxUnavailable设为 0，maxSurge设为 1。这样更新时先创建新 Pod，等新 Pod 就绪后再删除旧 Pod，全程保证可用副本数不低于期望值。代价是需要额外资源，但换来的是零中断，对于在线服务来说非常值得。

3.3 滚动更新参数的计算与实战取舍

假设你有 6 个副本，maxSurge: 1，maxUnavailable: 0。更新开始后，Deployment 会先创建一个新 Pod，此时总 Pod 数为 7，可用数为 6。新 Pod 就绪后，删除一个旧 Pod，总数回到 6，可用数还是 6。如此循环，直到全部替换完成。整个过程可用副本数始终不低于 6，服务容量不下降。

如果资源紧张，可以把maxSurge设为 0，maxUnavailable设为 1。这样更新时先删一个旧 Pod，再创建一个新 Pod，总资源占用不变，但可用副本数会短暂降到 5。对于内部服务或能容忍短暂容量下降的场景，这种配置更省资源。

还有一个字段叫minReadySeconds，表示新 Pod 就绪后要等多少秒才认为它真正可用。默认是 0，意味着 Pod 一就绪就继续下一步。我建议至少设 5 到 10 秒，给应用一点预热时间，避免刚启动就被流量打满导致崩溃。

注意：progressDeadlineSeconds默认是 600 秒，如果更新超过这个时间还没完成，Deployment 会标记为失败。对于大镜像或慢启动应用，要适当调大这个值，否则更新会被中断。

3.4 版本回滚与历史记录管理

Deployment 默认保留 10 个历史版本，通过revisionHistoryLimit控制。每次更新镜像或修改模板，都会生成一个新的 ReplicaSet，对应一个版本。回滚的时候，Deployment 会找到上一个 ReplicaSet，把副本数调上去，把当前 ReplicaSet 调下来，实现快速回退。

这里有个坑：如果你只改了副本数，不会生成新版本。只有修改了 Pod 模板（比如镜像、环境变量、资源限制），才会触发新版本。所以回滚的时候，副本数的变化不会被回滚，这点要心里有数。

查看历史版本用kubectl rollout history deployment/demo-deployment，回滚用kubectl rollout undo deployment/demo-deployment。如果要回滚到指定版本，加--to-revision参数。我一般会在更新前先记录当前版本号，出问题能快速定位。

4. Service：给动态 Pod 一个固定入口

4.1 Service 存在的意义与四种类型

Pod 的 IP 是动态的，重启就变，而且多个副本的 IP 各不相同。前端服务不可能每次都去查后端 Pod 的 IP 列表，所以需要一个稳定的虚拟 IP 和 DNS 名称来屏蔽后端的动态变化。Service 就是干这个的：它通过标签选择器找到一组 Pod，为它们提供一个统一的访问入口，并自动做负载均衡。

Service 有四种类型，适用场景完全不同：

ClusterIP 是默认类型，也是用得最多的。NodePort 会在每个节点上开一个端口，范围默认是 30000 到 32767，外部通过节点IP:端口访问。LoadBalancer 需要云厂商支持，会自动创建一个外部负载均衡器，成本较高但最省心。ExternalName 比较特殊，它不做代理，只是返回一个 CNAME 记录，适合把外部数据库映射成集群内的服务名。

4.2 ClusterIP 与标签选择器的配合细节

一个标准的 ClusterIP Service YAML：

apiVersion: v1 kind: Service metadata: name: demo-service spec: type: ClusterIP selector: app: demo ports: - name: http protocol: TCP port: 80 targetPort: 8080

selector里的app: demo必须和 Pod 模板里的标签一致，否则 Endpoints 列表为空，Service 找不到后端。port是 Service 对外暴露的端口，targetPort是容器实际监听的端口。两者可以不同，比如 Service 暴露 80，容器监听 8080，这样外部访问不用关心容器内部端口。

targetPort还可以写成名称，比如targetPort: http，然后在容器里给端口起个名字name: http。这样做的好处是，即使容器端口号变了，只要名字不变，Service 就不用改。对于多端口 Pod，这种命名方式尤其清晰。

4.3 NodePort 的端口分配与访问链路

NodePort 在 ClusterIP 的基础上，额外在每个节点上开一个端口。外部请求先到节点 IP 的 NodePort，然后转发到 Service 的 ClusterIP，再转发到 Pod 的 targetPort。这条链路里，kube-proxy 负责维护转发规则，iptables 或 ipvs 模式会影响性能和连接保持行为。

spec: type: NodePort ports: - port: 80 targetPort: 8080 nodePort: 30080

nodePort不写的话，系统会在 30000 到 32767 之间随机分配一个。我建议在测试环境手动指定，方便记忆和防火墙配置。但要注意端口冲突，同一个节点上不能有两个 Service 用同一个 nodePort。

提示：NodePort 模式下，如果节点有公网 IP，服务就直接暴露在公网了。生产环境一定要配合网络策略或防火墙规则，只放行必要的来源 IP。

4.4 Service 与 Endpoints 的联动机制

Service 本身不直接管理 Pod，它通过 Endpoints 对象来记录后端 Pod 的 IP 和端口。当你创建 Service 时，控制器会根据标签选择器找到匹配的 Pod，把它们的 IP 和 targetPort 写入 Endpoints。Pod 就绪探针失败时，会被从 Endpoints 中移除，流量就不会打到未就绪的 Pod 上。

你可以用kubectl get endpoints demo-service查看当前后端列表。如果发现 Endpoints 为空，基本就是标签选择器写错了，或者 Pod 没有就绪。这是排查 Service 不通问题的第一步，比看日志快得多。

另外，无选择器的 Service 不会自动创建 Endpoints，需要手动创建 Endpoints 对象来指向外部服务。这种用法比较少见，但在迁移传统应用时偶尔会用到。

5. 三类 YAML 的联动与完整部署示例

5.1 从零搭建一个可访问的 Web 服务

把前面三部分串起来，一个完整的部署流程是这样的：先写 Deployment，定义 Pod 模板和副本数；再写 Service，通过标签选中 Pod；最后应用两个 YAML，验证访问。

apiVersion: apps/v1 kind: Deployment metadata: name: web-deployment spec: replicas: 2 selector: matchLabels: app: web template: metadata: labels: app: web spec: containers: - name: web image: nginx:1.25 ports: - containerPort: 80 readinessProbe: httpGet: path: / port: 80 initialDelaySeconds: 5 periodSeconds: 10 --- apiVersion: v1 kind: Service metadata: name: web-service spec: type: NodePort selector: app: web ports: - port: 80 targetPort: 80 nodePort: 30080

应用之后，用kubectl get pods看到两个 Running 的 Pod，用kubectl get svc看到 web-service 的 NodePort 是 30080。然后通过任意节点的 IP 加 30080 就能访问到 Nginx 页面。如果访问不通，先查 Endpoints，再查 Pod 就绪状态，最后查网络策略和防火墙。

5.2 标签与选择器不一致的典型故障

我遇到过好几次 Service 创建了但访问不通，最后发现都是标签问题。比如 Deployment 模板里写的是app: web，Service 选择器写的是app: web-server，差一个单词，Endpoints 就是空的。这种错误不会报错，Service 正常创建，但就是没后端。

排查方法很简单：kubectl describe svc web-service看 Endpoints 那一行，如果是<none>，就去检查标签。kubectl get pods --show-labels可以列出所有 Pod 的标签，对比一下就能发现不一致的地方。

还有一种情况是 Pod 没有就绪。readinessProbe 失败时，Pod 虽然 Running，但不会加入 Endpoints。这时候要看kubectl describe pod里的 Events 和探针状态，确认是路径不对、端口不对还是启动太慢。

5.3 资源限制与调度失败的关联

Pod 一直 Pending，最常见的原因是资源不足。kubectl describe pod会显示Insufficient cpu或Insufficient memory。这时候要么调低 requests，要么扩容节点。但调低 requests 要谨慎，设得太低会导致节点超卖，多个 Pod 争抢资源，性能急剧下降。

我的经验是，requests 按应用正常负载的 70% 设置，limits 按峰值负载的 120% 设置。这样既保证调度器有足够信息做决策，又给突发流量留了余量。对于内存，limits 不要设得比 requests 高太多，因为内存是不可压缩资源，超限会被 OOM Kill，而不是像 CPU 那样被限流。

6. 实操中容易踩的坑与排查清单

6.1 YAML 缩进与格式的常见错误

YAML 对缩进极其敏感，只能用空格，不能用 Tab。我见过有人从网页复制 YAML，里面混了 Tab，应用时报error converting YAML to JSON，找半天找不到原因。建议编辑器统一设置成 2 个空格缩进，并且开启显示空白字符。

冒号后面必须跟一个空格，key:value是错的，key: value才对。列表项前面的短横线后面也要有空格。多行字符串用|保留换行，用>折叠换行，这两个符号在写配置文件时很有用，但容易混淆。

还有一个坑是布尔值。YAML 里yes、no、on、off都会被解析成布尔值，如果你本意是字符串，要加引号。比如环境变量value: "no"，不加引号就变成false了。

6.2 镜像拉取失败的排查思路

ImagePullBackOff是另一个高频问题。原因通常有三个：镜像名写错、标签不存在、私有仓库认证失败。先用docker pull在本地试一下，确认镜像能拉下来。如果是私有仓库，要创建 Secret 并在 Pod 里引用imagePullSecrets。

Secret 的创建命令是kubectl create secret docker-registry，需要提供仓库地址、用户名、密码和邮箱。创建后在 Pod 的spec里加imagePullSecrets: - name: 你的secret名。注意 Secret 必须和 Pod 在同一个命名空间，跨命名空间不会生效。

6.3 服务访问不通的分层排查法

Service 访问不通，我一般按这个顺序排查：

1. 查 Endpoints：kubectl get endpoints，为空就是标签或就绪问题。
2. 查 Pod 状态：kubectl get pods，不是 Running 就先解决 Pod 问题。
3. 查探针：kubectl describe pod，看 readiness 是否通过。
4. 查端口：确认targetPort和容器实际监听端口一致。
5. 查网络策略：如果有 NetworkPolicy，确认是否放行了流量。
6. 查节点防火墙：NodePort 模式下，节点防火墙可能拦截了端口。

这个顺序从内到外，基本能覆盖 90% 的访问问题。每次排查完，把原因记下来，下次遇到类似现象就能快速定位。

6.4 常见问题速查表

提示：kubectl rollout status可以实时查看更新进度，卡住的时候会告诉你当前卡在哪个副本上，比干等强得多。

7. 我个人的一些配置习惯与建议

写了这么多 YAML，我慢慢形成了一套自己的习惯。首先是所有资源都加标签，除了app，我还会加version、env、team这些标签，方便批量查询和监控分组。标签设计得好，后面做灰度发布、流量切分都会轻松很多。

其次是资源限制必写，而且 requests 和 limits 都要写。我见过太多因为没写 limits 导致单个 Pod 吃满节点内存，把其他服务挤挂的案例。宁可一开始设得保守一点，观察监控后再逐步调整，也不要留空。

第三是探针必配，尤其是 readinessProbe。没有就绪探针，Service 会把流量打到还没启动完成的 Pod 上，用户看到的就是 502。配了就绪探针，Pod 真正能处理请求了才加入后端，体验完全不一样。

最后是版本号固定，永远不用 latest。每次更新都改镜像标签，配合 Deployment 的滚动更新和回滚能力，出问题能秒级回退。这个习惯让我在多次线上故障中都能快速恢复，强烈推荐。

另外，我建议把 YAML 文件纳入版本管理，和代码一起提交。每次变更都有记录，谁改的、改了什么、为什么改，一目了然。配合 CI 流水线做自动部署，比手动kubectl apply可靠得多。刚开始可能觉得麻烦，但一旦团队规模上来，这套流程能省下大量沟通和排查时间。

如果你刚开始学，建议先在本地用轻量级集群工具搭个环境，把这三个 YAML 亲手写一遍、跑一遍、改错一遍。看十篇文章不如自己踩一次坑，尤其是标签不匹配和探针配置这两个点，亲手试过之后印象会深刻得多。