kubectl 命令速查：上下文、资源查看和故障排查
kubectl 日常使用速查，涵盖 kubeconfig、常用查询与执行命令、资源发布、服务排查和输出格式。
RunbooksCloud tooling
kubectl 是 Kubernetes 的命令行客户端。它负责和 Kubernetes API Server 通信，用来查看集群资源、排查 Pod 问题、应用 YAML 配置、管理 Deployment 发布和执行临时调试命令。
日常使用时，它基本就是 Kubernetes 的入口：
text
kubectl
-> 连接 kubeconfig 指定的集群
-> 读取或修改 Kubernetes API 对象
-> 输出资源状态、事件、日志和配置
这篇是 kubectl 的工具介绍和常用命令手册，不是 Kubernetes 原理教程。目标是：知道它是什么、什么时候用，以及常见场景下该敲哪条命令。
什么时候用 kubectl
日常最常见的使用场景：
text
查看资源:
get / describe
排查问题:
logs / exec / events / describe
临时访问服务:
port-forward
应用配置:
apply / delete / edit
管理发布:
rollout / scale / autoscale
查看 API 字段:
explain
常用占位符：
text
<namespace>
<pod-name>
<container-name>
<deployment-name>
<service-name>
<node-name>
先确认自己在哪
查看当前 context：
bash
kubectl config current-context
kubectl config get-contexts
kubectl config view --minify
切换 context：
bash
kubectl config use-context <context-name>
为当前上下文设置默认命名空间：
bash
kubectl config set-context --current --namespace=<namespace>
单次命令指定 kubeconfig：
bash
kubectl --kubeconfig=/path/to/config get pods
当前 shell 指定多个 kubeconfig：
bash
export KUBECONFIG=/path/to/config1:/path/to/config2
kubectl config get-contexts
优先级：
text
--kubeconfig > KUBECONFIG > ~/.kube/config
基本语法
text
kubectl <command> <resource-type> <resource-name> <flags>
例子：
bash
kubectl get pods
kubectl get pod <pod-name> -n <namespace>
kubectl describe deployment <deployment-name> -n <namespace>
kubectl delete pod <pod-name> -n <namespace>
资源类型可以用完整名或缩写：
bash
kubectl get pods
kubectl get po
kubectl get services
kubectl get svc
kubectl get deployments
kubectl get deploy
get：列资源和看状态
查看 Pod：
bash
kubectl get pods
kubectl get pods -n <namespace>
kubectl get pods -A
kubectl get pods -o wide
kubectl get pods -w
查看常见资源：
bash
kubectl get nodes
kubectl get ns
kubectl get deploy -n <namespace>
kubectl get rs -n <namespace>
kubectl get svc -n <namespace>
kubectl get endpoints -n <namespace>
kubectl get configmap -n <namespace>
kubectl get secret -n <namespace>
kubectl get ingress -n <namespace>
查看某个资源完整 YAML：
bash
kubectl get pod <pod-name> -n <namespace> -o yaml
kubectl get deployment <deployment-name> -n <namespace> -o yaml
只输出资源名：
bash
kubectl get pods -n <namespace> -o name
describe：看事件和现场
Pod 现场：
bash
kubectl describe pod <pod-name> -n <namespace>
Deployment 现场：
bash
kubectl describe deployment <deployment-name> -n <namespace>
Service 现场：
bash
kubectl describe svc <service-name> -n <namespace>
Node 现场：
bash
kubectl describe node <node-name>
describe pod 重点看：
text
Node
Status
Containers
State / Last State
Ready
Restart Count
Events
排障时先看这些方向：
text
ImagePullBackOff 看 image、secret、registry
CrashLoopBackOff 看 logs --previous
Pending 看 describe pod 的 Events 和 node 资源
Readiness probe failed 看 probe 配置和应用端口
MountVolume failed 看 PVC、Secret、ConfigMap
logs：看容器输出
当前日志：
bash
kubectl logs <pod-name> -n <namespace>
持续跟随：
bash
kubectl logs -f <pod-name> -n <namespace>
多容器 Pod 指定容器：
bash
kubectl logs <pod-name> -c <container-name> -n <namespace>
看上一次崩溃前日志：
bash
kubectl logs <pod-name> --previous -n <namespace>
kubectl logs <pod-name> -c <container-name> --previous -n <namespace>
按 label 看日志：
bash
kubectl logs -l app=<app-name> -n <namespace>
限制行数：
bash
kubectl logs <pod-name> -n <namespace> --tail=200
exec：进入容器或执行命令
进入 shell：
bash
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh
kubectl exec -it <pod-name> -c <container-name> -n <namespace> -- /bin/bash
直接执行命令：
bash
kubectl exec <pod-name> -n <namespace> -- env
kubectl exec <pod-name> -n <namespace> -- ls /app
kubectl exec <pod-name> -n <namespace> -- cat /etc/resolv.conf
镜像很精简时，先试：
bash
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh
如果容器里缺少调试工具，考虑临时 debug pod 或 ephemeral container。
cp：容器和本地拷文件
从容器拷到本地：
bash
kubectl cp <namespace>/<pod-name>:/path/to/file ./local-file -c <container-name>
从本地拷到容器：
bash
kubectl cp ./local-file <namespace>/<pod-name>:/path/to/file -c <container-name>
注意：kubectl cp 依赖容器里有 tar。极简镜像可能失败。
port-forward：本地访问集群内部服务
转发 Pod：
bash
kubectl port-forward pod/<pod-name> 8080:80 -n <namespace>
转发 Service：
bash
kubectl port-forward svc/<service-name> 8080:80 -n <namespace>
本地访问：
bash
curl http://127.0.0.1:8080
port-forward 适合临时调试，不适合作为发布入口。
apply / create / delete
声明式应用配置：
bash
kubectl apply -f deployment.yaml
kubectl apply -f ./manifests/
创建命名空间：
bash
kubectl create namespace <namespace>
生成 YAML 模板，不直接创建：
bash
kubectl create deployment nginx \
--image=nginx \
--dry-run=client \
-o yaml
删除资源：
bash
kubectl delete -f deployment.yaml
kubectl delete pod <pod-name> -n <namespace>
kubectl delete pods --all -n <namespace>
强制删除卡住的 Pod：
bash
kubectl delete pod <pod-name> --force --grace-period=0 -n <namespace>
强制删除要谨慎。Pod 如果由 Deployment 管理，删除后控制器会重新拉起。
edit：临时改线上对象
bash
kubectl edit deployment <deployment-name> -n <namespace>
kubectl edit svc <service-name> -n <namespace>
edit 适合临时验证或救火。长期配置应该回到 YAML、Helm 或 GitOps。
rollout：发布、重启、回滚
查看发布状态：
bash
kubectl rollout status deployment/<deployment-name> -n <namespace>
查看发布历史：
bash
kubectl rollout history deployment/<deployment-name> -n <namespace>
回滚到上一版：
bash
kubectl rollout undo deployment/<deployment-name> -n <namespace>
回滚到指定修订版本：
bash
kubectl rollout undo deployment/<deployment-name> --to-revision=2 -n <namespace>
重启 Deployment：
bash
kubectl rollout restart deployment/<deployment-name> -n <namespace>
扩缩容：
bash
kubectl scale deployment/<deployment-name> --replicas=3 -n <namespace>
设置 HPA：
bash
kubectl autoscale deployment/<deployment-name> --cpu-percent=80 --min=2 --max=10 -n <namespace>
Service 没流量时
看 Service：
bash
kubectl get svc <service-name> -n <namespace>
kubectl describe svc <service-name> -n <namespace>
看 endpoints：
bash
kubectl get endpoints <service-name> -n <namespace>
kubectl get endpointslice -n <namespace>
看 Pod labels：
bash
kubectl get pods -n <namespace> --show-labels
kubectl get pods -n <namespace> -l app=<app-name>
Service 没有 endpoints 时，优先查：
text
Service selector 是否匹配 Pod label
Pod 是否 Ready
targetPort 是否对上容器端口
namespace 是否正确
输出格式
YAML：
bash
kubectl get pod <pod-name> -n <namespace> -o yaml
JSON：
bash
kubectl get pod <pod-name> -n <namespace> -o json
JSONPath：
bash
kubectl get pods -n <namespace> -o jsonpath='{.items[*].metadata.name}'
自定义列：
bash
kubectl get pods -n <namespace> \
-o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,PHASE:.status.phase
按字段排序：
bash
kubectl get pods -n <namespace> --sort-by=.metadata.creationTimestamp
explain：查字段文档
bash
kubectl explain pod
kubectl explain pod.spec
kubectl explain pod.spec.containers
kubectl explain deployment.spec.strategy
不知道 YAML 字段怎么写时，可以先用 explain 查看 API 结构说明。
临时调试 Pod
BusyBox：
bash
kubectl run -it --rm debug-pod --image=busybox --restart=Never -n <namespace> -- sh
Ubuntu：
bash
kubectl run -it --rm debug-ubuntu --image=ubuntu --restart=Never -n <namespace> -- bash
检查 DNS：
bash
kubectl run -it --rm dnsutils --image=registry.k8s.io/e2e-test-images/jessie-dnsutils:1.3 -n <namespace> -- nslookup kubernetes.default
节点维护
禁止新 Pod 调度到节点：
bash
kubectl cordon <node-name>
驱逐节点上 Pod：
bash
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
恢复调度：
bash
kubectl uncordon <node-name>
drain 会影响工作负载，生产环境要先确认 PDB、本地数据卷和 DaemonSet。
常用排障顺序
服务访问不了：
bash
kubectl get pods -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> --previous -n <namespace>
kubectl get svc <service-name> -n <namespace>
kubectl describe svc <service-name> -n <namespace>
kubectl get endpoints <service-name> -n <namespace>
kubectl describe deployment <deployment-name> -n <namespace>
kubectl get rs -n <namespace>
发布卡住：
bash
kubectl rollout status deployment/<deployment-name> -n <namespace>
kubectl describe deployment <deployment-name> -n <namespace>
kubectl get pods -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>
Pod 一直重启：
bash
kubectl get pod <pod-name> -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> --previous -n <namespace>
kubectl logs <pod-name> -n <namespace>
别名和补全
别名：
bash
alias k=kubectl
Zsh 补全：
bash
source <(kubectl completion zsh)
写进 ~/.zshrc：
bash
echo 'source <(kubectl completion zsh)' >> ~/.zshrc
文档和 runbook 里建议写完整 kubectl，不要默认读者有 k alias。