From c6386a1101c6dc249babc99358878d93f822408b Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Wed, 16 Sep 2026 14:48:02 +0000 Subject: [PATCH] =?UTF-8?q?=E4=BE=9D=E6=8D=AE=20#34=20=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=20SPIRE=20=E9=98=B6=E6=AE=B5=E7=8A=B6=E6=80=81=E5=B9=B6?= =?UTF-8?q?=E6=98=8E=E7=A1=AE=E7=8A=B6=E6=80=81=E6=9F=A5=E8=AF=A2=E5=89=8D?= =?UTF-8?q?=E7=9A=84=E6=B2=9F=E9=80=9A=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 4 +- CONTRIBUTING.md | 12 +++++- README.md | 3 ++ architecture/constraints.md | 2 +- services/index.md | 5 ++- services/spire.md | 81 +++++++++++++++++++++++++++++++++++++ verification.md | 14 +++++-- 7 files changed, 113 insertions(+), 8 deletions(-) create mode 100644 services/spire.md diff --git a/AGENTS.md b/AGENTS.md index d2e7e0e..ff58dbc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,9 @@ - 正式知识写给人和 AI 共同阅读；本文件只放工作规则，不另存一份服务事实。 - 以中文维护正文、commit、PR；配置键、命令和上游专有名称保留原文。 - 区分设计、配置、部署记录与现场验证。没有访问现场，不得写“运行正常”。 -- 修改前读取对应源码 README/runbook，核实相关运行状态；发现冲突先记录，不能自行把计划升级为事实。 +- 查询服务或项目状态前先问维护者：哪些工作正在动态进行、由哪个 ticket 跟踪、哪些现状尚未记录。已有明确授权的范围无需重复询问；不能从一个项目扩大到其他项目或现场查询。 +- 维护者指定 ticket 为依据时，先读正文和讨论，区分已完成阶段与开放的后续范围。issue open 不等于尚未部署，README 与 ticket 不同也不能立即认定为运行异常。 +- 修改前读取对应源码 README/runbook；需要现场核实时先取得维护者对范围的确认。发现差异先记录来源，不能自行把计划升级为事实。 - 新增服务同时补用途、入口、登录方式、第一次使用示例、依赖和故障入口。 - 改变行为、入口、依赖、状态或恢复方法时，在同一任务更新对应文档与服务索引。 - 跨仓库修改互相关联 commit/PR；未完成的文档同步明确记入 verification.md，不能宣称全部完成。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60bac00..19a8876 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,15 @@ # 文档维护规则 +## 查询前先对齐 + +查询项目状态前，先询问维护者正在进行的工作、跟踪 ticket 和尚未成文的现状。 +已有明确授权则在该范围内继续，不重复询问；文档查询授权不自动扩展为现场检查。 +2026-09-16 维护者指定 SPIFFE/SPIRE 基本以 homelab-infra #34 的记录为依据； +本轮仅查该 ticket 及其直接引用的 runbook，没有查询现场。其他项目仍需先询问。 + +稳定设计与使用方法放知识库，动态进度链接到 ticket。知识库只保留注明查阅日期的阶段摘要， +不复制维护第二份实时任务列表。issue open 可能表示后续阶段未完成，不能据此推断基础服务未部署。 + ## 状态与证据 分别记录服务生命周期和验证程度，避免一个“完成”掩盖多个状态： @@ -16,7 +26,7 @@ accepted 不代表部署完成，implemented 必须附实现和验收依据。 ## 一项工作的完成条件 -1. 修改前读取服务文档及相关约束，检查已知冲突。 +1. 先按上述规则对齐查询范围，再读取服务文档、相关 ticket 和约束，区分动态工作与事实冲突。 2. 实施和必要验证后，同步用途、入口、使用方法、依赖和恢复步骤中的变化。 3. 新增或退役服务时更新服务总览；退役文档保留替代入口和原因。 4. 代码与文档分属仓库时互相链接 commit/PR；未部署或未同步的部分明确写出。 diff --git a/README.md b/README.md index 28ef858..230f401 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ ## 从这里开始 - [服务总览](services/index.md)：有什么、有什么用、在哪里、状态依据是什么。 +- [SPIFFE/SPIRE](services/spire.md)：按 #34 整理的阶段状态、使用与 runbook 入口。 - [待核实与文档缺口](verification.md)：互相矛盾的记录、缺少使用说明的服务、下一步核实方法。 - [架构约束](architecture/constraints.md)：修改环境前必须遵守的设计及原始依据。 - [文档维护规则](CONTRIBUTING.md)：人和 AI 如何共同维护知识。 @@ -15,6 +16,8 @@ 首轮盘点日期为 **2026-09-16**，依据 `/home/panxiao81/services` 工作区，基线 commit 为 `ebe0ec154dab557598075b5cf6d3629c3c23fe2a`。该工作区包含未提交修改和未跟踪文件。 +SPIFFE/SPIRE 随后按维护者授权补读了 #34 及其已合并 runbook；其他条目仍以初轮工作区证据为限。 +后续状态查询先向维护者确认动态工作与资料来源，授权范围内不重复询问。 本轮没有查询运行环境；“文档记录已部署”不等于今天已验证健康。 本库中的入口地址来自原有记录，也尚未逐一验证可达性。 diff --git a/architecture/constraints.md b/architecture/constraints.md index 3354f79..566bd40 100644 --- a/architecture/constraints.md +++ b/architecture/constraints.md @@ -9,7 +9,7 @@ | OpenBao 恢复不能依赖 k3s 或读取自己内部的恢复凭据 | 先恢复信任根，再恢复消费者 | `infrastructure/openbao/README.md`、`CLAUDE.md` | | 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 提供 | 身份签发不等于资源授权；SPIRE 实施状态见核实清单 | `platform/spire/README.md` | +| 人类身份由 Samba AD / Authelia 提供，workload 身份由 SPIRE 提供 | 身份签发不等于资源授权；基础设施与最小 PoC 已完成，后续集成以 #34 为准 | [SPIRE 状态与依据](../services/spire.md) | | 已由 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 eae400f..ed5a8d9 100644 --- a/services/index.md +++ b/services/index.md @@ -1,7 +1,8 @@ # 服务总览 审阅日期：2026-09-16。以下覆盖源码工作区 apps/、platform/、infrastructure/ 的一级组件，以及集群入口。 -**所有条目本轮均未现场验证。** 状态栏表示文档或配置证据，不表示实时健康状态。 +**所有条目本轮均未现场验证。** 状态栏表示文档、ticket 或配置证据，不表示实时健康状态。 +SPIFFE/SPIRE 已按维护者授权补读 #34；其他条目仍为初轮工作区盘点，查询前先向维护者对齐。 来源路径相对于 [homelab-infra](https://git.ddupan.top/panxiao81/homelab-infra)；包含未提交内容，见首页证据边界。 入口按来源记录列出，访问范围和可达性仍需验证。缺口详情见[待核实清单](../verification.md)。 @@ -41,7 +42,7 @@ | 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 | workload 身份签发 | `Workload API / spire-oidc.ad.ddupan.top` | zot 验收有运行证据；集群总览冲突 | `platform/spire/README.md` | 核实状态，补身份申请和消费流程 | +| [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 为准 | ## 基础设施 diff --git a/services/spire.md b/services/spire.md new file mode 100644 index 0000000..46537e6 --- /dev/null +++ b/services/spire.md @@ -0,0 +1,81 @@ +--- +title: SPIFFE/SPIRE 使用入口与阶段状态 +lifecycle: active +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +sources: + - https://git.ddupan.top/panxiao81/homelab-infra/issues/34 + - https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/platform/spire/RUNBOOK.md +--- + +# SPIFFE/SPIRE + +为运行中的程序提供可证明、短期的身份。SPIRE 负责签发身份，OpenBao 和其他目标服务 +根据身份决定权限。人类登录继续使用 Samba AD 与 Authelia。 + +## 当前做到哪里 + +**基础设施与最小 OpenBao PoC 已完成，真实 workload 的推广接入仍在推进。** +`active` 仅描述已有基础设施，不表示所有消费者均已迁移。 + +维护者指定以 [homelab-infra #34](https://git.ddupan.top/panxiao81/homelab-infra/issues/34) +为主要状态依据。2026-09-16 查阅时 issue 为 open，最后更新时间为 +2026-09-14 12:43:54 UTC；本页是该次查阅的阶段摘要，不替代 ticket 的动态进度。 +本轮没有访问运行环境，以下完成结论均为 ticket 记录。 + +| 已完成阶段 | 记录依据 | +|---|---| +| SPIRE Server、Agent、CSI、OIDC Discovery Provider 上线；节点证明成功 | [9 月 13 日基础设施验收](https://git.ddupan.top/panxiao81/homelab-infra/issues/34#issuecomment-283)，对应 #51 | +| OIDC HTTPS、DNS、TLS、discovery/JWKS 验证；OpenBao JWT backend/role/policy 创建 | [9 月 14 日端到端验收](https://git.ddupan.top/panxiao81/homelab-infra/issues/34#issuecomment-301)，对应 #52、#53 | +| 测试 Pod 获得 aud=openbao 的 JWT-SVID，交换为仅含 spire-poc policy、TTL 300 秒的 Bao token；lookup-self/revoke-self 验证完成 | 同上；临时 workload 与 registration entries 已清理，最终 Terraform plan 为 No changes | +| 新 workload 接入、故障排查和恢复说明已合并 | [9 月 14 日文档记录](https://git.ddupan.top/panxiao81/homelab-infra/issues/34#issuecomment-308)，对应 #54 | + +## 如何使用 + +这是一项面向程序的基础能力，没有供人登录的 SPIRE 业务门户。 +如果你的 CI job 或 AI Agent 需要访问 OpenBao，接入路径是： + +1. 为 Kubernetes workload 定义专用 ServiceAccount 和稳定 SPIFFE ID。 +2. 通过 ClusterSPIFFEID 声明哪些 Pod 能取得该身份，并挂载 CSI Workload API socket。 +3. 在 OpenBao 为精确的 subject 和 audience 配置 role 与最小 policy。 +4. 程序从 Workload API 获取 `aud=openbao` 的 JWT-SVID，再调用 + `auth/jwt-spire/login` 换取短期 Bao token。 +5. 只执行该 policy 允许的操作；退出时尽力吊销 token，并清理进程内的临时凭据。 + +可直接沿用的配置模板、交换示例和排障步骤见 +[权威 RUNBOOK](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/platform/spire/RUNBOOK.md) +的第 4–8 节。这里不复制第二份操作脚本。接入需要新增身份和授权配置，不是挂载 socket 后 +就能读取业务秘密；临时 PoC workload 已清理，不是可直接使用的常驻客户端。 + +运行配置使用的 Kubernetes 身份约定为 +`spiffe://ddupan.top/ns//sa/`。 +ticket 目标章节列出的其他身份形式是设计示例，不应直接替换现有 subject。 +OIDC issuer 为 `https://spire-oidc.ad.ddupan.top`，其 discovery/JWKS 用于机器验签。 + +## 仍在 ticket 中跟踪 + +截至本次查阅，后续范围包括真实 Gitea CI/AI Agent 的 OpenBao 接入、credential-exec、 +SeaweedFS Web Identity/STS、非 Kubernetes 主机与临时 VM 的证明和回收、 +Compute/DBaaS 消费身份，以及 HA、备份恢复和多 issuer 约定。 +这些是 #34 的开放范围；单个消费者已有其他 PoC，不等于整项已完成。 + +最小 PoC 标为完成，但验收清单仍有三个未勾选项目： + +- 错误 namespace、ServiceAccount 或 selector 无法获得该身份； +- SVID 自动轮换不影响后续登录； +- 删除 registration entry 后不能再取得新 SVID。 + +因此不能把“PoC 完成”概括成所有负向、轮换和撤销测试都已通过。 +已有恢复说明也不等于恢复演练已完成。最新进度回到 #34 查询，不在本页维护另一套勾选清单。 + +## 必须遵守的边界 + +- SPIFFE ID 是身份，不自动授予资源权限；资源授权仍由目标服务执行。 +- audience 按目标服务绑定，OpenBao role 精确限制 subject；不授予整个 trust domain 通用权限。 +- 人类身份保持 Samba AD / Authelia，当前方案不依赖迁移 Keycloak。 +- 不因能访问 Agent socket 就允许任意身份；不将短期凭据持久化到镜像、Secret、artifact 或日志。 +- PostgreSQL registration state 与 signing-key PVC 必须分别考虑备份；恢复路径不能形成循环依赖。 +- PoC 和推广期间保留现有认证回退路径，不能把目标架构当作已经完成的凭据迁移。 + +完整边界见 ticket 的架构决策与安全恢复章节，以及 RUNBOOK 第 3、9 节。 diff --git a/verification.md b/verification.md index aaa569d..c03327e 100644 --- a/verification.md +++ b/verification.md @@ -1,14 +1,22 @@ # 待核实与文档缺口 -审阅日期：2026-09-16；本轮只盘点仓库，未查询现场。 +审阅日期：2026-09-16；初版依据工作区，SPIFFE/SPIRE 已按维护者指定补读 #34 与 runbook，未查询现场。 +下面的检查方法只是候选步骤，执行前先问维护者当前进度及查询范围。 以下路径相对于 homelab-infra。优先修复影响恢复、认证、DNS 和首次使用的问题。 -## 记录冲突 +## 已对齐的动态工作 + +SPIFFE/SPIRE 按维护者指定，以 [#34](https://git.ddupan.top/panxiao81/homelab-infra/issues/34) +记录为主要依据：基础设施与最小 OpenBao PoC 已完成，issue 保持 open 跟踪后续集成。 +已合并的 runbook 也包含新 workload 接入和运维说明，不能再标记为“缺接入指南”。 +原工作区集群总览的“首次上线待验证”不作为当前阶段判断。 +详见 [SPIFFE/SPIRE 使用入口与阶段状态](services/spire.md)；源码工作区本轮未修改。 + +## 待向维护者确认的记录差异 | 项目 | 两边的记录 | 核实与收敛方式 | |---|---|---| | LAN DNS | `apps/blocky/README.md` 说已是主 DNS；`infrastructure/dns/README.md` 仍说未成为正式 resolver | 读取 NEC DHCP 配置、客户端 DNS 和 Blocky 查询结果，再同步两份说明 | -| SPIRE | `clusters/homelab/README.md` 说首次上线待验证；`apps/zot/README.md` 记录 9 月 14/16 日真实 JWT-SVID 验收 | 核对 Flux revision、SPIRE 健康和 Workload API，再更新集群总览；zot 的部分验收不等于全部身份集成完成 | | Authelia | README 仍描述 OIDC 为后续阶段、旧 Contour/Traefik 路径；退役记录和 Envoy 文档已描述 Authelia 替代旧 IdP | 核对 OIDC discovery、登录及 forward-auth，重写过时段落；迁移旧文档前检查其中的敏感示例 | | microVM runner | `infrastructure/microvm-runner/README.md` 说 PoC 完成但正式启用仍有前提；远端已有独立 runner 仓库 | 查清两个仓库的职责、controller/worker 部署和一次 job 生命周期，不能把仓库存在当作服务已启用 | | NATS durable 名称 | NATS 文档示例为 `kind-microvm-pve2`；microVM 文档配置为 `kind-microvm`，要求同类 worker 共享 durable | 查运行配置和 consumer；统一文档，避免多 worker 队列语义不一致 |