Module Document

基础架构 · K8S 平台详细设计文档

基础架构 · K8S 平台详细设计文档

版本: v0.3
日期: 2026-07-07
归属: 基础架构 / K8S 平台

1. 模块定位与目标

K8S 平台详细设计覆盖 Rancher 多集群、K8S 配套组件、物理主机纳管、Grafana 可观测栈、弹性伸缩五条主线，与网络模块协同（Ingress 对接 LB/WAF，CoreDNS 对接 PrivateZone）。

目标 说明
Rancher 统一管控 三套集群统一 RBAC、配套、监控、备份；一个控制台管所有。
配套组件标准化 每套集群同一套配套，版本锁定，Rancher 应用商店下发。
Grafana 可观测 集群/节点/Pod/业务全链路可视，Loki 日志可检索。
弹性可控 Pod 和节点双层弹性，成本护栏兜底。
物理主机台账 内网裸金属完整登记，OS 与 K8S 节点协同运维。

2. 执行计划

阶段 时间 交付物 Owner 工作量
P0 规范+ACK 0–14 天 Namespace/RBAC/标签规范，ACK 创建，Rancher HA 部署 平台运维 2人×2周
P1 配套标准化 15–30 天 6 个配套组件 Rancher 应用商店统一安装 平台运维 1人×2周
P2 GitOps 31–45 天 ArgoCD 接入三集群，生产配置全走 GitOps 平台运维 1人×2周
P3 内网+海外 46–75 天 K3s + EKS 接入 Rancher，物理主机台账建立 平台运维 2人×4周
P4 弹性 76–105 天 HPA/VPA、ACK ESS/EKS ASG CA、成本护栏 平台运维 2人×4周
P5 可观测 106–135 天 Prometheus 多集群汇聚、Grafana 标准看板、Loki 接入 平台+研发 2人×4周

3. 困难点与复杂度分析

困难点 复杂度 应对
Rancher 纳管三种云 K8S 高 ACK/EKS 走 API 导入，K3s 走 Rancher agent；RBAC 统一但节点层归各自云。
配套组件版本跨三集群对齐 中 Rancher 应用商店锁定版本，升级走变更窗口。
Prometheus 多集群指标汇聚 中 每集群本地 Prometheus，Thanos 做全局查询；Grafana 连 Thanos。
Loki 日志量大，存储成本 中 按日志级别采集（ERROR 必采，DEBUG 按需），热数据 30 天，冷归档 OSS。
Cluster Autoscaler 跨云差异 中 ACK 接 ESS，EKS 接 ASG，K3s 固定节点；弹性参数统一抽象。
物理主机与 K3s 节点维护 低 维护前 kubectl drain，维护后 uncordon，台账更新。

4. 核心流程

4.1 业务上线

flowchart LR
  A["申请命名空间+配额"] --> B["Rancher 审批+创建"]
  B --> C["ArgoCD Sync Deployment"]
  C --> D["Ingress + cert-manager"]
  D --> E["HPA 策略配置"]
  E --> F["Grafana 看板关联"]
  F --> G["上线 & 监控在线"]

4.2 物理主机维护

flowchart LR
  A["计划维护"] --> B["台账登记维护窗口"]
  B --> C["kubectl drain 节点"]
  C --> D["执行硬件/OS 维护"]
  D --> E["kubectl uncordon"]
  E --> F["Grafana 确认节点恢复"]
  F --> G["台账更新维护记录"]

5. 系统架构

flowchart LR
  subgraph Rancher["Rancher (HA 3节点)"]
    RUI["Rancher UI/API"]
    APP_STORE["应用商店"]
  end
  subgraph ACK["阿里云 ACK"]
    ADDON_CN["配套组件"] --> POD_CN["业务 Pods"]
    HPA_CN["HPA + ESS CA"] --> POD_CN
  end
  subgraph EKS["AWS EKS"]
    ADDON_AWS["配套组件"] --> POD_AWS["业务 Pods"]
    HPA_AWS["HPA + ASG CA"] --> POD_AWS
  end
  subgraph K3S["内网 K3s (物理机)"]
    ADDON_IDC["配套组件"] --> POD_IDC["内网 Pods"]
    PHYSICAL["物理主机台账"]
  end
  subgraph Observ["可观测栈"]
    PROM["Prometheus × 3"] --> THANOS["Thanos"]
    THANOS --> GRAFANA["Grafana"]
    LOKI["Loki"] --> GRAFANA
  end
  RUI --> ACK
  RUI --> EKS
  RUI --> K3S
  APP_STORE --> ADDON_CN
  APP_STORE --> ADDON_AWS
  APP_STORE --> ADDON_IDC
  ACK --> PROM
  EKS --> PROM
  K3S --> PROM
  K3S --> LOKI
  PHYSICAL --> K3S

6. 关键技术决策

决策点 选择 理由
多集群控制面 Rancher 开源、ACK/EKS/K3s 统一、应用商店简化配套。
GitOps ArgoCD 多集群、与 GitLab 集成成熟、变更 diff 审计。
可观测指标 Prometheus + Thanos + Grafana 开源标准，跨集群汇聚成熟。
日志 Grafana Loki + Promtail 轻量，与 Grafana 统一，成本低。
Pod 弹性 HPA（主）+ VPA（资源建议） HPA 成熟稳定，VPA 仅建议不自动改。
节点弹性 Cluster Autoscaler ACK ESS / EKS ASG，K3s 固定。
物理主机管理 结构化台账 + 标准运维流程 内网 K3s 节点少，台账够用。

7. 数据模型

模型 关键字段 说明
ClusterDef id、name、cloud、env、rancher_id、k8s_version、status 集群定义。
NamespaceDef id、cluster_id、name、team、cpu_quota、mem_quota、max_nodes 命名空间配额。
AddonDef id、name、version、clusters、install_status 配套组件版本与安装状态。
HpaPolicy id、ns_id、workload、min、max、metric、target Pod 弹性策略。
NodePoolPolicy id、cluster_id、pool_name、min、max、spot、cost_budget 节点弹性与成本上限。
PhysicalHost id、hostname、spec_cpu、spec_mem、spec_disk、location、role、warranty_until 物理主机台账。
GrafanaDashboard id、name、uid、datasource、owner、ns_scope Grafana 看板登记。

8. 接口设计

接口 方法 说明
/clusters GET 集群列表及 Rancher 状态。
/namespaces GET/POST 命名空间查询 / 申请。
/addons GET 配套组件版本与安装状态。
/hpa-policies GET/POST Pod 弹性策略查询 / 配置。
/node-pools GET/POST 节点弹性策略。
/physical-hosts GET/POST 物理主机台账查询 / 登记。
/dashboards GET Grafana 看板列表。

9. 验收点

验收点 量化标准
Rancher 纳管 三套集群 100% 注册，配套组件 6 个全部安装并健康。
GitOps 生产配置变更 100% 经 ArgoCD，0 手工 kubectl apply。
Grafana 指标 集群/节点/Pod 指标全覆盖，p99 指标延迟 < 1min。
Loki 日志 业务 ERROR 日志 100% 可检索，保留 30 天。
HPA + CA 核心命名空间 100% 有 HPA，CA 扩缩事件有审计。
物理主机台账 内网 K3s 节点与裸金属 100% 登记，0 黑户设备。
成本护栏 命名空间超配额告警，超成本预算 1 小时内飞书通知。

10. 风险与应对

风险 应对
Rancher 升级影响所有集群 测试集群先升，生产有维护窗口和回滚预案。
弹性雪崩 节点上限 + 成本预算双重兜底，Spot 仅无状态。
Thanos 查询慢 Thanos 加 Store 层缓存，合理 retention；超 7 天长查询走 Grafana 报表。
Loki 存储爆增 日志分级采集 + 热 30 天 TTL + OSS 冷归档，月度成本复盘。
物理主机单点 内网 K3s 不承载生产，故障影响范围仅内网测试。