聊到 Kubernetes 项目实战很多人第一反应是YAML 太繁琐、生命周期太抽象。确实Pod、Deployment、Service 这些概念拆开看每个都能找到文档可真要独立负责一个项目的上线、升级、回滚、下线就会发现零散的知识根本拼不成一张完整的地图。这篇文章我打算聚焦两件事项目生命周期管理和 yml 文件编写。前者解决一个项目从部署到销毁要经历哪些阶段、每个阶段该做什么的问题后者解决这些动作到底怎么写进 Kubernetes 资源清单、字段之间有什么隐含关系的问题。适合已经能把容器跑起来、但还没独立编排过整套应用的同学参考也适合想把自己团队的发布流程规范化的运维同事。1. 项目生命周期管理到底在管什么第一次接触 Kubernetes 的人最容易困惑项目生命周期管理这个词听着像在讲 DevOps 流程可又总看到 Pod 有 Pending、Running 这些状态到底指的是哪一个我的理解是这里的生命周期有两层含义并且两层都得管。一层是业务项目本身从代码到版本上线、迭代、下线的完整过程另一层是运行时资源对象的状态变化。Kubernetes 的核心思想是声明式管理你描述期望状态系统负责把实际状态对齐。所以项目生命周期的一切动作本质上都是围绕期望状态的变化展开的。1.1 一条代码从提交到运行的完整链路一个项目要从代码变成 Kubernetes 里正在运行的服务至少要经历这几步代码提交到 Git触发 CI 构建产出带版本号的容器镜像推送到镜像仓库然后编写或更新 YAML 资源清单执行 kubectl apply最后由 kubelet 拉取镜像并启动容器。这条链路里Kubernetes 只负责后半程也就是从你提交 YAML 到 Pod 真正运行起来这一段。理解了这个边界你就不容易甩错锅镜像没构建出来、仓库权限不对、镜像 tag 写错这些问题 YAML 定义得再规范也没用。很多团队排查问题喜欢盯着集群里的状态看却忽略了源头可能根本不在集群里。后半程里有一个容易忽略的关键点Kubernetes 不会主动去发布你的代码它只负责持续维护你声明的那份期望状态。比如你定义了 replicas: 3它就保证集群里正好有 3 个副本某个节点挂了导致只剩 2 个它会自动在其他节点重新调度。这也是生命周期管理的基础机制由控制器协调持续修正实际状态与期望状态的偏差。理解了这个后面各种升级策略、回滚操作就都顺理成章了。反过来说如果你在 YAML 里声明了错误的配置Kubernetes 也会忠实地帮你把错误状态维持住而不是替你纠错这也是为什么资源清单的编写规范如此重要。1.2 运行阶段的管理动作更新、扩容、回滚、下线项目上线之后日常管理动作主要围绕四件事更新、扩容、回滚、下线。更新最常见的做法是改镜像 tag再执行 kubectl apply。默认策略是滚动更新Deployment 会先起一个新的 Pod等它通过 readiness 探针后再停掉一个旧的逐个替换避免服务中断。扩容则分两种手动改 replicas或者配置 HPAHorizontal Pod Autoscaler让系统根据 CPU、内存或自定义指标自动伸缩。我建议项目初期先手动管理副本数摸清流量峰值规律后再上 HPA否则容易出现频繁扩缩容带来的抖动。很多团队一上来就配了很激进的 HPA 策略结果业务请求量平缓时副本数照样上下乱跳日志里全是扩容记录。回滚是所有运维动作里最需要肌肉记忆的。发布前务必执行 kubectl rollout history deployment/名字 把版本基线记录下来万一新版本有问题kubectl rollout undo deployment/名字 --to-revision版本号 就能回到上一个稳定版本。这里有个细节回滚不仅动容器镜像还会连带回滚这次发布附带的启动参数、环境变量等变更所以不要把临时排障用的手动改动和正式发布混在一次 apply 里。最后是下线很多团队忽略这个动作的生命周期属性。删除 Deployment 只是停止副本Service、Ingress、ConfigMap、Secret 还要分别清理涉及持久化存储时要先确认 PV 的回收策略否则数据可能被自动删除也可能变成无人认领的僵尸卷这个优先级我会在第 4.4 节专门展开。其实说到这你会发现生命周期管理的核心不在某个命令而是一套先声明、再校验、后操作的习惯。kubectl 给了很多便捷操作但便捷操作如果跳过了资源描述文件项目状态就会逐渐失控。比如临时用 kubectl scale 扩到 10 个副本但 YAML 里还写着 3下次有人 apply 一下就又缩回去了这种配置漂移在团队协作里非常常见。所以生命周期管理做得好不好很大程度取决于你的 YAML 文件能不能被团队稳定复用。这就自然过渡到本文的后半部分yml 文件编写。2. 读懂 YAMLK8s 资源清单的底层逻辑很多朋友一看到 YAML 就头大觉得格式要求太严格多一个空格就报错。但实际上 YAML 的语法非常少真正难的是理解 Kubernetes 的资源模型什么样的资源对象对应什么样的生命周期字段之间有哪些隐含约束。你可以把资源模型想成一张项目审批表apiVersion 是表格模板的版本kind 是表格类型metadata 是表头信息spec 是你要填的业务内容。搞清楚这个再看任何 YAML 都不会晕。Kubernetes 里几乎所有资源的定义都遵循同一套骨架熟悉一个对象之后其他对象能很快举一反三。2.1 YAML 基础语法与 Kubernetes 约定YAML 本身只依赖三个核心规则缩进表示层级、冒号后必须带空格、短横线表示列表项。Kubernetes 对缩进还有一个强制约定必须使用空格不能用 Tab。我见过不少线上事故是从一个 Tab 混入文件开始的。还有一个容易踩的坑是字符串和数字的区分像 replicas: 3 不加引号Kubernetes 会按整数解析如果写成 replicas: 3某些工具会把它当字符串虽然 Deployment 能容忍但转换逻辑链一长就容易出问题。我的建议是严格区分数字不加引号带特殊字符的字符串加单引号多行文本用竖线 | 保留换行。除语法之外Kubernetes 还约定了一些资源对象的固定字段。apiVersion 不是随意填的apps/v1、v1、networking.k8s.io/v1 各自对应不同资源类别旧版本字段在新集群上可能需要转换。metadata.name 在同 namespace 下必须唯一且对象创建后大多不可改名所以命名最好一开始就建立规范比如 应用名-组件名。Selector 和标签labels是 Kubernetes 的寻址系统Deployment 的 selector.matchLabels 必须包含 template.metadata.labels 里的字段否则创建资源时就会校验失败。这也是新手写 YAML 最常见的报错来源之一后面第 4.1 节我会给出具体的排查办法。2.2 Deployment项目运行的指挥官Deployment 是绝大多数无状态项目的主力资源对象它本身不直接创建容器而是通过管理 ReplicaSet 来间接管理 Pod。为什么要中间再加一层 ReplicaSet因为滚动更新时 Deployment 需要保留历史版本每个版本的 Pod 模板都会对应一个独立的 ReplicaSet回滚时直接把对应 ReplicaSet 的副本数调上去即可。理解了这层结构你就能看懂为什么执行 kubectl get rs 时会有多个 ReplicaSet 同时存在它们其实代表着一次次的发布历史。这个设计是 Kubernetes 实现版本控制的关键比简单地重启容器要可靠得多。Deployment 的核心字段我逐个说。spec.replicas 是期望副本数取值可以是 0常用于暂时停止服务但保留资源定义spec.selector 用于关联 Pod 模板创建后基本不能修改spec.template 里定义了 Pod 的模板其中 metadata.labels 必须与 selector 匹配spec.containers 列表里至少有一个容器每个容器必须定义 name 和 image。image 的 tag 建议写全不要用 latest否则无法精确回滚到某个镜像版本。还有两个发布关键参数在 spec.strategy 下rollingUpdate.maxSurge 表示更新期间最多能多出多少个临时 PodmaxUnavailable 表示最多允许多少个旧 Pod 不可用。默认值分别是 25% 和 25%意思是每次滚动至少保留 75% 的副本可用同时最多临时启动 25% 的新副本。如果副本数是 3更新时会先起 1 个新 Pod等它 ready 后再逐个替换旧的。探针配置直接影响生命周期里的存活判断。livenessProbe 决定容器是否需要被重启比如进程僵死但端口还在监听时靠它兜底readinessProbe 决定 Pod 是否被纳入 Service 的流量转发它没通过时不代表 Pod 要重启而是流量先不给它。我强烈建议生产环境至少配 readinessProbe否则滚动更新会出现一种危险情况旧 Pod 已经被删除、新 Pod 还没真正就绪Service 后端的可用实例数瞬间掉到很低甚至触发大规模 5xx。这个问题我会在第 4.3 节用真实案例展开讲它值得每个负责发布的同学重视。2.3 Service 与 Ingress流量入口的编排Pod 是临时对象IP 地址会随重建变化所以项目对外提供访问必须通过 Service 做稳定入口。Service 通过 selector 匹配一组 Pod将流量负载均衡到这些 Pod 上。type 字段有几种选择ClusterIP 只在集群内部可达常用于服务间调用NodePort 会在每个节点上开一个端口用于简单外部访问LoadBalancer 则对接云厂商负载均衡器。企业项目里最常见的组合是集群内部用 ClusterIP外部统一走 Ingress 接入 HTTP 流量再转发到各 Service。这个分层设计把服务发现和流量治理拆开了比在应用代码里写死 IP 或者用笨重的端口映射要容易维护得多。Ingress 资源定义的是转发规则真正干活的是集群里的 Ingress Controller比如 nginx-ingress 或 traefik。写 Ingress YAML 时要注意 path 的匹配规则比如 prefix 类型会做前缀匹配/api 能同时匹配 /api/order 和 /api/user如果路由规则写不当可能把两个服务的流量串到一处。我也建议在企业项目里为每个服务单独定义一条 Ingress 规则不要一股脑把所有规则堆在同一个 Ingress 对象里否则后续改路由时很容易误伤其他服务。近几年也有 Gateway API 作为下一代替代方案但对大部分项目而言Ingress 已经足够适用不必为了追新而更换基础设施。3. 一步步写出一套可用的项目 YAML前面讲了原理这一节进入实操。我的核心建议是不要从记事本空手写 YAML先用 kubectl 的 dry-run 生成骨架再手动补字段。原因有两个一是生成的骨架能保证 apiVersion、kind、metadata、spec 等最外层结构完全标准避免低级语法错误二是手动补字段时你对每个字段的理解会更扎实。等到你对常用资源和字段足够熟悉后再回到手写完全没问题。团队协作阶段我还会用 kubectl apply --dry-runserver 做预校验这一步能拦截大部分会被集群拒绝的错误配置省下不少无效 apply 的时间。3.1 从 dry-run 生成骨架开始先准备一个最小可用的示例。假设团队要上线一个名为 order-service 的订单服务镜像在私有仓库端口是 8080。执行下面这条命令Kubernetes 会帮你生成一个 Deployment 的 YAML 骨架kubectl create deployment order-service --imageregistry.example.com/order-service:v1.0.0 --dry-runclient -o yaml deployment.yaml注意 --dry-runclient 表示只在本地生成不会真的在集群创建资源加上 -o yaml 后输出结果是 YAML 格式。生成后打开文件你会看到 apiVersion、kind、metadata、spec.template 等结构但 replicas、resources、探针这些字段还需要自己补。这里有一个很多人忽略的点create deployment 生成的是单副本如果你要部署三副本记得补 spec.replicas: 3如果你用的是较新版本的 kubectl生成的 Deployment 里默认带了一个 pod-template-hash 的标签不要随意改动它。补全后的 Deployment 示例大概长这样apiVersion: apps/v1 kind: Deployment metadata: name: order-service namespace: production labels: app: order-service spec: replicas: 3 selector: matchLabels: app: order-service strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 maxUnavailable: 0 template: metadata: labels: app: order-service spec: containers: - name: order-service image: registry.example.com/order-service:v1.0.0 ports: - containerPort: 8080 resources: requests: cpu: 500m memory: 512Mi limits: cpu: 1 memory: 1Gi readinessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 10 periodSeconds: 5提示strategy 里的 maxSurge: 1、maxUnavailable: 0 是我比较推荐的配置组合表示先多起一个新副本等它健康后再停旧副本保证发布期间服务不降级代价是发布期间会短暂占用额外资源。如果集群资源紧张可以用默认的 25%/25% 配置。关于 resources 字段我要多说两句。requests 是调度依据Kubernetes 调度器会按它判断节点是否有足够资源limits 是运行限制超过可能触发容器被杀死或 CPU 限流。建议 requests 和 limits 的比值不要拉太大比如 CPU 的 limits 写成 1 但 requests 只有 100m会导致节点资源被大量预留但实际用量极低浪费集群容量。内存方面如果容器内存超过 limits可能会被 OOMKilled业务方就会反复重启这种问题最不好排查所以内存的 limits 要给业务留出合理余量建议先压测摸清基线再定值。3.2 配套 ConfigMap、Service、Ingress 的组合一个项目通常不止 Deployment 一个资源还需要把配置、网络入口组织起来。配置类内容建议放 ConfigMap避免把环境变量硬编码在镜像或 Deployment 里。比如 order-service 的 Spring Boot 配置文件可以单独写成 ConfigMapapiVersion: v1 kind: ConfigMap metadata: name: order-service-config namespace: production data: application.yml: | server: port: 8080 spring: datasource: url: jdbc:mysql://mysql-service:3306/order username: order password: ${DB_PASSWORD}然后在 Deployment 的容器 spec 里通过 volumeMounts 挂载或通过 envFrom 注入。这里要特别注意ConfigMap 内容更新后Pod 里的文件内容会自动同步有延迟但环境变量不会自动更新如果你用 envFrom 方式注入配置修改 ConfigMap 后必须手动触发一次滚动更新。常见做法是在 Deployment 的 template.metadata.annotations 里加一个 configMap 的 hash 值比如 checksum/config: sha256:xxxConfigMap 内容一变就改这个 hashapply 后自动触发滚动发布。这个小技巧能避免配置改了但服务还在用旧配置的经典事故。Service 是流量入口。order-service 内部端口是 8080其他服务调用它时希望统一走 80 端口可以在 Service 里做端口映射apiVersion: v1 kind: Service metadata: name: order-service namespace: production spec: selector: app: order-service ports: - name: http port: 80 targetPort: 8080 type: ClusterIPselector 必须能匹配到 Deployment 创建的 Pod 标签否则 Service 后端为空访问会超时。检查方式很简单kubectl get endpoints order-service -n production如果 ENDPOINTS 列为空说明标签没匹配上。最后是 Ingress如果订单服务需要被外部域名访问可以配一条规则apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: order-service namespace: production spec: rules: - host: order.example.com http: paths: - path: / pathType: Prefix backend: service: name: order-service port: number: 80这段配置的含义是访问 order.example.com 的请求由 Ingress Controller 转发到名为 order-service 的 Service 的 80 端口。如果你在集群里看到 Ingress 创建成功但访问不通首先要排查 Ingress Controller 是否安装资源对象定义好了不等于有实际流量入口。很多初学者在云托管集群里配了 Ingress 却一直 404最后发现只是没装 controller白白浪费了一下午。3.3 文件组织与提交规范YAML 文件本身也是项目资产建议纳入 Git 管理并且按资源类型拆分文件一个资源一个文件避免所有内容堆在一个超级 YAML 里。我的习惯目录结构大致这样deploy/ production/ namespace.yaml configmap.yaml secret.example.yaml deployment.yaml service.yaml ingress.yaml staging/ ...几个团队协作的约定值得现在就立下。第一所有 YAML 文件必须通过 kubectl apply --dry-runserver -f 校验后再提交防止把语法错误的文件进 Git第二镜像 tag 不要用 latest发布记录里写清楚 commit 对应的 tag第三Secret 不建议明文入库可以先用 example 占位文件实际密文用 SealedSecret 或者外部密钥管理工具第四每个资源文件的 metadata.namespace 要显式写出来如果漏写资源会落到 default namespace环境就乱了。这四条看起来都是小事但我在真实团队里见过太多次因为小事引发的配置漂移和发布事故。4. 常见问题与排查技巧实录前面讲了怎么写、怎么管但真正让生命周期这个词变得有价值的是踩坑经验。这里挑几个我实际遇到过的、能明显影响项目生命周期管理的典型问题。每个问题我都尽量给出从现象到根因的排查路径而不是只甩一句检查日志。4.1 YAML 报错缩进、格式与资源校验最常见的第一个报错是 Error from server (NotFound) 或者 error: unable to recognize。前者通常是资源类型或 apiVersion 在新集群里不存在比如把旧的 extensions/v1beta1 的 Ingress 定义拿到新版本集群上使用后者常见于文件开头多了 BOM、YAML 里出现 Tab 或冒号后缺空格。处理思路是先用 kubectl explain 看资源结构再用 yaml lint 工具做静态检查。我个人长期用的组合是 VS Code 的 YAML 插件加 kubectl-validate编辑器里就能标红不用等到 apply 时才被集群怼回来。排查 YAML 问题有个实用惯例把出错的 YAML 拆成上下两半先 apply 前半再 apply 后半用二分法定位问题资源。另外几乎所有明明 apply 成功但资源没生效的情况都要先看同一 namespace 下是否已有同名资源。metadata.name 冲突时apply 会按新配置覆盖但 label 和 selector 的变化可能不会像预期那样更新所以资源上线前确认命名唯一非常重要。还有一种隐蔽情况YAML 里写了对不存在的 ConfigMap 或 Secret 的引用Deployment 一样能 apply 成功但 Pod 会一直 ContainerCreating事件里明确写着 volume not mounted 或 secret not found。这种问题靠看 describe 一眼就能定位。4.2 Pod 生命周期卡住Pending 与 CrashLoopBackOffPod 生命周期状态里最常见两个异常是 Pending 和 CrashLoopBackOff。Pending 表示调度器还没把 Pod 放到某个节点上最常见原因是资源不足、PVC 绑定不上、节点亲和性或污点容忍不满足。用 kubectl describe pod -n production 能看到 Events 里的调度失败原因如果显示 Insufficient cpu 或 Insufficient memory就要检查节点资源或者调低 requests如果显示 pod has unbound immediate PersistentVolumeClaims则是存储卷没准备好。很多新手看到 Pending 就以为节点挂了其实大部分时候是 requests 设得比节点剩余资源还高。CrashLoopBackOff 表示容器反复启动失败Kubernetes 判定每次退避后延后重启。这种情况通常要看日志kubectl logs --previous 能拿到上一次崩溃时的输出。这里我特别提醒不要只看当前日志很多启动类崩溃只在第一次运行时出现--previous 参数能把上一轮的输出翻出来很多问题一下子就有线索。还有一类隐蔽问题是探针配置过严比如 livenessProbe 的路径在启动后 10 秒内还没准备好容器一直好好的却被不断重启这种情况在日志里往往看不到明显报错需要检查探针的事件记录来判断是不是探针误杀。4.3 滚动更新失败的坑readiness 探针缺失导致的假发布成功这是我印象最深的一个生产事故。团队给核心服务做了一次小版本升级Deployment 里没有 readinessProbeapply 后 rollout status 显示成功但经过 Ingress 的流量开始大规模超时。原因其实很简单镜像里的进程启动了但上游依赖配置中心、数据库连接池还没就绪Service 已经把它当成可用的后端开始转发流量。因为没有 readinessProbeKubernetes 判断 Pod ready 的唯一依据就是容器进程启动进程起来了但业务并没有准备好。我把这种情况叫作假发布成功它比直接发布失败更难发现因为集群视角一切正常实际业务已经挂了。正确的处理方式分两步。第一步所有对外提供服务的 Deployment 必须配 readinessProbe探针的 path 要选真正能做业务就绪检查的接口比如 Spring Boot 的 /actuator/health 配合 liveness 和 readiness 分组第二步发布前先执行 kubectl rollout status --timeout120s 观察如果超时立刻 kubectl rollout undo。这里给大家一个实用技巧把发布和回滚写成两个简单的脚本无论谁执行都不会手忙脚乱。第一次在大半夜回滚的时候你就知道有一个预写好的脚本有多重要。脚本里我还会加上发布前后 Service 后端端点数量的对比如果新版本就绪后端点数比发布前少就自动中止流程。4.4 项目下线时的清理顺序与数据回收很多团队项目上线很积极下线却很随意直接在控制台删掉 Deployment 就以为完事了。实际上一个项目的完整生命周期结束至少要做这几步清理先删 Ingress停止外部流量入口再删 Service断掉服务间调用然后删 Deployment 或 StatefulSet让副本数归零最后清理 ConfigMap、Secret、PVC。删除顺序的核心逻辑是先断流量再停服务最后处理数据避免出现服务还在运行但配置已经没了、请求进来直接 500 的情况。尤其是先删 ConfigMap 再删 Deployment 这个顺序很多人搞反了结果 Pod 还在跑重启时发现配置找不到了。数据回收是下线里最需要谨慎的一环。PV 的回收策略写在 StorageClass 或 PV 的 persistentVolumeReclaimPolicy 里可选三种Retain 表示删除 PVC 后 PV 变成 Released 状态数据保留由管理员手动处理适合需要归档的场景Delete 表示删除 PVC 时底层存储卷也一起删掉适合测试环境和无状态数据Recycle 现在已经基本不推荐使用。企业项目里生产环境我建议统一用 Retain哪怕多几步人工操作也比数据被自动删了再找回要强得多。如果你的项目用了 StatefulSet 和 PVC删除顺序要更谨慎先缩容到 0确认数据持久卷正常再决定是否删除 PVC。别被一条命令清理所有的脚本唬住在数据面前多花十分钟人工核对完全值得。这些经验不是一次就能总结出来的。我最早写 Kubernetes YAML 也是从复制粘贴示例开始第一次上线就碰上滚动更新卡住后来才明白 readinessProbe 的重要性第一次下线服务也是删完 Deployment 才发现 PVC 还没处理差点把数据搞没了。所以我特别推荐大家在自己的项目里先搭一套最小的模板目录把 Deployment、Service、ConfigMap、Ingress 四个文件固定下来每次开新项目就基于这套模板改逐步积累团队的发布基线。配置管理重试、版本回滚脚本这些不紧急但很必要的东西能提前一天准备就别拖到故障时再临时写。至少在我的团队里这样做之后项目生命周期管理才真正从一知半解变成按部就班。
Kubernetes项目实战：掌握生命周期管理与YAML编写
聊到 Kubernetes 项目实战很多人第一反应是YAML 太繁琐、生命周期太抽象。确实Pod、Deployment、Service 这些概念拆开看每个都能找到文档可真要独立负责一个项目的上线、升级、回滚、下线就会发现零散的知识根本拼不成一张完整的地图。这篇文章我打算聚焦两件事项目生命周期管理和 yml 文件编写。前者解决一个项目从部署到销毁要经历哪些阶段、每个阶段该做什么的问题后者解决这些动作到底怎么写进 Kubernetes 资源清单、字段之间有什么隐含关系的问题。适合已经能把容器跑起来、但还没独立编排过整套应用的同学参考也适合想把自己团队的发布流程规范化的运维同事。1. 项目生命周期管理到底在管什么第一次接触 Kubernetes 的人最容易困惑项目生命周期管理这个词听着像在讲 DevOps 流程可又总看到 Pod 有 Pending、Running 这些状态到底指的是哪一个我的理解是这里的生命周期有两层含义并且两层都得管。一层是业务项目本身从代码到版本上线、迭代、下线的完整过程另一层是运行时资源对象的状态变化。Kubernetes 的核心思想是声明式管理你描述期望状态系统负责把实际状态对齐。所以项目生命周期的一切动作本质上都是围绕期望状态的变化展开的。1.1 一条代码从提交到运行的完整链路一个项目要从代码变成 Kubernetes 里正在运行的服务至少要经历这几步代码提交到 Git触发 CI 构建产出带版本号的容器镜像推送到镜像仓库然后编写或更新 YAML 资源清单执行 kubectl apply最后由 kubelet 拉取镜像并启动容器。这条链路里Kubernetes 只负责后半程也就是从你提交 YAML 到 Pod 真正运行起来这一段。理解了这个边界你就不容易甩错锅镜像没构建出来、仓库权限不对、镜像 tag 写错这些问题 YAML 定义得再规范也没用。很多团队排查问题喜欢盯着集群里的状态看却忽略了源头可能根本不在集群里。后半程里有一个容易忽略的关键点Kubernetes 不会主动去发布你的代码它只负责持续维护你声明的那份期望状态。比如你定义了 replicas: 3它就保证集群里正好有 3 个副本某个节点挂了导致只剩 2 个它会自动在其他节点重新调度。这也是生命周期管理的基础机制由控制器协调持续修正实际状态与期望状态的偏差。理解了这个后面各种升级策略、回滚操作就都顺理成章了。反过来说如果你在 YAML 里声明了错误的配置Kubernetes 也会忠实地帮你把错误状态维持住而不是替你纠错这也是为什么资源清单的编写规范如此重要。1.2 运行阶段的管理动作更新、扩容、回滚、下线项目上线之后日常管理动作主要围绕四件事更新、扩容、回滚、下线。更新最常见的做法是改镜像 tag再执行 kubectl apply。默认策略是滚动更新Deployment 会先起一个新的 Pod等它通过 readiness 探针后再停掉一个旧的逐个替换避免服务中断。扩容则分两种手动改 replicas或者配置 HPAHorizontal Pod Autoscaler让系统根据 CPU、内存或自定义指标自动伸缩。我建议项目初期先手动管理副本数摸清流量峰值规律后再上 HPA否则容易出现频繁扩缩容带来的抖动。很多团队一上来就配了很激进的 HPA 策略结果业务请求量平缓时副本数照样上下乱跳日志里全是扩容记录。回滚是所有运维动作里最需要肌肉记忆的。发布前务必执行 kubectl rollout history deployment/名字 把版本基线记录下来万一新版本有问题kubectl rollout undo deployment/名字 --to-revision版本号 就能回到上一个稳定版本。这里有个细节回滚不仅动容器镜像还会连带回滚这次发布附带的启动参数、环境变量等变更所以不要把临时排障用的手动改动和正式发布混在一次 apply 里。最后是下线很多团队忽略这个动作的生命周期属性。删除 Deployment 只是停止副本Service、Ingress、ConfigMap、Secret 还要分别清理涉及持久化存储时要先确认 PV 的回收策略否则数据可能被自动删除也可能变成无人认领的僵尸卷这个优先级我会在第 4.4 节专门展开。其实说到这你会发现生命周期管理的核心不在某个命令而是一套先声明、再校验、后操作的习惯。kubectl 给了很多便捷操作但便捷操作如果跳过了资源描述文件项目状态就会逐渐失控。比如临时用 kubectl scale 扩到 10 个副本但 YAML 里还写着 3下次有人 apply 一下就又缩回去了这种配置漂移在团队协作里非常常见。所以生命周期管理做得好不好很大程度取决于你的 YAML 文件能不能被团队稳定复用。这就自然过渡到本文的后半部分yml 文件编写。2. 读懂 YAMLK8s 资源清单的底层逻辑很多朋友一看到 YAML 就头大觉得格式要求太严格多一个空格就报错。但实际上 YAML 的语法非常少真正难的是理解 Kubernetes 的资源模型什么样的资源对象对应什么样的生命周期字段之间有哪些隐含约束。你可以把资源模型想成一张项目审批表apiVersion 是表格模板的版本kind 是表格类型metadata 是表头信息spec 是你要填的业务内容。搞清楚这个再看任何 YAML 都不会晕。Kubernetes 里几乎所有资源的定义都遵循同一套骨架熟悉一个对象之后其他对象能很快举一反三。2.1 YAML 基础语法与 Kubernetes 约定YAML 本身只依赖三个核心规则缩进表示层级、冒号后必须带空格、短横线表示列表项。Kubernetes 对缩进还有一个强制约定必须使用空格不能用 Tab。我见过不少线上事故是从一个 Tab 混入文件开始的。还有一个容易踩的坑是字符串和数字的区分像 replicas: 3 不加引号Kubernetes 会按整数解析如果写成 replicas: 3某些工具会把它当字符串虽然 Deployment 能容忍但转换逻辑链一长就容易出问题。我的建议是严格区分数字不加引号带特殊字符的字符串加单引号多行文本用竖线 | 保留换行。除语法之外Kubernetes 还约定了一些资源对象的固定字段。apiVersion 不是随意填的apps/v1、v1、networking.k8s.io/v1 各自对应不同资源类别旧版本字段在新集群上可能需要转换。metadata.name 在同 namespace 下必须唯一且对象创建后大多不可改名所以命名最好一开始就建立规范比如 应用名-组件名。Selector 和标签labels是 Kubernetes 的寻址系统Deployment 的 selector.matchLabels 必须包含 template.metadata.labels 里的字段否则创建资源时就会校验失败。这也是新手写 YAML 最常见的报错来源之一后面第 4.1 节我会给出具体的排查办法。2.2 Deployment项目运行的指挥官Deployment 是绝大多数无状态项目的主力资源对象它本身不直接创建容器而是通过管理 ReplicaSet 来间接管理 Pod。为什么要中间再加一层 ReplicaSet因为滚动更新时 Deployment 需要保留历史版本每个版本的 Pod 模板都会对应一个独立的 ReplicaSet回滚时直接把对应 ReplicaSet 的副本数调上去即可。理解了这层结构你就能看懂为什么执行 kubectl get rs 时会有多个 ReplicaSet 同时存在它们其实代表着一次次的发布历史。这个设计是 Kubernetes 实现版本控制的关键比简单地重启容器要可靠得多。Deployment 的核心字段我逐个说。spec.replicas 是期望副本数取值可以是 0常用于暂时停止服务但保留资源定义spec.selector 用于关联 Pod 模板创建后基本不能修改spec.template 里定义了 Pod 的模板其中 metadata.labels 必须与 selector 匹配spec.containers 列表里至少有一个容器每个容器必须定义 name 和 image。image 的 tag 建议写全不要用 latest否则无法精确回滚到某个镜像版本。还有两个发布关键参数在 spec.strategy 下rollingUpdate.maxSurge 表示更新期间最多能多出多少个临时 PodmaxUnavailable 表示最多允许多少个旧 Pod 不可用。默认值分别是 25% 和 25%意思是每次滚动至少保留 75% 的副本可用同时最多临时启动 25% 的新副本。如果副本数是 3更新时会先起 1 个新 Pod等它 ready 后再逐个替换旧的。探针配置直接影响生命周期里的存活判断。livenessProbe 决定容器是否需要被重启比如进程僵死但端口还在监听时靠它兜底readinessProbe 决定 Pod 是否被纳入 Service 的流量转发它没通过时不代表 Pod 要重启而是流量先不给它。我强烈建议生产环境至少配 readinessProbe否则滚动更新会出现一种危险情况旧 Pod 已经被删除、新 Pod 还没真正就绪Service 后端的可用实例数瞬间掉到很低甚至触发大规模 5xx。这个问题我会在第 4.3 节用真实案例展开讲它值得每个负责发布的同学重视。2.3 Service 与 Ingress流量入口的编排Pod 是临时对象IP 地址会随重建变化所以项目对外提供访问必须通过 Service 做稳定入口。Service 通过 selector 匹配一组 Pod将流量负载均衡到这些 Pod 上。type 字段有几种选择ClusterIP 只在集群内部可达常用于服务间调用NodePort 会在每个节点上开一个端口用于简单外部访问LoadBalancer 则对接云厂商负载均衡器。企业项目里最常见的组合是集群内部用 ClusterIP外部统一走 Ingress 接入 HTTP 流量再转发到各 Service。这个分层设计把服务发现和流量治理拆开了比在应用代码里写死 IP 或者用笨重的端口映射要容易维护得多。Ingress 资源定义的是转发规则真正干活的是集群里的 Ingress Controller比如 nginx-ingress 或 traefik。写 Ingress YAML 时要注意 path 的匹配规则比如 prefix 类型会做前缀匹配/api 能同时匹配 /api/order 和 /api/user如果路由规则写不当可能把两个服务的流量串到一处。我也建议在企业项目里为每个服务单独定义一条 Ingress 规则不要一股脑把所有规则堆在同一个 Ingress 对象里否则后续改路由时很容易误伤其他服务。近几年也有 Gateway API 作为下一代替代方案但对大部分项目而言Ingress 已经足够适用不必为了追新而更换基础设施。3. 一步步写出一套可用的项目 YAML前面讲了原理这一节进入实操。我的核心建议是不要从记事本空手写 YAML先用 kubectl 的 dry-run 生成骨架再手动补字段。原因有两个一是生成的骨架能保证 apiVersion、kind、metadata、spec 等最外层结构完全标准避免低级语法错误二是手动补字段时你对每个字段的理解会更扎实。等到你对常用资源和字段足够熟悉后再回到手写完全没问题。团队协作阶段我还会用 kubectl apply --dry-runserver 做预校验这一步能拦截大部分会被集群拒绝的错误配置省下不少无效 apply 的时间。3.1 从 dry-run 生成骨架开始先准备一个最小可用的示例。假设团队要上线一个名为 order-service 的订单服务镜像在私有仓库端口是 8080。执行下面这条命令Kubernetes 会帮你生成一个 Deployment 的 YAML 骨架kubectl create deployment order-service --imageregistry.example.com/order-service:v1.0.0 --dry-runclient -o yaml deployment.yaml注意 --dry-runclient 表示只在本地生成不会真的在集群创建资源加上 -o yaml 后输出结果是 YAML 格式。生成后打开文件你会看到 apiVersion、kind、metadata、spec.template 等结构但 replicas、resources、探针这些字段还需要自己补。这里有一个很多人忽略的点create deployment 生成的是单副本如果你要部署三副本记得补 spec.replicas: 3如果你用的是较新版本的 kubectl生成的 Deployment 里默认带了一个 pod-template-hash 的标签不要随意改动它。补全后的 Deployment 示例大概长这样apiVersion: apps/v1 kind: Deployment metadata: name: order-service namespace: production labels: app: order-service spec: replicas: 3 selector: matchLabels: app: order-service strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 maxUnavailable: 0 template: metadata: labels: app: order-service spec: containers: - name: order-service image: registry.example.com/order-service:v1.0.0 ports: - containerPort: 8080 resources: requests: cpu: 500m memory: 512Mi limits: cpu: 1 memory: 1Gi readinessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 10 periodSeconds: 5提示strategy 里的 maxSurge: 1、maxUnavailable: 0 是我比较推荐的配置组合表示先多起一个新副本等它健康后再停旧副本保证发布期间服务不降级代价是发布期间会短暂占用额外资源。如果集群资源紧张可以用默认的 25%/25% 配置。关于 resources 字段我要多说两句。requests 是调度依据Kubernetes 调度器会按它判断节点是否有足够资源limits 是运行限制超过可能触发容器被杀死或 CPU 限流。建议 requests 和 limits 的比值不要拉太大比如 CPU 的 limits 写成 1 但 requests 只有 100m会导致节点资源被大量预留但实际用量极低浪费集群容量。内存方面如果容器内存超过 limits可能会被 OOMKilled业务方就会反复重启这种问题最不好排查所以内存的 limits 要给业务留出合理余量建议先压测摸清基线再定值。3.2 配套 ConfigMap、Service、Ingress 的组合一个项目通常不止 Deployment 一个资源还需要把配置、网络入口组织起来。配置类内容建议放 ConfigMap避免把环境变量硬编码在镜像或 Deployment 里。比如 order-service 的 Spring Boot 配置文件可以单独写成 ConfigMapapiVersion: v1 kind: ConfigMap metadata: name: order-service-config namespace: production data: application.yml: | server: port: 8080 spring: datasource: url: jdbc:mysql://mysql-service:3306/order username: order password: ${DB_PASSWORD}然后在 Deployment 的容器 spec 里通过 volumeMounts 挂载或通过 envFrom 注入。这里要特别注意ConfigMap 内容更新后Pod 里的文件内容会自动同步有延迟但环境变量不会自动更新如果你用 envFrom 方式注入配置修改 ConfigMap 后必须手动触发一次滚动更新。常见做法是在 Deployment 的 template.metadata.annotations 里加一个 configMap 的 hash 值比如 checksum/config: sha256:xxxConfigMap 内容一变就改这个 hashapply 后自动触发滚动发布。这个小技巧能避免配置改了但服务还在用旧配置的经典事故。Service 是流量入口。order-service 内部端口是 8080其他服务调用它时希望统一走 80 端口可以在 Service 里做端口映射apiVersion: v1 kind: Service metadata: name: order-service namespace: production spec: selector: app: order-service ports: - name: http port: 80 targetPort: 8080 type: ClusterIPselector 必须能匹配到 Deployment 创建的 Pod 标签否则 Service 后端为空访问会超时。检查方式很简单kubectl get endpoints order-service -n production如果 ENDPOINTS 列为空说明标签没匹配上。最后是 Ingress如果订单服务需要被外部域名访问可以配一条规则apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: order-service namespace: production spec: rules: - host: order.example.com http: paths: - path: / pathType: Prefix backend: service: name: order-service port: number: 80这段配置的含义是访问 order.example.com 的请求由 Ingress Controller 转发到名为 order-service 的 Service 的 80 端口。如果你在集群里看到 Ingress 创建成功但访问不通首先要排查 Ingress Controller 是否安装资源对象定义好了不等于有实际流量入口。很多初学者在云托管集群里配了 Ingress 却一直 404最后发现只是没装 controller白白浪费了一下午。3.3 文件组织与提交规范YAML 文件本身也是项目资产建议纳入 Git 管理并且按资源类型拆分文件一个资源一个文件避免所有内容堆在一个超级 YAML 里。我的习惯目录结构大致这样deploy/ production/ namespace.yaml configmap.yaml secret.example.yaml deployment.yaml service.yaml ingress.yaml staging/ ...几个团队协作的约定值得现在就立下。第一所有 YAML 文件必须通过 kubectl apply --dry-runserver -f 校验后再提交防止把语法错误的文件进 Git第二镜像 tag 不要用 latest发布记录里写清楚 commit 对应的 tag第三Secret 不建议明文入库可以先用 example 占位文件实际密文用 SealedSecret 或者外部密钥管理工具第四每个资源文件的 metadata.namespace 要显式写出来如果漏写资源会落到 default namespace环境就乱了。这四条看起来都是小事但我在真实团队里见过太多次因为小事引发的配置漂移和发布事故。4. 常见问题与排查技巧实录前面讲了怎么写、怎么管但真正让生命周期这个词变得有价值的是踩坑经验。这里挑几个我实际遇到过的、能明显影响项目生命周期管理的典型问题。每个问题我都尽量给出从现象到根因的排查路径而不是只甩一句检查日志。4.1 YAML 报错缩进、格式与资源校验最常见的第一个报错是 Error from server (NotFound) 或者 error: unable to recognize。前者通常是资源类型或 apiVersion 在新集群里不存在比如把旧的 extensions/v1beta1 的 Ingress 定义拿到新版本集群上使用后者常见于文件开头多了 BOM、YAML 里出现 Tab 或冒号后缺空格。处理思路是先用 kubectl explain 看资源结构再用 yaml lint 工具做静态检查。我个人长期用的组合是 VS Code 的 YAML 插件加 kubectl-validate编辑器里就能标红不用等到 apply 时才被集群怼回来。排查 YAML 问题有个实用惯例把出错的 YAML 拆成上下两半先 apply 前半再 apply 后半用二分法定位问题资源。另外几乎所有明明 apply 成功但资源没生效的情况都要先看同一 namespace 下是否已有同名资源。metadata.name 冲突时apply 会按新配置覆盖但 label 和 selector 的变化可能不会像预期那样更新所以资源上线前确认命名唯一非常重要。还有一种隐蔽情况YAML 里写了对不存在的 ConfigMap 或 Secret 的引用Deployment 一样能 apply 成功但 Pod 会一直 ContainerCreating事件里明确写着 volume not mounted 或 secret not found。这种问题靠看 describe 一眼就能定位。4.2 Pod 生命周期卡住Pending 与 CrashLoopBackOffPod 生命周期状态里最常见两个异常是 Pending 和 CrashLoopBackOff。Pending 表示调度器还没把 Pod 放到某个节点上最常见原因是资源不足、PVC 绑定不上、节点亲和性或污点容忍不满足。用 kubectl describe pod -n production 能看到 Events 里的调度失败原因如果显示 Insufficient cpu 或 Insufficient memory就要检查节点资源或者调低 requests如果显示 pod has unbound immediate PersistentVolumeClaims则是存储卷没准备好。很多新手看到 Pending 就以为节点挂了其实大部分时候是 requests 设得比节点剩余资源还高。CrashLoopBackOff 表示容器反复启动失败Kubernetes 判定每次退避后延后重启。这种情况通常要看日志kubectl logs --previous 能拿到上一次崩溃时的输出。这里我特别提醒不要只看当前日志很多启动类崩溃只在第一次运行时出现--previous 参数能把上一轮的输出翻出来很多问题一下子就有线索。还有一类隐蔽问题是探针配置过严比如 livenessProbe 的路径在启动后 10 秒内还没准备好容器一直好好的却被不断重启这种情况在日志里往往看不到明显报错需要检查探针的事件记录来判断是不是探针误杀。4.3 滚动更新失败的坑readiness 探针缺失导致的假发布成功这是我印象最深的一个生产事故。团队给核心服务做了一次小版本升级Deployment 里没有 readinessProbeapply 后 rollout status 显示成功但经过 Ingress 的流量开始大规模超时。原因其实很简单镜像里的进程启动了但上游依赖配置中心、数据库连接池还没就绪Service 已经把它当成可用的后端开始转发流量。因为没有 readinessProbeKubernetes 判断 Pod ready 的唯一依据就是容器进程启动进程起来了但业务并没有准备好。我把这种情况叫作假发布成功它比直接发布失败更难发现因为集群视角一切正常实际业务已经挂了。正确的处理方式分两步。第一步所有对外提供服务的 Deployment 必须配 readinessProbe探针的 path 要选真正能做业务就绪检查的接口比如 Spring Boot 的 /actuator/health 配合 liveness 和 readiness 分组第二步发布前先执行 kubectl rollout status --timeout120s 观察如果超时立刻 kubectl rollout undo。这里给大家一个实用技巧把发布和回滚写成两个简单的脚本无论谁执行都不会手忙脚乱。第一次在大半夜回滚的时候你就知道有一个预写好的脚本有多重要。脚本里我还会加上发布前后 Service 后端端点数量的对比如果新版本就绪后端点数比发布前少就自动中止流程。4.4 项目下线时的清理顺序与数据回收很多团队项目上线很积极下线却很随意直接在控制台删掉 Deployment 就以为完事了。实际上一个项目的完整生命周期结束至少要做这几步清理先删 Ingress停止外部流量入口再删 Service断掉服务间调用然后删 Deployment 或 StatefulSet让副本数归零最后清理 ConfigMap、Secret、PVC。删除顺序的核心逻辑是先断流量再停服务最后处理数据避免出现服务还在运行但配置已经没了、请求进来直接 500 的情况。尤其是先删 ConfigMap 再删 Deployment 这个顺序很多人搞反了结果 Pod 还在跑重启时发现配置找不到了。数据回收是下线里最需要谨慎的一环。PV 的回收策略写在 StorageClass 或 PV 的 persistentVolumeReclaimPolicy 里可选三种Retain 表示删除 PVC 后 PV 变成 Released 状态数据保留由管理员手动处理适合需要归档的场景Delete 表示删除 PVC 时底层存储卷也一起删掉适合测试环境和无状态数据Recycle 现在已经基本不推荐使用。企业项目里生产环境我建议统一用 Retain哪怕多几步人工操作也比数据被自动删了再找回要强得多。如果你的项目用了 StatefulSet 和 PVC删除顺序要更谨慎先缩容到 0确认数据持久卷正常再决定是否删除 PVC。别被一条命令清理所有的脚本唬住在数据面前多花十分钟人工核对完全值得。这些经验不是一次就能总结出来的。我最早写 Kubernetes YAML 也是从复制粘贴示例开始第一次上线就碰上滚动更新卡住后来才明白 readinessProbe 的重要性第一次下线服务也是删完 Deployment 才发现 PVC 还没处理差点把数据搞没了。所以我特别推荐大家在自己的项目里先搭一套最小的模板目录把 Deployment、Service、ConfigMap、Ingress 四个文件固定下来每次开新项目就基于这套模板改逐步积累团队的发布基线。配置管理重试、版本回滚脚本这些不紧急但很必要的东西能提前一天准备就别拖到故障时再临时写。至少在我的团队里这样做之后项目生命周期管理才真正从一知半解变成按部就班。
