kubectl 是面向 kube-apiserver 的官方 CLI：把你在终端输入的子命令翻译成对 Kubernetes API 的 HTTP 请求（认证通过后）。它不直接登录某台节点替你在 docker run；节点上起容器是 kubelet 的工作（对应 k8s-01 图 5 步骤 5）。本篇建立「终端 → API → 对象 → 事件/日志」的日常观测心智，与生信里「查作业号、看日志」的习惯对应。
本系列与编号约定
- 总览与 步骤 1～5 见 pipeline-frameworks-k8s-01.框架概述 的 图 5；本文对应 步骤 1（客户端经
kubectl提交/查询请求）。 - 建议顺序：k8s-01 → k8s-02 → 本文。
系列导航
| 篇目 | 链接 |
|---|---|
| 上一篇 | pipeline-frameworks-k8s-02.集群与运行环境 |
| 下一篇 | pipeline-frameworks-k8s-04.工作负载与资源调度 |
1. kubectl 在架构中的位置
图 1 从用户终端到 kube-apiserver
要点：
- 读操作（如
get、describe）与 写操作（如apply、delete）都走 同一 API Server；区别在 HTTP 方法与对象路径。 - etcd 不直接对终端开放；持久化由 apiserver 完成（图 5 步骤 2）。
- 你看到「资源被创建/更新」是 API 已接受并写入对象；Pod 是否 Running 还取决于调度器、kubelet、镜像等（后续步骤）。
2. kubeconfig 与上下文（context）
默认配置常在 ~/.kube/config（或环境变量 KUBECONFIG 指向的文件）。三个核心概念绑在一起叫 context：
| 概念 | 作用 |
|---|---|
| cluster | API Server 地址与集群 CA（校验服务端证书） |
| user | 客户端证书、token 或 exec 插件（向 apiserver 证明身份） |
| namespace | 默认命名空间（可被命令行 -n 覆盖） |
常用命令：
kubectl config get-contexts：列出当前可选上下文。kubectl config use-context <name>：切换「连哪套集群、用哪个用户、默认哪个命名空间」。
多集群 / 多环境（开发/预发/生产）时，务必养成先看当前 context 的习惯，避免误操作生产。
3. 命名空间（Namespace）
命名空间是 Kubernetes 对象的一种作用域：同名资源在不同 namespace 下可以并存（例如两个都叫 app 的 Deployment）。它不是 Linux 内核里的 network namespace 的同义词，但常被用来在组织层面划分团队、项目或环境。
图 2 集群内多命名空间（示意）
注意：
- 集群级对象（如
Node、部分StorageClass）不属于某个 namespace。 - 网络策略、RBAC 可以按 namespace 收紧权限（见 k8s-05）。
- Argo 常会为每个 Workflow 或某类资源使用专用 namespace，查找 Pod 时要带上
-n。
4. 日常观测：最小够用的一组命令
下面不是手册大全，而是排障顺序上最常用的一组（与生信「先看状态、再看日志」一致）。
| 目的 | 命令思路 | 说明 |
|---|---|---|
| 列资源 | kubectl get pods -n <ns> |
看 STATUS、就绪、重启次数 |
| 详情与事件 | kubectl describe pod <name> -n <ns> |
Events 里常有调度失败、镜像拉取失败原因 |
| 容器日志 | kubectl logs <pod> -n <ns> [-c <container>] |
多容器 Pod 需 -c；可加 --previous 看崩溃前容器日志 |
| 进容器调试 | kubectl exec -it <pod> -n <ns> -- /bin/sh |
镜像需有 shell；生产环境慎用 |
get vs describe：get 适合扫一眼列表；describe 适合追「为什么 Pending、为什么 CrashLoop」——事件时间线往往比只看 YAML 更直接。
5. 与 Argo Workflows 的衔接
Argo 在集群里创建 Workflow 对象，并由控制器创建 Pod（可能多步、多 Pod）。当你在 Argo UI 里看到某步失败时，落地到 K8s 层通常是：
- 用 UI 或
kubectl get workflow -n <argo-ns>找到工作流与命名空间。 kubectl get pods -n <ns>找到对应 Pod（名称常带 workflow 名与 step 前缀）。kubectl logs/describe定位镜像失败、资源不足、卷挂载等问题。
Argo 的 DAG、重试、制品传递仍以 Argo 入门篇 为主；这里只强调：K8s 层的观测命令仍然适用。
6. 小结
kubectl是 kube-apiserver 的客户端；理解 kubeconfig / context 才能安全地在多集群间切换。- Namespace 划分资源作用域；查 Pod、看日志时带对
-n是常见失误来源。 - 观测闭环：
get→describe（看 Events）→logs（必要时exec）。 - 下一步：k8s-04 展开 Job、资源请求与调度、Pending 等与工作负载直接相关的概念。