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 只能包含引用，不包含值。示例形态：

{
  "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 默认路径：

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，然后检查 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，后续单独更新规格。

5.7 KiB Raw Blame History Unescape Escape