kubectl 命令完整手册：上下文、查询、修改、日志与现场调试

实验基线：Kubernetes v1.37.0、kubectl v1.37.0。先在测试环境执行，记录变更前状态与回滚点；生产集群不得直接照抄节点地址、网段、存储类或资源额度。

第一原则：每次操作先确认上下文

kubectl config current-context
kubectl config get-contexts
kubectl config use-context kind-lab
kubectl auth can-i create deployments -n lab

生产事故常不是命令写错，而是上下文或命名空间错。脚本中显式写 --context 与 --namespace，变更前执行 auth can-i。

查询与定位

kubectl get deploy,pod,svc -n lab -o wide
kubectl get pods -n lab -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'
kubectl explain deployment.spec.template.spec.containers.resources
kubectl describe pod <pod> -n lab
kubectl get events -n lab --sort-by=.metadata.creationTimestamp

get看总体状态，describe看事件和关联配置，logs看进程输出。不要一开始就进入容器修改文件，这会制造不可追踪状态。

变更、观察与回滚

kubectl diff -f web.yaml
kubectl apply -f web.yaml
kubectl rollout status deployment/web -n lab --timeout=120s
kubectl rollout history deployment/web -n lab
kubectl rollout undo deployment/web -n lab

临时补丁用 kubectl patch，长期配置应回写 Git 中的清单。kubectl edit适合紧急修复，但操作后必须导出对象并复盘差异。

日志与调试

kubectl logs -n lab <pod> -c app --since=10m --timestamps
kubectl logs -n lab <pod> -c app --previous
kubectl port-forward -n lab service/web 8080:80
kubectl debug -n lab pod/<pod> -it --image=busybox:1.36 --target=app

--previous用于崩溃重启前一实例；临时容器是否可用取决于集群策略。调试结束删除临时资源，并把证据保存到工单。

kubeconfig 与多集群安全管理

kubectl config view --minify
kubectl config get-contexts
kubectl config set-context --current --namespace=lab
kubectl config rename-context old-name lab-cluster
kubectl config view --raw

--raw可能输出证书和令牌，只能在受控终端查看，禁止粘贴到工单。自动化使用短期凭据或专用 ServiceAccount，不共享管理员 kubeconfig。

结构化输出而不是 grep

kubectl get pods -n lab -o custom-columns='NAME:.metadata.name,IMAGE:.spec.containers[*].image,READY:.status.containerStatuses[*].ready'
kubectl get pods -n lab -o jsonpath='{range .items[?(@.status.phase!="Running")]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'
kubectl get deployment web -n lab -o yaml --show-managed-fields

JSONPath 适合轻量查询，复杂统计使用 JSON 配合 jq。脚本不要解析默认表格，因为列可能随版本和终端宽度改变。

声明式修改的完整流程

kubectl apply --dry-run=server -f让 API Server 做校验与准入。
kubectl diff -f审阅实际差异。
提交到版本库并由流水线 apply。
rollout status等待部署，再做业务检查。
失败时 rollback，并保存事件和日志。

kubectl apply --dry-run=server -f web.yaml
kubectl diff -f web.yaml
kubectl apply -f web.yaml --field-manager=gitops
kubectl rollout status deployment/web -n lab --timeout=180s

patch 类型不要混用

kubectl patch deployment web -n lab --type=merge \
  -p '{"spec":{"replicas":3}}'
kubectl patch deployment web -n lab --type=json \
  -p='[{"op":"replace","path":"/spec/template/spec/containers/0/image","value":"nginx:1.27.1-alpine"}]'

merge patch 适合对象字段，JSON patch 精确到路径；数组下标变化会使 JSON patch 指错容器，执行前必须导出对象确认。

现场取证顺序

记录 context、namespace、时间范围与对象 UID。
保存 get/describe/events。
采集当前和 previous 日志。
仅在必要时 exec/debug，不在容器内做永久修改。
导出最终 YAML 和 rollout history。

kubectl get pod <pod> -n lab -o yaml > pod-evidence.yaml
kubectl describe pod <pod> -n lab > pod-describe.txt
kubectl logs <pod> -n lab --all-containers --timestamps > pod-current.log
kubectl logs <pod> -n lab --all-containers --previous --timestamps > pod-previous.log

可复现记录模板

每次实验记录：集群版本、容器运行时、CNI/CSI 版本、命名空间、使用的 YAML Git 提交、开始与结束时间。命令输出至少保留对象状态、事件、关键日志和回滚结果。文中的占位符必须替换成自己的值，生产执行前应由第二人复核。

故障处理原则

先缩小影响面，不删除现场。
按对象状态—事件—日志—依赖顺序收集证据。
提出可证伪假设，一次只改变一个变量。
验证恢复后清理临时权限、调试 Pod、端口转发和测试数据。

完成检查

命令退出码为 0，目标对象状态与预期一致。
保存执行前后 YAML、事件与关键日志，确认没有把测试命名空间以外的对象改动。
故障演练完成后执行清理或回滚，再进行下一章。