适用范围：kubectl 1.19 ~ 1.34+，命令以 GA（稳定） 子命令为主，避免依赖 alpha/beta 特性。
约定：未指定 -n 时默认为 default 命名空间；生产环境建议始终显式指定 -n <namespace>。

---

一、通用约定

1.1 资源简称（alias）

全称	简称	说明
pods	po	Pod
deployments	deploy	Deployment
statefulsets	sts	StatefulSet
daemonsets	ds	DaemonSet（非 dm）
configmaps	cm	ConfigMap
secrets	secret	Secret（无官方 sc 简称；sc 通常指 StorageClass）
services	svc	Service
ingresses	ing	Ingress
namespaces	ns	Namespace
persistentvolumeclaims	pvc	PVC
persistentvolumes	pv	PV
storageclasses	sc	StorageClass
serviceaccounts	sa	ServiceAccount
jobs	job	Job
cronjobs	cj	CronJob
replicasets	rs	ReplicaSet
horizontalpodautoscalers	hpa	HPA

查看本机全部简称：

kubectl api-resources
kubectl api-resources --verbs=list,get,create,update,patch,delete

1.2 全局参数（各资源通用）

# 命名空间
-n <ns>                    # 指定命名空间
-A  或  --all-namespaces    # 所有命名空间

# 输出格式（1.19+ 均支持）
-o wide                    # 额外列（节点、IP 等）
-o yaml / -o json          # 完整清单
-o name                    # 仅资源名
-o custom-columns=...      # 自定义列

# 标签选择（稳定语法）
-l key=value
--field-selector status.phase=Running   # Pod 等支持字段选择

# 上下文与集群
kubectl config current-context
kubectl config use-context <ctx>
kubectl config set-context --current --namespace=<ns>

1.3 四种变更方式（通用，优先顺序建议）

方式	命令	特点	版本
声明式	kubectl apply -f file.yaml	可重复执行、GitOps 友好	全版本
命令式（对象）	kubectl create/edit/patch/set/scale/rollout	适合临时改字段	全版本
交互式	kubectl edit <type> <name>	直接改 API 对象	全版本
替换式	kubectl replace -f file.yaml	需完整对象，易踩坑	全版本

生成 YAML 模板（不真正创建，全版本通用）：

kubectl create deployment nginx --image=nginx:1.25 --dry-run=client -o yaml > deploy.yaml
kubectl create configmap my-cm --from-literal=k=v --dry-run=client -o yaml > cm.yaml

1.19+ 也支持 --dry-run=server（服务端校验），需 apiserver 开启相应能力。

1.4 通用查询 / 删除

# 列表
kubectl get <资源简称> [-n <ns>] [-o wide|yaml]
kubectl get all -n <ns>              # 常见工作负载聚合（不含 CM/Secret/PVC 等）

# 详情
kubectl describe <资源简称> <name> -n <ns>

# 事件（排障）
kubectl get events -n <ns> --sort-by='.lastTimestamp'
kubectl get events -A --field-selector involvedObject.name=<pod名>

# 删除
kubectl delete <资源简称> <name> -n <ns>
kubectl delete -f manifest.yaml
kubectl delete <资源简称> --all -n <ns>          # 慎用
kubectl delete <资源简称> -l app=foo -n <ns>     # 按标签删

1.5 通用标签 / 注解

kubectl label <type> <name> key=value [--overwrite] -n <ns>
kubectl annotate <type> <name> key=value [--overwrite] -n <ns>

1.6 通用 patch（JSON / strategic merge）

# 合并 patch（改副本数示例）
kubectl patch deployment my-deploy -n <ns> -p '{"spec":{"replicas":3}}'

# strategic merge patch（改容器镜像）
kubectl patch deployment my-deploy -n <ns> --type=strategic -p \
  '{"spec":{"template":{"spec":{"containers":[{"name":"nginx","image":"nginx:1.26"}]}}}}'

---

二、Pod（po）

2.1 创建

# 命令式单 Pod（调试用，非生产推荐）
kubectl run nginx --image=nginx:1.25 --restart=Never -n <ns>
kubectl run nginx --image=nginx:1.25 --restart=Never --dry-run=client -o yaml > pod.yaml
kubectl apply -f pod.yaml

# 由 Deployment/STS 等控制器创建（推荐）
kubectl apply -f deploy.yaml   # 见 Deployment 章节

2.2 查询

kubectl get pods -n <ns>
kubectl get pods -n <ns> -o wide
kubectl get pod <name> -n <ns> -o yaml
kubectl describe pod <name> -n <ns>

# 按标签 / 字段
kubectl get pods -n <ns> -l app=nginx
kubectl get pods -n <ns> --field-selector=status.phase=Running

# 查看容器状态
kubectl get pod <name> -n <ns> -o jsonpath='{.status.containerStatuses[*].ready}'

2.3 修改 / 运维

# 资源限制（需 Pod 由可 patch 的控制器管理时改 controller）
kubectl set resources pod <name> -c <container> --limits=cpu=500m,memory=512Mi -n <ns>

# 注意：直接改独立 Pod 用 edit；由 Deployment 管理的应改 Deployment
kubectl edit pod <name> -n <ns>

# 进入容器
kubectl exec -it <pod> -n <ns> -- /bin/sh
kubectl exec -it <pod> -c <container> -n <ns> -- bash

# 端口转发
kubectl port-forward pod/<name> 8080:80 -n <ns>

# 拷贝文件
kubectl cp <ns>/<pod>:/path/in/container ./local -c <container>
kubectl cp ./local <ns>/<pod>:/path/in/container -c <container>

# 查看日志
kubectl logs <pod> -n <ns>
kubectl logs <pod> -c <container> -n <ns> --tail=100 -f
kubectl logs <pod> -n <ns> --previous          # 崩溃前一次实例

2.4 删除

kubectl delete pod <name> -n <ns>
kubectl delete pod <name> -n <ns> --grace-period=0 --force   # 节点失联等极端场景，慎用

---

三、Deployment（deploy）

3.1 创建

kubectl create deployment nginx --image=nginx:1.25 -n <ns>
kubectl create deployment nginx --image=nginx:1.25 --replicas=3 -n <ns> \
  --dry-run=client -o yaml > deploy.yaml
kubectl apply -f deploy.yaml

3.2 查询

kubectl get deploy -n <ns>
kubectl get deploy <name> -n <ns> -o wide
kubectl describe deploy <name> -n <ns>
kubectl get rs -n <ns> -l app=<label>    # 关联 ReplicaSet

3.3 修改

# 扩缩容
kubectl scale deployment <name> --replicas=5 -n <ns>

# 改镜像（最常用）
kubectl set image deployment/<name> <container>=<image:tag> -n <ns>

# 环境变量
kubectl set env deployment/<name> KEY=VALUE -n <ns>

# 资源
kubectl set resources deployment <name> -c <container> \
  --requests=cpu=100m,memory=128Mi --limits=cpu=500m,memory=512Mi -n <ns>

# 声明式
kubectl apply -f deploy.yaml
kubectl edit deployment <name> -n <ns>

3.4 发布与回滚（rollout）

kubectl rollout status deployment/<name> -n <ns>
kubectl rollout history deployment/<name> -n <ns>
kubectl rollout undo deployment/<name> -n <ns>
kubectl rollout undo deployment/<name> --to-revision=2 -n <ns>
kubectl rollout restart deployment/<name> -n <ns>    # 滚动重启（1.15+）
kubectl rollout pause deployment/<name> -n <ns>      # 金丝雀：暂停后逐步改副本/镜像
kubectl rollout resume deployment/<name> -n <ns>

3.5 删除

kubectl delete deployment <name> -n <ns>
kubectl delete -f deploy.yaml

---

四、StatefulSet（sts）

4.1 创建

# 建议 YAML（含 serviceName、volumeClaimTemplates 等）
kubectl apply -f statefulset.yaml

# 最小示例生成
kubectl create statefulset web --image=nginx:1.25 --replicas=3 -n <ns> \
  --dry-run=client -o yaml > sts.yaml
# 需补全 spec.serviceName、selector 等字段后再 apply

4.2 查询

kubectl get sts -n <ns>
kubectl describe sts <name> -n <ns>
kubectl get pods -n <ns> -l app=<label>   # 通常 pod 名为 <sts名>-0、-1...

4.3 修改

kubectl scale statefulset <name> --replicas=3 -n <ns>
kubectl set image statefulset/<name> <container>=<image:tag> -n <ns>
kubectl patch statefulset <name> -n <ns> -p '{"spec":{"replicas":5}}'
kubectl apply -f statefulset.yaml
kubectl edit statefulset <name> -n <ns>

4.4 发布（与 Deployment 类似）

kubectl rollout status statefulset/<name> -n <ns>
kubectl rollout history statefulset/<name> -n <ns>
kubectl rollout undo statefulset/<name> -n <ns>
kubectl rollout restart statefulset/<name> -n <ns>

注意：STS 缩容不会自动删 PVC，需人工 kubectl delete pvc；扩缩容顺序固定（0→1→2）。

4.5 删除

kubectl delete statefulset <name> -n <ns>
kubectl delete statefulset <name> -n <ns> --cascade=foreground   # 等待 Pod 删完
# 按需删除关联 PVC
kubectl delete pvc -l app=<label> -n <ns>

---

五、DaemonSet（ds）

5.1 创建

kubectl apply -f daemonset.yaml
kubectl create daemonset fluentd --image=fluentd -n <ns> \
  --dry-run=client -o yaml > ds.yaml

5.2 查询

kubectl get ds -n <ns>
kubectl get ds -n <ns> -o wide
kubectl describe ds <name> -n <ns>

5.3 修改

kubectl set image daemonset/<name> <container>=<image:tag> -n <ns>
kubectl apply -f daemonset.yaml
kubectl edit daemonset <name> -n <ns>

5.4 发布

kubectl rollout status daemonset/<name> -n <ns>
kubectl rollout undo daemonset/<name> -n <ns>
kubectl rollout restart daemonset/<name> -n <ns>

5.5 删除

kubectl delete daemonset <name> -n <ns>

---

六、ConfigMap（cm）

6.1 创建

# 字面量
kubectl create configmap app-cm --from-literal=KEY=VALUE -n <ns>
kubectl create configmap app-cm --from-literal=k1=v1 --from-literal=k2=v2 -n <ns>

# 文件 / 目录
kubectl create configmap app-cm --from-file=app.properties -n <ns>
kubectl create configmap app-cm --from-file=./config-dir -n <ns>

# 声明式
kubectl create configmap app-cm --from-literal=KEY=VALUE --dry-run=client -o yaml -n <ns> > cm.yaml
kubectl apply -f cm.yaml

6.2 查询

kubectl get cm -n <ns>
kubectl describe cm <name> -n <ns>
kubectl get cm <name> -n <ns> -o yaml
kubectl get cm <name> -n <ns> -o jsonpath='{.data}'

6.3 修改

# 改单个 key（导出编辑再 apply）
kubectl get cm <name> -n <ns> -o yaml > cm.yaml
# 编辑 data 后
kubectl apply -f cm.yaml

kubectl edit configmap <name> -n <ns>

# 替换整个对象（需 resourceVersion 等字段正确）
kubectl replace -f cm.yaml

已挂载 CM 的 Pod：不会自动热更新（除非用 subPath 除外场景），通常需滚动重启 Deployment：kubectl rollout restart deployment/<name> -n <ns>。

6.4 删除

kubectl delete configmap <name> -n <ns>

---

七、Secret

7.1 创建

# 通用 key-value（值会 base64 存在 data 里）
kubectl create secret generic db-secret \
  --from-literal=username=admin --from-literal=password='xxx' -n <ns>

# 从文件
kubectl create secret generic tls-secret --from-file=tls.crt --from-file=tls.key -n <ns>

# Docker 仓库
kubectl create secret docker-registry regcred \
  --docker-server=<registry> --docker-username=<user> --docker-password=<pass> -n <ns>

# TLS 类型
kubectl create secret tls tls-secret --cert=tls.crt --key=tls.key -n <ns>

kubectl apply -f secret.yaml

7.2 查询

kubectl get secret -n <ns>
kubectl describe secret <name> -n <ns>
kubectl get secret <name> -n <ns> -o yaml
# 解码某个 key（Linux/macOS）
kubectl get secret <name> -n <ns> -o jsonpath='{.data.password}' | base64 -d

7.3 修改

kubectl edit secret <name> -n <ns>
kubectl apply -f secret.yaml

7.4 删除

kubectl delete secret <name> -n <ns>

---

八、Service（svc）

8.1 创建

kubectl expose deployment <deploy名> --port=80 --target-port=8080 --name=<svc名> -n <ns>
kubectl create service clusterip my-svc --tcp=80:8080 -n <ns> --dry-run=client -o yaml > svc.yaml
kubectl apply -f svc.yaml

8.2 查询

kubectl get svc -n <ns>
kubectl describe svc <name> -n <ns>
kubectl get endpoints <name> -n <ns>    # 1.19+ 仍可用；1.33+ 部分集群改用 EndpointSlice

8.3 修改 / 删除

kubectl edit svc <name> -n <ns>
kubectl apply -f svc.yaml
kubectl delete svc <name> -n <ns>

---

九、Ingress（ing）

kubectl apply -f ingress.yaml
kubectl get ing -n <ns>
kubectl describe ing <name> -n <ns>
kubectl edit ingress <name> -n <ns>
kubectl delete ingress <name> -n <ns>

---

十、Namespace（ns）

kubectl create namespace <name>
kubectl get ns
kubectl describe ns <name>
kubectl config set-context --current --namespace=<name>
kubectl delete namespace <name>    # 会级联删除其下资源，较慢

---

十一、PVC / PV / StorageClass（sc）

11.1 PVC

kubectl apply -f pvc.yaml
kubectl get pvc -n <ns>
kubectl describe pvc <name> -n <ns>
kubectl edit pvc <name> -n <ns>
kubectl delete pvc <name> -n <ns>

11.2 PV（通常集群级）

kubectl get pv
kubectl describe pv <name>
kubectl delete pv <name>

11.3 StorageClass

kubectl get sc
kubectl describe sc <name>
kubectl apply -f storageclass.yaml
kubectl delete sc <name>    # 慎用，影响动态供给

---

十二、Job / CronJob

Job

kubectl apply -f job.yaml
kubectl get job -n <ns>
kubectl describe job <name> -n <ns>
kubectl logs job/<name> -n <ns>
kubectl delete job <name> -n <ns>

CronJob

kubectl apply -f cronjob.yaml
kubectl get cj -n <ns>
kubectl describe cronjob <name> -n <ns>
kubectl create job --from=cronjob/<cj名> <手动job名> -n <ns>   # 手动触发一次
kubectl delete cronjob <name> -n <ns>

---

十三、ServiceAccount / RBAC（简要）

kubectl create serviceaccount <name> -n <ns>
kubectl get sa -n <ns>
kubectl create role ... / kubectl create rolebinding ...
kubectl create clusterrole ... / kubectl create clusterrolebinding ...
kubectl auth can-i <verb> <resource> --as=system:serviceaccount:<ns>:<sa>

---

十四、HPA（自动扩缩容）

kubectl autoscale deployment <name> --min=2 --max=10 --cpu-percent=80 -n <ns>
kubectl get hpa -n <ns>
kubectl describe hpa <name> -n <ns>
kubectl delete hpa <name> -n <ns>
# 推荐用 YAML 引用 metrics API / resource 指标
kubectl apply -f hpa.yaml

---

十五、跨资源排障命令（通用）

# 节点与 Pod 分布
kubectl get nodes -o wide
kubectl get pods -A -o wide --field-selector spec.nodeName=<node>

# API 是否正常
kubectl cluster-info
kubectl get --raw /healthz?verbose
kubectl version --short

# 资源用量（需 metrics-server）
kubectl top nodes
kubectl top pods -n <ns>

# 强制拉取镜像 / 调度问题
kubectl describe pod <name> -n <ns> | tail -30

# 导出某命名空间全部 YAML（备份/迁移）
kubectl get all,cm,secret,pvc,ing -n <ns> -o yaml > backup-ns.yaml

---

十六、版本差异与兼容性说明

能力	1.19	1.29	1.34	建议
apply / get / describe / delete	✅	✅	✅	日常首选
rollout restart	✅	✅	✅	改 CM/Secret 后重启
kubectl debug（临时调试容器）	Beta	稳定	稳定	老集群慎用
kubectl alpha / 新子命令	视版本	变化大	变化大	文档不写 alpha
--dry-run=server	✅	✅	✅	CI 校验清单
kubectl replace --force	✅	✅	✅	仅当 apply 冲突且明确要替换
EndpointSlice 为主	逐步默认	是	是	get endpoints 仍常见

编写清单时的兼容建议：

1. 使用 apiVersion: apps/v1（Deployment/STS/DS）、v1（Pod/Service/CM/Secret）。
2. 避免已废弃字段（如 extensions/v1beta1 Ingress）。
3. 优先 kubectl apply + Git 管理，少用 kubectl run 默认生成带多余注解的对象。
4. 脚本里用资源全称或文档中的简称，不依赖 shell 别名。

---

十七、命令速查表

操作	模板
创建	kubectl apply -f <file> 或 kubectl create <type> ...
查询列表	kubectl get <type> -n <ns>
查询详情	kubectl describe <type> <name> -n <ns>
改字段	kubectl set image/env/resources ... / patch / edit
扩缩容	kubectl scale <type>/<name> --replicas=N
发版/回滚	`kubectl rollout status
删除	kubectl delete <type> <name> -n <ns>

---

附录：最小 YAML 骨架示例

Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: demo
  template:
    metadata:
      labels:
        app: demo
    spec:
      containers:
        - name: app
          image: nginx:1.25
          ports:
            - containerPort: 80
          volumeMounts:
            - name: config
              mountPath: /etc/config
      volumes:
        - name: config
          configMap:
            name: demo-cm

ConfigMap + 引用

apiVersion: v1
kind: ConfigMap
metadata:
  name: demo-cm
data:
  app.properties: |
    key=value

---