Codex
113 lines
5.7 KiB
Markdown
113 lines
5.7 KiB
Markdown
# v0.1 Secret 与 API Key 分发规格
|
||
|
||
本文定义 AgentRun `v0.1` 的 Secret 和 Code Agent API Key 分发边界。Code Agent 一定需要上游模型 API Key，但这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。
|
||
|
||
## 设计目标
|
||
|
||
- API Key 只通过 Kubernetes SecretRef 分发到需要它的 manager、runner 或 backend adapter。
|
||
- `deploy/deploy.json` 只记录 SecretRef 名称、key 名称、mount/env intent 和 secret scope，不记录 Secret 值。
|
||
- `v0.1-gitops` 的 rendered manifests 只能引用 Secret 名称和 key，不包含 Secret data。
|
||
- `agentrun-mgr` 保存 run 的 `executionPolicy.secretScope`，但保存的是 credential source reference，不是 credential value。
|
||
- runner 和 backend adapter 只能消费 manager 已授权的 secret scope，不能枚举 namespace 内所有 Secret。
|
||
|
||
## Secret 分类
|
||
|
||
| Secret 类别 | 用途 | 默认消费者 | v0.1 规则 |
|
||
| --- | --- | --- | --- |
|
||
| Postgres DSN | manager 连接 durable store | `agentrun-mgr` | 只通过 `agentrun-v01-mgr-db/DATABASE_URL` 注入。 |
|
||
| Codex/OpenAI-compatible API Key | 真实 Code Agent backend 调上游模型 | runner 或 backend adapter | 只通过 provider profile SecretRef 注入，不写入 run payload。 |
|
||
| Git SSH deploy key | Tekton checkout source/GitOps promotion，Argo 读取 GitOps branch | Tekton、Argo CD | 只存在于 `agentrun-ci` 或 `argocd` Secret；不进入 runtime Pod。 |
|
||
| Registry credential | push/pull private registry | Tekton、runtime imagePullSecret | 只作为 ServiceAccount/imagePullSecret 引用。 |
|
||
| Future tenant credential | tenant 专属工具或外部服务 | runner/backend adapter | 必须先定义 SecretRef 和 secret scope，再允许 run 引用。 |
|
||
|
||
## 固定命名建议
|
||
|
||
| 对象 | v0.1 建议 |
|
||
| --- | --- |
|
||
| Manager DB Secret | `agentrun-v01-mgr-db` key `DATABASE_URL` |
|
||
| Provider Secret | `agentrun-v01-provider-codex` key `API_KEY` |
|
||
| Provider config Secret | `agentrun-v01-provider-codex` key `BASE_URL` 或 ConfigMap 中非敏感 base URL |
|
||
| Tekton Git SSH Secret | `agentrun-ci/agentrun-git-ssh` |
|
||
| Argo Git SSH Secret | `argocd/agentrun-git-ssh` |
|
||
| Runtime ServiceAccount | `agentrun-v01-mgr`、`agentrun-v01-runner` |
|
||
|
||
命名可以在实现时因集群约束调整，但必须满足 lane 独立、用途单一、最小 RBAC 和不跨 `v0.1`/`v0.2` 复用的原则。
|
||
|
||
## Run secretScope 合同
|
||
|
||
Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例形态：
|
||
|
||
```json
|
||
{
|
||
"providerCredentials": [
|
||
{
|
||
"profile": "codex",
|
||
"secretRef": {
|
||
"namespace": "agentrun-v01",
|
||
"name": "agentrun-v01-provider-codex",
|
||
"key": "API_KEY"
|
||
}
|
||
}
|
||
],
|
||
"allowCredentialEcho": false
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- `allowCredentialEcho` 必须固定为 `false`。
|
||
- `secretRef.namespace` 默认只能是 run 所在 lane namespace 或明确批准的 platform namespace。
|
||
- manager 可以保存 `secretRef`，但不得读取 Secret 值后存库。
|
||
- runner/backend adapter 获得 Secret 的方式必须来自 Kubernetes env/file projection 或受限 Secret API 读取；不得通过 run payload、event、CLI 参数或日志传递。
|
||
- SecretRef 不存在或 RBAC 不允许时，run 必须失败为结构化 `failureKind=secret-unavailable` 或等价错误，不得降级成无凭证重试风暴。
|
||
|
||
## 分发路径
|
||
|
||
`v0.1` 默认路径：
|
||
|
||
```text
|
||
deploy/deploy.json
|
||
-> declares SecretRef names and mount/env intent only
|
||
Tekton promotion
|
||
-> renders SecretRef references into v0.1-gitops manifests
|
||
Argo CD
|
||
-> syncs workload references to agentrun-v01
|
||
Kubernetes Secret
|
||
-> created out-of-band by operator or approved secret-management flow
|
||
runner/backend Pod
|
||
-> receives API Key via env/file projection
|
||
```
|
||
|
||
Secret 创建和轮换不由 source branch 自动生成；source branch 只声明需要哪个 SecretRef。后续如果接入 External Secrets、Vault、SealedSecrets 或 SOPS，必须新增或更新本 spec，明确 controller、source of truth、rotation 和 redaction 规则。
|
||
|
||
## 日志与事件 Redaction
|
||
|
||
- event、trace、日志、CLI 输出、health 和 diagnostics 不得打印 Secret 值。
|
||
- `Authorization`、`api_key`、`token`、`password`、URL credential、DSN password 必须 redacted。
|
||
- 可以打印 SecretRef 名称、key 名称、credential source、是否存在、是否被挂载、是否通过 readiness 检查。
|
||
- provider auth 失败只能报告 failure kind、HTTP status 分类和 request id；不得打印请求 header 或 body 中的凭据。
|
||
|
||
## 测试规格
|
||
|
||
### T1 SecretRef render
|
||
|
||
阅读本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后检查 `deploy/deploy.json` 只包含 SecretRef 名称/key 和 mount/env intent；rendered GitOps manifest 也只包含 SecretRef，不包含 Secret data。
|
||
|
||
### T2 Runner credential projection
|
||
|
||
阅读本文，然后启动一个最小 backend runner dry-run，确认 Pod env/file projection 能看到 provider credential，但 event、日志和 CLI 输出只显示 redacted credential source。
|
||
|
||
### T3 Missing secret failure
|
||
|
||
阅读本文，然后用一个不存在的 provider SecretRef 创建 run，确认 run 失败为结构化 `secret-unavailable`，不会打印 Secret 值，也不会无限重试。
|
||
|
||
## 规格的实现情况
|
||
|
||
| 规格项 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| Secret 分发规格 | 已定义 | 本文为 v0.1 API Key 分发权威。 |
|
||
| Kubernetes SecretRef 注入 | 未实现 | 需要后续 GitOps/runtime 实现。 |
|
||
| provider API Key projection | 未实现 | 需要后续 runner/backend adapter 实现。 |
|
||
| redaction 最小规则 | 已定义 | 需要后续代码实现和测试。 |
|
||
| 外部 secret manager | 未采用 | 如需 Vault/ExternalSecrets/SOPS，后续单独更新规格。 |
|