ShowDocs
搜索文章Ctrl K

外观

← 返回Kubernetes列表
知识专题

kubectl 基础命令 ​

按实际操作顺序，先确认环境，再查询资源、创建与更新、观察发布。遇到问题从日志与容器调试和基础排障顺序进入；清理前查看删除边界。

本文以一套占位符命令覆盖日常流程：将 <namespace>、<name> 等替换为已确认目标。Kubernetes 架构见 知识手册。

一、命令结构与环境确认 ​

text
kubectl [command] [TYPE] [NAME] [flags]

示例使用 Bash/Zsh；先确认客户端、集群与命名空间，再执行写操作。

bash
kubectl version --client
kubectl version
kubectl cluster-info
kubectl config current-context
kubectl config view --minify

kubectl version 需要连接 API Server，并显示客户端与服务端版本。版本偏差应遵循所用 Kubernetes 版本的官方 kubectl 兼容策略。

开启命令补全：

bash
# Bash
source <(kubectl completion bash)

# Zsh
source <(kubectl completion zsh)

临时缩写能减少输入，但脚本和文档中建议保留完整命令：

bash
alias k=kubectl

二、上下文、集群与命名空间 ​

2.1 查看和切换上下文 ​

bash
kubectl config get-contexts
kubectl config current-context
kubectl config use-context <context>
kubectl config view --minify

将当前上下文的默认命名空间设为指定值：

bash
kubectl config set-context --current --namespace=<namespace>

set-context 会修改 kubeconfig。共享终端或频繁跨环境时，仍建议每条命令显式写 -n <namespace>。

2.2 使用多个 kubeconfig ​

bash
kubectl --kubeconfig <path> config get-contexts
KUBECONFIG=<path-a>:<path-b> kubectl config view --merge

Kubeconfig 可能包含客户端证书或访问凭据，应设置最小文件权限且禁止提交到 Git：

bash
chmod 600 <kubeconfig-path>

三、发现 API 与查询字段 ​

bash
kubectl api-resources
kubectl api-resources --namespaced=true
kubectl api-resources --api-group=apps
kubectl api-versions

kubectl explain deployment
kubectl explain deployment.spec
kubectl explain deployment.spec.template.spec.containers --recursive

kubectl explain 读取当前集群的 OpenAPI 信息，是确认字段含义和结构的首选入口。

常用资源简称包括 po（Pod）、deploy（Deployment）、sts（StatefulSet）、ds（DaemonSet）、svc（Service）、cm（ConfigMap）、secret、ing（Ingress）、pvc 和 ns。可用简称以 kubectl api-resources 输出为准。

四、查询资源 ​

bash
kubectl get namespaces
kubectl -n <namespace> get pods
kubectl -n <namespace> get pods -o wide
kubectl -n <namespace> get pods --show-labels
kubectl get pods -A

kubectl -n <namespace> get deployment <name>
kubectl -n <namespace> get deployment <name> -o yaml
kubectl -n <namespace> get pod <pod> -o json
kubectl -n <namespace> describe pod <pod>

持续观察：

bash
kubectl -n <namespace> get pods --watch
kubectl -n <namespace> get deployment <name> --watch

describe 是客户端组织的可读摘要；自动化应使用 get -o json，不要解析 describe 的文本。

kubectl get all 只查询一组常见资源，并不代表命名空间里的所有资源；排查时不要依赖它做完整清单。

按字段找出非 Running Pod：

bash
kubectl get pods -A --field-selector='status.phase!=Running'

4.1 标签选择器 ​

bash
kubectl -n <namespace> get pods -l app=api
kubectl -n <namespace> get pods -l 'environment in (staging,production)'
kubectl -n <namespace> get pods -l app=api,tier=backend

4.2 查看事件 ​

bash
kubectl -n <namespace> get events --sort-by=.metadata.creationTimestamp
kubectl -n <namespace> get events --field-selector type=Warning

事件有保留时间且可能被聚合。生产排障应同时查看控制面、节点和应用的集中日志与监控。

4.3 输出与字段提取 ​

bash
kubectl -n <namespace> get pods -o name
kubectl -n <namespace> get pods -o custom-columns='NAME:.metadata.name,NODE:.spec.nodeName,PHASE:.status.phase'
kubectl -n <namespace> get pod <pod> -o jsonpath='{.status.podIP}{"\n"}'

复杂筛选和脚本化输出见 kubectl 进阶。

五、声明式创建和更新 ​

5.1 推荐工作流 ​

bash
# 客户端预检
kubectl apply --dry-run=client -f <manifest.yaml>

# 服务端准入、默认值和策略检查，不持久化
kubectl apply --dry-run=server -f <manifest.yaml>

# 查看与集群现状的差异；有差异时退出码通常为 1
kubectl diff -f <manifest.yaml>

# 应用变更
kubectl apply -f <manifest.yaml>

目录和远端 URL：

bash
kubectl apply -f <manifest-directory>/
kubectl apply -f https://<trusted-host>/<manifest.yaml>

执行远端清单前先下载、审查并固定可信版本，避免 URL 内容变化或供应链风险。

临时检查或修改单个资源可使用编辑器：

bash
kubectl -n <namespace> edit deployment/<name>

保存后变更会直接提交到集群；后续仍应把有效修改同步到清单或 Git，避免下次 apply 覆盖。

5.2 快速生成 YAML ​

bash
kubectl create deployment web \
  --image=nginx:<pinned-version> \
  --replicas=2 \
  --dry-run=client -o yaml > deployment.yaml

kubectl create service clusterip web \
  --tcp=80:80 \
  --dry-run=client -o yaml > service.yaml

生成后补充资源 requests/limits、健康检查、安全上下文、标签和镜像拉取策略，再进入评审和发布流程。不要在生产使用浮动的 latest 镜像标签。

六、Deployment 发布与伸缩 ​

6.1 查看发布与更新镜像 ​

bash
kubectl -n <namespace> get deployment <name>
kubectl -n <namespace> rollout status deployment/<name> --timeout=5m
kubectl -n <namespace> rollout history deployment/<name>

更新镜像：

bash
kubectl -n <namespace> set image deployment/<name> \
  <container>=<registry>/<image>:<version>

kubectl -n <namespace> rollout status deployment/<name> --timeout=5m

滚动重启会创建新的 Pod，应先确认容量和 PodDisruptionBudget：

bash
kubectl -n <namespace> rollout restart deployment/<name>
kubectl -n <namespace> rollout status deployment/<name> --timeout=5m

6.2 调整环境变量与资源 ​

bash
kubectl -n <namespace> set env deployment/<name> APP_MODE=production
kubectl -n <namespace> set env deployment/<name> APP_MODE-
kubectl -n <namespace> set resources deployment/<name> -c <container> \
  --requests=cpu=100m,memory=128Mi --limits=cpu=500m,memory=256Mi
kubectl -n <namespace> rollout status deployment/<name> --timeout=5m

APP_MODE- 删除该环境变量；数值仅为命令示例，应按实际负载设定。修改 Pod 模板通常会触发发布，应同步更新声明式清单。

6.3 手工伸缩与前置条件 ​

bash
kubectl -n <namespace> scale deployment/<name> --replicas=<count>

需要避免覆盖他人的副本数变更时，可要求“当前副本数仍为 2”才改为 1；前置条件不符则拒绝：

bash
kubectl -n <namespace> scale deployment/<name> --current-replicas=2 --replicas=1

若 HPA 或 GitOps 控制相同字段，手工副本数可能很快被覆盖。先确认所有控制器和期望状态来源。

6.4 回滚到上一版本或指定修订 ​

bash
kubectl -n <namespace> rollout undo deployment/<name>
kubectl -n <namespace> rollout undo deployment/<name> --to-revision=<revision>
kubectl -n <namespace> rollout status deployment/<name> --timeout=5m

回滚 Deployment 不会自动回滚外部数据库或不兼容配置，发布前必须单独设计数据迁移策略。

七、日志、执行命令与本地转发 ​

7.1 Pod 日志 ​

bash
kubectl -n <namespace> logs <pod>
kubectl -n <namespace> logs <pod> -c <container>
kubectl -n <namespace> logs <pod> --all-containers=true --tail=200
kubectl -n <namespace> logs -f <pod> -c <container> --since=10m
kubectl -n <namespace> logs <pod> -c <container> --previous

--previous 用于容器重启后的上一实例日志；如果日志已超过节点保留范围，应查集中日志系统。

按标签汇总多个 Pod 时限制并发和输出范围：

bash
kubectl -n <namespace> logs -l app=api \
  --all-containers=true --prefix --tail=100 --max-log-requests=10

7.2 在容器中执行命令 ​

bash
kubectl -n <namespace> exec <pod> -c <container> -- <command>
kubectl -n <namespace> exec -it <pod> -c <container> -- /bin/sh

-- 分隔 kubectl 参数与容器内命令。生产容器可能没有 Shell 或诊断工具，此时使用 临时调试容器，不要把工具永久塞进业务镜像。

7.3 复制文件 ​

bash
kubectl -n <namespace> cp <pod>:<remote-path> <local-path> -c <container>
kubectl -n <namespace> cp <local-path> <pod>:<remote-path> -c <container>

kubectl cp 通常依赖容器内存在 tar。复制日志或数据前确认内容不含秘密和个人数据。

7.4 端口转发 ​

bash
kubectl -n <namespace> port-forward pod/<pod> 8080:<container-port>
kubectl -n <namespace> port-forward service/<service> 8080:<service-port> --address=127.0.0.1

默认只绑定本机环回地址。不要随意使用 --address 0.0.0.0，否则可能把集群内部服务暴露到所在网络。

八、Service 与访问路径 ​

bash
kubectl -n <namespace> get service
kubectl -n <namespace> describe service <service>
kubectl -n <namespace> get endpointslice -l kubernetes.io/service-name=<service>

从已有 Deployment 创建 ClusterIP Service：

bash
kubectl -n <namespace> expose deployment <name> \
  --name=<service> --type=ClusterIP --port=<service-port> --target-port=<container-port>

命令式创建适合学习和临时验证；长期资源应导出为清单并纳入版本控制。Service 没有后端时，依次比较 Service selector 与 Pod labels，并确认 Pod Ready。

九、ConfigMap 与 Secret ​

9.1 ConfigMap ​

bash
kubectl -n <namespace> create configmap <name> \
  --from-literal=LOG_LEVEL=info \
  --dry-run=client -o yaml

kubectl -n <namespace> create configmap <name> \
  --from-file=<config-file> \
  --dry-run=client -o yaml | kubectl apply -f -

9.2 Secret ​

bash
chmod 600 <secret-file>
kubectl -n <namespace> create secret generic <name> \
  --from-file=password=<secret-file> \
  --dry-run=client -o yaml | kubectl apply -f -

Secret 不是天然加密

Secret 的 data 只是 Base64 编码。不要把生成的 YAML、解码结果或命令行明文提交到 Git、终端历史和工单。集群应启用静态加密、最小 RBAC 和审计，优先通过组织批准的秘密管理系统交付凭据。

检查 Secret 元数据而不打印值：

bash
kubectl -n <namespace> get secret <name>
kubectl -n <namespace> describe secret <name>

ConfigMap 或 Secret 更新后，已通过环境变量注入的容器不会自动刷新；卷投影也有传播延迟，应用是否热加载取决于自身实现。

十、Job 与 CronJob ​

bash
kubectl -n <namespace> create job <job-name> \
  --image=busybox:<pinned-version> \
  --dry-run=client -o yaml -- date

kubectl -n <namespace> create cronjob <cronjob-name> \
  --image=busybox:<pinned-version> \
  --schedule='*/5 * * * *' \
  --dry-run=client -o yaml -- date

查询执行情况：

bash
kubectl -n <namespace> get jobs,cronjobs
kubectl -n <namespace> describe job <job-name>
kubectl -n <namespace> logs job/<job-name>

从 CronJob 手工创建一次 Job：

bash
kubectl -n <namespace> create job \
  --from=cronjob/<cronjob-name> <manual-job-name>

CronJob 应设置并发策略、历史保留、截止时间和时区策略；任务必须考虑重试导致的重复执行。

十一、标签与注解 ​

bash
kubectl -n <namespace> label deployment/<name> environment=staging
kubectl -n <namespace> annotate deployment/<name> owner='team-a'

# 覆盖已有键必须显式写 --overwrite
kubectl -n <namespace> label deployment/<name> environment=production --overwrite

# 键后加减号表示删除该标签或注解
kubectl -n <namespace> label deployment/<name> environment-
kubectl -n <namespace> annotate deployment/<name> owner-

修改标签可能立即改变 Service、NetworkPolicy、监控或控制器的选择结果。变更前搜索所有依赖该标签的 selector。

十二、资源使用与自动伸缩 ​

bash
kubectl top nodes
kubectl -n <namespace> top pods
kubectl -n <namespace> top pod <pod> --containers

这些命令需要集群安装并正常运行 Metrics API。创建基于 CPU 的 HPA：

bash
kubectl -n <namespace> autoscale deployment/<name> \
  --min=<min-replicas> --max=<max-replicas> --cpu-percent=<target-percent>
kubectl -n <namespace> get hpa
kubectl -n <namespace> describe hpa <name>

HPA 的 CPU 利用率依赖容器 CPU request；生产 HPA 建议用清单管理并结合业务指标、扩缩容行为和容量测试。

十三、等待条件 ​

bash
kubectl -n <namespace> wait \
  --for=condition=Available deployment/<name> --timeout=5m

kubectl -n <namespace> wait \
  --for=condition=Ready pod -l app=<app> --timeout=5m

kubectl -n <namespace> wait \
  --for=condition=complete job/<job-name> --timeout=10m

脚本应先检查选择器是否匹配了目标，避免把空目标误判为等待成功。wait 超时只是说明条件未在期限内满足。接下来用 describe、事件和日志查原因，不应立即循环重试变更。

十四、删除资源 ​

bash
# 先确认精确目标
kubectl -n <namespace> get <resource> <name> -o wide

kubectl -n <namespace> delete <resource> <name> \
  --wait=true --timeout=2m

# 删除清单声明的资源
kubectl delete -f <manifest.yaml>

删除和强制删除

删除 Namespace 会级联删除其中大量资源。--grace-period=0 --force 只会强制移除 API 对象，不保证节点上的进程已停止，可能导致重复实例和数据损坏。仅在理解控制器、存储和终结器状态且完成审批后使用。

十五、基础排障顺序 ​

bash
kubectl config current-context
kubectl config view --minify
kubectl -n <namespace> get pod <pod> -o wide
kubectl -n <namespace> describe pod <pod>
kubectl -n <namespace> get events --sort-by=.metadata.creationTimestamp
kubectl -n <namespace> logs <pod> -c <container> --tail=200
kubectl -n <namespace> logs <pod> -c <container> --previous --tail=200

进一步的 Pending、CrashLoopBackOff、ImagePull、Service 和节点排障见 Kubernetes 进阶命令。

继续阅读