Kubernetes 管理

本文是“Kubernetes 管理”模块的规划与持续维护入口。当前内容用于确定模块边界、教学路线和代码框架，不表示所有功能已经开发或验证完成。后续每完成并验证一个小功能，再逐步补充实现代码、逐行解释、测试结果和常见问题。

文档版本	v0.2.0
更新时间	2026-08-26 11:34:30 +0800
本次更新	产品和项目正式由 devops（旧名） 更名为 devopsX，同步调整项目根路径和相关框架名称；博客分类 Python / devops 保持不变。
当前状态	模块规划稿，功能尚未开始或尚未全部验证
Django App	kubernetes

1 模块定位

负责接入 Kubernetes 集群并管理集群资源、工作负载、日志和受控终端。它是独立模块，可以被应用发布和监控使用，但不要求其他模块理解 Kubernetes 客户端细节。

1.1 模块目标

• 安全接入多个 Kubernetes 集群。
• 统一查询集群、节点、命名空间和工作负载。
• 提供受权限控制的变更操作。
• 支持日志、事件和受控终端。
• 为发布模块提供稳定的工作负载更新接口。

1.2 顺序不是固定合同

本文中的功能顺序只表示当前推荐的学习路线，不是永久不变的产品编号。以后可以在本模块中插入新的功能，也可以在整个平台中增加新的独立模块，不需要重命名本文、重排其他文章标题或重构其他 Django App。

2 模块边界

2.1 本模块负责

• 集群连接
• Node 与 Namespace
• Deployment、StatefulSet 和 Pod
• Service 与 Ingress
• 日志、事件和终端
• 资源变更

2.2 本模块不负责

• 应用发布状态机
• Prometheus 长期指标
• 云账号资产同步
• 通用用户系统

边界的目的不是阻止模块协作，而是避免一个 App 直接承担其他 App 的业务职责。跨模块需求应通过公开服务、API、事件或稳定标识完成。

3 代码位置与目录规划

本模块使用稳定的 Django App 名称 kubernetes。开始教学时先保留 Django 默认文件，只有代码真实增长后才拆分 services、api 或 tests 等目录。

C:\Users\lizexiong\devopsX
└── kubernetes
    ├── __init__.py
    ├── admin.py
    ├── apps.py
    ├── models.py
    ├── tests.py
    ├── urls.py             # 需要页面路由时再创建
    ├── views.py
    ├── migrations
    │   └── __init__.py
    └── templates
        └── kubernetes           # 模板 namespace

3.1 最小接入点

新增业务模块时，只应增加自己的 App、URL namespace、模板 namespace、权限前缀和必要的平台注册项。根配置允许增加少量明确的注册代码，但不能要求修改其他业务 App 的内部文件。

3.2 不提前制造复杂目录

文章展示的是发展方向，不要求第一节一次创建完整目录。初期优先使用 Django 默认生成的文件；只有 models.py、views.py、tests.py 等文件真实变大后，才按职责拆分。

4 候选数据模型

下面是当前候选模型，用于帮助理解领域，不代表第一节全部创建。每个模型都需要在对应功能开始时再次验证是否必要。

模型或能力	职责
Cluster	集群名称、API 地址、环境和启停状态。
ClusterCredential	连接凭证引用；敏感内容应加密或存放在外部安全系统。
ResourceSnapshot	仅在确有审计或对比需要时保存资源快照。
ClusterOperation	记录受控变更请求及结果。

5 当前功能路线

下面是当前推荐路线。以后可以增加、删除或调整某一步，而不影响其他模块文章和 App 结构。

当前顺序	功能	状态
1	创建 kubernetes App	按当前学习进度逐步确定
2	接入第一个测试集群	按当前学习进度逐步确定
3	查询集群版本和连接状态	按当前学习进度逐步确定
4	展示 Node 和 Namespace	按当前学习进度逐步确定
5	展示 Deployment、StatefulSet 和 Pod	按当前学习进度逐步确定
6	展示 Service 和 Ingress	按当前学习进度逐步确定
7	查询 Pod 日志和事件	按当前学习进度逐步确定
8	实现受控扩缩容和重启	按当前学习进度逐步确定
9	实现容器终端	按当前学习进度逐步确定
10	提供发布模块调用接口	按当前学习进度逐步确定
11	增加权限、超时和异常测试	按当前学习进度逐步确定

6 与其他模块的协作契约

• accounts 决定用户是否可以查看或修改指定集群和命名空间。
• deployment 通过公开服务提交工作负载更新，不直接使用内部 Kubernetes Client。
• monitoring 关联集群 ID，但通过自己的数据源查询指标。
• 所有变更操作发送审计事件。

6.1 避免内部耦合

其他 App 不应导入本模块的视图、表单或私有服务，也不应直接修改本模块数据库表。确实需要协作时，先定义最小公开接口；只有多个模块已经出现相同需求后，才考虑把稳定能力抽取到 common。

7 独立扩展规则

• 文章标题不依赖固定的全局数字编号。
• 文章内部继续使用 1、1.1、1.1.1 的标题层级。
• 模块使用稳定的 App 名称、URL namespace、模板 namespace 和权限前缀。
• 每个 App 管理自己的模型、迁移、服务、页面和测试。
• 新增未知模块时，新建自己的文章和 App，不重排现有文章和目录。
• 推荐学习顺序可以变化，但稳定标识和模块边界不能随意变化。
• 不为“未来可能需要”提前建设复杂插件系统；先用 Django 明确的注册点保持低耦合。

8 教学与练习方式

本模块后续每个小功能都按以下方式展开：

本节目标
→ 知识背景
→ 当前工作目录
→ 文件清单和完整路径
→ 完整命令与代码
→ 逐行或逐段解释
→ 执行流程和设计原因
→ 运行验证
→ 常见错误与调试
→ 跟随、修改、填空、独立和排错练习
→ 完成后的目录树
→ 等待用户反馈

默认由用户亲手创建文件、输入代码并执行命令。除非用户明确要求代为操作，否则不自动一次写完整个模块。

9 模块验收标准

• 无效或过期凭证能被安全识别
• 只读用户不能修改工作负载
• 集群不可用时请求有明确超时
• 资源变更前后有可追踪记录
• 终端和日志访问受到命名空间权限限制

只有具体功能通过相应测试和实际操作验证后，才把它标记为完成并整理为可复现教程。规划、候选模型和未来路线不能被描述为已经实现。

10 当前状态与维护方式

当前文章已完成模块边界和路线规划，具体代码将随着实际开发逐步补充。后续修改遵循以下原则：

• 用户在 Python / devops 分类中维护文章入口；
• 每次完成并验证功能后，更新对应文章正文；
• 架构变化时先判断影响范围，再更新 Skill 和相关模块文章；
• 只修改真正受影响的模块，不因为增加一个模块而批量重写其他文章；
• 文章可以持续优化，但必须保留准确的状态说明。