本文定位：速查手册。 只收录日常最高频的 kubectl 子命令，供现场对照执行，不展开 K8s 对象原理。想了解资源类型定义与关系，读同目录的《Kubernetes核心概念详解》。

版本说明

本文基于 kubectl v1.20-v1.31 通用语法整理。kubectl 与 API Server 需遵循版本偏差策略：客户端可比服务端新/旧 1 个小版本。超过此范围可能出现字段不识别或行为差异。建议保持 kubectl 版本与集群版本接近。

---

集群与上下文

命令	用途
kubectl cluster-info	查看集群地址与核心服务地址
kubectl version	查看客户端与服务器版本
kubectl config current-context	查看当前上下文
kubectl config get-contexts	列出所有上下文
kubectl config use-context <name>	切换上下文
kubectl config set-context --current --namespace=<ns>	为当前上下文设置默认命名空间

易错点：跨多个集群操作时，忘记确认当前上下文可能导致误操作生产环境。建议在 prompt 中显示当前 context（如 kube-ps1）。

---

Pod 操作

命令	用途
kubectl get pods	列出 default 命名空间的 Pod
kubectl get pods -n <ns> -o wide	指定命名空间，显示节点 IP
kubectl describe pod <name>	查看 Pod 详情（事件、状态变更）
kubectl logs <name>	查看 Pod 日志
kubectl logs <name> --previous	查看上次终止容器的日志（崩溃排查）
kubectl logs -f <name>	实时跟踪日志（tail -f 效果）
kubectl logs <name> -c <container>	多容器 Pod 指定容器名
kubectl exec -it <name> -- /bin/sh	进入容器执行交互命令
kubectl cp <pod>:/path /local/path	复制文件从容器到本地
kubectl top pod	查看 Pod CPU/内存使用（需 metrics-server）

批量操作 Pod：

# 删除某标签的全部 Pod
kubectl delete pods -l app=nginx

# 重启 Deployment 下的全部 Pod（触发滚动更新）
kubectl rollout restart deployment/nginx

---

Deployment 与 ReplicaSet

命令	用途
kubectl get deployments	列出 Deployment
kubectl get deployments -n <ns>	指定命名空间
kubectl describe deployment <name>	查看详情（滚动策略、事件）
kubectl scale deployment <name> --replicas=3	调整副本数
kubectl rollout status deployment/<name>	查看滚动更新状态
kubectl rollout history deployment/<name>	查看更新历史
kubectl rollout undo deployment/<name>	回滚到上一版本
kubectl rollout undo deployment/<name> --to-revision=2	回滚到指定版本

易错点：kubectl apply 更新 Deployment 后，Pod 不会立即全部替换。使用 rollout status 确认完成再验证。

---

Service 与网络

命令	用途
kubectl get services	列出 Service
kubectl get svc -n <ns> -o wide	显示 ClusterIP/NodePort
kubectl describe svc <name>	查看 endpoints（关联的 Pod IP 列表）
kubectl port-forward svc/<name> 8080:80	本地端口转发到 Service
kubectl port-forward pod/<name> 8080:80	本地端口转发到 Pod

端口转发调试：

# 本地 3306 转发到集群内 mysql 服务的 3306
kubectl port-forward svc/mysql 3306:3306 -n database

# 然后在本地用 mysql 客户端连接 localhost:3306

---

ConfigMap 与 Secret

命令	用途
kubectl get configmaps	列出 ConfigMap
kubectl get secrets	列出 Secret（值默认不显示）
kubectl create configmap <name> --from-literal=key=value	从命令行创建
kubectl create configmap <name> --from-file=app.conf	从文件创建
kubectl create secret generic <name> --from-literal=pass=123	创建通用 Secret
kubectl create secret tls <name> --cert=cert.pem --key=key.pem	创建 TLS Secret
kubectl describe secret <name>	查看 Secret 键名（不显示值）
kubectl get secret <name> -o jsonpath='{.data.pass}' | base64 -d	解码查看密码

易错点：Secret 的 value 是 base64 编码，但不是加密。任何有 namespace 读权限的人都能解码查看。

---

资源创建与编辑

命令	用途
kubectl apply -f manifest.yaml	根据 YAML 创建/更新资源
kubectl apply -f /path/to/dir/	应用目录下所有 YAML
kubectl delete -f manifest.yaml	根据 YAML 删除资源
kubectl edit deployment <name>	交互式编辑资源
kubectl get deployment <name> -o yaml	导出 YAML 到 stdout
kubectl diff -f manifest.yaml	预览变更（试运行）

快捷导出：

# 快速导出 Deployment YAML 以便修改
kubectl get deploy nginx -o yaml > nginx-backup.yaml

# 导出时不带集群特定字段（干净导入其他集群）
kubectl get deploy nginx -o yaml | kubectl-neat > nginx-clean.yaml

---

故障排查三板斧

1. 看事件：

kubectl get events -n <ns> --sort-by='.lastTimestamp'

2. 看日志：

kubectl logs <pod> --previous  # 崩溃前日志
kubectl logs <pod> -f         # 实时日志

3. 进容器：

kubectl exec -it <pod> -- /bin/sh
# 或指定容器
kubectl exec -it <pod> -c <container> -- /bin/sh

---

常用选项速查

选项	含义
-n, --namespace	指定命名空间
-o wide	额外信息（节点、IP）
-o yaml	YAML 格式输出
-o json	JSON 格式输出
-o jsonpath='...'	提取特定字段
-l, --selector	按标签筛选
--all-namespaces, -A	所有命名空间
--dry-run=client	客户端试运行（不提交）
-w, --watch	持续监视变化

---

坑与边界

1. 权限不足的表现

kubectl get pods 返回成功但列表为空，通常是 RBAC 限制（当前用户无权查看该 namespace），而非真的没 Pod。

2. 端口转发的局限性

kubectl port-forward 通过 API Server 代理，不适合高吞吐量场景（性能损耗大）。长期暴露服务请用 kubectl expose 或 Ingress。

3. apply vs create

• create：资源已存在时报错
• apply：声明式，存在则更新，不存在则创建

生产脚本优先用 apply，配合 GitOps 工作流。

4. 资源删除顺序

删除 Deployment 会自动删除其创建的 ReplicaSet 和 Pod。但删除 Service 不会自动删除后端 Pod。

---

🤖 Agent 可直接解析的元数据块（点击展开）

{
  "_meta": {
    "doc_version": "2022-03-29",
    "article_id": "kubectl-cheatsheet",
    "profile_context": "k8s",
    "estimated_setup_time": "5min"
  },
  "quick_start": {
    "check_cluster": "kubectl cluster-info",
    "list_pods": "kubectl get pods -n default",
    "view_logs": "kubectl logs -f <pod-name>",
    "exec_shell": "kubectl exec -it <pod-name> -- /bin/sh",
    "port_forward": "kubectl port-forward svc/<svc> 8080:80",
    "apply_manifest": "kubectl apply -f manifest.yaml",
    "rollout_restart": "kubectl rollout restart deployment/<name>"
  },
  "safety_rules": [
    "执行前确认当前 context：kubectl config current-context",
    "生产环境删除前先用 --dry-run=client 预览",
    "Secret 非加密，敏感信息考虑配合 Sealed Secrets 或 Vault",
    "kubectl port-forward 不适合生产流量"
  ],
  "verification": {
    "cluster_ready": "kubectl get nodes",
    "pod_running": "kubectl get pod <name> -o jsonpath='{.status.phase}'",
    "service_endpoints": "kubectl get endpoints <svc-name>"
  },
  "troubleshooting": {
    "pod_crash": "kubectl logs <pod> --previous",
    "pod_pending": "kubectl describe pod <pod> | grep -A 10 Events",
    "rbac_denied": "kubectl auth can-i get pods -n <ns>"
  }
}