📚 课程目录第4章调试环境准备

4. 调试环境准备：安装 kubectl、配置 kubeconfig、创建临时调试容器的方法

在进入故障域划分与资源模型排错之前，必须搭建一个标准、可复现的调试环境。本章围绕三个核心动作展开：kubectl 安装、kubeconfig 配置、临时调试容器创建。这三个环节是后续所有 kubectl debug 操作的基础，任何一个环节出错都会导致调试指令无法送达目标 Pod 或节点。

4.1 安装 kubectl：版本对齐与校验

kubectl 的版本必须与目标集群的 Kubernetes 版本保持 ±1 小版本 以内，否则可能出现 API 兼容性问题。推荐使用包管理器或官方二进制安装。

安装方式	适用平台	命令示例	版本校验
curl 下载二进制	Linux / macOS	`curl -LO "https://dl.k8s.io/release/v1.28.0/bin/linux/amd64/kubectl"`	`kubectl version --client`
apt 安装	Ubuntu / Debian	`sudo apt-get install -y kubectl`	`kubectl version --client`
yum 安装	CentOS / RHEL	`sudo yum install -y kubectl`	`kubectl version --client`
Homebrew	macOS	`brew install kubectl`	`kubectl version --client`

版本对齐检查： 使用 kubectl version --client 查看客户端版本，使用 kubectl version --short 查看服务端版本。若主版本号不一致，优先升级 kubectl 至与服务端匹配的版本。

4.2 配置 kubeconfig：上下文、集群与认证

kubeconfig 是 kubectl 访问集群的“通行证”，默认路径为 ~/.kube/config。一个 kubeconfig 文件可包含多个集群、用户和上下文，通过 kubectl config use-context 切换。

典型 kubeconfig 结构包含三个核心段：

clusters：定义集群 API Server 地址与 CA 证书。
users：定义客户端证书、或用户名/密码。
contexts：将 cluster 与 user 绑定，并可指定默认 namespace。

apiVersion: v1
kind: Config
current-context: prod-cluster
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTiBDRV...  # base64 编码的 CA 证书
    server: https://192.168.1.100:6443
  name: prod-cluster
users:
- user:
    client-certificate-data: LS0tLS1CRUdJTiBDRV...  # base64 编码的客户端证书
    client-key-data: LS0tLS1CRUdJTiBSU0EgUFJ...    # base64 编码的客户端密钥
  name: admin-user
contexts:
- context:
    cluster: prod-cluster
    user: admin-user
    namespace: kube-system
  name: prod-cluster

常见配置错误：

证书过期或 base64 解码失败 → 报错 certificate has expired 或 unable to parse certificate。
server 地址不可达 → 检查网络连通性与防火墙规则。
context 未设置 → 使用 kubectl config set-context --current --namespace=default 修正。

4.3 创建临时调试容器：kubectl debug 的核心操作

临时调试容器（Ephemeral Container）是 kubectl debug 的核心机制。它允许在目标 Pod 中注入一个临时容器，共享 Pod 的 Network Namespace、PID Namespace（可选）和存储卷，从而在不影响原容器进程的前提下执行诊断命令。

创建临时调试容器的标准语法：

kubectl debug <pod-name> -n <namespace> \
  --image=nicolaka/netshoot:latest \
  --target=<container-name> \
  -- sh

--image：指定调试镜像，推荐 nicolaka/netshoot（内置 curl、tcpdump、dig、ip 等工具）。
--target：指定目标容器，使调试容器进入该容器的 PID Namespace（需启用 EphemeralContainers 特性门控）。
-- sh：启动交互式 Shell。

  调试容器 vs 传统 exec：
  
        对比维度
        kubectl exec
        kubectl debug (临时容器)
      
        侵入性
        需目标容器包含 Shell 和调试工具
        独立镜像，不依赖目标容器
      
        持久性
        容器重启后丢失
        临时容器随 Pod 生命周期，可保留日志
      
        权限隔离
        继承目标容器 SecurityContext
        可指定独立 SecurityContext
      
        适用场景
        容器内有 Shell 且未崩溃
        容器崩溃、无 Shell、需额外工具

对比维度	kubectl exec	kubectl debug (临时容器)
侵入性	需目标容器包含 Shell 和调试工具	独立镜像，不依赖目标容器
持久性	容器重启后丢失	临时容器随 Pod 生命周期，可保留日志
权限隔离	继承目标容器 SecurityContext	可指定独立 SecurityContext
适用场景	容器内有 Shell 且未崩溃	容器崩溃、无 Shell、需额外工具

4.4 调试环境验证清单

完成安装与配置后，建议执行以下验证步骤，确保环境就绪：

kubectl 连通性测试： kubectl cluster-info 应返回集群 Master 和 CoreDNS 地址。
节点状态检查： kubectl get nodes 所有节点应为 Ready 状态。
临时容器特性确认： kubectl api-resources | grep ephemeral 应返回 ephemeralcontainers。
调试镜像拉取测试： 使用 kubectl debug 创建一个临时容器，确认镜像拉取成功且 Shell 可用。

生产环境建议： 将调试镜像提前推送到私有镜像仓库，并在 Pod 所在节点预拉取，避免调试时因镜像拉取超时而延误排错窗口。

4.5 常见环境问题与快速修复

问题现象	可能原因	快速修复
`Unable to connect to the server: dial tcp: connection refused`	API Server 地址错误或端口不通	检查 kubeconfig 中 server 地址；使用 `telnet <ip> 6443` 测试连通性
`certificate signed by unknown authority`	CA 证书不匹配或未配置	更新 `certificate-authority-data` 或设置 `insecure-skip-tls-verify: true`（仅测试环境）
`error: ephemeral containers are not allowed`	集群未启用 EphemeralContainers 特性门控	检查 kube-apiserver 启动参数是否包含 `--feature-gates=EphemeralContainers=true`
`ImagePullBackOff`	调试镜像不存在或拉取凭证不足	确认镜像名称正确；配置 ImagePullSecret 或使用本地已缓存镜像

安全提醒： 临时调试容器默认继承 Pod 的 ServiceAccount 权限。在敏感环境中，建议使用 --context 参数指定只读 ServiceAccount，或通过 RBAC 限制调试操作范围。