docs: 同步 v0.1 backend profile 规格
This commit is contained in:
Codex
@@ -1,6 +1,6 @@
|
||||
# v0.1 Secret 与 provider credential 分发规格
|
||||
|
||||
本文定义 AgentRun `v0.1` 的 Secret 和 Code Agent provider credential 分发边界。真实 Code Agent backend 需要上游模型凭据；Codex 测试凭据以 `~/.codex/auth.json` 与 `~/.codex/config.toml` 为输入源，通过 Kubernetes Secret 投影进入 runner/backend Pod。这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。
|
||||
本文定义 AgentRun `v0.1` 的 Secret 和 Code Agent provider credential 分发边界。真实 Code Agent backend 需要上游模型凭据；Codex stdio profile 测试凭据以 `~/.codex/auth.json` 与 `~/.codex/config.toml` 形态为输入源，通过 Kubernetes Secret 投影进入 runner/backend Pod。这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。
|
||||
|
||||
## 设计目标
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
| Secret 类别 | 用途 | 默认消费者 | v0.1 规则 |
|
||||
| --- | --- | --- | --- |
|
||||
| Postgres DSN | manager 连接 durable store | `agentrun-mgr` | 只通过 `agentrun-v01-mgr-db/DATABASE_URL` 注入。 |
|
||||
| Codex 测试凭据文件 | 真实 Code Agent backend 调上游模型 | runner 或 backend adapter | 测试来源固定为 `~/.codex/auth.json` 与 `~/.codex/config.toml`，只通过 Kubernetes SecretRef 文件投影注入，不写入 run payload。 |
|
||||
| Codex stdio profile 凭据文件 | 真实 Code Agent backend 调上游模型 | runner 或 backend adapter | `codex` 与 `deepseek` 均使用 `auth.json`/`config.toml` 文件形态，只通过 profile-scoped Kubernetes 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 引用。 |
|
||||
@@ -25,8 +25,9 @@
|
||||
| 对象 | v0.1 建议 |
|
||||
| --- | --- |
|
||||
| Manager DB Secret | `agentrun-v01-mgr-db` key `DATABASE_URL` |
|
||||
| Provider Secret | `agentrun-v01-provider-codex` keys `auth.json`、`config.toml` |
|
||||
| Provider projection target | runner/backend 容器用户的 `~/.codex/auth.json`、`~/.codex/config.toml` |
|
||||
| Codex Provider Secret | `agentrun-v01-provider-codex` keys `auth.json`、`config.toml` |
|
||||
| DeepSeek Provider Secret | `agentrun-v01-provider-deepseek` keys `auth.json`、`config.toml` |
|
||||
| Provider projection target | 只读 `/var/run/agentrun/secrets/<profile>-<index>/auth.json`、`config.toml`，再复制到当前 run/profile 的 writable `CODEX_HOME` |
|
||||
| Provider config | 非敏感 base URL/model 可以来自 `config.toml` 或 ConfigMap；credential value 不得放入 ConfigMap。 |
|
||||
| Tekton Git SSH Secret | `agentrun-ci/agentrun-git-ssh` |
|
||||
| Argo Git SSH Secret | `argocd/agentrun-git-ssh` |
|
||||
@@ -36,24 +37,24 @@
|
||||
|
||||
## Codex 测试凭据注入
|
||||
|
||||
`v0.1` 综合联调使用的 Codex 测试凭据源固定为 operator 环境中的：
|
||||
`v0.1` 综合联调使用的 Codex stdio profile 测试凭据源固定为 operator 环境中的文件形态：
|
||||
|
||||
```text
|
||||
~/.codex/auth.json
|
||||
~/.codex/config.toml
|
||||
```
|
||||
|
||||
这两个文件只能作为 Kubernetes Secret 创建或轮换的输入源。禁止把宿主机 `~/.codex` 以 hostPath 挂入 runner/backend Pod，禁止复制进镜像，禁止提交到 source branch、GitOps branch、artifact catalog、issue、PR、event、trace、日志或 CLI 输出。
|
||||
这两个文件只能作为 Kubernetes Secret 创建或轮换的输入源。`codex` profile 默认使用 operator 当前 Codex 配置；`deepseek` profile 使用 operator 准备的 DeepSeek-compatible Codex 配置，可以来自另一个 `--codex-home` 或显式 `--auth-file`/`--config-file`。禁止把宿主机 `~/.codex` 以 hostPath 挂入 runner/backend Pod，禁止复制进镜像，禁止提交到 source branch、GitOps branch、artifact catalog、issue、PR、event、trace、日志或 CLI 输出。
|
||||
|
||||
默认 Secret projection 规则：
|
||||
|
||||
| 项目 | v0.1 规格 |
|
||||
| --- | --- |
|
||||
| Kubernetes Secret | `agentrun-v01/agentrun-v01-provider-codex` |
|
||||
| Kubernetes Secret | `agentrun-v01/agentrun-v01-provider-codex` 或 `agentrun-v01/agentrun-v01-provider-deepseek` |
|
||||
| Secret key | `auth.json`，来自 `~/.codex/auth.json` |
|
||||
| Secret key | `config.toml`，来自 `~/.codex/config.toml` |
|
||||
| Projection path | 只读 Secret projection 挂到 `/var/run/agentrun/secrets/<profile>-<index>/auth.json` 和 `config.toml`；该路径只作为 credential source。 |
|
||||
| Runtime config path | runner 启动时把授权的 Secret projection 复制到 writable `CODEX_HOME`，默认 `/home/agentrun/.codex/auth.json` 和 `config.toml`。 |
|
||||
| Runtime config path | runner 启动时把当前 `backendProfile` 授权的 Secret projection 复制到 writable `CODEX_HOME`，Kubernetes Job 默认可以使用该 Job 独占的 `/home/agentrun/.codex/auth.json` 和 `config.toml`；复用进程必须使用 run/profile 独占目录。 |
|
||||
| Projection mode | 只读，建议 `0400` 或等价最小权限 |
|
||||
| Runtime env | `HOME=/home/agentrun`，`CODEX_HOME=/home/agentrun/.codex`，`AGENTRUN_CODEX_SECRET_HOME=<projection path>`；不得 fallback 到节点宿主机 home。 |
|
||||
|
||||
@@ -74,6 +75,15 @@ Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例
|
||||
"keys": ["auth.json", "config.toml"],
|
||||
"mountPath": "~/.codex"
|
||||
}
|
||||
},
|
||||
{
|
||||
"profile": "deepseek",
|
||||
"secretRef": {
|
||||
"namespace": "agentrun-v01",
|
||||
"name": "agentrun-v01-provider-deepseek",
|
||||
"keys": ["auth.json", "config.toml"],
|
||||
"mountPath": "~/.codex"
|
||||
}
|
||||
}
|
||||
],
|
||||
"allowCredentialEcho": false
|
||||
@@ -86,6 +96,7 @@ Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例
|
||||
- `secretRef.namespace` 默认只能是 run 所在 lane namespace 或明确批准的 platform namespace。
|
||||
- manager 可以保存 `secretRef`，但不得读取 Secret 值后存库。
|
||||
- runner/backend adapter 获得 Secret 的方式必须来自 Kubernetes env/file projection 或受限 Secret API 读取；Codex 默认从只读 Secret projection 复制 `auth.json` 和 `config.toml` 到 writable `CODEX_HOME` 后启动 app-server，不得通过 run payload、event、CLI 参数或日志传递。
|
||||
- runner/backend adapter 只能选择与 run `backendProfile` 同名的 provider credential；`backendProfile=deepseek` 缺少 `deepseek` SecretRef 时必须 `secret-unavailable`，不得 fallback 到 `codex`。
|
||||
- Secret projection 不能直接作为 `CODEX_HOME`。Codex app-server 会读取并可能维护默认配置、PATH 或运行态文件；把只读 Secret volume 直接挂到 `CODEX_HOME` 会造成启动期写入失败。v0.1 的固定边界是：Secret volume 只读、`/home/agentrun` 由 `emptyDir` 提供可写 runtime home、复制动作只发生在 runner/backend 容器内且不打印文件内容。
|
||||
- SecretRef 不存在或 RBAC 不允许时，run 必须失败为结构化 `failureKind=secret-unavailable` 或等价错误，不得降级成无凭证重试风暴。
|
||||
|
||||
@@ -101,7 +112,7 @@ Tekton promotion
|
||||
Argo CD
|
||||
-> syncs workload references to agentrun-v01
|
||||
Kubernetes Secret
|
||||
-> created from ~/.codex/auth.json and ~/.codex/config.toml by operator or approved secret-management flow
|
||||
-> created from profile-specific auth.json and config.toml by operator or approved secret-management flow
|
||||
runner/backend Pod
|
||||
-> receives Codex auth/config via read-only file projection
|
||||
-> copies authorized files into writable CODEX_HOME before starting Codex app-server
|
||||
@@ -111,18 +122,19 @@ Secret 创建和轮换不由 source branch 自动生成；source branch 只声
|
||||
|
||||
## Codex Secret dry-run 工具
|
||||
|
||||
`v0.1` 提供只读 CLI 工具，用 operator 本地 `~/.codex/auth.json` 与 `~/.codex/config.toml` 构造 Kubernetes Secret 创建计划：
|
||||
`v0.1` 提供只读 CLI 工具，用 operator 本地 `~/.codex/auth.json` 与 `~/.codex/config.toml` 形态的文件构造 Kubernetes Secret 创建计划：
|
||||
|
||||
```bash
|
||||
./scripts/agentrun secrets codex render --dry-run
|
||||
./scripts/agentrun secrets codex render --dry-run [--profile codex|deepseek]
|
||||
```
|
||||
|
||||
可选参数：
|
||||
|
||||
- `--codex-home <dir>`：覆盖默认 `~/.codex` 输入目录。
|
||||
- `--profile <name>`：默认 `codex`；`deepseek` 使用同一文件形态但默认 Secret name 为 `agentrun-v01-provider-deepseek`。
|
||||
- `--auth-file <path>` / `--config-file <path>`：分别覆盖输入文件路径。
|
||||
- `--namespace <name>`：默认 `agentrun-v01`。
|
||||
- `--secret-name <name>`：默认 `agentrun-v01-provider-codex`。
|
||||
- `--secret-name <name>`：默认随 profile 变化，`codex` 为 `agentrun-v01-provider-codex`，`deepseek` 为 `agentrun-v01-provider-deepseek`。
|
||||
|
||||
输出必须是 JSON，并且只包含 `namespace`、`secretName`、`keys`、每个输入文件的 `bytes`、`sha256`/`contentHash`、整体 hash、redaction 状态、apply 命令形状和 Secret manifest 摘要。输出不得包含 Secret value、`auth.json` 明文、`config.toml` 明文、base64 `data` 字段或可直接恢复 credential 的内容。工具只支持 `--dry-run`；不得执行 `kubectl apply`。
|
||||
|
||||
@@ -143,7 +155,7 @@ Secret 创建和轮换不由 source branch 自动生成；source branch 只声
|
||||
|
||||
### T2 Runner credential projection
|
||||
|
||||
阅读本文，然后启动一个最小 backend runner dry-run，确认 Pod file projection 挂在 `/var/run/agentrun/secrets/...` 且只读，`/home/agentrun` 是 writable runtime home，`CODEX_HOME=/home/agentrun/.codex`，runner/backend 会把授权文件复制到 `CODEX_HOME` 后再启动 Codex；event、日志和 CLI 输出只显示 redacted credential source，不显示文件内容。
|
||||
阅读本文，然后分别启动 `backendProfile=codex` 与 `backendProfile=deepseek` 的最小 backend runner dry-run，确认 Pod file projection 挂在 `/var/run/agentrun/secrets/...` 且只读，`/home/agentrun` 是 writable runtime home，runner/backend 只把当前 profile 授权文件复制到 `CODEX_HOME` 后再启动 Codex；event、日志和 CLI 输出只显示 redacted credential source，不显示文件内容。
|
||||
|
||||
### T3 Missing secret failure
|
||||
|
||||
@@ -157,5 +169,6 @@ Secret 创建和轮换不由 source branch 自动生成；source branch 只声
|
||||
| Kubernetes SecretRef 注入 | 已实现/已通过主闭环 | runner Job dry-run 和正式 Job 创建路径已按 run `executionPolicy.secretScope.providerCredentials` 生成 Secret volume projection、writable runtime home 和 `AGENTRUN_CODEX_SECRET_HOME`；真实 Secret 与 Codex turn 已通过主闭环。 |
|
||||
| Codex Secret dry-run 工具 | 已实现 | `./scripts/agentrun secrets codex render --dry-run` 只输出 Secret 创建计划、hash 和 redacted manifest 摘要，不执行 apply。 |
|
||||
| Codex auth/config file projection | 已实现主路径 | backend readiness 检查 `auth.json`/`config.toml` 可读性，缺失时返回 `secret-unavailable`；真实 runner Job 将只读 projection 复制到 writable `CODEX_HOME`。 |
|
||||
| DeepSeek profile SecretRef | 已定义/待实现 | 需要新增 `agentrun-v01-provider-deepseek` render、Job projection、profile 选择和负向 missing-secret 验收。 |
|
||||
| redaction 最小规则 | 已实现主路径 | Secret dry-run 工具、event、Job dry-run 输出、self-test 和真实主闭环均不打印 Secret value；复杂审计按 [spec-v01-validation.md](spec-v01-validation.md) 人工抽查。 |
|
||||
| 外部 secret manager | 未采用 | 如需 Vault/ExternalSecrets/SOPS，后续单独更新规格。 |
|
||||
|
||||
Reference in New Issue
Block a user