docs: add ESO secret UI spec
This commit is contained in:
root
@@ -0,0 +1,198 @@
|
||||
# HWLAB v0.3 ESO 密钥管理 UI 规格
|
||||
|
||||
SPEC: HWLAB-ESO-UI-20260630 ESO UI draft-2026-06-30-p0.
|
||||
Issue: [#2292](https://github.com/pikasTech/HWLAB/issues/2292).
|
||||
上级: [#2233](https://github.com/pikasTech/HWLAB/issues/2233), [#2277](https://github.com/pikasTech/HWLAB/issues/2277).
|
||||
参考: Weave GitOps 0.22.0 Manage Secrets UI, HWLAB `config/hwlab-v03/secrets.yaml`.
|
||||
|
||||
本文只定义 `hwlab.pikapython.com` 的 ESO / External Secrets Operator 密钥管理界面。它不是生产 Secret 迁移方案，也不触发部署、apply、rollout 或后端选型变更。
|
||||
|
||||
## 范围
|
||||
|
||||
- 在 Cloud Web 管理侧边栏新增 `密钥` 入口，路由建议为 `/admin/secrets`，`navId` 为 `admin.secrets`，排序固定在 `授权` 与 `用户` 之间。
|
||||
- 仅覆盖 ESO、`ExternalSecret`、`SecretStore`、`ClusterSecretStore`、目标 Kubernetes Secret cache 和 consumer rollout 可视化。
|
||||
- 默认上下文由同源 API 返回的 active target 决定；当前 JD01 作为 [#2277](https://github.com/pikasTech/HWLAB/issues/2277) 设计目标展示，不在前端硬编码。D518 和 D601 只作为历史或明确选择的 target。
|
||||
- SOPS、age/GPG、Git 加密文件、PR 生成、手工 `kubectl` 指令和 secret value 输入框不进入本界面。
|
||||
|
||||
## 信息架构
|
||||
|
||||
管理区导航顺序：
|
||||
|
||||
```text
|
||||
管理
|
||||
授权 /admin/access admin.access
|
||||
密钥 /admin/secrets admin.secrets
|
||||
用户 /admin/users admin.users
|
||||
账务 /admin/billing admin.billing
|
||||
HWPOD /admin/hwpod-groups admin.hwpodGroups
|
||||
Profiles /admin/provider-profiles admin.providerProfiles
|
||||
```
|
||||
|
||||
`admin.secrets` 必须受 HWLAB RBAC 控制。无权限用户看不到导航项；只读用户可看脱敏状态，不能进入 apply、rotate、rollback 或 destructive 操作。
|
||||
|
||||
## 页面结构
|
||||
|
||||
### 概览
|
||||
|
||||
首屏顶部展示当前 target 摘要，不把 target 写死在前端：
|
||||
|
||||
- node、lane、public URL、runtime namespace、infra namespace。
|
||||
- ESO controller / webhook / cert-controller readiness。
|
||||
- `SecretStore` / `ClusterSecretStore` readiness 和 store scope。
|
||||
- 最近一次 sync 时间、最近一次 validate 时间、当前 fingerprint 对齐摘要。
|
||||
- consumer rollout 摘要：关联 Deployment/Job 数量、ready 数量、pending 数量、最近一次 fingerprint 触发的 rollout revision。
|
||||
- `valuesPrinted=false` 固定可见。
|
||||
|
||||
概览区域只显示状态、引用和下一步 drill-down；不显示教程式长文案，也不提供复制 secret value 的入口。
|
||||
|
||||
### ExternalSecrets 列表
|
||||
|
||||
列表列字段：
|
||||
|
||||
- `ExternalSecret` 名称、namespace、target node/lane、目标 Secret 名称。
|
||||
- `SecretStore` / `ClusterSecretStore` 名称、store scope。
|
||||
- 状态：`Ready`、`NotReady`、`Pending`、`SyncError`、`Unknown`。
|
||||
- 最近刷新时间、创建时间、refresh interval。
|
||||
- 目标 Secret key presence、fingerprint 摘要、resourceVersion。
|
||||
- 关联 consumer 与 rollout 状态。
|
||||
- 操作：详情、事件、复制脱敏诊断摘要、打开受控 validate 结果。
|
||||
|
||||
列表不得提供复制、下载、解码或 reveal secret value 的操作。
|
||||
|
||||
### ExternalSecret 详情
|
||||
|
||||
详情页分区：
|
||||
|
||||
- 状态摘要：Ready/NotReady、LastRefreshTime、LastTransitionTime、reason、message 摘要。
|
||||
- 基本信息：ExternalSecret、target Secret、node/lane、namespace、store kind/name/scope。
|
||||
- 数据映射：remoteRef path、property、version、target key、fingerprint；路径可脱敏或 hash，不能显示 value。
|
||||
- 目标 Secret：key presence、fingerprint、resourceVersion、valuesPrinted=false。
|
||||
- Consumer：Deployment/Job、image、pod readiness、rollout revision、template fingerprint annotation、最后 validate 结果。
|
||||
- Provenance：配置来源文件、Git source commit、GitOps revision、Argo revision 或 status job id。
|
||||
|
||||
### 创建/编辑向导
|
||||
|
||||
本 issue 只设计向导，不启用生产 apply。向导提交后的默认动作是 dry-run/plan。
|
||||
|
||||
1. 选择 node/lane/namespace。默认值来自 API active target；JD01/v0.3 只有在 API 标记为 active 时自动选中。
|
||||
2. 输入 ExternalSecret 名称和目标 Kubernetes Secret 名称。
|
||||
3. 选择 `SecretStore` 或 `ClusterSecretStore`。namespace scoped store 只能绑定同 namespace；cluster scoped store 必须显示目标 namespace。
|
||||
4. 配置 remoteRef path/property/version、target key、refresh interval、consumer rollout 标记。
|
||||
5. 展示 dry-run/plan 结果、受影响 consumer、脱敏摘要和风险提示。
|
||||
|
||||
未来 apply 能力必须走 HWLAB/UniDesk 受控 API；前端不展示裸 `kubectl`、Helm 或 YAML 复制执行步骤。
|
||||
|
||||
### 事件与排障
|
||||
|
||||
事件页按资源归组，覆盖：
|
||||
|
||||
- Store auth failed。
|
||||
- Store unavailable。
|
||||
- ExternalSecret sync failed。
|
||||
- Target Secret missing。
|
||||
- Consumer rollout pending。
|
||||
- Consumer validation failed。
|
||||
- Unknown / stale status。
|
||||
|
||||
每条事件显示时间、资源、reason、message 摘要、建议 drill-down 和关联 trace/job id。message 需要经过后端脱敏；如果后端判定消息可能含有凭据，前端只显示 redacted reason 和 raw drill-down id。
|
||||
|
||||
## 状态模型
|
||||
|
||||
状态优先级从高到低：
|
||||
|
||||
1. `SecretLeakBlocked`: 发现响应含疑似 value、base64 payload、token、DSN、password 或 auth header，整页进入 blocked，要求后端修脱敏。
|
||||
2. `StoreUnavailable`: ESO 可达但 Store 不 Ready 或认证失败。
|
||||
3. `SyncError`: Store Ready，但 ExternalSecret 同步失败。
|
||||
4. `TargetMissing`: ExternalSecret Ready 但目标 Secret/key 不存在。
|
||||
5. `RolloutPending`: 目标 Secret fingerprint 更新，但 consumer 未滚动到新 fingerprint。
|
||||
6. `ValidationFailed`: rollout 已完成，但原入口 validate 失败。
|
||||
7. `Ready`: Store、ExternalSecret、target Secret、consumer fingerprint 和 validate 全部对齐。
|
||||
8. `Unknown`: 信息缺失、API 超时或 status 过期。
|
||||
|
||||
UI 可以把 `Pending` 作为 `Unknown` 与明确错误之间的中间态，但不得把 `Pending` 渲染成成功。
|
||||
|
||||
## API 契约草案
|
||||
|
||||
所有接口走 Cloud Web 同源 `/v1/admin/secrets/*`，由后端调用受控 node/lane API、GitOps status 或 UniDesk CLI。前端不得直连 Kubernetes API、Vault/OpenBao、ESO webhook 或 platform-infra 服务。
|
||||
|
||||
```text
|
||||
GET /v1/admin/secrets/summary
|
||||
GET /v1/admin/secrets/external-secrets?node=<id>&lane=<lane>&namespace=<ns>
|
||||
GET /v1/admin/secrets/external-secrets/:namespace/:name
|
||||
GET /v1/admin/secrets/events?node=<id>&lane=<lane>&limit=<n>
|
||||
POST /v1/admin/secrets/external-secrets/plan
|
||||
POST /v1/admin/secrets/external-secrets/validate
|
||||
```
|
||||
|
||||
未来写入接口需要单独 issue 评审：
|
||||
|
||||
```text
|
||||
POST /v1/admin/secrets/external-secrets/apply
|
||||
POST /v1/admin/secrets/external-secrets/rollback
|
||||
POST /v1/admin/secrets/rotate
|
||||
```
|
||||
|
||||
响应共同字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"contractVersion": "hwlab-admin-secrets-v1",
|
||||
"target": {
|
||||
"node": "JD01",
|
||||
"lane": "v03",
|
||||
"runtimeNamespace": "hwlab-v03",
|
||||
"infraNamespace": "platform-infra",
|
||||
"source": "yaml-active-target"
|
||||
},
|
||||
"valuesPrinted": false,
|
||||
"secretMaterialStored": false,
|
||||
"generatedAt": "2026-06-30T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
错误响应必须包含 `valuesPrinted=false`、`layer`、`code`、`retryable` 和可审计 request/trace id。后端不能把 live Secret 解码结果作为 response 的任何字段。
|
||||
|
||||
## 脱敏规则
|
||||
|
||||
允许展示：
|
||||
|
||||
- 对象名、namespace、node、lane、store kind/name、scope。
|
||||
- target Secret 名称、target key 名、presence、resourceVersion。
|
||||
- remoteRef path/property/version 的脱敏形式。
|
||||
- fingerprint、字节数、状态、reason、时间、trace id、job id。
|
||||
- `valuesPrinted=false`、`secretMaterialStored=false`。
|
||||
|
||||
禁止展示：
|
||||
|
||||
- Secret value、base64 payload、token、password、API key、Authorization header、Cookie、DSN、private key、Vault root token。
|
||||
- 可直接还原凭据的完整 JSON、TOML、YAML、env dump、stdout/stderr。
|
||||
- 从 runtime Secret、pod env、日志或数据库反推 sourceRef 的结果。
|
||||
|
||||
如果任一后端字段命中凭据模式，后端必须删除或替换为 fingerprint；前端发现疑似泄露时进入 `SecretLeakBlocked`。
|
||||
|
||||
## 权限
|
||||
|
||||
- `admin.secrets.read`: 读取概览、列表、详情、事件和 validate 结果。
|
||||
- `admin.secrets.plan`: 提交 dry-run/plan，不写运行面。
|
||||
- `admin.secrets.apply`: 未来 apply/rollback/rotate；本 SPEC 不启用。
|
||||
- `admin.secrets.audit`: 查看操作历史、trace、job id 和 rollout provenance。
|
||||
|
||||
权限来自 HWLAB Access/RBAC，同一用户 session 下不新增第二套登录或临时 token。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 侧边栏设计明确 `密钥` 位于 `授权` 和 `用户` 之间。
|
||||
- 页面覆盖概览、ExternalSecrets 列表、详情、创建/编辑 dry-run 向导、事件与 rollout/validate 可视化。
|
||||
- 所有 target 默认值由 API/YAML active target 解析，前端不硬编码 JD01、D518、D601 或 G14。
|
||||
- UI 只覆盖 ESO；没有 SOPS、age/GPG、Git 加密文件、PR 工作流或 secret value 输入框。
|
||||
- API 草案只通过同源受控 API 暴露脱敏状态，不要求用户执行裸 `kubectl`。
|
||||
- 任意页面、事件和错误态都只能展示 presence、fingerprint、状态、reason 和引用，不展示 secret value。
|
||||
- 本设计可以映射现有 `config/hwlab-v03/secrets.yaml` 的 `secretPlane`、`ExternalSecret`、target Secret 和 consumer envRef。
|
||||
|
||||
## 后续阶段
|
||||
|
||||
- P1 只读 MVP：新增导航、概览、列表、详情和事件页，后端只读 status。
|
||||
- P2 dry-run：新增创建/编辑向导和 plan API，不执行 apply。
|
||||
- P3 validate/rollout 可视化：串联 Secret fingerprint、consumer rollout revision 和原入口 validate 结果。
|
||||
- P4 受控 apply/rollback：必须另开 issue，确认生产 backend、RBAC、审计、rollback 和 rollout 验收后才能实现。
|
||||
Reference in New Issue
Block a user