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: 3Deployment 就会保证任何时候都有 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设为 0maxSurge设为 1。这样更新时先创建新 Pod等新 Pod 就绪后再删除旧 Pod全程保证可用副本数不低于期望值。代价是需要额外资源但换来的是零中断对于在线服务来说非常值得。3.3 滚动更新参数的计算与实战取舍假设你有 6 个副本maxSurge: 1maxUnavailable: 0。更新开始后Deployment 会先创建一个新 Pod此时总 Pod 数为 7可用数为 6。新 Pod 就绪后删除一个旧 Pod总数回到 6可用数还是 6。如此循环直到全部替换完成。整个过程可用副本数始终不低于 6服务容量不下降。如果资源紧张可以把maxSurge设为 0maxUnavailable设为 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集群外部通过节点 IP 访问测试环境暴露服务LoadBalancer外部负载均衡器云环境生产服务ExternalName映射到外部 DNS访问外部依赖ClusterIP 是默认类型也是用得最多的。NodePort 会在每个节点上开一个端口范围默认是 30000 到 32767外部通过节点IP:端口访问。LoadBalancer 需要云厂商支持会自动创建一个外部负载均衡器成本较高但最省心。ExternalName 比较特殊它不做代理只是返回一个 CNAME 记录适合把外部数据库映射成集群内的服务名。4.2 ClusterIP 与标签选择器的配合细节一个标准的 ClusterIP Service YAMLapiVersion: v1 kind: Service metadata: name: demo-service spec: type: ClusterIP selector: app: demo ports: - name: http protocol: TCP port: 80 targetPort: 8080selector里的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: 30080nodePort不写的话系统会在 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: webService 选择器写的是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 访问不通我一般按这个顺序排查查 Endpointskubectl get endpoints为空就是标签或就绪问题。查 Pod 状态kubectl get pods不是 Running 就先解决 Pod 问题。查探针kubectl describe pod看 readiness 是否通过。查端口确认targetPort和容器实际监听端口一致。查网络策略如果有 NetworkPolicy确认是否放行了流量。查节点防火墙NodePort 模式下节点防火墙可能拦截了端口。这个顺序从内到外基本能覆盖 90% 的访问问题。每次排查完把原因记下来下次遇到类似现象就能快速定位。6.4 常见问题速查表现象可能原因快速验证Pod Pending资源不足或节点亲和性不满足kubectl describe pod看 EventsImagePullBackOff镜像名错、标签不存在、认证失败本地docker pull测试CrashLoopBackOff应用启动报错或探针配置不当kubectl logs看容器日志Service 无 Endpoints标签选择器不匹配或 Pod 未就绪kubectl get endpointsNodePort 访问不通防火墙拦截或端口冲突节点上curl localhost:nodePort滚动更新卡住新 Pod 起不来或就绪探针失败kubectl rollout status提示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 亲手写一遍、跑一遍、改错一遍。看十篇文章不如自己踩一次坑尤其是标签不匹配和探针配置这两个点亲手试过之后印象会深刻得多。