在Kubernetes里摸爬滚打一段时间后你会发现一个特别有意思的现象很多人能熟练敲出kubectl get pods、kubectl logs这类命令但一到了写部署文件、或者需要排查别人留下的YAML时就开始头疼。尤其是当集群规模变大、服务一多YAML文件从几十行膨胀到几百行各种metadata、spec、selector之间的关联关系很容易把人绕晕。这篇文章是K8S系列的第五篇我想专门把YAML文件这件事掰开揉碎聊清楚从为什么K8S选择YAML作为配置文件格式到核心字段的逐个拆解再到常见报错的定位思路全给你过一遍。无论你是刚接触K8S的运维新人还是已经开始写Deployment和Service的开发者这篇文章都值得花十几分钟读一遍。因为我不仅会告诉你每个字段“是什么”更会告诉你“为什么这么写”“不这么写会踩什么坑”这些都是我在实际集群部署和故障排查里一点一点攒出来的经验。1. 为什么K8S坚持用YAML以及它的语法“潜规则”1.1 YAML和JSON的关系以及K8S为什么选它很多人第一次看到K8S的配置文件第一反应是这格式怎么这么眼熟没错YAML本质上就是JSON的超集。Kubernetes API Server接收的请求内容其实是JSON格式但为了方便人类阅读和编写kubectl在发送请求前会把YAML转成JSON。你完全可以写一个JSON格式的K8S资源定义比如{ apiVersion: v1, kind: Pod, metadata: { name: my-nginx } }这样写是合法的但几乎没有人在生产环境里这么干。原因很简单JSON太啰嗦一堆花括号、方括号、逗号而且在多人协作的Git仓库里做diff时一眼根本看不出哪个字段改动了。YAML用缩进代替花括号用key: value代替key: value可读性直接提升一个量级。为什么K8S最终选择YAML而不是TOML或者XML一个核心原因在于K8S的资源定义天然是“树状嵌套结构”Deployment下面套PodTemplatePodTemplate下面套ContainerContainer下面还有ports、env、resources这种多层嵌套用YAML表达最自然。XML也能表达树状结构但标签符号太多写过pom.xml或者web.xml的人应该都懂那种痛苦TOML虽然简洁但它是面向扁平化配置设计的表达复杂嵌套层级时会比较别扭这也是社区里toml和yaml对比时大家普遍认为YAML更适合K8S的原因。1.2 缩进、空格、注释最容易翻车的三个细节YAML的语法规则不多但每一条都很致命。先说缩进YAML严格要求使用空格缩进禁止使用Tab键。有些编辑器默认把Tab展开成4个空格看起来好像没问题但如果你在服务器上直接用vim编辑而vim的expandtab没有开启一个Tab字符会让整个文件解析失败报的错误还是莫名其妙的mapping values are not allowed in this context。再说空格冒号后面必须有一个空格。name:nginx和name: nginx在YAML解析器眼里是完全不同的东西前者会被解析成一个值为nginx的key还是直接报错取决于YAML解析器的严格程度。K8S用的解析器是严格的遇到这种情况基本就是报错。破折号列表项后面也要有空格比如- name: nginx如果你写成-name: nginxYAML会把-name当做一个新的key结果完全偏离你的预期。注释用#这个和大部分配置文件一样。但有个细节#必须在行首或者前面有空格的位置才表示注释像key: value#注释这种写法#会被当成value的一部分不会报错但你的字段值就会变成value#注释这种隐性问题比报错更坑人因为排查起来特别费劲。还有两个用了之后能明显提升文件质量但新手很少用的特性文档分隔符---以及锚点和别名*。---用于在一个文件里分隔多个文档用kubectl apply -f xxx.yaml时K8S会逐个读取并应用文档。锚点和别名能在同一个文件里复用配置片段比如apiVersion: v1 kind: ConfigMap metadata: name: shared-config data: common: common log.level: info retry.count: 3锚点和别名写多了会影响可读性我个人的建议是同一文件里复制粘贴不超过三次的就别用锚点超过三次的考虑拆分文件或者在语雀/GitHub里写个模板生成脚本别为了炫耀技巧牺牲排障效率。2. 从Pod到Deployment到Service核心对象字段拆解2.1 PodK8S世界里最小的调度单元刚接触K8S的人一上来就写Deployment其实是不太合理的。Deployment本质上管理的是Pod如果不懂Pod的字段含义你写出来的Deployment很可能只是“能跑”但“为什么这么写”完全不清楚。所以先从Pod说起。一个最简的Pod定义apiVersion: v1 kind: Pod metadata: name: nginx-pod labels: app: nginx spec: containers: - name: nginx image: nginx:1.25 ports: - containerPort: 80apiVersion和kind是K8S API的定位坐标告诉API Server请求的是哪个资源类型、哪个版本。metadata里最重要的是name和labelsname是资源对象在命名空间内的唯一标识创建之后不能修改除非删除重建labels是K8S的“标签系统”Service、ReplicaSet都是靠标签选择器来关联Pod的这也是kubectl系列命令能按标签筛选资源的基础。spec.containers是一个数组所以看到- name: nginx这种带破折号的缩进要知道这是一个列表项。image指定镜像。这里有一个非常关键但容易忽略的字段imagePullPolicy。如果你不写K8S会根据镜像tag自动推断tag是latest或者省略时默认是Always每次都拉取tag是具体版本号时默认是IfNotPresent本地没有才拉取。这个自动推断机制在生产环境里坑过不少人——你明明把镜像tag改成了1.25但节点上本地有旧的1.25缓存K8S就不会去拉新的导致你部署的还是旧版本。ports.containerPort只是“声明性”的告诉K8S这个容器打算监听哪个端口它本身不会“打开”这个端口。这一点和Docker的-p参数完全不一样很多从Docker转过来的人在这里会懵。在Docker里-p 8080:80是实际做了端口映射的在K8S里你写containerPort: 80只是给K8S一个提示信息真正的网络打通是靠Service来完成的。2.2 Deployment真正生产环境里你该用的对象Pod的特点是“生命周期短、会被调度、会被销毁”单独创建Pod没有任何自愈能力节点挂了Pod就没了。Deployment就是为了解决这个问题而生的它通过ReplicaSet来维持Pod的期望副本数你声明“我要3个副本”Deployment会保证集群里始终保持3个Pod在跑。一个典型的Deployment写法apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment spec: replicas: 3 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.25 ports: - containerPort: 80这里最核心、也最容易被误解的是selector.matchLabels和template.metadata.labels的关系。很多人会问为什么不直接从Deployment里读取Pod模板的labels非要单独写一个selector答案是ReplicaSet创建Pod时会用template里的labels给Pod打标签但ReplicaSet本身并不知道自己该管理哪些Pod它必须通过selector去“认领”。如果selector和template.labels不一致Pod创建出来后ReplicaSet根本不会去管理它们。生产环境里你如果手贱改了template.labels但忘了改selectorDeployment会报错倒过来改selector但忘了改template.labelsDeployment会创建新Pod但旧的Pod因为不再匹配selector会被“孤立”在集群里白白占用资源。spec.replicas是期望副本数。注意“期望”这个词K8S会持续尝试让实际Pod数等于这个值所以你不应该用kubectl delete pod的方式去重启某个Pod因为Deployment会立刻再拉起一个新的。想要安全重启应该用kubectl rollout restart deployment/nginx-deployment这是滚动重启的正确姿势。另外有一个字段不得不提strategy。它定义Deployment的更新策略两种可选RollingUpdate滚动更新默认和Recreate先删除所有旧Pod再创建新Pod。Recreate适合那种不支持多实例同时在跑的独占型应用但会有短暂停服。RollingUpdate下还有两个子参数maxUnavailable和maxSurge分别控制更新过程中允许有多少个Pod暂时不可用、允许超量创建多少个Pod。这两个参数直接影响发布速度发布窗口短的可以调大一点比如maxSurge: 1、maxUnavailable: 0表示先创建一个新Pod确认成功后再杀掉一个旧Pod整个过程始终保持有3个Pod在提供服务。2.3 Service把Pod的“易变身份”固定下来Pod的IP不是固定的每次重建都会变。如果客户端直接通过Pod IP访问服务Pod一重启就全断了。Service就是K8S里的“固定入口”它有一个稳定的虚拟IPClusterIP客户端访问ClusterIPService把流量转发给后端的Pod。Service选择Pod也是靠标签apiVersion: v1 kind: Service metadata: name: nginx-service spec: selector: app: nginx ports: - protocol: TCP port: 80 targetPort: 80 type: ClusterIPspec.selector里的app: nginx会匹配所有带appnginx标签的Pod。port是Service对外暴露的端口targetPort是Pod里容器实际监听的端口。这里有个比较隐晦的知识点port和targetPort不需要相等比如port: 80、targetPort: 8080也是合法的前提是你容器里的进程确实监听8080。type常用的有四种ClusterIP默认仅集群内可访问、NodePort在每个节点上开一个端口外部通过节点IP:NodePort访问、LoadBalancer云厂商提供负载均衡器把外部流量转到NodePort、ExternalName返回一个外部域名不涉及端口和标签。NodePort有一个默认端口范围30000-32767如果你自定义NodePort要在这段范围内否则会报错。这里要特别提醒一件事很多人用Docker的时候习惯了宿主机端口映射到了K8S里也会下意识地去找“端口映射”的配置。我见过不少初学者在Service的YAML里写nodePort: 8080但type却是ClusterIP结果Service创建成功但外部根本访问不到。nodePort只有type: NodePort或者type: LoadBalancer时才会生效ClusterIP类型下这个字段会被忽略而且不报错排查起来非常迷惑。3. kubectl与YAML的配合正确的工作流与调试技巧3.1 用kubectl生成模板而不是从零手写从零手写一个复杂的Deployment YAML对任何人来说都是低效且容易出错的。更高效的方式是用kubectl的dry-run参数让API Server帮你生成模板。kubectl create deployment nginx-deploy --imagenginx:1.25 --replicas3 --dry-runclient -o yaml nginx-deploy.yaml这条命令会生成一个比较标准的Deployment YAML保存到文件里之后你只需要在生成的基础上做修改而不是面对一个空文件发呆。--dry-runclient表示只在客户端模拟生成不实际请求API Server-o yaml表示以YAML格式输出。这里有个进阶用法--dry-runserver。client模式不会经过API Server的校验说实话有些字段错误它发现不了server模式会真的把请求发到API Server触发所有校验逻辑但不持久化。当你拿不准某个字段写没写对时可以用server模式试一下。不过要注意server模式会比client模式多一步网络请求速度略慢日常快速生成模板用client就够了真正校验用下面讲的--validate或者直接kubectl apply加--dry-runserver。3.2 声明式 vs 命令式apply和create的区别kubectl操作资源有两种范式命令式和声明式。命令式就是你直接告诉K8S“我要做什么”比如kubectl run nginx --imagenginx、kubectl scale deployment/nginx --replicas5声明式是你把期望状态写在YAML里然后kubectl apply -f xxx.yaml让K8S自己去对比当前状态和期望状态的差异然后协调。生产环境强烈建议用声明式因为YAML文件可以进Git仓库做版本管理任何人改动都能diff、回溯。K8S社区常见的GitOps实践核心就是“以YAML文件为准”CI/CD流水线把文件变更推给集群集群自己完成剩余操作。这里要注意kubectl create和kubectl apply的核心区别create是“新建”语义如果资源已经存在会直接报错apply是“声明”语义资源不存在就创建存在就根据文件内容做增量更新。apply更新的逻辑是“三方合并”它会读取资源上一次apply时保存的配置然后把它和当前文件内容、集群上已有状态合并。所以记住一条黄金法则同一个资源要么都用apply管理要么都不用别把create和apply混着用否则K8S在计算diff时可能会把你没改动的字段判定为“需要删除”造成意想不到的资源变更。3.3 快速定位已部署资源的问题get、describe、logs三件套YAML写完了资源也apply上去了接下来怎么验证是不是真的按照你的预期运行了核心看三步。第一步kubectl getkubectl get deployment nginx-deploy kubectl get pods -l appnginx kubectl get svc注意-l appnginx这种标签筛选是K8S日常排查的高频操作比kubectl get pods不带任何筛选然后在一堆Pod里找目标要高效得多。第二步kubectl describekubectl describe pod nginx-deploy-xxxxxdescribe输出里有几个关键段落Events是最有价值的K8S会把调度、拉镜像、启动容器、健康检查等过程中的所有事件按时间顺序列在这里。如果Pod一直Pending看Events里是什么原因——是资源不足、镜像拉取失败还是节点亲和性约束不满足。如果Pod一直CrashLoopBackOffEvents里通常会有退出码和错误日志。第三步kubectl logskubectl logs -f nginx-deploy-xxxxx如果Pod里有多个容器需要加-c 容器名指定比如kubectl logs -f nginx-deploy-xxxxx -c nginx。-f是持续跟踪输出。还有一个技巧Pod已经崩溃了用kubectl logs --previous可以看上一次容器的日志这个在排查CrashLoopBackOff时非常有用。3.4 环境变量和配置管理ConfigMap与Secret实际部署的应用基本都需要配置比如数据库连接地址、日志级别、密钥等。直接在Deployment的YAML里写死配置会有两个问题一是多环境开发、测试、生产要维护多个文件二是密钥写进YAML后等于明文存储安全隐患很大。K8S给出的方案是ConfigMap和Secret。ConfigMap存非敏感配置Secret存敏感配置。两者用法类似都是把配置从Pod的定义里抽离出来。常见的注入方式有两种环境变量和挂载文件。用环境变量注入apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: template: spec: containers: - name: app image: my-app:1.0 env: - name: DB_HOST valueFrom: configMapKeyRef: name: app-config key: db.host - name: DB_PASSWORD valueFrom: secretKeyRef: name: app-secret key: db.password用挂载方式注入volumeMounts: - name: config-volume mountPath: /etc/app-config volumes: - name: config-volume configMap: name: app-config挂载方式的优势是配置更新后容器内的文件内容会自动刷新会有秒级延迟但环境变量方式必须重启Pod才能生效。所以如果配置变更频率高建议用挂载如果配置只是在启动时读一次环境变量更简单直观。4. YAML编写中的常见报错与排查实录4.1 高频报错速查表这一节是实战排障经验的精华部分我按“报错信息→出现原因→解决思路”的格式整理了一份速查表覆盖我在实际运维中遇到和学员群里反馈的高频问题。报错现象常见原因解决思路error: error validating x.yaml: error validating data: ValidationError(Deployment.spec.template.spec.containers[0].image): missing required field name in io.k8s.api.core.v1.Containercontainers数组里的容器缺少name字段每个container必须有name检查破折号下面的缩进是否正确error: error parsing x.yaml: error converting YAML to JSON: yaml: line N: mapping values are not allowed in this context冒号后面缺空格或缩进层级错误定位到报错的N行检查冒号后是否有空格、是否误用了TabThe Deployment x is invalid: spec.selector: Invalid value: v1.LabelSelector: field is immutable创建Deployment后修改了selectorselector一旦创建不可修改只能删除重建DeploymentError creating: pods x is forbidden: error looking up service account ...ServiceAccount不存在检查serviceAccountName字段是否拼写正确或namespace下是否创建了对应SAinvalid spec: container x has invalid imagePullPolicy: Always拼错了imagePullPolicy的取值合法值是Always、IfNotPresent、NeverErrImagePull/ImagePullBackOff镜像不存在、tag错误、私有仓库未认证登录节点手动docker pull测试检查image地址和镜像仓库凭据CrashLoopBackOff容器启动后立即退出用kubectl logs --previous查看上次退出日志0/3 nodes are available: 1 Insufficient cpu, 2 Insufficient memory节点资源不足kubectl top nodes查看节点资源使用率考虑扩容或减小requests4.2 两种最隐蔽的“不报错但行为异常”情况有些问题比报错更危险因为它不会给你任何错误信息但运行结果就是不对。第一种是metadata.name和metadata.namespace不一致。比如你的YAML文件metadata里没写namespace那资源会被创建在default命名空间下但你的Service可能在别的命名空间里通过服务名.命名空间去访问它这时候会显示DNS解析失败。如果发现一个Service解析不到第一反应先确认目标资源到底在哪个namespace。第二种是selector选错了Pod。Service的selector会选到所有匹配标签的Pod如果你两个应用复用了同一个app标签流量就会漂到不想去的Pod上而且是间歇性的很难复现。解决方法是设计标签时采用更细粒度的方案比如同时加app和tier或component标签Service的selector里同时匹配多个标签最小化误选概率。4.3 关于YAML文件的“版本陷阱”K8S的API版本和资源绑定关系是一个高频考点也是写YAML时容易踩的坑。一个资源对象创建时apiVersion必须和集群支持的版本匹配。Deployment需要apps/v1旧版本是extensions/v1beta1早已废弃Pod直接就是v1CronJob需要batch/v1Ingress比较特别老版本集群支持extensions/v1beta1和networking.k8s.io/v1beta1新版本集群一般用networking.k8s.io/v1。判断当前的K8S版本用kubectl version准备写不熟悉的资源时先用下面这条命令看集群支持的API版本kubectl api-resources | grep -E deployment|ingress|cronjob这条命令会列出资源名、短名、API分组和版本。养成这个习惯之后基本不会在apiVersion上栽跟头。5. 一些关于YAML文件写法与K8S使用的个人经验总结讲了这么多原理和排查最后分享几个我自己在实际使用中的体会看起来是小事但很影响效率。多文件管理建议按“应用”而不是按“类型”组织。初学者经常把所有Deployment放一个文件、所有Service放另一个文件这个方式在你应用少的时候还行一旦应用多了改一个服务的配置要开两个文件来回切。我推荐按应用拆目录比如base/nginx/deployment.yaml、base/nginx/service.yaml配合Kustomize做环境差异化覆盖后面接GitOps也比较顺。编辑器一定要配YAML插件。VS Code加Red Hat的YAML扩展写的时候能实时校验缩进和语法还能自动补全K8S字段前提是在settings里开启redhat.telemetry.enabled这个随意并配置好yaml.schemas把kubernetes.yaml这个schema关联到.yaml文件上。补全功能能帮你少拼错很多字段名。有一个操作要点使用kubectl apply -f之前如果文件是生产环境要用的可以先在测试环境应用一遍并且先用kubectl diff -f x.yaml看看它会做什么改动。kubectl diff是非常强大的预览工具它会对比文件内容和集群当前状态输出精确到字段的diff上线前花十秒钟看一眼能拦住大量手滑事故。最后再赘述一句其实K8S官方文档把YAML文件设计得很克制能在集群里用一条命令解决的问题它一定不会让你在YAML里手动声明。所以学YAML文件最好的方式不是背字段而是多写、多拆别人的文件再配合kubectl explain这个命令想看什么字段就看什么字段kubectl explain deployment.spec kubectl explain deployment.spec.template.spec.containerskubectl explain的进阶用法是加--recursive参数一次把所有嵌套字段全展开适合系统梳理某个资源的所有可选字段。当你能熟练使用kubectl explain的时候YAML文件在你眼里基本就是一张写满期望状态的清单而不是一堆需要记背的语法这时你离“能用K8S”就真正迈过一道坎了。
Kubernetes YAML文件从入门到排错：核心字段与常见坑全解析
在Kubernetes里摸爬滚打一段时间后你会发现一个特别有意思的现象很多人能熟练敲出kubectl get pods、kubectl logs这类命令但一到了写部署文件、或者需要排查别人留下的YAML时就开始头疼。尤其是当集群规模变大、服务一多YAML文件从几十行膨胀到几百行各种metadata、spec、selector之间的关联关系很容易把人绕晕。这篇文章是K8S系列的第五篇我想专门把YAML文件这件事掰开揉碎聊清楚从为什么K8S选择YAML作为配置文件格式到核心字段的逐个拆解再到常见报错的定位思路全给你过一遍。无论你是刚接触K8S的运维新人还是已经开始写Deployment和Service的开发者这篇文章都值得花十几分钟读一遍。因为我不仅会告诉你每个字段“是什么”更会告诉你“为什么这么写”“不这么写会踩什么坑”这些都是我在实际集群部署和故障排查里一点一点攒出来的经验。1. 为什么K8S坚持用YAML以及它的语法“潜规则”1.1 YAML和JSON的关系以及K8S为什么选它很多人第一次看到K8S的配置文件第一反应是这格式怎么这么眼熟没错YAML本质上就是JSON的超集。Kubernetes API Server接收的请求内容其实是JSON格式但为了方便人类阅读和编写kubectl在发送请求前会把YAML转成JSON。你完全可以写一个JSON格式的K8S资源定义比如{ apiVersion: v1, kind: Pod, metadata: { name: my-nginx } }这样写是合法的但几乎没有人在生产环境里这么干。原因很简单JSON太啰嗦一堆花括号、方括号、逗号而且在多人协作的Git仓库里做diff时一眼根本看不出哪个字段改动了。YAML用缩进代替花括号用key: value代替key: value可读性直接提升一个量级。为什么K8S最终选择YAML而不是TOML或者XML一个核心原因在于K8S的资源定义天然是“树状嵌套结构”Deployment下面套PodTemplatePodTemplate下面套ContainerContainer下面还有ports、env、resources这种多层嵌套用YAML表达最自然。XML也能表达树状结构但标签符号太多写过pom.xml或者web.xml的人应该都懂那种痛苦TOML虽然简洁但它是面向扁平化配置设计的表达复杂嵌套层级时会比较别扭这也是社区里toml和yaml对比时大家普遍认为YAML更适合K8S的原因。1.2 缩进、空格、注释最容易翻车的三个细节YAML的语法规则不多但每一条都很致命。先说缩进YAML严格要求使用空格缩进禁止使用Tab键。有些编辑器默认把Tab展开成4个空格看起来好像没问题但如果你在服务器上直接用vim编辑而vim的expandtab没有开启一个Tab字符会让整个文件解析失败报的错误还是莫名其妙的mapping values are not allowed in this context。再说空格冒号后面必须有一个空格。name:nginx和name: nginx在YAML解析器眼里是完全不同的东西前者会被解析成一个值为nginx的key还是直接报错取决于YAML解析器的严格程度。K8S用的解析器是严格的遇到这种情况基本就是报错。破折号列表项后面也要有空格比如- name: nginx如果你写成-name: nginxYAML会把-name当做一个新的key结果完全偏离你的预期。注释用#这个和大部分配置文件一样。但有个细节#必须在行首或者前面有空格的位置才表示注释像key: value#注释这种写法#会被当成value的一部分不会报错但你的字段值就会变成value#注释这种隐性问题比报错更坑人因为排查起来特别费劲。还有两个用了之后能明显提升文件质量但新手很少用的特性文档分隔符---以及锚点和别名*。---用于在一个文件里分隔多个文档用kubectl apply -f xxx.yaml时K8S会逐个读取并应用文档。锚点和别名能在同一个文件里复用配置片段比如apiVersion: v1 kind: ConfigMap metadata: name: shared-config data: common: common log.level: info retry.count: 3锚点和别名写多了会影响可读性我个人的建议是同一文件里复制粘贴不超过三次的就别用锚点超过三次的考虑拆分文件或者在语雀/GitHub里写个模板生成脚本别为了炫耀技巧牺牲排障效率。2. 从Pod到Deployment到Service核心对象字段拆解2.1 PodK8S世界里最小的调度单元刚接触K8S的人一上来就写Deployment其实是不太合理的。Deployment本质上管理的是Pod如果不懂Pod的字段含义你写出来的Deployment很可能只是“能跑”但“为什么这么写”完全不清楚。所以先从Pod说起。一个最简的Pod定义apiVersion: v1 kind: Pod metadata: name: nginx-pod labels: app: nginx spec: containers: - name: nginx image: nginx:1.25 ports: - containerPort: 80apiVersion和kind是K8S API的定位坐标告诉API Server请求的是哪个资源类型、哪个版本。metadata里最重要的是name和labelsname是资源对象在命名空间内的唯一标识创建之后不能修改除非删除重建labels是K8S的“标签系统”Service、ReplicaSet都是靠标签选择器来关联Pod的这也是kubectl系列命令能按标签筛选资源的基础。spec.containers是一个数组所以看到- name: nginx这种带破折号的缩进要知道这是一个列表项。image指定镜像。这里有一个非常关键但容易忽略的字段imagePullPolicy。如果你不写K8S会根据镜像tag自动推断tag是latest或者省略时默认是Always每次都拉取tag是具体版本号时默认是IfNotPresent本地没有才拉取。这个自动推断机制在生产环境里坑过不少人——你明明把镜像tag改成了1.25但节点上本地有旧的1.25缓存K8S就不会去拉新的导致你部署的还是旧版本。ports.containerPort只是“声明性”的告诉K8S这个容器打算监听哪个端口它本身不会“打开”这个端口。这一点和Docker的-p参数完全不一样很多从Docker转过来的人在这里会懵。在Docker里-p 8080:80是实际做了端口映射的在K8S里你写containerPort: 80只是给K8S一个提示信息真正的网络打通是靠Service来完成的。2.2 Deployment真正生产环境里你该用的对象Pod的特点是“生命周期短、会被调度、会被销毁”单独创建Pod没有任何自愈能力节点挂了Pod就没了。Deployment就是为了解决这个问题而生的它通过ReplicaSet来维持Pod的期望副本数你声明“我要3个副本”Deployment会保证集群里始终保持3个Pod在跑。一个典型的Deployment写法apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment spec: replicas: 3 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.25 ports: - containerPort: 80这里最核心、也最容易被误解的是selector.matchLabels和template.metadata.labels的关系。很多人会问为什么不直接从Deployment里读取Pod模板的labels非要单独写一个selector答案是ReplicaSet创建Pod时会用template里的labels给Pod打标签但ReplicaSet本身并不知道自己该管理哪些Pod它必须通过selector去“认领”。如果selector和template.labels不一致Pod创建出来后ReplicaSet根本不会去管理它们。生产环境里你如果手贱改了template.labels但忘了改selectorDeployment会报错倒过来改selector但忘了改template.labelsDeployment会创建新Pod但旧的Pod因为不再匹配selector会被“孤立”在集群里白白占用资源。spec.replicas是期望副本数。注意“期望”这个词K8S会持续尝试让实际Pod数等于这个值所以你不应该用kubectl delete pod的方式去重启某个Pod因为Deployment会立刻再拉起一个新的。想要安全重启应该用kubectl rollout restart deployment/nginx-deployment这是滚动重启的正确姿势。另外有一个字段不得不提strategy。它定义Deployment的更新策略两种可选RollingUpdate滚动更新默认和Recreate先删除所有旧Pod再创建新Pod。Recreate适合那种不支持多实例同时在跑的独占型应用但会有短暂停服。RollingUpdate下还有两个子参数maxUnavailable和maxSurge分别控制更新过程中允许有多少个Pod暂时不可用、允许超量创建多少个Pod。这两个参数直接影响发布速度发布窗口短的可以调大一点比如maxSurge: 1、maxUnavailable: 0表示先创建一个新Pod确认成功后再杀掉一个旧Pod整个过程始终保持有3个Pod在提供服务。2.3 Service把Pod的“易变身份”固定下来Pod的IP不是固定的每次重建都会变。如果客户端直接通过Pod IP访问服务Pod一重启就全断了。Service就是K8S里的“固定入口”它有一个稳定的虚拟IPClusterIP客户端访问ClusterIPService把流量转发给后端的Pod。Service选择Pod也是靠标签apiVersion: v1 kind: Service metadata: name: nginx-service spec: selector: app: nginx ports: - protocol: TCP port: 80 targetPort: 80 type: ClusterIPspec.selector里的app: nginx会匹配所有带appnginx标签的Pod。port是Service对外暴露的端口targetPort是Pod里容器实际监听的端口。这里有个比较隐晦的知识点port和targetPort不需要相等比如port: 80、targetPort: 8080也是合法的前提是你容器里的进程确实监听8080。type常用的有四种ClusterIP默认仅集群内可访问、NodePort在每个节点上开一个端口外部通过节点IP:NodePort访问、LoadBalancer云厂商提供负载均衡器把外部流量转到NodePort、ExternalName返回一个外部域名不涉及端口和标签。NodePort有一个默认端口范围30000-32767如果你自定义NodePort要在这段范围内否则会报错。这里要特别提醒一件事很多人用Docker的时候习惯了宿主机端口映射到了K8S里也会下意识地去找“端口映射”的配置。我见过不少初学者在Service的YAML里写nodePort: 8080但type却是ClusterIP结果Service创建成功但外部根本访问不到。nodePort只有type: NodePort或者type: LoadBalancer时才会生效ClusterIP类型下这个字段会被忽略而且不报错排查起来非常迷惑。3. kubectl与YAML的配合正确的工作流与调试技巧3.1 用kubectl生成模板而不是从零手写从零手写一个复杂的Deployment YAML对任何人来说都是低效且容易出错的。更高效的方式是用kubectl的dry-run参数让API Server帮你生成模板。kubectl create deployment nginx-deploy --imagenginx:1.25 --replicas3 --dry-runclient -o yaml nginx-deploy.yaml这条命令会生成一个比较标准的Deployment YAML保存到文件里之后你只需要在生成的基础上做修改而不是面对一个空文件发呆。--dry-runclient表示只在客户端模拟生成不实际请求API Server-o yaml表示以YAML格式输出。这里有个进阶用法--dry-runserver。client模式不会经过API Server的校验说实话有些字段错误它发现不了server模式会真的把请求发到API Server触发所有校验逻辑但不持久化。当你拿不准某个字段写没写对时可以用server模式试一下。不过要注意server模式会比client模式多一步网络请求速度略慢日常快速生成模板用client就够了真正校验用下面讲的--validate或者直接kubectl apply加--dry-runserver。3.2 声明式 vs 命令式apply和create的区别kubectl操作资源有两种范式命令式和声明式。命令式就是你直接告诉K8S“我要做什么”比如kubectl run nginx --imagenginx、kubectl scale deployment/nginx --replicas5声明式是你把期望状态写在YAML里然后kubectl apply -f xxx.yaml让K8S自己去对比当前状态和期望状态的差异然后协调。生产环境强烈建议用声明式因为YAML文件可以进Git仓库做版本管理任何人改动都能diff、回溯。K8S社区常见的GitOps实践核心就是“以YAML文件为准”CI/CD流水线把文件变更推给集群集群自己完成剩余操作。这里要注意kubectl create和kubectl apply的核心区别create是“新建”语义如果资源已经存在会直接报错apply是“声明”语义资源不存在就创建存在就根据文件内容做增量更新。apply更新的逻辑是“三方合并”它会读取资源上一次apply时保存的配置然后把它和当前文件内容、集群上已有状态合并。所以记住一条黄金法则同一个资源要么都用apply管理要么都不用别把create和apply混着用否则K8S在计算diff时可能会把你没改动的字段判定为“需要删除”造成意想不到的资源变更。3.3 快速定位已部署资源的问题get、describe、logs三件套YAML写完了资源也apply上去了接下来怎么验证是不是真的按照你的预期运行了核心看三步。第一步kubectl getkubectl get deployment nginx-deploy kubectl get pods -l appnginx kubectl get svc注意-l appnginx这种标签筛选是K8S日常排查的高频操作比kubectl get pods不带任何筛选然后在一堆Pod里找目标要高效得多。第二步kubectl describekubectl describe pod nginx-deploy-xxxxxdescribe输出里有几个关键段落Events是最有价值的K8S会把调度、拉镜像、启动容器、健康检查等过程中的所有事件按时间顺序列在这里。如果Pod一直Pending看Events里是什么原因——是资源不足、镜像拉取失败还是节点亲和性约束不满足。如果Pod一直CrashLoopBackOffEvents里通常会有退出码和错误日志。第三步kubectl logskubectl logs -f nginx-deploy-xxxxx如果Pod里有多个容器需要加-c 容器名指定比如kubectl logs -f nginx-deploy-xxxxx -c nginx。-f是持续跟踪输出。还有一个技巧Pod已经崩溃了用kubectl logs --previous可以看上一次容器的日志这个在排查CrashLoopBackOff时非常有用。3.4 环境变量和配置管理ConfigMap与Secret实际部署的应用基本都需要配置比如数据库连接地址、日志级别、密钥等。直接在Deployment的YAML里写死配置会有两个问题一是多环境开发、测试、生产要维护多个文件二是密钥写进YAML后等于明文存储安全隐患很大。K8S给出的方案是ConfigMap和Secret。ConfigMap存非敏感配置Secret存敏感配置。两者用法类似都是把配置从Pod的定义里抽离出来。常见的注入方式有两种环境变量和挂载文件。用环境变量注入apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: template: spec: containers: - name: app image: my-app:1.0 env: - name: DB_HOST valueFrom: configMapKeyRef: name: app-config key: db.host - name: DB_PASSWORD valueFrom: secretKeyRef: name: app-secret key: db.password用挂载方式注入volumeMounts: - name: config-volume mountPath: /etc/app-config volumes: - name: config-volume configMap: name: app-config挂载方式的优势是配置更新后容器内的文件内容会自动刷新会有秒级延迟但环境变量方式必须重启Pod才能生效。所以如果配置变更频率高建议用挂载如果配置只是在启动时读一次环境变量更简单直观。4. YAML编写中的常见报错与排查实录4.1 高频报错速查表这一节是实战排障经验的精华部分我按“报错信息→出现原因→解决思路”的格式整理了一份速查表覆盖我在实际运维中遇到和学员群里反馈的高频问题。报错现象常见原因解决思路error: error validating x.yaml: error validating data: ValidationError(Deployment.spec.template.spec.containers[0].image): missing required field name in io.k8s.api.core.v1.Containercontainers数组里的容器缺少name字段每个container必须有name检查破折号下面的缩进是否正确error: error parsing x.yaml: error converting YAML to JSON: yaml: line N: mapping values are not allowed in this context冒号后面缺空格或缩进层级错误定位到报错的N行检查冒号后是否有空格、是否误用了TabThe Deployment x is invalid: spec.selector: Invalid value: v1.LabelSelector: field is immutable创建Deployment后修改了selectorselector一旦创建不可修改只能删除重建DeploymentError creating: pods x is forbidden: error looking up service account ...ServiceAccount不存在检查serviceAccountName字段是否拼写正确或namespace下是否创建了对应SAinvalid spec: container x has invalid imagePullPolicy: Always拼错了imagePullPolicy的取值合法值是Always、IfNotPresent、NeverErrImagePull/ImagePullBackOff镜像不存在、tag错误、私有仓库未认证登录节点手动docker pull测试检查image地址和镜像仓库凭据CrashLoopBackOff容器启动后立即退出用kubectl logs --previous查看上次退出日志0/3 nodes are available: 1 Insufficient cpu, 2 Insufficient memory节点资源不足kubectl top nodes查看节点资源使用率考虑扩容或减小requests4.2 两种最隐蔽的“不报错但行为异常”情况有些问题比报错更危险因为它不会给你任何错误信息但运行结果就是不对。第一种是metadata.name和metadata.namespace不一致。比如你的YAML文件metadata里没写namespace那资源会被创建在default命名空间下但你的Service可能在别的命名空间里通过服务名.命名空间去访问它这时候会显示DNS解析失败。如果发现一个Service解析不到第一反应先确认目标资源到底在哪个namespace。第二种是selector选错了Pod。Service的selector会选到所有匹配标签的Pod如果你两个应用复用了同一个app标签流量就会漂到不想去的Pod上而且是间歇性的很难复现。解决方法是设计标签时采用更细粒度的方案比如同时加app和tier或component标签Service的selector里同时匹配多个标签最小化误选概率。4.3 关于YAML文件的“版本陷阱”K8S的API版本和资源绑定关系是一个高频考点也是写YAML时容易踩的坑。一个资源对象创建时apiVersion必须和集群支持的版本匹配。Deployment需要apps/v1旧版本是extensions/v1beta1早已废弃Pod直接就是v1CronJob需要batch/v1Ingress比较特别老版本集群支持extensions/v1beta1和networking.k8s.io/v1beta1新版本集群一般用networking.k8s.io/v1。判断当前的K8S版本用kubectl version准备写不熟悉的资源时先用下面这条命令看集群支持的API版本kubectl api-resources | grep -E deployment|ingress|cronjob这条命令会列出资源名、短名、API分组和版本。养成这个习惯之后基本不会在apiVersion上栽跟头。5. 一些关于YAML文件写法与K8S使用的个人经验总结讲了这么多原理和排查最后分享几个我自己在实际使用中的体会看起来是小事但很影响效率。多文件管理建议按“应用”而不是按“类型”组织。初学者经常把所有Deployment放一个文件、所有Service放另一个文件这个方式在你应用少的时候还行一旦应用多了改一个服务的配置要开两个文件来回切。我推荐按应用拆目录比如base/nginx/deployment.yaml、base/nginx/service.yaml配合Kustomize做环境差异化覆盖后面接GitOps也比较顺。编辑器一定要配YAML插件。VS Code加Red Hat的YAML扩展写的时候能实时校验缩进和语法还能自动补全K8S字段前提是在settings里开启redhat.telemetry.enabled这个随意并配置好yaml.schemas把kubernetes.yaml这个schema关联到.yaml文件上。补全功能能帮你少拼错很多字段名。有一个操作要点使用kubectl apply -f之前如果文件是生产环境要用的可以先在测试环境应用一遍并且先用kubectl diff -f x.yaml看看它会做什么改动。kubectl diff是非常强大的预览工具它会对比文件内容和集群当前状态输出精确到字段的diff上线前花十秒钟看一眼能拦住大量手滑事故。最后再赘述一句其实K8S官方文档把YAML文件设计得很克制能在集群里用一条命令解决的问题它一定不会让你在YAML里手动声明。所以学YAML文件最好的方式不是背字段而是多写、多拆别人的文件再配合kubectl explain这个命令想看什么字段就看什么字段kubectl explain deployment.spec kubectl explain deployment.spec.template.spec.containerskubectl explain的进阶用法是加--recursive参数一次把所有嵌套字段全展开适合系统梳理某个资源的所有可选字段。当你能熟练使用kubectl explain的时候YAML文件在你眼里基本就是一张写满期望状态的清单而不是一堆需要记背的语法这时你离“能用K8S”就真正迈过一道坎了。
