kubectl 这玩意儿说简单很简单就是给 Kubernetes 集群下指令的小工具说复杂也复杂光是常用参数和隐藏技巧能写出一本小册子。我接触 Kubernetes 这几年见过不少同事把kubectl当成get 和 describe 专用工具遇到问题就只会这两招排查效率低得让人着急。这篇文章我会对kubectl的高频命令做一次系统性梳理从日常操作、错误排查到声明式管理再到集群运维进阶把我自己实际用下来觉得最顺手、最省心的命令和解法分享出来。不管你是刚接触 Kubernetes 的小白还是已经写了几个月 YAML 的开发者这篇文章都能帮你减少敲错命令、重复查询的时间。1. 日常高频操作命令——kubectl 的起步与肌肉记忆1.1 查看资源状态的核心命令刚开始用 Kubernetes 的时候最容易产生的困惑就是我明明部署了一个应用为什么访问不到我 Pod 到底起没起来这时候最常用的就是get和describe系列。kubectl get pods kubectl get pods -n namespace kubectl get pods -o wide kubectl get nodes kubectl get svc kubectl get deployget命令的核心逻辑是列表展示适合快速概览。但有一个细节很多人会忽略不加-n参数时kubectl默认查询的是当前 context 对应的 namespace而不是所有 namespace。也就是说如果你的应用部署在production这个 namespace 下直接get pods只会看到当前 namespace 的资源要么加-n production要么用-A或--all-namespaces查看所有 namespace 下的 Pod。kubectl get pods -A这个-A参数在排查哪个 namespace 下面有异常 Pod的时候非常有用。我用它排查过不少次某应用突然不可用的问题往往很快就能定位到问题 Pod 所在的命名空间。describe是另一个高频命令它的作用是查看某个资源的详细信息包括 Events 事件、挂载的存储卷、容器状态、标签、注解等。kubectl describe pod pod-name kubectl describe node node-namedescribe不会告诉你怎么修但会告诉你哪里出了问题。比如 Pod 一直Pendingdescribe就能看到调度失败的具体原因比如节点资源不足、节点亲和性不匹配等。我的习惯是任何异常先get扫一遍再describe看细节最后才是看日志。1.2 Pod 的创建、更新和删除操作创建 Pod 的方式无非两种直接用run命令临时拉起或者通过 YAML 文件声明式创建。run命令适合快速做实验、验证镜像是否正常但生产环境几乎不会直接用run创建 Pod因为这种命令行创建的方式不利于跟踪、回顾和版本管理。kubectl run nginx-test --imagenginx:latest --port80需要注意kubectl run在不同版本中默认创建的资源类型略有差异早期版本默认创建的是 Deployment而有些版本中需要用--generator或直接指定资源类型才可以。为了明确意图我用run时通常会显式写明资源类型kubectl create deployment nginx-test --imagenginx:latest --replicas3更新操作同样是两种路径直接set命令修改或者apply一个更新后的 YAML。举几个常见的操作kubectl set image deployment/nginx-test nginxnginx:1.21.5 kubectl scale deployment/nginx-test --replicas5 kubectl rollout status deployment/nginx-test删除操作相对直接kubectl delete pod pod-name kubectl delete deployment deployment-name kubectl delete ns namespace-name这里有个容易踩的坑直接删除 Deployment 管理的 PodDeployment 会自动重新拉一个新 Pod 出来因为期望副本数没有变化。如果你希望重启这些 Pod更好的做法是执行kubectl rollout restart而不是把 Pod 一个个删掉。这个命令在滚动更新策略下可以优雅地分批重启 Pod不影响业务整体可用性。1.3 进入容器与日志的实时追踪kubectl exec和kubectl logs是日常调试的两板斧。kubectl exec -it pod-name -- /bin/sh kubectl logs pod-name kubectl logs -f pod-name kubectl logs pod-name -c container-name --tail50logs -f是追踪实时日志配合后端服务排查问题时非常好用。多容器 Pod 里必须用-c container-name指定容器否则日志命令会报错。--tail参数控制输出条数排查问题时我一般会加--tail50甚至更少而不是让命令行哗啦啦地滚动几千行那样反而容易错过关键报错。一个容易忽略的小点exec进入容器后很多精简镜像里没有 bash只有 sh。所以我会直接写成/bin/sh避免 exec 进去后发现 shell 不存在。如果容器连 sh 都没有可以用kubectl debug复制一份带调试工具的容器这个我在后面的排错章节详细说。2. 一键查错日志、事件与调试容器的排查技巧2.1 从 Events 中找到故障根因Kubernetes 最让人头疼的就是它不是不工作而是没按你以为的方式工作。比如 Pod 一直处于CrashLoopBackOff或者ImagePullBackOff这时候去翻logs未必有有效日志反而describe里的 Events 会直接告诉你原因。Events 是 Kubernetes 集群内部各组件之间沟通留下的痕迹。比如调度器尝试把 Pod 调度到某个节点、kubelet 尝试拉取镜像、容器运行时有报错都会在这里留下记录。kubectl describe pod pod-name在输出最底部有一块Events区域这才是排错的核心。常见的事件信息包括FailedScheduling调度失败通常是资源不足或节点亲缘性不匹配Failed pulling image拉取镜像失败可能是网络问题、仓库认证问题或镜像标签不存在Back-off restarting failed container容器反复启动失败进程内部异常Liveness probe failed存活探针探测失败说明应用本身已经不健康我的总结是Events 先告诉我们台上发生了什么Logs 再告诉我们容器内部发生了什么。两者结合才能真正定位故障点。如果你已经熟练使用describe还可以用一条命令快速过滤出事件kubectl get events --sort-by.lastTimestamp这条命令按时间排序输出全部事件适合在故障发生时快速扫描整个 namespace 的事件分布。2.2 用 debug 命令和临时容器调试故障 Pod生产环境最尴尬的情况是Pod 确实起来了但它里面连 shell 都没有想进去看进程、看端口、看配置文件都无从下手。Kubernetes 1.23 以后开始逐步完善kubectl debug现在用起来已经比较成熟了。kubectl debug pod-name -it --imagebusybox:latest --copy-todebug-pod-name这条命令的核心逻辑是复制目标 Pod 的配置生成一个新的临时 Pod并给它挂上一个带调试工具的容器。相当于在保留原 Pod 运行状态的同时在旁边开一个观察窗口让我能够在不干扰原 Pod 的前提下检查网络、挂载卷、环境变量等。如果目标 Pod 是节点上直接跑的静态 Pod还可以用kubectl debug node/node-name来调试节点本身。调试完直接删掉临时 Pod 即可不会影响原工作负载。需要说明的是kubectl debug生成的临时 Pod 默认会在原 Pod 所在节点上调度并且挂载相同的存储卷。这样就能直接看到原容器挂载的数据目录内容。如果只想临时加一个容器到原有 Pod 里可以用kubectl debug pod-name -it --imagebusybox --targetcontainer-name这种方式直接在目标容器旁添加一个临时容器共享同一个网络命名空间用localhost就能直接访问业务端口。2.3 查看资源占用与节点状态除了 Pod 本身的问题节点层面的资源不足也经常导致应用异常。这时候需要查看节点状态和资源占用情况。kubectl top node kubectl top podkubectl top依赖集群部署了 metrics-server或类似的指标采集组件如果集群没装这个命令会报错。它显示的是实时的 CPU 和内存使用量是排查节点资源快满了但不知道谁在消耗的最直接工具。另外节点状态本身可以用 describe 查看kubectl describe node node-name在输出里重点看Conditions字段其中有几个关键的标识MemoryPressure内存压力大DiskPressure磁盘压力大PIDPressure进程数过多Ready节点是否就绪这四个条件组合起来能快速判断节点是不是亚健康状态。有些节点虽然Ready为 True但MemoryPressure也是 True说明它已经在硬撑着运行了这时候新调度的 Pod 很有可能被挤到其他节点或者一直 Pending。3. 声明式配置的管理诀窍——apply、delete、label 与注解3.1 为什么推荐用 apply 而不是 createkubectl create和kubectl apply都能创建资源但两者的理念完全不同。create是命令式的告诉 Kubernetes创建这个东西apply是声明式的告诉 Kubernetes我要这个最终状态。在生产环境管理 YAML 配置时我几乎只用apply原因有三点apply具有幂等性同一份 YAML 可以反复执行不会因为资源已存在而报错apply在更新时会自动计算 YAML 与线上资源的差异只更新变化的部分apply会把最后应用的配置以注解的形式记录下来kubectl.kubernetes.io/last-applied-configuration便于追踪资源和配置之间的对应关系用法很简单kubectl apply -f deployment.yaml kubectl apply -f ./configs/ kubectl apply -f https://raw.githubusercontent.com/xxx/manifests.yaml对一个目录执行apply -f时会递归读取目录下所有 YAML 文件。这种方式在管理多个相关资源时特别高效比如一个包含 Deployment、Service、ConfigMap 的完整应用目录。create也有它的适用场景。比如需要通过命令行快速创建资源又不想写 YAML 文件时kubectl create configmap app-config --from-fileconfig.properties kubectl create secret generic db-secret --from-literalpasswordxxxcreate支持直接从命令行参数生成资源这是apply做不到的。但一旦资源需要更新我更倾向于生成一份 YAML 然后apply保持记录完整。3.2 用 label 和 annotation 给资源打标分类Kubernetes 里的 label标签是资源管理的核心手段之一它的作用是为资源附加可查询的键值标识。比如给一组 Pod 打上appnginx、envstaging就可以用-l参数快速筛选kubectl get pods -l appnginx kubectl get pods -l envstaging,appnginx kubectl get pods -l tier in (frontend, backend)label 的查询语法支持、、!、in、notin等集合操作可以组合出非常灵活的筛选条件。在故障排查时我经常用 label 按版本和模块筛选 Pod快速缩小问题范围。给资源打标签的操作也非常直观kubectl label pod pod-name versionv1 kubectl label pod pod-name version- # 删除一个标签 kubectl label pods --all versionv2 # 给所有匹配的 Pod 打标签这个--all会作用于当前 namespace 下的所有同类资源使用时需要格外注意最好先用get --show-labels看一眼当前资源情况再操作。注解annotation和 label 类似但它的定位是非标识性信息不需要被查询、筛选更多是作为元数据记录或供工具使用。比如记录联系人、变更原因、镜像来源等。kubectl annotate pod pod-name description临时修复网络问题 kubectl annotate deployment deployment-name ownerplatform-team注解在资源迁移、审计、追溯方面很有价值。很多运维平台都是通过注解来写入业务元数据的比如这个 Deployment 属于哪个业务线上次变更人是谁。3.3 离线编辑资源与临时配置修改有时候线上服务出问题来不及改 YAML 文件再 apply可以直接用kubectl edit进入编辑模式kubectl edit deployment/nginx-test这条命令会调起默认编辑器通常是 vi直接编辑线上的资源配置。保存退出后Kubernetes 会自动执行一次更新。edit本质上是 get patch 的组合它先拉取最新配置让你编辑再把你改动的内容以 patch 方式推送回去。kubectl patch则适合脚本化、精准化地修改资源不需要打开编辑器kubectl patch deployment/nginx-test -p {spec:{replicas:3}} kubectl patch deployment/nginx-test --typestrategic -p {spec:{template:{spec:{containers:[{name:nginx,image:nginx:1.21.5}]}}}}这里strategic patch是 Kubernetes 的默认补丁策略适合修改列表类型的字段。如果对 JSON Patch 更熟悉还可以指定--typejson。在高频更新的环境里patch比apply更轻量因为不需要处理整个文件。注意生产环境使用patch时建议先get -o yaml确认当前配置结构避免字段路径写错导致意外变更。4. 资源扩展存储、网络与多集群的关键命令4.1 ConfigMap 和 Secret 的常用操作ConfigMap 和 Secret 是 Kubernetes 中传递配置信息的两种核心资源前者保存明文配置后者保存敏感信息如密码、Token内容以 Base64 或加密形式存储。对它们的操作跟普通资源差不多但有几个常用命令值得单独列一下。kubectl get configmaps kubectl get secrets kubectl describe configmap app-config kubectl describe secret db-secret创建 ConfigMap 的常见方式kubectl create configmap app-config --from-literalkey1value1 --from-literalkey2value2 kubectl create configmap app-config --from-fileconfig.properties kubectl create configmap app-config --from-fileconfig-dir/--from-literal适合少量键值对--from-file适合从本地配置文件直接生成文件内容会以文件名为 key 保存--from-file指定目录时会读取目录下所有文件。Secret 的创建逻辑完全一致只是多了类型参数kubectl create secret generic db-secret --from-literalpasswordxxx kubectl create secret docker-registry regcred --docker-serverregistry-server --docker-usernameusername --docker-passwordpassworddocker-registry类型的 Secret 专门用于拉取私有仓库镜像在配置 Deployment 的imagePullSecrets时需要用到。需要提醒的是Secret 的数据虽然以 Base64 编码存储但 Base64 只是编码不是加密。如果集群默认开启了加密Secret 会以加密形式写入 etcd如果没有开启任何人只要能读取 Secret 对象就能轻松解码看到明文。敏感信息的安全最终依赖 RBAC 权限控制和集群自身的加密能力别把 Secret 当成安全边界。4.2 Service 端口映射与 Ingress 访问配置Service 是 Pod 对外暴露服务的抽象层日常排查中get svc是最常用的命令之一。Service 常见类型有ClusterIP、NodePort、LoadBalancer三种分别对应集群内访问、节点端口访问、云负载均衡器访问。kubectl get svc kubectl get svc -o wide kubectl describe svc service-name查看 Service 详细信息时重点看Port、TargetPort和NodePort三个字段。Port是 Service 对外暴露的端口TargetPort是 Pod 内容器实际监听的端口NodePort是节点上暴露的端口。三者之间的关系搞不清楚网络排查很容易误判。比如你部署了一个 Nginx 服务容器内监听 80Service 配置为port: 8080 targetPort: 80 nodePort: 30080那么集群内访问Service IP:8080能到达容器 80集群外访问节点IP:30080能到达容器 80直接访问容器 IP 的 80 端口也能通但 Pod IP 是动态的端口映射还会涉及kubectl port-forward它可以通过本地端口直接访问集群内的服务方便本地联调kubectl port-forward service/nginx-service 8080:80这条命令把本地的 8080 端口转发到集群内 Service 的 80 端口之后在本地浏览器访问http://localhost:8080就能直接看到集群内的服务效果。开发调试时非常实用不用经过 Ingress 或者 LoadBalancer网络路径最短。4.3 多集群、多 context 的管理与快速切换当公司同时维护多个 Kubernetes 集群比如测试、预发、生产频繁切换 context 就成了日常操作。kubectl提供了一组管理 context 的命令kubectl config get-contexts kubectl config current-context kubectl config use-context context-name kubectl config viewconfig get-contexts列出所有已经配置的 contextcurrent-context查看当前正在使用哪一个use-context切换目标集群。这三条命令构成了最基础的多集群管理方式。如果集群较多、命名也有规律建议配合 shell 别名使用。比如我在本地配置了几个短命令alias kctxkubectl config use-context alias kdevkubectl config use-context dev-cluster alias kprodkubectl config use-context prod-cluster切换 context 最大的坑是误操作生产环境。我的建议是生产环境 context 的名字尽量带上prod并且不要在本地终端里长期停留在生产 context。工作流上先切到生产执行完操作指令立刻切回测试环境。还有一个习惯值得养成执行高危命令比如delete时先敲kubectl config current-context或者kubectl get ns确认当前环境再继续操作。如果公司内部有多个集群且 context 分散在各 kubeconfig 文件中可以用--kubeconfig参数指定文件kubectl --kubeconfig/path/to/prod-config get nodes总之多集群管理的核心是让切换变得轻松但让误操作变难。5. 我踩过的坑kubectl 使用中的常见陷阱与规避方法5.1 默认 namespace 的陷阱我在接手一个项目时发现某个应用升级后迟迟不生效查了半天最后发现是 namespace 搞混了。明明我更新的是production下的 Deployment但kubectl当前 context 的默认 namespace 却是default导致我反复查询、反复确认的资源根本不是同一个对象。查看当前默认 namespace 的方法kubectl config view --minify | grep namespace如果嫌麻烦可以直接在命令里显式指定 namespacekubectl get pods -n production kubectl get deploy -n production或者修改当前 context 的默认 namespacekubectl config set-context --current --namespaceproduction这个--namespace参数一旦设置后续所有操作都会默认带上这个 namespace大幅降低漏写-n的概率。但要记住这个修改只对当前 context 有效不影响其他 context。5.2 镜像拉取策略导致的问题另一个高频坑是镜像拉取策略。默认情况下如果镜像标签是latestKubernetes 每次调度 Pod 时都会去仓库检查最新镜像如果标签是固定版本号比如v1.2.3只在节点本地不存在该镜像时才会拉取。在开发环境这个问题表现为明明推送了新镜像Pod 起来后还是旧代码。原因就是节点上已经缓存了同名镜像而 Pod 的imagePullPolicy是IfNotPresent。解决办法有两种修改镜像标签每次发布用不同的版本号在 Deployment 配置里设置imagePullPolicy: Always其实更推荐第一种做法。版本号标签是发布管理的基础也是回滚的依据。如果一定用latest那就要接受它每次调度都会去拉最新镜像或者手动在节点上清理旧镜像。kubectl get deploy deployment-name -o yaml | grep imagePullPolicy5.3 输出格式与 grep 过滤的技巧kubectl get的默认输出可读性一般列多的时候很容易看花眼。善用-o参数可以大幅提升效率。kubectl get pods -o name # 只输出资源名称 kubectl get pods -o jsonpath{.items[*].metadata.name} kubectl get pods -o custom-columnsNAME:.metadata.name,STATUS:.status.phase kubectl get pods -o yaml pods.yaml # 导出完整配置用于备份或分析custom-columns是我用得最多的输出格式。它允许指定列名和取值路径比如只看NAME和STATUS两列就比默认输出清爽得多。如果想配合 grep 做关键字过滤我通常会结合-o wide或者直接查自定义字段kubectl get pods -o wide | grep node-name5.4 权限不足时的排查思路kubectl报错最常见的是Forbidden或Unauthorized看到这类报错第一反应不是去改集群权限而是先确认两件事当前 context 是否正确当前用户/ServiceAccount 是否具备目标 namespace 的操作权限kubectl config current-context kubectl auth can-i get pods -n productionauth can-i是快速判断权限的利器返回yes或no。如果要看某个用户对指定资源的详细权限还可以kubectl auth can-i create deployments --assystem:serviceaccount:kube-system:deployer -n production这种确认方式在跨团队协作、别人报权限不足时尤其管用。先确认是权限配置问题还是 context 切错环境的问题再决定后续动作。6. 写在最后的一些感受回过头来看kubectl虽然命令多但核心脉络其实很清晰看资源、查状态、改配置、排故障。绝大多数日常操作都围绕这四件事展开真正要死记硬背的命令反而不多。我个人的习惯是每接手一个新集群先把 context 和 namespace 理清楚再看一遍节点状态和关键资源分布做到心里有数。真遇到故障时按照先get扫描、再describe看事件、然后logs看应用日志、最后exec或debug进容器确认这个顺序来基本能覆盖百分之九十的问题场景。如果你刚接触 Kubernetes 不久别急着把所有命令都背下来先掌握get、describe、logs、exec这几个核心命令配合-o wide、-n、-l这些参数灵活组合已经能应对大部分日常场景。等你用得多了自然会发现哪些命令需要频繁使用再针对性地记一些别名和快捷方式也不迟。最后分享一个小技巧kubectl自带 explain 命令忘记字段结构时可以直接在终端里查kubectl explain deployment.spec.template.spec.containers不用打开浏览器翻文档效率能高不少。Kubernetes 的命令体系虽然庞大但只要你把它当成查资源状态、改期望状态、看运行日志三件事来做整个心智负担都会轻很多。