kubectl 与日常运维实战深度解析

本文不是 kubectl 命令手册——命令手册看官方 Cheat Sheet 就够了。本文要解决的是:kubectl 背后到底在做什么、kubectl apply 的三方合并为什么能正确工作、面对一个故障现象时你的排障思路应该是什么。

掌握 kubectl 的关键不是背命令,而是理解它背后的 API 请求链路和排障思维。


1. kubectl 架构与工作原理

1.1 kubectl 到底在做什么?

很多人把 kubectl 当作一个"K8s 专用命令行工具",但它的本质比这简单得多:kubectl 就是一个 HTTP 客户端,它把你的命令翻译成 RESTful API 请求发给 apiserver,再把 JSON 响应格式化成你看到的表格。

kubectl get pods -n default
  ↓ 翻译成
GET /api/v1/namespaces/default/pods
  Accept: application/json
  Authorization: Bearer <token>

这意味着什么?意味着 kubectl 能做的事,curl 也能做。kubectl 没有任何"特权"——它不会直接操作 etcd,不会直接跟 kubelet 通信,一切都经过 apiserver。

理解这一点很重要,因为当你遇到 kubectl 报错时,第一反应应该是:"这个 API 请求到底发了什么?apiserver 返回了什么?"而不是把 kubectl 当黑箱去猜。

查看 kubectl 真实行为的方法:

# -v=6 显示请求的 API URL 和状态码
kubectl get pods -v=6
# I0101 GET https://k8s:6443/api/v1/namespaces/default/pods 200 OK

# -v=8 显示完整的 HTTP 请求头、请求体、响应头、响应体
kubectl get pods -v=8

# -v=9 加上 curl 命令(可以直接复制出来用 curl 重放)
kubectl get pods -v=9

实战技巧:当 kubectl 报错信息模糊时(比如只说 "error"),加 -v=8 看完整的 HTTP 响应体,通常能看到 apiserver 返回的详细错误原因。

1.2 kubeconfig:kubectl 怎么知道连哪个集群?

kubectl 启动时做的第一件事是读取 kubeconfig(默认 ~/.kube/config)。这个文件定义了三类实体:

apiVersion: v1
kind: Config
current-context: prod-admin       # 当前激活的 context

clusters:                          # "集群在哪?"
- name: prod-cluster
  cluster:
    server: https://k8s.example.com:6443
    certificate-authority-data: <base64-ca-cert>

users:                             # "我是谁?"
- name: admin
  user:
    client-certificate-data: <base64-cert>
    client-key-data: <base64-key>
# 也可以是 token、exec(如 aws-iam-authenticator)、OIDC 等

contexts:                          # 把"集群"和"身份"绑在一起
- name: prod-admin
  context:
    cluster: prod-cluster
    user: admin
    namespace: production          # 默认 namespace

Context = Cluster + User + 默认 Namespace。切换 context 就是切换"我以什么身份访问哪个集群"。

为什么要这么设计?因为在实际工作中,你可能同时管理多个集群(开发、预发、生产),每个集群用不同的身份认证。如果没有 context 机制,你每次都要手动指定 --server、--token、--namespace——极其容易出错,尤其是在生产集群上误操作。

多集群管理的两种方式:

# 方式 1:合并多个 kubeconfig 文件
export KUBECONFIG=~/.kube/config:~/.kube/staging:~/.kube/prod
kubectl config view --merge --flatten > ~/.kube/merged

# 方式 2:临时切换(不影响全局设置)
KUBECONFIG=~/.kube/staging kubectl get pods

生产环境安全建议:在 Shell 提示符中显示当前 context 和 namespace,避免"以为在 staging 其实在 prod"的惨剧:

# 使用 kube-ps1
source "/usr/local/opt/kube-ps1/share/kube-ps1.sh"
PS1='$(kube_ps1) \W \$ '
# 效果:(⎈ |prod-cluster:production) ~ $

1.3 从缩写到 API 路径:RESTMapper 的工作

当你输入 kubectl get deploy 时,kubectl 怎么知道 deploy 对应的是 apps/v1/deployments?

这由 RESTMapper 完成。过程是:

graph TB
  input["用户输入 "deploy""] --> mapper["RESTMapper.ResourceFor("deploy")"]
  mapper -->|"查询 apiserver 的 /apis 发现接口"| gvr["apps/v1 Deployment (namespaced)"]
  gvr --> path["构造 API 路径:
/apis/apps/v1/namespaces/{ns}/deployments"]
  1. kubectl 向 apiserver 的 /apis 和 /api 端点查询所有已注册的 API 资源(包括资源名、缩写、所属 Group/Version、是否 namespaced)
  2. RESTMapper 在结果中查找 deploy 这个缩写,匹配到 deployments(Group: apps,Version: v1)
  3. 根据 GVR + namespace 构造完整的 API 路径

Discovery Cache:为了避免每次执行命令都查询 apiserver,kubectl 会把发现结果缓存到 ~/.kube/cache/discovery/。通常这没问题,但有一个坑:如果你刚安装了一个 CRD(自定义资源),但 kubectl 报 error: the server doesn't have a resource type "xxx",可能是缓存没更新。解决方法:

rm -rf ~/.kube/cache/discovery/
# 下次执行 kubectl 时会重新查询

1.4 kubectl 插件机制

kubectl 的插件机制极其简单:任何在 PATH 中、名字以 kubectl- 开头的可执行文件,自动成为 kubectl 的子命令。

# 如果 PATH 中有一个叫 kubectl-tree 的可执行文件
# 你就可以执行:
kubectl tree deployment/nginx
# kubectl 会调用 kubectl-tree,传入 deployment/nginx 作为参数

Krew 是社区维护的插件管理器,类似于 brew:

kubectl krew install tree     # 安装
kubectl krew upgrade tree     # 升级
kubectl krew list             # 列出已安装

生产环境推荐的插件:

插件 解决什么问题 使用场景
kubectl-tree 看不清资源的 Owner 关系链 Deployment → ReplicaSet → Pod 的层级关系一目了然
kubectl-neat kubectl get -o yaml 输出太多冗余字段(managedFields、status 等) 只看"我写的那部分"YAML
kubectl-ctx / kubectl-ns 切换 context/namespace 命令太长 kubectx prod、kubens production
kubectl-who-can 不知道谁有权限做某个操作 kubectl who-can delete pods -n production
kubectl-sniff 需要抓 Pod 的网络包 注入 tcpdump 容器抓包,本地 Wireshark 分析

2. 资源管理:create、replace、apply 到底有什么区别?

K8s 提供了三种管理资源的方式。很多人分不清它们的区别,导致在生产环境踩坑。让我们用一个场景说清楚。

2.1 命令式操作(Imperative Commands)

kubectl run nginx --image=nginx:1.25
kubectl create deployment web --image=nginx --replicas=3
kubectl scale deployment web --replicas=5
kubectl delete pod nginx

特点:快速、适合一次性调试。但不可审计、不可复现——没有 YAML 文件记录你做了什么,同事不知道你改了什么,回滚也无从谈起。

适用场景:开发环境临时测试、紧急情况下的应急操作。绝不应该是生产环境的常规操作方式。

2.2 命令式对象配置(create / replace)

kubectl create -f deployment.yaml    # 创建
kubectl replace -f deployment.yaml   # 更新(全量替换)
kubectl delete -f deployment.yaml    # 删除

replace 的问题在哪?它是全量替换——用你提交的 YAML 完全覆盖 etcd 中的对象。如果有人手动给 Deployment 加了一个 annotation(比如监控系统自动添加的),而你的 YAML 里没有这个 annotation,replace 会把它删掉。

更严重的场景:你的 YAML 是上周写的,这周同事通过 kubectl patch 加了一个新的环境变量。你一 replace,同事的修改就没了。

2.3 声明式配置(apply)——生产环境唯一推荐

kubectl apply -f deployment.yaml
kubectl apply -f manifests/         # 整个目录
kubectl apply -k overlays/prod/     # kustomize

kubectl apply 不是简单的"创建或替换"。它使用三方合并(Three-way Merge)——同时考虑三个版本的信息来决定如何更新。这是它能安全用于生产环境的根本原因。

2.4 三方合并:kubectl apply 为什么不会覆盖别人的修改?

kubectl apply 比较三个版本:

graph LR
  la["Last Applied
上次 apply 的快照"] --- lo["Live Object
etcd 中的当前状态"] --- nc["New Config
你这次提交的 YAML"]

三方合并的逻辑(用具体例子说明):

场景 1:你修改了一个字段

Last Applied: replicas=3    Live Object: replicas=3    New Config: replicas=5
→ 结果:replicas=5(你改了,按你的来)

场景 2:你删除了一个字段

Last Applied: 有 label env=dev    Live Object: 有 label env=dev    New Config: 无此 label
→ 结果:删除 label env=dev

关键:kubectl 怎么区分"你故意删了"和"你从来没写过"?靠 Last Applied。Last Applied 里有、New Config 里没有 = 你故意删了。Last Applied 里也没有 = 这个字段不是你管的,别动它。

场景 3:别人修改了你没碰的字段

Last Applied: 无 annotation X    Live Object: annotation X=hello    New Config: 无 annotation X
→ 结果:保留 annotation X=hello(不是你加的,也不是你删的,别动)

场景 4:你和别人改了同一个字段

Last Applied: replicas=3    Live Object: replicas=10(运维手动改了)    New Config: replicas=3
→ 结果:replicas=10(Live 和 Last Applied 不一样,说明有人改了,保留别人的修改)

等等,这个结果对吗?如果你就是想把 replicas 改回 3 呢?这时你需要的 New Config 中写 replicas: 3,并且 Last Applied 中也是 replicas: 3——此时三方合并的逻辑看到"你没改这个值"(Last Applied == New Config),但 Live Object 不同,说明别人改了,所以保留 Live Object 的值。

这确实是一个 Client-Side Apply 的局限性——它无法区分"你没改所以保留旧值"和"你故意改成和 Last Applied 一样的值"。这正是 Server-Side Apply 要解决的问题。

2.5 Server-Side Apply:更精确的字段管理

Client-Side Apply(默认)的三方合并在 kubectl 客户端执行,依赖 last-applied-configuration annotation。它的局限性:

Server-Side Apply(--server-side,K8s 1.22 GA)将合并逻辑移到 apiserver 服务端,引入了 Field Management 概念——每个字段都有一个"管理者"(manager)标识:

# 使用 Server-Side Apply
kubectl apply --server-side -f deployment.yaml

# 查看字段管理者
kubectl get deployment nginx -o yaml

输出的 metadata.managedFields 会显示:

managedFields:
- manager: kubectl
  operation: Apply
  fieldsV1:
    f:spec:
      f:replicas: {}         # replicas 由 kubectl 管理
      f:template:
        f:spec:
          f:containers: {}   # containers 由 kubectl 管理
- manager: hpa-controller
  operation: Update
  fieldsV1:
    f:spec:
      f:replicas: {}         # replicas 也由 HPA 管理 → 冲突!

当两个管理者尝试修改同一字段时,Server-Side Apply 会返回 Conflict 错误,而不是默默覆盖。你可以通过 --force-conflicts 强制接管,或协商谁应该管理这个字段。

什么时候用 Server-Side Apply?


3. 高效使用 kubectl

3.1 输出与过滤:从信息洪流中找到你要的

kubectl 默认的表格输出只显示最基本的列。当你需要更多信息时:

# -o wide:显示 Node 名、Pod IP 等额外列
kubectl get pods -o wide

# -o yaml / -o json:完整对象(debug 必备)
kubectl get deploy nginx -o yaml

# -o json + jq:精准提取
kubectl get pods -o json | jq '.items[] | {name: .metadata.name, node: .spec.nodeName, ip: .status.podIP}'

# custom-columns:自定义表格列
kubectl get pods -o custom-columns=\
NAME:.metadata.name,\
STATUS:.status.phase,\
NODE:.spec.nodeName,\
IP:.status.podIP,\
RESTARTS:.status.containerStatuses[0].restartCount

# JSONPath:内置模板(不需要安装 jq)
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

过滤与排序:

# Label Selector——最常用的过滤方式
kubectl get pods -l app=nginx                    # 等于
kubectl get pods -l 'app in (nginx, web)'        # 集合
kubectl get pods -l 'app!=nginx'                 # 不等于
kubectl get pods -l 'app,version'                # 同时有这两个 label
kubectl get pods --show-labels                   # 显示所有 label

# Field Selector——只支持有限字段(metadata.name, metadata.namespace, status.phase 等)
kubectl get pods --field-selector status.phase=Running
kubectl get pods --field-selector spec.nodeName=node-1
kubectl get events --field-selector type=Warning   # 只看 Warning 事件

# 排序
kubectl get pods --sort-by=.metadata.creationTimestamp
kubectl get events --sort-by=.lastTimestamp

# 所有命名空间
kubectl get pods -A    # 等价于 --all-namespaces

API 发现——kubectl 自带的文档:

# 不确定某个字段怎么写?explain 就是你的文档
kubectl explain pod.spec.containers.resources
kubectl explain pod.spec.containers.resources --recursive   # 展开所有子字段

# 列出集群中所有可用的资源类型
kubectl api-resources
# 输出包括:NAME, SHORTNAMES, APIVERSION, NAMESPACED, KIND
# 可以看到 deploy 是 deployments 的缩写、pods 的缩写是 po 等

# 列出所有 API 版本
kubectl api-versions

3.2 Patch:不想写完整 YAML 时的部分更新

有时候你只想改一个字段(比如调整 replicas),没必要提交完整的 YAML。kubectl patch 提供三种部分更新方式:

Strategic Merge Patch(默认)——K8s 独有,最智能:

kubectl patch deployment nginx -p '{"spec":{"replicas":5}}'

Strategic Merge Patch 理解 K8s 资源的列表合并语义。例如你想给 Pod 添加一个新的环境变量,Strategic Merge 会追加到现有环境变量列表中,而不是替换整个列表。这比 JSON Merge Patch 更安全。

JSON Merge Patch(--type=merge)——简单但粗暴:

kubectl patch deployment nginx --type=merge -p '{"spec":{"replicas":5}}'

遵循 RFC 7396。对于列表字段,它会整体替换——如果你只想加一个端口,你必须把所有端口都写上,否则原来的会被删掉。

JSON Patch(--type=json)——最精确:

kubectl patch deployment nginx --type=json \
  -p '[{"op":"replace","path":"/spec/replicas","value":5}]'

遵循 RFC 6902。支持 add、remove、replace、move、copy、test 六种操作,可以精确操作数组中的某个元素(通过索引)。适合需要精确控制修改位置的场景。

3.3 Rollout:部署的版本管理

# 查看 Deployment 的滚动更新进度
kubectl rollout status deployment/nginx
# 输出会实时显示新旧 Pod 的替换进度,直到完成

# 查看历史版本
kubectl rollout history deployment/nginx
# REVISION  CHANGE-CAUSE
# 1         kubectl apply --filename=v1.yaml
# 2         kubectl apply --filename=v2.yaml

# 查看某个历史版本的详情
kubectl rollout history deployment/nginx --revision=2

# 回滚到上一版本
kubectl rollout undo deployment/nginx

# 回滚到指定版本
kubectl rollout undo deployment/nginx --to-revision=1

# 重启所有 Pod(不改配置,只是触发滚动更新)
# 原理:给 Pod template 加一个 annotation kubectl.kubernetes.io/restartedAt
kubectl rollout restart deployment/nginx

# 暂停滚动更新(想一次性改多个字段后再一起生效)
kubectl rollout pause deployment/nginx
# 修改 image、env、resources...
kubectl rollout resume deployment/nginx
# resume 后所有修改一起触发一次滚动更新

rollout restart 的实际场景:你更新了 ConfigMap 的内容,但挂载 ConfigMap 作为环境变量的 Pod 不会自动重启。kubectl rollout restart 可以触发 Pod 滚动重建,让 Pod 读到新的 ConfigMap。

3.4 上下文与命名空间切换

# 原生方式
kubectl config get-contexts          # 列出所有 context
kubectl config use-context staging   # 切换
kubectl config set-context --current --namespace=production  # 改默认 namespace

# 推荐工具:kubectx + kubens(交互式选择、支持 - 切回上一个)
kubectx staging         # 切换 context
kubectx -               # 切回上一个
kubens production       # 切换默认 namespace
kubens -                # 切回上一个

4. 排障实战:从现象到根因的思维链

排障的核心不是"知道哪个命令",而是面对一个现象时,你的大脑怎么推理。下面按常见故障场景,展示完整的思维链。

4.1 Pod 排障:一个 Pod 出问题了,怎么一步步定位?

第一步:看 Pod 处于什么状态

kubectl get pods -n <namespace>

Pod 的状态告诉你问题发生在哪个阶段。不同状态对应完全不同的排查方向:

graph TD
  start["Pod 异常"] --> check["kubectl get pods:什么状态?"]
  check --> pending["Pending"]
  check --> imgpull["ImagePullBackOff"]
  check --> crash["CrashLoopBackOff"]
  check --> running["Running 但不工作"]
  check --> term["Terminating 卡住"]

  pending --> p_think["调度阶段或启动前阶段出问题"]
  imgpull --> i_think["镜像拉取失败"]
  crash --> c_think["容器启动了但立刻崩溃"]
  running --> r_think["容器在运行但业务不正常"]
  term --> t_think["Pod 删不掉"]

Pending:Pod 卡在调度或启动前

思维链:Pending 意味着 Pod 还没开始运行容器。可能卡在两个阶段——调度(Scheduler 找不到合适的 Node)或启动前(等待 Volume 挂载、镜像拉取等)。

# 关键命令:describe 看 Events
kubectl describe pod <pod-name> -n <namespace>

拉到最下面看 Events 部分,它会告诉你卡在哪:

情况 1:FailedScheduling

Events:
  Warning  FailedScheduling  0/5 nodes are available:
    2 Insufficient cpu, 3 node(s) had taint {dedicated: gpu}, that the pod didn't tolerate.

翻译:5 个 Node,2 个 CPU 不够,3 个有 Taint 但 Pod 没有 Toleration。

排查思路:

# 看各 Node 的资源剩余
kubectl describe nodes | grep -A 5 "Allocated resources"
# 或
kubectl top nodes

# 看 Node 的 Taint
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

# 看 Pod 的 requests
kubectl get pod <pod> -o jsonpath='{.spec.containers[*].resources.requests}'

解决:要么降低 Pod 的 resource requests,要么扩容 Node,要么给 Pod 加 Toleration。

情况 2:Pending PVC

Events:
  Warning  FailedScheduling  0/5 nodes are available:
    5 node(s) didn't find available persistent volumes to bind.

排查:

kubectl get pvc -n <namespace>
# 如果 PVC 状态是 Pending → 没有匹配的 PV

kubectl get pv
# 检查是否有可用的 PV、StorageClass 是否正确、accessMode 是否匹配

ImagePullBackOff:镜像拉不下来

思维链:容器运行时尝试拉取镜像失败,正在指数退避重试。

kubectl describe pod <pod-name> | grep -A 10 "Events"
# 看具体的错误信息:
# - "repository does not exist" → 镜像名写错了
# - "unauthorized" → Registry 认证失败
# - "manifest unknown" → Tag 不存在
# - "dial tcp: i/o timeout" → 网络不通(DNS/防火墙)

常见原因和对应排查:

错误信息 原因 排查
repository does not exist 镜像名拼写错误 检查 image 字段,注意 Docker Hub 的镜像要写全(如 docker.io/library/nginx:1.25)
unauthorized Registry 认证失败 检查 imagePullSecrets 是否配置、Secret 是否在正确 namespace、凭证是否过期
manifest unknown Tag 不存在 确认镜像 Tag 是否真的存在(去 Registry 查)
dial tcp: i/o timeout 网络问题 从 Node 上 curl Registry 地址测试连通性,检查 DNS、代理、防火墙

CrashLoopBackOff:容器反复崩溃重启

思维链:容器启动了,但很快退出,kubelet 以指数退避重试(10s → 20s → 40s → ... → 最大 5min)。

# 第 1 步:看容器退出的原因
kubectl describe pod <pod-name> | grep -A 10 "Last State"
# Reason: OOMKilled, Exit Code: 137  → 内存不足被杀
# Reason: Error, Exit Code: 1        → 应用报错退出
# Reason: Error, Exit Code: 127      → 命令找不到(entrypoint 写错)
# Reason: Error, Exit Code: 126      → 权限问题(文件不可执行)

# 第 2 步:看上一次崩溃的日志
kubectl logs <pod-name> --previous
# 如果是多容器 Pod:
kubectl logs <pod-name> -c <container-name> --previous

Exit Code 137(OOMKilled)的完整排查链路:

这是生产中最常见的崩溃原因之一。Exit Code 137 = 被 SIGKILL(128 + 9 = 137),通常是内核 OOM Killer 干的。

# 1. 确认是 OOM
kubectl describe pod <pod> | grep -A 5 "Last State"
# Reason: OOMKilled

# 2. 看容器的 memory limits 设了多少
kubectl get pod <pod> -o jsonpath='{.spec.containers[*].resources}'
# 如果 limits.memory = 256Mi,但应用启动就需要 300Mi → 永远 OOM

# 3. 看实际内存使用(需要 metrics-server)
kubectl top pod <pod> --containers
# NAME       CPU    MEMORY
# app        50m    240Mi    ← 接近 256Mi limits,随时可能 OOM

# 4. 检查是 Pod 级 OOM 还是 Node 级 OOM
kubectl describe node <node> | grep -A 5 "Conditions"
# MemoryPressure=True → Node 整体内存不足,kubelet 按 QoS 驱逐 Pod

应对策略:

  1. 临时止血:调大 memory limits → kubectl patch deploy <name> -p '{"spec":{"template":{"spec":{"containers":[{"name":"app","resources":{"limits":{"memory":"1Gi"}}}]}}}}'
  2. 根因排查:应用是否有内存泄漏?Java 应用的 heap size 是否和 container limits 匹配?(常见坑:JVM 默认 heap = 容器 memory 的 1/4,但 JVM 的 native memory + metaspace 也占内存,总量可能超过 limits)
  3. 预防:设置合理的 requests 确保 QoS 等级,配置 VPA(Vertical Pod Autoscaler)自动调整

Exit Code 1(应用错误)的排查:

# 看日志——答案通常就在日志里
kubectl logs <pod-name> --previous

# 常见原因:
# - 配置文件错误(ConfigMap/Secret 内容不对)
# - 依赖服务未就绪(数据库连不上)
# - 端口冲突
# - 权限不足(文件读写)

Running 但不工作:容器在跑但业务不正常

思维链:容器没崩溃,但用户反馈"服务不可用"。问题可能在应用本身、网络、配置挂载等。

# 1. 看日志——应用自己报了什么
kubectl logs <pod-name> -f          # 实时跟踪
kubectl logs <pod-name> --since=5m  # 最近 5 分钟

# 2. 进容器看——进程活着吗?端口监听了吗?
kubectl exec -it <pod-name> -- sh
  > ps aux                           # 进程还在吗
  > netstat -tlnp                    # 端口监听了吗
  > curl localhost:8080/health       # 健康检查过吗
  > cat /etc/config/app.yaml         # 配置对吗
  > env | grep DB_                   # 环境变量对吗

# 3. 如果是 distroless 镜像(没有 shell),用 kubectl debug
kubectl debug -it <pod-name> --image=busybox --target=app
# 这会注入一个 busybox 容器到目标 Pod,共享 PID namespace
# 可以看到应用进程、检查网络

Terminating 卡住:Pod 删不掉

思维链:Pod 被标记删除但没有真正消失。两个常见原因——Finalizer 阻塞或 kubelet 无法终止容器。

# 检查是否有 Finalizer
kubectl get pod <pod> -o jsonpath='{.metadata.finalizers}'
# 如果有值 → 某个 Controller 注册了 Finalizer 但没来清理

# 如果 Node 已经不可达(kubelet 断联),Pod 会一直 Terminating
# 因为 apiserver 等 kubelet 确认"容器已停止",但 kubelet 失联了

# 强制删除(慎用——不会优雅终止容器)
kubectl delete pod <pod> --grace-period=0 --force

4.2 网络排障:Service 不通的排查思维链

当有人报告"访问某个 Service 不通"时,问题可能出在五个层次的任何一个。从下往上排查:

graph BT
    L1["Layer 1: Endpoints — Service 有后端吗?"]
    L2["Layer 2: 应用层 — 容器进程正常运行吗?"]
    L3["Layer 3: Pod 直连 — Pod IP 直连能通吗?"]
    L4["Layer 4: Service 规则 — ClusterIP 转发正常吗?"]
    L5["Layer 5: DNS 解析 — Service 名能解析到 ClusterIP 吗?"]
    L1 --> L2 --> L3 --> L4 --> L5

按这个顺序排查:

# Step 1: Service 有后端吗?
kubectl get endpoints <service-name> -n <namespace>
# 如果 Endpoints 是 <none> → Label Selector 没匹配到任何 Ready 的 Pod

# 常见坑:
kubectl get svc <service-name> -o yaml | grep -A 3 selector
# selector: app=nginx     ← Service 选择 app=nginx 的 Pod
kubectl get pods -l app=nginx
# 没有结果 → Pod 的 label 不是 app=nginx(大小写?拼写?)
# 或者 Pod 都不是 Ready(readinessProbe 没过)

# Step 2: Pod 直连能通吗?
kubectl exec -it <client-pod> -- curl http://<pod-ip>:<container-port>
# 如果直连不通 → 问题在 Pod 本身(进程没启动、端口没监听)
# 如果直连通 → 问题在 Service 层

# Step 3: Service ClusterIP 能转发吗?
kubectl exec -it <client-pod> -- curl http://<cluster-ip>:<service-port>
# 如果 ClusterIP 不通但 Pod 直连通 → kube-proxy 规则有问题
# 检查 kube-proxy:
kubectl logs -n kube-system -l k8s-app=kube-proxy

# Step 4: DNS 能解析吗?
kubectl exec -it <client-pod> -- nslookup <service-name>
kubectl exec -it <client-pod> -- nslookup <service-name>.<namespace>.svc.cluster.local
# 如果解析失败 → CoreDNS 问题
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns

# Step 5: 如果以上都正常但还是不通
# 检查 NetworkPolicy 是否拦截了流量
kubectl get networkpolicies -n <namespace>

DNS 排障的常见坑——ndots:5

Pod 内的 /etc/resolv.conf 默认配置 ndots:5,意思是:如果域名中的点数少于 5 个,先在集群内搜索域中查找,找不到再去外部查。

所以当你在 Pod 里访问 api.example.com(2 个点,< 5),DNS 解析顺序是:

  1. api.example.com.default.svc.cluster.local → 查不到
  2. api.example.com.svc.cluster.local → 查不到
  3. api.example.com.cluster.local → 查不到
  4. api.example.com → 终于查到了

一个简单的外部域名解析要经过 4 次查询,延迟翻了 4 倍。在高并发场景下,这些多余的 DNS 查询会把 CoreDNS 打满。

解决方案:

# 方案 1:在 Pod spec 中降低 ndots
spec:
  dnsConfig:
    options:
    - name: ndots
      value: "2"

# 方案 2:外部域名末尾加点(显式 FQDN,跳过搜索域)
# 代码中用 "api.example.com." 而不是 "api.example.com"

4.3 Node 排障:Node NotReady 的排查链路

当 kubectl get nodes 显示某个 Node 是 NotReady,意味着 kubelet 没有按时上报心跳。排查思路是从 K8s 层到操作系统层逐步深入。

K8s 层排查:

# 看 Node 的 Conditions——哪个条件异常?
kubectl describe node <node-name> | grep -A 15 "Conditions"
# Ready=False:kubelet 明确报告自己不正常
# Ready=Unknown:kubelet 失联,apiserver 收不到心跳
# MemoryPressure=True:Node 内存不足,kubelet 开始驱逐 Pod
# DiskPressure=True:磁盘空间不足
# PIDPressure=True:进程数耗尽

# 看 Node 上有哪些 Pod
kubectl get pods --field-selector spec.nodeName=<node-name> -A

# 看 Node 资源用量
kubectl top node <node-name>

如果 Node 完全失联(Ready=Unknown),需要 SSH 到 Node 排查:

# 1. kubelet 还活着吗?
systemctl status kubelet
journalctl -u kubelet --since "10 minutes ago" -f
# 常见问题:
# - "failed to run Kubelet: running with swap on is not supported"
#   → 关闭 swap:swapoff -a
# - "certificate has expired"
#   → 证书过期:kubeadm certs renew all
# - "Unable to register node with API server"
#   → 网络不通:检查到 apiserver 的连通性

# 2. 容器运行时还活着吗?
systemctl status containerd    # 或 docker
crictl ps                      # 列出运行中的容器
crictl pods                    # 列出 Pod sandbox
# 如果 containerd 挂了 → 所有容器都停了

# 3. 系统资源
df -h          # 磁盘满了?(/var/lib/containerd 或 /var/lib/kubelet)
free -h        # 内存耗尽?
dmesg | tail   # 内核有没有报错(OOM killer、硬件错误)

Node 维护操作:

当你需要对 Node 做维护(升级内核、扩容磁盘等),正确的流程是:

# 1. 标记 Node 为不可调度(新 Pod 不会被调度到这个 Node)
kubectl cordon <node-name>

# 2. 驱逐 Node 上的 Pod(优雅迁移到其他 Node)
kubectl drain <node-name> \
  --ignore-daemonsets \           # DaemonSet Pod 不驱逐(它们注定要在每个 Node 上)
  --delete-emptydir-data \        # 允许删除 emptyDir 数据
  --grace-period=60               # 给 Pod 60 秒优雅终止

# 3. 执行维护操作...

# 4. 维护完成,恢复可调度
kubectl uncordon <node-name>

drain 为什么会卡住? 常见原因:


5. 资源管理进阶

5.1 requests vs limits:看似简单,坑很深

resources:
  requests:          # "保底"——调度依据 + QoS 分类依据
    cpu: 100m        # 0.1 核
    memory: 128Mi
  limits:            # "上限"——运行时硬约束
    cpu: 500m
    memory: 512Mi

这两个字段影响着 K8s 中三个完全不同的子系统,理解它们的差异至关重要。

requests 影响调度

Scheduler 在决定 Pod 放到哪个 Node 时,看的是 requests,不是 limits,也不是实际使用量。Scheduler 将 Node 的"已分配 requests 总和"与 Node 的总容量对比,判断是否"放得下"。

这导致一个常见问题:Node 实际使用率很低,但 Pod 调度不上去。比如一个 Node 有 4 CPU,上面 10 个 Pod 各 request 了 400m CPU,合计 4000m = 4 CPU。Scheduler 认为这个 Node "满了",不再调度新 Pod。但实际上这 10 个 Pod 可能只用了 1 CPU——requests 设太高了。

反过来:requests 设太低,Scheduler 认为 Node 还有空间,继续塞 Pod。结果 Node 被超卖(overcommit),所有 Pod 一起抢 CPU/Memory,性能恶化甚至 OOM。

limits 影响运行时——CPU 和 Memory 的行为完全不同

CPU limits:超过时被 throttle(限流)——内核通过 CFS(Completely Fair Scheduler)限制容器的 CPU 时间片。表现是:不会 OOM,但延迟变高、吞吐下降。

CPU throttle 的坑在于它很难被发现。应用不会报错,日志里没有任何异常,只是"慢了"。在 Prometheus 中可以通过 container_cpu_cfs_throttled_seconds_total 指标观察。

很多团队选择 不设置 CPU limits(只设 requests):让 Pod 在 Node 有空闲 CPU 时可以突发使用,避免无谓的 throttle。代价是如果多个 Pod 同时突发,CPU 争抢靠 requests 的比例分配(CFS shares)。

Memory limits:超过时触发 OOMKill(Exit Code 137)。内存不像 CPU 可以限流——内核无法"暂停"一个进程的内存分配。如果容器尝试分配的内存超过 limits,内核 OOM Killer 直接杀掉进程。

生产建议:

# 推荐配置模式
resources:
  requests:
    cpu: 200m         # 基于实际观察的 P50 用量
    memory: 256Mi     # 基于实际观察的 P95 用量
  limits:
    memory: 512Mi     # 设为 requests 的 1.5-2 倍,留缓冲
    # 不设 cpu limits  → 避免 throttle

为什么 memory requests 看 P95 而 CPU requests 看 P50?因为 memory 不足是致命的(OOM),需要更保守;CPU 不足只是变慢,可以容忍。

5.2 RBAC:从"Forbidden"到找到根因

当用户或 ServiceAccount 报告 Error from server (Forbidden): pods is forbidden: User "jane" cannot list resource "pods" in API group "" in the namespace "production" 时,排查思路是:

第 1 步:确认身份

# K8s 1.27+ 可以用 auth whoami
kubectl auth whoami
# Username: jane
# Groups: [developers system:authenticated]

# 或通过 -v=8 看请求中的认证信息
kubectl get pods -v=8 2>&1 | grep "User-Agent\|Authorization"

第 2 步:验证权限

# 检查当前用户是否有某个权限
kubectl auth can-i list pods -n production
# no

# 检查具体原因——以目标用户身份模拟
kubectl auth can-i list pods -n production --as=jane
# no

# 是否是集群管理员
kubectl auth can-i '*' '*' --as=jane
# no

第 3 步:找到该用户关联的 RoleBinding

# 查找所有涉及 jane 的绑定
kubectl get rolebindings,clusterrolebindings -A -o json | \
  jq '.items[] | select(.subjects[]? | .name=="jane" or .name=="developers") | {name: .metadata.name, namespace: .metadata.namespace, role: .roleRef.name}'

# 结果可能是空的 → jane 没有任何权限绑定!

第 4 步:授权

# 给 jane 在 production namespace 中的 edit 权限
kubectl create rolebinding jane-edit \
  --clusterrole=edit \
  --user=jane \
  --namespace=production

# 给整个 developers 组 view 权限
kubectl create rolebinding dev-view \
  --clusterrole=view \
  --group=developers \
  --namespace=production

第 5 步:反向查询——谁有权限做这个操作?

# 使用 kubectl-who-can 插件
kubectl who-can delete pods -n production
# ROLEBINDING          NAMESPACE    SUBJECT    TYPE
# admin-binding        production   admin      User
# ops-binding          production   ops-team   Group

6. 效率工具链

6.1 stern:解决多 Pod 日志聚合的痛点

kubectl logs 一次只能看一个 Pod。当你的 Deployment 有 10 个副本,Bug 报告说"有时候报错"——你不知道是哪个 Pod,需要逐个查看。stern 解决了这个问题:

# 查看所有名字匹配 web-.* 的 Pod 日志(支持正则)
stern "web-.*" -n production
# 输出会用不同颜色标记不同 Pod

# 只看特定容器
stern web -c nginx

# 过滤——只看 ERROR 和 WARN
stern web --include "ERROR|WARN"
stern web --exclude "health"    # 排除健康检查日志

# 最近 10 分钟
stern web --since 10m

# 带时间戳
stern web --timestamps

6.2 k9s:给不想记命令的人

k9s 是一个终端 UI,让你用交互式界面管理 K8s 资源——不用记命令,用快捷键操作。

k9s                     # 启动

# 核心快捷键
# :pods      → Pod 视图
# :deploy    → Deployment 视图
# :svc       → Service 视图
# :ns        → Namespace 视图
# /keyword   → 过滤
# d          → Describe
# l          → Logs(实时)
# s          → Shell(exec 进容器)
# e          → Edit(编辑 YAML)
# ctrl-d     → Delete
# :xray dp   → X-Ray 视图(展示 Deployment→RS→Pod 关系树)
# :pulses    → 集群概览仪表盘

6.3 kustomize:管理多环境配置差异

生产中同一个应用需要部署到多个环境(staging、production),它们的区别可能只是副本数、镜像版本、环境变量。如果为每个环境维护一份完整的 YAML,大量重复且容易漏改。

kustomize 用 Base + Overlay 模式解决:

base/                              # 基础配置(所有环境共享)
  ├── deployment.yaml
  ├── service.yaml
  └── kustomization.yaml
overlays/
  ├── staging/
  │   ├── kustomization.yaml       # 引用 base,叠加 staging 差异
  │   └── replicas-patch.yaml      # staging 用 1 个副本
  └── production/
      ├── kustomization.yaml       # 引用 base,叠加 production 差异
      └── replicas-patch.yaml      # production 用 5 个副本
# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base                       # 引用 base
namePrefix: prod-                  # 所有资源名加 prod- 前缀
commonLabels:
  env: production                  # 所有资源加 env=production label
patches:
- path: replicas-patch.yaml        # 叠加副本数补丁
# 预览渲染结果(不实际应用)
kubectl kustomize overlays/production/

# 直接应用
kubectl apply -k overlays/production/

kustomize 的核心优势:base 的 YAML 不需要任何修改——它不需要模板语法(不像 Helm 需要 {{ .Values.replicas }}),是纯粹的 K8s YAML。

6.4 Helm:复杂应用的包管理

当你需要部署一个复杂的第三方应用(比如 Prometheus 全家桶,涉及几十个 K8s 资源),手动写 YAML 不现实。Helm 用模板化的方式把这些资源打包成一个 Chart,用户只需要提供 values(配置参数)即可安装。

# 添加 Chart 仓库
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

# 搜索
helm search repo prometheus

# 查看这个 Chart 有哪些可配置的 values
helm show values prometheus-community/kube-prometheus-stack

# 安装(用自定义 values 覆盖默认值)
helm install monitoring prometheus-community/kube-prometheus-stack \
  -n monitoring --create-namespace \
  -f custom-values.yaml

# 升级(修改 values 后)
helm upgrade monitoring prometheus-community/kube-prometheus-stack \
  -n monitoring -f custom-values.yaml

# 查看已安装的 Release
helm list -A

# 回滚到上一个版本
helm rollback monitoring 1 -n monitoring

# 查看 Release 的当前 values
helm get values monitoring -n monitoring

kustomize vs Helm 的选择:


7. 生产环境运维 Checklist

7.1 上线前检查清单

资源配置:

健康检查:

高可用:

安全:

配置与优雅关闭:

7.2 常见事故场景与应急处理

场景 你看到的现象 应急止血 根因排查方向
应用 OOM Pod CrashLoopBackOff,Exit Code 137 kubectl patch deploy <name> -p '{"spec":{"template":{"spec":{"containers":[{"name":"app","resources":{"limits":{"memory":"1Gi"}}}]}}}}' 内存泄漏?JVM heap 设置不合理?
错误配置上线 新 Pod 起不来,旧 Pod 被逐步替换掉 kubectl rollout undo deployment/<name> 检查 ConfigMap/Secret 内容、环境变量
Node 故障 Node NotReady,Pod Terminating/Unknown kubectl drain <node> --force --grace-period=0(如果 Node 完全不可达) SSH 到 Node 检查 kubelet、containerd、系统资源
etcd 空间满 apiserver 只读,任何创建/更新操作都报错 etcdctl alarm disarm && etcdctl compact <rev> && etcdctl defrag 监控 etcd DB 大小,调大配额,定期压缩
误删 Namespace Namespace 及其下所有资源被级联删除 从 etcd 备份恢复(etcdctl snapshot restore),或从 Velero 备份恢复 加强 RBAC,限制 namespace delete 权限
证书过期 apiserver/kubelet 认证失败,kubectl 报 x509 错误 kubeadm certs renew all(kubeadm 部署) 设置证书过期监控告警

7.3 监控与告警:必须监控的指标

不是所有指标都需要告警。以下是**如果漏掉会导致"半夜被叫起来"**的指标:

集群级别(Control Plane 健康):

# etcd 是否健康——etcd 挂了,整个集群停摆
etcd_server_has_leader == 0                → 紧急告警

# apiserver 是否响应——apiserver 挂了,kubectl 用不了
apiserver_request_duration_seconds{verb="GET"} P99 > 1s   → 告警
apiserver_request_total{code=~"5.."}       → 5xx 错误率飙升

# Node 数量是否正常
count(kube_node_status_condition{condition="Ready",status="true"}) < expected

Node 级别:

# 内存/磁盘即将耗尽
node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes < 0.1    → 10% 剩余
node_filesystem_avail_bytes{mountpoint="/"} < 5Gi

# kubelet 健康
kubelet_running_pods vs expected

应用级别:

# Pod 反复重启——可能在 CrashLoop
rate(kube_pod_container_status_restarts_total[5m]) > 0    → 告警

# Pod 长时间 Pending——调度不上
kube_pod_status_phase{phase="Pending"} 持续 > 5min

# OOMKill 事件
kube_pod_container_status_last_terminated_reason{reason="OOMKilled"}

# HPA 是否拉满(可能需要扩容 Node)
kube_horizontalpodautoscaler_status_current_replicas
  == kube_horizontalpodautoscaler_spec_max_replicas

8. 参考资料

资源 链接 说明
kubectl 官方参考 kubernetes.io 命令完整参考
kubectl Cheat Sheet kubernetes.io 官方速查表
管理资源的三种方式 kubernetes.io 声明式 vs 命令式详解
Server-Side Apply kubernetes.io SSA 详细文档
调试 Pod kubernetes.io 官方排障指南
调试 Service kubernetes.io Service 排障
Ephemeral Containers kubernetes.io kubectl debug 原理
Troubleshooting Deployments Learnk8s 最佳排障流程图(强烈推荐)
Krew 插件列表 krew.sigs.k8s.io 社区插件索引
stern GitHub 多 Pod 日志聚合
k9s k9scli.io 终端 UI
kubectx + kubens GitHub Context/Namespace 快速切换
kube-ps1 GitHub Shell 提示符集成
kubectl-tree GitHub 资源树可视化
Helm helm.sh 包管理
Kustomize kustomize.io 配置管理
Kubernetes in Action (2nd Ed) Marko Lukša kubectl 使用和原理最详细
Cloud Native DevOps with K8s Arundel & Domingus 运维最佳实践

本文基于 Kubernetes v1.30+ 和 kubectl 对应版本撰写。