diff --git a/architecture/constraints.md b/architecture/constraints.md index 566bd40..a7754ef 100644 --- a/architecture/constraints.md +++ b/architecture/constraints.md @@ -10,6 +10,7 @@ | Terraform 管 API 配置,Ansible 管主机及不能安全纳管的密钥材料 | 不可读回秘密和根密钥不能靠反复重建实现收敛 | `infrastructure/openbao/README.md` | | LAN HTTP 入口为 Envoy Gateway;新增服务核对 parentRefs、DNS 和认证 | 不直接套用 archive 中的 Gateway 示例 | `platform/envoy-gateway/README.md`、`AGENTS.md` | | 人类身份由 Samba AD / Authelia 提供,workload 身份由 SPIRE 提供 | 身份签发不等于资源授权;基础设施与最小 PoC 已完成,后续集成以 #34 为准 | [SPIRE 状态与依据](../services/spire.md) | +| SPIFFE 提供跨基础设施的统一机器身份入口,替代 workload-sts 统一 IAM 平台方案 | 服务信任 SPIFFE 身份、签发自己的 token 并维护自身权限;非 Kubernetes 身份不依赖 Kubernetes ServiceAccount,优先复用服务现有接入机制 | [核心设计与取舍](../services/spire.md#核心设计与取舍),维护者于 2026-09-16 补充 | | 已由 Flux 接管的资源通过 Git 修改;brownfield 不全局开启 prune | 防止漂移回滚与误删;未接管资源不能假定受 Flux 管理 | `clusters/homelab/README.md` | | DNS 各视图保留权威边界;只管理明确声明的 RRset | 不清理 Samba 自动维护的域记录;DNS 文档尚有冲突 | `infrastructure/dns/README.md` | | Docker 地址池不得与 DN42 的 172.20.0.0/14 重叠 | 本地直连路由会干扰 DN42;已有网络不自动改地址 | `infrastructure/docker/README.md` | diff --git a/services/index.md b/services/index.md index ed5a8d9..4882cc5 100644 --- a/services/index.md +++ b/services/index.md @@ -42,7 +42,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34;其他条目仍为初轮工作区 | nats | 共享消息与 JetStream 队列 | `nats.ad.ddupan.top:4222` | 有配置与拓扑记录;现场待核实 | `platform/nats/README.md` | 补生产/消费示例与队列检查 | | observability | Grafana、指标、日志和追踪 | `grafana.ad.ddupan.top` | 记录已接管 Flux;9 月 16 日变更入口 | `platform/observability/README.md` | 补看板和查询使用指南 | | openebs | k3s 本地 ZFS 持久卷 | `localpv-zfs-ceph StorageClass` | 记录已接管 Flux | `platform/openebs/README.md` | 已有运维检查;补 PVC 使用边界 | -| [spire](spire.md) | workload 身份签发 | `Workload API / spire-oidc.ad.ddupan.top` | #34 记录基础设施与最小 OpenBao PoC 已完成;后续集成进行中 | [#34](https://git.ddupan.top/panxiao81/homelab-infra/issues/34)、[RUNBOOK](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/platform/spire/RUNBOOK.md) | 已有接入指南;动态任务以 ticket 为准 | +| [spire](spire.md) | 跨基础设施的统一机器身份入口 | `Workload API / spire-oidc.ad.ddupan.top` | #34 记录基础设施与最小 OpenBao PoC 已完成;后续集成进行中 | [#34](https://git.ddupan.top/panxiao81/homelab-infra/issues/34)、[RUNBOOK](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/platform/spire/RUNBOOK.md) | 已有接入指南;动态任务以 ticket 为准 | ## 基础设施 diff --git a/services/spire.md b/services/spire.md index 46537e6..fc24a3d 100644 --- a/services/spire.md +++ b/services/spire.md @@ -11,8 +11,38 @@ sources: # SPIFFE/SPIRE -为运行中的程序提供可证明、短期的身份。SPIRE 负责签发身份,OpenBao 和其他目标服务 -根据身份决定权限。人类登录继续使用 Samba AD 与 Authelia。 +SPIFFE 为 homelab 中跨基础设施、由我们自行集成的服务提供统一的机器身份入口, +相当于跨平台的 service account。SPIRE 负责证明运行中的 workload 身份并签发 SVID, +让 Kubernetes、普通 Linux 主机、VM 和 CI/AI Agent 能使用同一套身份体系。 + +## 核心设计与取舍 + +SPIFFE/SPIRE 取代了原计划中由 **workload-sts 承担统一 IAM 平台**的方案。 +统一的是机器身份:应用信任 SPIFFE 身份,在验证后签发服务自己的 token, +并继续自行维护角色、policy 和资源权限。 + +```text +运行在不同基础设施上的 workload + → SPIRE 证明身份,签发 SPIFFE SVID + → 目标服务验证并信任该身份 + → 目标服务签发自己的 token + → 按该服务维护的权限访问资源 +``` + +例如 OpenBao 验证 JWT-SVID 后,按照自己的 role/policy 签发短期 Bao token。 +能够直接验证 SVID 的服务也可以直接消费身份,授权仍由该服务决定。 +人类登录继续使用 Samba AD 与 Authelia。 + +这一设计有两个主要优势: + +- **跨基础设施获取身份。** 非 Kubernetes workload 可以通过适合其环境的节点和进程证明 + 接入 SPIRE,无需依赖 Kubernetes ServiceAccount。Kubernetes ServiceAccount 只是 + Kubernetes 环境内的初始证明方式,不是整个 homelab 的身份根。 +- **控制现有系统的改造量。** 优先利用目标服务已有的身份验证、token 交换和权限机制, + 增加对 SPIFFE 的信任与身份映射,保留各服务已有的授权模型。 + +设计定位由维护者于 2026-09-16 补充。这里记录的是方案替代关系,不代表 workload-sts +仓库已删除或所有相关组件已退役;非 Kubernetes 接入和各消费者的实施进度仍以 ticket 为准。 ## 当前做到哪里 @@ -34,7 +64,9 @@ sources: ## 如何使用 这是一项面向程序的基础能力,没有供人登录的 SPIRE 业务门户。 -如果你的 CI job 或 AI Agent 需要访问 OpenBao,接入路径是: +下面以已经完成最小 PoC 的 **Kubernetes workload → OpenBao** 路径为例; +其他基础设施使用各自的初始证明方式,取得 SPIFFE 身份后沿用目标服务的信任与授权机制。 +如果你的 Kubernetes CI job 或 AI Agent 需要访问 OpenBao,接入路径是: 1. 为 Kubernetes workload 定义专用 ServiceAccount 和稳定 SPIFFE ID。 2. 通过 ClusterSPIFFEID 声明哪些 Pod 能取得该身份,并挂载 CSI Workload API socket。 diff --git a/verification.md b/verification.md index c03327e..d232666 100644 --- a/verification.md +++ b/verification.md @@ -37,6 +37,8 @@ SPIFFE/SPIRE 按维护者指定,以 [#34](https://git.ddupan.top/panxiao81/hom - `infrastructure/docker/README.md` 提及仓库外 `research-auto`,不能在本轮算作已盘点服务。 - 本轮发现远端仓库 `gitea-microvm-runner`、`postgresql-tenant-operator`、`workload-sts`, 尚未审阅内容或运行状态。后续将跨仓库服务纳入总览。 + 维护者已明确原计划由 workload-sts 承担的统一 IAM 平台方案被 SPIFFE/SPIRE 替代, + 见 [设计定位](services/spire.md#核心设计与取舍);仓库及组件的实际保留范围仍未查询。 - 新增 NATS、zot、microVM 等来源含未提交文件;合并后补可访问的 commit/PR 链接。 - Backstage 仍作为计划入口记录;本轮没有证明已有部署。