kubectl 命令速查

kubectl（Kubernetes 命令行客户端）快速参考：上下文切换、get/describe、apply、日志/exec、rollout、扩缩容与排障，并附带常用参数和实操示例。

40 条命令

集群与上下文

kubectl version

打印客户端与服务端的版本信息（用于排查版本不一致问题）。

--client 仅客户端；-o yaml/json

kubectl version -o yaml | yq '.clientVersion.minor'

kubectl cluster-info

显示集群中 Master 和各服务的信息。

--context ctx；--output json|yaml

kubectl cluster-info --context prod-eu

kubectl config get-contexts

列出 kubeconfig 中所有的 context。

--minify；-o name|json|yaml

kubectl config get-contexts -o name | xargs -I{} echo {}

kubectl config use-context <name>

切换当前 context。

kubectl config use-context prod-eu

kubectl config current-context / set-context <name>

读取当前 context 或重命名 / 更新 context（设置命名空间、集群、用户）。

--current 打印当前；set-context --namespace N --cluster C --user U

kubectl config set-context dev-team-a --namespace shop --cluster dev --user dev

kubectl config set <name> <value>

修改当前 context 的默认命名空间，后续命令就不用每次加 -n。

kubectl config set-context --current --namespace=argocd && kubectl get pods

查看与检查

kubectl get all

列出 Pod、Service、Deployment、ReplicaSet、StatefulSet 等常用资源。

-A 所有命名空间；-n ns；-l label=key=value 选择器；-o wide|yaml|json|name|custom-columns；--sort-by

kubectl get all -A -o wide | grep -i Error

kubectl get pods / svc / deploy / ds / sts

列出某一类资源（最常用的几种类型）。

-A；-l app=api；-o wide（显示节点与 IP）；--field-selector；--sort-by .metadata.creationTimestamp

kubectl get pod -n kube-system -l k8s-app=metrics-server -o wide

kubectl get -o yaml|json

将对象完整导出为 YAML / JSON，便于检查或导出。

-o yaml；--export 保存时去除集群特有字段

kubectl get deploy api -n shop -o yaml | grep -E 'image|replicas|envFrom'

kubectl describe <type> <name>

显示对象的底层信息、事件、容器状态与生命周期——排查问题的首选。

-n ns；-A 所有命名空间；--show-events=true

kubectl describe pod api-7c5d-xn2kq -n shop | tail -50

kubectl explain <resource[.field]>

直接从 API Server 读取并展示资源 / 字段的 schema 文档。

kubectl explain pod.spec.containers.resources.limits

应用与管理

kubectl apply -f <file|dir|url>

以声明式方式应用或更新清单，使集群状态与清单一致。

-f 文件|目录|URL；-R 递归目录；--prune；--force-conflicts 强制覆盖（服务端 apply）；--server-side

kubectl apply -k overlays/prod && kubectl apply -f https://.../manifests.yaml

kubectl diff -f <file>

预览 apply 会产生的差异（需要设置 KUBECTL_EXTERNAL_DIFF 或安装 diff 工具）。

-R；--server-side；--prune

kubectl diff -f overlays/prod | head -50

kubectl create|delete -f <file>

命令式地从清单创建或删除资源（一次性操作）。

create -f；delete -f；delete pod foo；delete svc,deploy -l app=foo（多种资源）

kubectl delete -f bad-app.yaml --grace-period=0 --force

kubectl edit <type> <name>

在编辑器（默认 vi）中直接编辑集群中的对象。

-o yaml；--save-config；--windows-line-ending

KUBE_EDITOR="code --wait" kubectl edit deploy api -n shop

kubectl patch <type> <name> --patch '<json>'

对线上对象应用 strategic-merge 或 JSON patch。

--type strategic|merge|json；--patch-file file.json

kubectl patch deploy api -n shop --type merge -p '{"spec":{"replicas":6}}'

kubectl set image <type> <name> container=image

通过新镜像触发滚动更新；同样可用于 set image env / resources。

set image env / resources / serviceaccount / subject / selector

kubectl set image deploy/api api=ghcr.io/team/api:1.4.2 && kubectl rollout status deploy/api

kubectl label / annotate <type> <name>

为线上对象添加或更新标签 / 注解。

key=value 新增；key- 移除（以 - 结尾）；--overwrite

kubectl label pod -n shop -l app=api release=v1.4.2 --overwrite

日志与 Exec

kubectl logs <pod>

打印 Pod 的日志（配合 -c 可指定容器）。

-f 跟踪；--tail N；--since R|D|T；--timestamps；-c 容器；--all-containers；-p 上一个实例

kubectl logs -n shop -f --tail 100 --timestamps api-7c5d-xn2kq

kubectl logs --previous

显示容器上一个实例的日志（崩溃 / 重启之后）。

-c 容器；--tail N

kubectl logs -p api-7c5d-xn2kq -c api --tail 200 | grep panic

kubectl logs -l <label> --all-containers

按 label 聚合多个 Pod 的日志，查看 Deployment 全量日志很方便。

-l app=api；--all-containers=true；-f；--max-log-requests N

kubectl logs -n shop -l app=worker --all-containers -f --max-log-requests 8

kubectl exec -it <pod> -- <cmd>

在 Pod 内执行命令，支持交互式 Shell（bash/sh）。

-it；-c 容器；-n ns；-- /bin/sh

kubectl exec -n shop -it api-7c5d-xn2kq -- /bin/sh -c 'printenv | grep DATABASE'

kubectl cp <pod>:<src> <dest>

在 Pod 与本机之间复制文件/目录（底层使用 exec + tar）。

-c 容器；-n ns

kubectl cp shop/api-7c5d-xn2kq:app/config.yaml ./config.yaml

kubectl port-forward <pod> <local>:remote>

将一个或多个本地端口转发到 Pod（或 svc、deploy）。

pod/<name> <l>:r；svc/<name> <l>:r；--address 127.0.0.1

kubectl port-forward svc/argocd-server -n argocd 8443:443

发布与扩缩

kubectl rollout status deploy/<name>

观察滚动更新的进度，直至完成（或超时）。

--timeout 5m；--revision N

kubectl rollout status deploy/api -n shop --timeout 2m

kubectl rollout history / undo

查看发布历史 / 回滚到指定版本。

history --revision N；undo --to-revision N；--dry-run=client

kubectl rollout history deploy/api -n shop && kubectl rollout undo deploy/api --to-revision=3

kubectl rollout restart deploy/<name>

通过修改 Pod 模板触发 Deployment（或 DaemonSet、StatefulSet）重启。

-n ns

kubectl rollout restart deploy api -n shop && kubectl get pods -l app=api -w

kubectl scale deploy/<n> --replicas=N

手动设置副本数；不会修改清单文件本身。

--current-replicas 先校验；--dry-run=client -o yaml

kubectl scale deploy/api -n shop --current-replicas 2 --replicas 6

kubectl autoscale deploy/<n> --min=2 --max=10 --cpu-percent=80

按给定上下界创建 HPA（也可使用 kubectl create hpa）。

--max --min --cpu-percent；--dry-run=client -o yaml

kubectl autoscale deploy/api -n shop --min=3 --max=15 --cpu-percent=70

节点与 Pod 生命周期

kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

在节点维护（如升级）前，安全地驱逐节点上的 Pod。

--grace-period N；--force；--skip-errors；--dry-run；--delete-emptydir-data

kubectl drain ip-10-0-1-7 --ignore-daemonsets --delete-emptydir-data --grace-period 60

kubectl cordon / uncordon <node>

将节点标记为不可调度（cordon）/ 恢复可调度（uncordon）。维护结束后执行 uncordon。

无需参数，按位置传入节点名

kubectl cordon ip-10-0-1-7 && kubectl uncordon ip-10-0-1-7

kubectl delete pod <pod>

删除一个 Pod——若属于 Deployment，控制器会重建（常用于强制重启单个实例）。

--grace-period=0 --force；-n ns；--now

kubectl delete pod -n shop api-7c5d-xn2kq --grace-period=0 --force

排障

kubectl top node / pod

显示实时的 CPU/内存使用情况（需要 metrics-server）。

--sort-by cpu|memory；--containers；-A；-l

kubectl top node && kubectl top pod -A --sort-by=memory | head

kubectl debug <pod>

附加一个带调试工具的容器（kubectl-debug / Ephemeral Containers）。

--image <img>；--target-container；--share-processes；--profile

kubectl debug -it api-7c5d-xn2kq --image=nicolaka/netshoot --target-container=api

kubectl get events --sort-by=.lastTimestamp

跟踪集群事件，便于定位调度 / 拉镜像 / 探针失败。

--field-selector involvedObject.name=podX；-A；-w；--watch-only-events

kubectl get events -n shop --sort-by=.lastTimestamp -w | grep -v 'Normal'

kubectl auth can-i <verb> <resource>

检查当前用户能做什么——RBAC 排障利器。

--as user；--as-group；-n ns；--all-namespaces

kubectl auth can-i create pods -n prod --as system:serviceaccount:team-a:deployer

kubectl wait --for=condition=Ready

阻塞直至资源达到期望状态（适合在 CI / 脚本中使用）。

--for condition=Ready|Available；--timeout 60s；--all --selector

kubectl wait -n shop --for=condition=Available deploy/api --timeout 120s

资源与清单

kubectl create cm|secret ... --from-file|--from-literal

命令式地创建 ConfigMap / Secret（Secret 可用 kubectl create secret generic ...）。

--from-file；--from-literal=KEY=val；--dry-run=client -o yaml

kubectl -n shop create secret generic api-creds --from-literal=API_KEY=$(cat key.txt)

kubectl create token <serviceaccount>

为 ServiceAccount 签发短期 token（推荐替代静态 Secret）。

--duration 24h

kubectl -n shop create token deployer --duration=12h | pbcopy

kubectl get secret <name> -o jsonpath='{.data.K}' | base64 -d

解码一个 base64 编码的 Secret 字段，用于临时查看。

kubectl -n shop get secret api-creds -o jsonpath='{.data.API_KEY}' | base64 -d

速查页版本 1.0.0

适用于 kubectl 1.28+