依据 #34 对齐 SPIRE 阶段状态并明确状态查询前的沟通规则

2026-09-16 14:48:02 +00:00
parent 5aa50d71ad
commit c6386a1101
7 changed files with 113 additions and 8 deletions
@@ -6,7 +6,9 @@
 - 正式知识写给人和 AI 共同阅读；本文件只放工作规则，不另存一份服务事实。
 - 以中文维护正文、commit、PR；配置键、命令和上游专有名称保留原文。
 - 区分设计、配置、部署记录与现场验证。没有访问现场，不得写“运行正常”。
- 修改前读取对应源码 README/runbook，核实相关运行状态；发现冲突先记录，不能自行把计划升级为事实。
+- 查询服务或项目状态前先问维护者：哪些工作正在动态进行、由哪个 ticket 跟踪、哪些现状尚未记录。已有明确授权的范围无需重复询问；不能从一个项目扩大到其他项目或现场查询。
+- 维护者指定 ticket 为依据时，先读正文和讨论，区分已完成阶段与开放的后续范围。issue open 不等于尚未部署，README 与 ticket 不同也不能立即认定为运行异常。
+- 修改前读取对应源码 README/runbook；需要现场核实时先取得维护者对范围的确认。发现差异先记录来源，不能自行把计划升级为事实。
 - 新增服务同时补用途、入口、登录方式、第一次使用示例、依赖和故障入口。
 - 改变行为、入口、依赖、状态或恢复方法时，在同一任务更新对应文档与服务索引。
 - 跨仓库修改互相关联 commit/PR；未完成的文档同步明确记入 verification.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；未部署或未同步的部分明确写出。
@@ -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；其他条目仍以初轮工作区证据为限。
+后续状态查询先向维护者确认动态工作与资料来源，授权范围内不重复询问。
 本轮没有查询运行环境；“文档记录已部署”不等于今天已验证健康。
 本库中的入口地址来自原有记录，也尚未逐一验证可达性。

@@ -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` |
@@ -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 为准 |

 ## 基础设施

@@ -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/<namespace>/sa/<service-account>`。
+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 节。
@@ -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 队列语义不一致 |