kubectl 基础

kubectl 是操作 Kubernetes 集群的命令行工具，几乎所有集群操作都通过它完成。本章讲解 kubectl 的配置方法、最常用命令、输出格式选项，以及几个能大幅提升效率的调试技巧。

安装与配置#

kubeconfig 是什么#

kubectl 通过 kubeconfig 文件知道要连接哪个集群、用哪个身份、在哪个 namespace 下操作。默认路径是 ~/.kube/config。

一个 kubeconfig 文件包含三部分：clusters（集群地址）、users（身份认证）、contexts（把集群+用户+namespace 绑定在一起）。

bash
# 查看当前 kubeconfig
cat ~/.kube/config

# 或直接用命令查看
kubectl config view

context 切换#

如果你管理多个 K8s 集群（比如开发环境、预发布环境、生产环境），kubeconfig 里会有多个 context，切换 context 就是切换"当前操作的集群"。

bash
# 查看所有 context
kubectl config get-contexts
# CURRENT   NAME           CLUSTER        AUTHINFO       NAMESPACE
# *         dev            dev-cluster     dev-user       default
#           staging        staging-cluster staging-user   default
#           production     prod-cluster    prod-user      production

# 切换到生产环境 context
kubectl config use-context production

# 快速确认当前所在集群
kubectl config current-context

namespace 快捷设置#

默认情况下 kubectl 操作 default namespace。可以把某个 namespace 设为当前 context 的默认 namespace，省去每次加 -n 参数：

bash
# 把当前 context 的默认 namespace 设为 production
kubectl config set-context --current --namespace=production

# 验证
kubectl get pods   # 现在直接查 production namespace 的 Pod

注意事项：建议把 ~/.kube/config 存好备份。生产环境的 kubeconfig 包含集群管理员凭证，泄露后相当于把集群控制权交出去。

常用命令速查#

下面 6 个命令覆盖了日常操作的 80% 场景。

kubectl get —— 查看资源列表#

bash
# 查看当前 namespace 的 Pod
kubectl get pods

# 指定 namespace
kubectl get pods -n production

# 所有 namespace
kubectl get pods -A

# 查看更多信息（节点名、Pod IP、镜像名）
kubectl get pods -o wide

# 查看所有资源类型（deployments、services、pods...）
kubectl get all -n production

# 用标签过滤
kubectl get pods -l app=nginx,env=prod

# 实时监听变化（类似 watch）
kubectl get pods -w

常用资源类型简写：po（pods）、deploy（deployments）、svc（services）、ns（namespaces）、cm（configmaps）、secret、node（nodes）。

kubectl describe —— 查看资源详情#

get 给你列表，describe 给你详情——包括配置、状态、事件（Events）。排错时 describe 是第一个要用的命令。

bash
# 查看 Pod 详情
kubectl describe pod my-app-7d8f9c6b5-x2k4 -n production

# 查看 Node 详情（看资源总量和已分配量）
kubectl describe node worker-01

# 查看 Deployment 详情
kubectl describe deployment my-app -n production

describe 输出里最有价值的是底部的 Events 部分，里面记录了最近发生的事件：

text
Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Normal   Scheduled  5m    default-scheduler  Successfully assigned production/my-app-xxx to worker-01
  Normal   Pulling    5m    kubelet            Pulling image "myapp:v1.0"
  Normal   Created    5m    kubelet            Created container app
  Normal   Started    5m    kubelet            Started container app
  Warning  Unhealthy  2m    kubelet            Readiness probe failed: HTTP probe failed...

kubectl apply —— 创建或更新资源#

apply 是声明式操作的核心命令。文件里的配置和目标资源比对，有差异就更新，没差异就不操作。

bash
# 应用单个文件
kubectl apply -f deployment.yaml

# 应用目录下所有 YAML 文件
kubectl apply -f ./manifests/

# 从 URL 直接应用（适合快速试用）
kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo.yaml

注意事项：apply 只更新 YAML 里出现的字段，不会删除 YAML 里没出现但集群里存在的字段。要彻底同步，用 kubectl apply --prune（慎用）。

kubectl delete —— 删除资源#

bash
# 按文件名删除
kubectl delete -f deployment.yaml

# 按资源类型和名称删除
kubectl delete pod my-app-xxx -n production

# 按标签批量删除（危险！）
kubectl delete pods -l app=nginx -n production

# 删除 namespace（会删除里面所有资源！）
kubectl delete namespace test-env

注意事项：删除 Deployment 时，ReplicaSet 和 Pod 会被级联删除。如果不想级联删除，可以加 --cascade=orphan，但一般不这样做。

kubectl logs —— 查看容器日志#

bash
# 查看当前日志
kubectl logs my-app-xxx -n production

# 实时跟踪（类似 tail -f）
kubectl logs my-app-xxx -f -n production

# 查看上一次崩溃容器的日志（排 CrashLoopBackOff 必用）
kubectl logs my-app-xxx --previous -n production

# 多容器 Pod 指定容器名
kubectl logs my-app-xxx -c sidecar -n production

# 查看所有匹配标签的 Pod 日志
kubectl logs -l app=my-app --all-containers=true -n production

kubectl exec —— 进入容器调试#

bash
# 进入容器 shell（调试首选）
kubectl exec -it my-app-xxx -n production -- bash

# 没有 bash 的镜像用 sh
kubectl exec -it my-app-xxx -n production -- sh

# 直接执行命令（不看 shell）
kubectl exec my-app-xxx -n production -- ls /app

# 多容器 Pod 指定容器
kubectl exec -it my-app-xxx -n production -c sidecar -- sh

参数说明：-i（交互式，保持 stdin 打开）、-t（分配伪终端，让体验像真终端）。

输出格式对比#

kubectl get 默认的表格输出信息有限，通过 -o（output）参数可以切换输出格式，适应不同场景。

-o wide —— 宽表模式#

在默认表格基础上增加几列有用信息（节点名、Pod IP、镜像等）。

bash
kubectl get pods -o wide
# NAME                      READY   STATUS    RESTARTS   AGE   IP            NODE       NOMINATED NODE
# my-app-7d8f9c6b5-x2k4    1/1     Running   0          5m    10.244.1.15   worker-01   <none>

适用场景：快速确认 Pod 跑在哪台节点、Pod IP 是什么。

-o yaml —— 完整 YAML 配置#

输出资源在 API Server 里存储的完整 YAML 配置，包括自动填充的默认值（这些默认值在你自己写的 YAML 里可能没出现，但 K8s 内部是有的）。

bash

kubectl get deployment my-app -o yaml

适用场景：

想看某个资源的完整配置（包括你没写的字段的默认值）
把现有资源导出成 YAML 文件（kubectl get deployment my-app -o yaml > my-app.yaml），修改后再 apply
排查"我明明写了这个配置，为什么没生效"的问题

注意事项：导出的 YAML 会包含一些 status、managedFields 等字段，直接 apply 时会报错，需要手动清理。

-o json —— 完整 JSON 配置#

和 -o yaml 类似，但输出 JSON 格式。适合用 jq 做进一步的 JSON 处理。

bash
# 用 jq 提取特定字段
kubectl get deployment my-app -o json | jq '.spec.replicas'

# 提取所有 Pod 的容器镜像
kubectl get pods -o json | jq '.items[].spec.containers[].image'

适用场景：需要编程处理 K8s 资源数据（比如写脚本批量操作）。

jsonpath —— 自定义输出列#

当你只需要某个特定字段，不想看整个 YAML/JSON 时，用 jsonpath 直接提取。

bash
# 提取所有 Pod 的名字和状态
kubectl get pods -o jsonpath='{.items[*].metadata.name}'

# 提取 Pod 的容器镜像
kubectl get pod my-app-xxx -o jsonpath='{.spec.containers[*].image}'

# 自定义列输出（最实用）
kubectl get pods -o custom-columns='NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName'

# 输出所有 Pod 的 IP（用于批量操作）
kubectl get pods -o jsonpath='{.items[*].status.podIP}' | tr ' ' '\n'

适用场景：写脚本、批量操作、只需要某几个字段时。

输出格式	信息量	人类可读性	机器处理	适用场景
默认表格	少	好	差	日常快速查看
`-o wide`	中	好	差	需要节点名/IP 时
`-o yaml`	全	中	中	导出配置、完整查看
`-o json`	全	差	好	编程处理、jq 过滤
`jsonpath`	自定义	差	好	脚本提取特定字段

调试技巧#

下面三个技巧能大幅减少"不知道为什么不行"的时间。

kubectl explain —— 查字段结构#

写 YAML 时不知道某个字段怎么写、有哪些子字段、类型是什么？不用翻文档，explain 直接在终端里查。

bash
# 查看 Pod 的资源结构说明
kubectl explain pod

# 查看嵌套字段（比如 containers 下面有什么）
kubectl explain pod.spec.containers

# 继续往下查
kubectl explain pod.spec.containers.resources

# 查看字段的类型和说明
kubectl explain deployment.spec.strategy.rollingUpdate
# KIND:     Deployment
# VERSION:  apps/v1
# FIELD:    rollingUpdate <Object>
#
# DESCRIPTION:
#   Rolling update config params...
#   maxSurge: 最多比 replicas 多几个 Pod
#   maxUnavailable: 最多有几个 Pod 可以同时不可用

适用场景：写 YAML 时不确定字段名或结构，直接终端里查，比翻官网文档快。

--dry-run=client —— 试运行#

不想真的创建资源，只是想验证 YAML 语法对不对，或者想生成 YAML 模板？

bash
# 试运行（不真正创建，只验证）
kubectl apply -f deployment.yaml --dry-run=client

# 让 kubectl 帮你生成 YAML 模板（不用手写）
kubectl create deployment nginx --image=nginx:alpine --dry-run=client -o yaml > deployment.yaml

# 生成 Service 模板
kubectl expose pod nginx --port=80 --target-port=80 --dry-run=client -o yaml > service.yaml

--dry-run=client 表示只在客户端验证，不发请求给 API Server。--dry-run=server 会发给 API Server 验证（包括权限检查），但不真正创建。

适用场景：快速生成 YAML 骨架、验证 YAML 语法、CI 里做配置校验。

kubectl diff —— 对比变更#

修改了 YAML 文件，apply 之前想看看具体会改什么？用 diff。

bash
# 对比本地文件和集群里实际资源的差异
kubectl diff -f deployment.yaml

# 输出示例：
# >   replicas: 3
# <   replicas: 5
# 表示：集群里是 5 个副本，文件里是 3 个（apply 后会缩容到 3）

适用场景：apply 前做最后确认，防止改错字段导致意外行为。比直接 apply 再后悔安全得多。

注意事项：kubectl diff 需要集群开启 server-side diff 功能（K8s 1.13+ 默认开启）。如果报错，检查集群版本。

小结#

本章核心要点：

kubeconfig/context/namespace：kubeconfig 是集群访问凭证，context 切换操作的集群，config set-context --current --namespace 设置默认 namespace
6 个核心命令：
- kubectl get：查看资源列表，加 -A 查所有 namespace
- kubectl describe：查看详情，重点看底部 Events
- kubectl apply：声明式创建/更新资源
- kubectl delete：删除资源，支持按文件/名称/标签删除
- kubectl logs：--previous 查上一次崩溃日志
- kubectl exec：-it 进入容器调试
输出格式：-o wide（多几列）、-o yaml（完整配置）、-o json（编程处理）、jsonpath（提取特定字段）
调试三件套：kubectl explain（查字段结构）、--dry-run=client（试运行生成模板）、kubectl diff（apply 前对比差异）