Kubernetes：集群对象、YAML 与 kubectl 入门

Kubernetes 通过声明对象和控制器维护工作负载。先掌握命名空间、Pod、Deployment 与 kubectl，再沿着配置、服务发现、存储和身份授权完成部署；生产验收需要同时观察对象状态与真实业务请求。

按任务阅读

当前任务	阅读内容	应掌握的结果
认识环境与基本操作	本篇的环境前提、基本对象与操作	说明管理的对象、执行身份和配置位置
理解机制并完成配置	控制循环、Service 网络与持久存储；部署配置、服务身份与持久卷	解释关键机制，按配置完成任务并核对结果
维护、排障与恢复	发布回滚、权限与集群维护；按 Pod、Service 与端点定位故障；Pod 运行但服务不可达的复盘	能保存证据、控制变更、恢复并验收

本课程以文件阅读和机制推演为目标，不要求创建真实或模拟集群。所有应用源码与资源均已列出，示例未执行；没有安装 kubectl、Helm、kind、minikube 或其他依赖，也不执行 dry-run。

版本与平台前置

Kubernetes 版本 边界采用稳定的 apps/v1 Deployment、core/v1 Service/ConfigMap/Secret/PVC 与 rbac.authorization.k8s.io/v1。2026-10-17 核对中英文官方概念文档，不将旧手册 2026-08-12 的 1.36.3 快照宣称为当前 latest；也不从网页默认版本推断目标集群版本。功能必须按目标服务端、发行版、CNI、CSI 与准入策略核对。

示例为 Linux 节点的 Python 3.13 容器；Windows 工作站可以编辑清单并使用获准的远程 Linux 集群，但 Linux securityContext、fsGroup 和 POSIX 信号不能直接套到 Windows 容器。macOS 不纳入。客户端不提供运行时，Docker Desktop、容器引擎和 Kubernetes 集群也不是同一对象。

未来自跑前需自行准备有管理授权的隔离命名空间、能拉取应用镜像的 Registry、可用 CNI/DNS、默认 StorageClass 及可动态制备且支持文件系统权限的 CSI。没有默认存储类时，本例 PVC 会 Pending；不会通过秘密创建 hostPath 或云资源来掩盖平台前提。

对象与责任分工

Kubernetes 对象 调谐从声明 spec 的期望状态开始，API Server 校验并持久化后，控制器不断比较现状并协调。Deployment 管理 ReplicaSet，ReplicaSet 管理 Pod 副本；scheduler 为 Pod 选节点，kubelet 再通过 CRI 运行时创建容器。提交成功只证明请求被接受，不证明镜像可拉取、卷可挂载、探针通过或业务正常。

status 由系统更新，metadata.uid 表示对象身份；相同名字删除重建后仍是新对象。Pod 可以消失并被替代，不能把 Pod IP 当长期服务地址。Service 提供稳定逻辑入口与端点选择，PVC 请求独立存储，ConfigMap/Secret 提供不同敏感度的配置。每个对象解决不同问题，不能用一个大 YAML 的“成功”替代逐层状态判断。

阅读与命令入口

Kubernetes 命令 必须先确认上下文、命名空间与对象；get 查看摘要，describe 查看对象关联与事件，logs 查看容器输出，rollout status 观察 Deployment 推进。它们通常访问 API Server。apply、delete、exec 和 port-forward 有写入或执行/监听影响，不能当静态解析。

# 仅供未来读者自跑，以下均未执行
kubectl --context=YOUR_CONTEXT -n m5-counter get deployment,pod,service,pvc
kubectl --context=YOUR_CONTEXT -n m5-counter describe pod POD_NAME
kubectl --context=YOUR_CONTEXT -n m5-counter logs POD_NAME -c counter

本课完整项目以单副本 SQLite 特意暴露存储与滚动发布的边界，不是生产高可用方案。不要从“能写 Deployment”跳到“已经得到数据库集群”。

练习与解答

问题：apply 返回 created 后 Pod 一直 Pending，是否说明 YAML 无效？答案：不一定。API 已接受对象，调度、PVC 绑定、节点资源或准入之后的执行仍可能阻塞。先看 Pod 条件与事件，定位是哪一层没有兑现期望状态。

问题：把直接运行的 Pod 删除后一定会重建吗？答案：只有存在仍然要求该副本的控制器才会重建；孤立 Pod 没有这个保证。

手册与来源

保留架构与 API、对象清单与工作负载手册的深入解释；旧安装记录中的 Docker shim、Kubernetes 1.19、废弃 API 与旧软件源按历史读，不照抄部署。

一手来源：中文控制器、英文工作负载、版本偏差策略。中英文翻译可能不同步，字段语义以目标版本英文 API 文档和发布说明核对。

旧安装记录应还原的平台合同

旧 kubeadm 记录中的 Pod CIDR、角色标签和 join token 分别解决什么问题？ 读取 kubeadm 记录先分开控制平面地址、Service CIDR、Pod CIDR、节点网络与 CNI 配置。旧 1.19.2 记录的 Pod CIDR 与 Flannel net-conf.json 都写 10.244.0.0/16，这是需要保持一致的依赖；另一个 Ubuntu 记录却混用多组 master IP，不能拼成一份安装过程。软件源、运行时 CRI/cgroup 配置、桥接参数、rp_filter、Swap 与发行版安全策略属于节点前置，需按目标版本和 CNI 核对，而非统一关闭防火墙或 SELinux。硬件草稿只有作者分配的 CPU/内存，不能推导业务容量或高可用。

ROLES 显示 none 与节点无法运行 Pod 不是同一问题。角色标签用于标识与选择，不会自动安装控制平面组件或制造高可用。加入节点需区分临时引导 token、CA 信任和操作者的 kubeconfig；丢失旧 join 输出应回到受控生成流程，不复用文章里的 token，也不把 admin.conf 分发给所有工作负载。reset 会改变节点状态，不能用作所有 join 错误的第一步。保留这些检查关系比复制旧安装源和整段 Flannel 清单更有用。标签和kubeadm token为核对入口（2026-10-17）；本课仍不提供或执行集群安装步骤。