ayatori/docs/api/job-v1alpha1.md

# Job API v1alpha1 草案

- 状态：Draft
- 日期：2026-09-17
- API group：`execution.ayatori.ddupan.top`
- Kind：`Job`
- Scope：Namespaced

## 目标

`Job` 表达一次有限时长、有明确退出结果的机器执行。调用者描述任务载荷和资源需求，平台
选择 execution backend 并持续观察，直到任务成功、失败或取消。

首个 adapter 使用 Kubernetes `batch/v1 Job`，第二个 adapter 使用 OpenSandbox lifecycle
与 execd API。API 不暴露 PodSpec、sandbox ID 创建参数或具体 adapter 配置，但允许表达两个
真实后端共有的 OCI image、进程、环境变量和资源语义。

`Job` 是短生命周期控制对象。完成后依据 `ttlSecondsAfterFinished` 回收，长期业务状态由调用
者保存，日志由 observability 平台保存。详细保留策略见 ADR-0005。

## 非目标

v1alpha1 不提供：

- DAG、workflow 或多步骤 task；
- 定时执行与可复用 Job template；
- 并行 completions、indexed job 或 gang scheduling；
- 自动业务重试；
- 暂停后恢复；
- 交互式 shell、endpoint、snapshot 或长生命周期 sandbox；
- workspace、cache、artifact 上传协议或结构化 task outputs；
- 永久 Job history。

上述能力应由后续独立资源或经过真实需求验证的兼容字段提供，不能通过透传 PodSpec 或
OpenSandbox extensions 提前进入 API。

## 示例

```yaml
apiVersion: execution.ayatori.ddupan.top/v1alpha1
kind: Job
metadata:
  generateName: hello-
  namespace: ci
spec:
  jobClassName: default
  task:
    image: docker.io/library/alpine:3.22
    imagePullSecrets: []
    command: ["/bin/sh", "-c"]
    args:
      - echo "hello ${TARGET}"
    workingDir: /workspace
    env:
      - name: TARGET
        value: world
      - name: TOKEN
        valueFrom:
          secretKeyRef:
            name: example-token
            key: token
      - name: CONFIG_VALUE
        valueFrom:
          configMapKeyRef:
            name: example-config
            key: value
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: "1"
      memory: 512Mi
  activeDeadlineSeconds: 600
  ttlSecondsAfterFinished: 3600
  desiredState: Running
```

## Spec

```yaml
spec:
  jobClassName: string
  task: TaskSpec
  resources: ResourceRequirements
  activeDeadlineSeconds: int64
  ttlSecondsAfterFinished: int32
  desiredState: Running | Cancelled
```

### `jobClassName`

可选。引用平台管理员维护的 cluster-scoped `JobClass`。调用者选择服务等级或执行
能力，而不是直接选择 adapter driver。省略时由 namespace policy 解析默认 class；不存在
默认值时 Job 保持未接受状态，不得静默选择任意后端。

一旦 Job 被接受，该字段不可变。解析出的实际 class 写入 status，以便默认策略后来变化时仍
能恢复原执行。

`JobClass` 及其强类型 parameters API 定义后端配置和调度策略。Job API 不暴露
Kubernetes namespace、OpenSandbox endpoint、API key 或 backend raw configuration。

### `task`

必填，创建后不可变。

```yaml
task:
  image: string
  imagePullSecrets: []LocalObjectReference
  command: []string
  args: []string
  workingDir: string
  env: []EnvVar
```

- `image`：必填 OCI image reference。首版允许 tag；生产策略可以通过 admission 要求 digest。
- `imagePullSecrets`：可选，同 namespace 的私有 registry 凭据引用。
- `command`：可选，覆盖 image entrypoint；空值表示使用 image 默认值。
- `args`：可选，传给 entrypoint/command。
- `workingDir`：可选；为空时使用 image/backend 默认值。
- `env`：可选，名称必须唯一。

`command` 和 `args` 使用 argv 语义，不隐式经过 shell。需要 shell 展开时，调用者必须显式
指定 `/bin/sh -c` 等命令。

#### 环境变量

```yaml
- name: EXAMPLE
  value: literal

- name: TOKEN
  valueFrom:
    secretKeyRef:
      name: example
      key: token
      optional: false
```

`value` 与 `valueFrom` 必须且只能设置一个。v1alpha1 支持同 namespace 的 `SecretKeyRef` 和
`ConfigMapKeyRef`，两者具有相同的引用、optional 和等待语义。Adapter 负责以适合后端且不
写入 Job status 的方式传递值。引用对象或 key 缺失时 Job 保持未开始并通过 Condition 报告。
Secret 内容不得复制到 Event、日志或 backend reference；ConfigMap 值虽然不视为机密，也不
写入 status，避免状态膨胀和不同后端行为不一致。

Kubernetes adapter 保留原生 `SecretKeyRef`/`ConfigMapKeyRef`，由 kubelet 在执行节点解析，
controller 不读取内容。OpenSandbox create API 只接收已经解析的环境变量值，因此该 adapter
必须读取引用并把值放入 sandbox create request。JobClass 必须明确允许 Secret 的这种
传递路径，且 controller 的日志、Event 和 status 不得记录请求正文。未来需要避免把真实凭据
暴露给 sandbox 进程时，使用 OpenSandbox Credential Vault 或 Ayatori 独立 Credential 能力，
而不是改变 `SecretKeyRef` 的既有语义。

私有镜像凭据采用 Kubernetes `kubernetes.io/dockerconfigjson` Secret。Kubernetes adapter
直接传递引用；OpenSandbox adapter 选择与目标 image registry 匹配的条目，并映射到其
`image.auth` create 参数。无法解析、没有匹配 registry 或所选 OpenSandbox runtime 不支持
per-request image auth 时，Job 以明确 reason 失败，不得退回匿名拉取后隐藏真实原因。

### `resources`

可选，使用 Kubernetes `resource.Quantity` 表示数值，但不复用完整 Pod
`ResourceRequirements` 行为。

v1alpha1 支持 `cpu` 和 `memory` 的 requests/limits。Requests 表达准入与调度需求，limits
表达执行上限。JobClass 可以提供默认值和允许范围；解析后的实际资源写入 status。

Adapter 必须显式验证能否满足请求，不能无提示地忽略 limit。后端无法区分 request 与 limit
时，其映射规则属于 JobClass，并在 Job 接受前确定。对 OpenSandbox，CPU 和内存
limits 直接映射为 sandbox VM/container 的 `resourceLimits`；requests 用于 Ayatori 的准入与
调度，并可由 JobClass 映射到后端 resource request 或 capacity profile。映射失败必须
显式拒绝或失败，不能静默降低资源保证。

### `activeDeadlineSeconds`

可选，必须大于零。表示从实际执行开始到任务必须终止的最长时间，不包含排队、class 解析或
后端 provisioning 时间。到期后 controller 请求终止后端，最终以 `Succeeded=False`、
`reason=DeadlineExceeded` 结束。

后端自身的 timeout 可以作为执行机制，但 Ayatori controller 仍以 `status.startTime` 和观察
结果维护领域语义。调度等待超时是不同概念，v1alpha1 不提供。

### `ttlSecondsAfterFinished`

可选，必须大于或等于零。语义与 Kubernetes Job 一致：从终态 transition time 起计算，零
表示立即具备删除资格。该字段在任务完成前后均可修改，但不能保证在既有 TTL 已过期后通过
延长 TTL 阻止并发删除。

平台应通过 schema、CEL 或 policy 设置最大值和推荐默认值。controller 本身不偷偷填充一个
无法从 spec 观察到的永久策略。

### `desiredState`

可选，默认 `Running`。允许的状态迁移只有：

```text
Running → Cancelled
```

设置 `Cancelled` 表示请求终止当前执行并保留 Job 至 TTL 到期。取消是尽力而为的异步操作；
只有 adapter 确认执行不会继续后，Job 才进入终态。字段不得从 `Cancelled` 改回 `Running`。
重新执行必须创建新的 Job。

v1alpha1 不提供 suspend/resume。对任意后端可靠实现 checkpoint/resume 并非共同能力，且暂停
不应被伪装为取消。

## 不可变性

创建后仅允许修改：

- `spec.desiredState`，且只能单向变为 `Cancelled`；
- `spec.ttlSecondsAfterFinished`。

`task`、`resources`、`activeDeadlineSeconds` 和 `jobClassName` 均不可变。首选 CRD CEL
validation 表达这些约束；只有 schema/CEL 无法正确表达时才引入 admission webhook。

Controller reconcile 的技术重试不表示任务重跑。v1alpha1 每个 Job 最多启动一个逻辑执行；
adapter 必须使用 Job UID 作为幂等键。若请求结果未知，controller 必须先 Observe，不能因为
网络超时重新创建可能已经开始的执行。

首个 Kubernetes adapter 创建 `backoffLimit: 0`、`restartPolicy: Never` 的原生 Job，避免继承
Kubernetes 默认的多次业务执行语义。需要重新执行时创建新的 Ayatori Job。

## Status

```yaml
status:
  observedGeneration: 1
  conditions:
    - type: Accepted
      status: "True"
      reason: Valid
      observedGeneration: 1
      lastTransitionTime: ...
    - type: Scheduled
      status: "True"
      reason: BackendCreated
      observedGeneration: 1
      lastTransitionTime: ...
    - type: Succeeded
      status: "Unknown"
      reason: Running
      observedGeneration: 1
      lastTransitionTime: ...
  resolvedJobClass:
    name: default
    uid: 8aa4...
    controllerName: execution.ayatori.ddupan.top/kubernetes
    parametersRef:
      group: execution.ayatori.ddupan.top
      kind: KubernetesExecutionParameters
      name: default
      uid: c413...
  effectiveResources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: "1"
      memory: 512Mi
  execution:
    adapter: kubernetes
    references:
      - type: Job
        id: 5cb0...
  startTime: ...
  completionTime: ...
  result:
    exitCode: 0
    reason: Completed
```

### Conditions

使用标准 `metav1.Condition`。v1alpha1 定义三个核心 Condition：

- `Accepted`：spec、引用、policy 和 JobClass 已解析，可进入调度；
- `Scheduled`：后端已确定并存在可观察的逻辑执行；
- `Succeeded`：任务结果。`Unknown` 表示尚未结束，`True` 表示成功，`False` 表示已经失败或
  取消。

失败不使用单独的 `Failed` Condition。`Succeeded=True` 与 `Failed=True` 会形成需要额外维护的
互斥状态，而标准三态 Condition 已能完整表达一次执行：运行中为 `Unknown`、成功为 `True`、
失败为 `False`。失败类型由稳定 reason 区分；这与 Tekton `TaskRun` 的状态约定一致。

不增加与 Conditions 重复的 `phase` 字段。面向 CLI 的阶段摘要由 printer columns 或客户端从
Conditions 推导，避免两个状态源发生漂移。

常用 `Succeeded` reason 初始包括：

- `Pending`、`Scheduling`、`Running`；
- `Completed`；
- `ProcessFailed`；
- `DeadlineExceeded`；
- `Cancelled`；
- `BackendLost`；
- `ResultUnknown`。

Reason 是稳定、机器可读的 PascalCase 标识；message 面向人类且不得承载程序逻辑。

## 状态机

状态机名称用于设计、测试和 metrics，不增加持久化 `status.phase`。当前状态必须能够从 spec、
deletionTimestamp、Conditions、时间和 execution references 唯一推导。

### 状态定义

| 状态 | 判定摘要 | 含义 |
|---|---|---|
| `Resolving` | `Accepted!=True`，非终态 | 等待 JobClass、Secret、ConfigMap 或 policy 解析 |
| `Scheduling` | `Accepted=True`、`Scheduled!=True` | 选择 adapter 并幂等创建后端执行 |
| `Starting` | `Scheduled=True`、无 `startTime` | 后端已存在，任务主体尚未确认开始 |
| `Running` | 有 `startTime`、`Succeeded=Unknown` | 任务主体正在执行 |
| `Cancelling` | `desiredState=Cancelled`、非终态 | 正在确认后端已经停止 |
| `ResultUnknown` | `Succeeded=Unknown/ResultUnknown` | 无法证明任务仍在运行或已经停止 |
| `Succeeded` | `Succeeded=True` | 成功终态 |
| `Failed` | `Succeeded=False`，reason 非 `Cancelled` | 失败终态 |
| `Cancelled` | `Succeeded=False/Cancelled` | 取消终态 |
| `Deleting` | 存在 `deletionTimestamp` | finalizer 正在停止并清理后端，覆盖其他状态 |

存在多个判定条件时按 `Deleting → terminal → Cancelling → ResultUnknown → Running → Starting →
Scheduling → Resolving` 的优先级推导，保证状态唯一。

`ResultUnknown` 不是终态，不设置 `completionTime`，也不启动 TTL。只有确认任务已经停止，才能
转为成功、失败或取消。暂时无法联系后端不等于后端执行失败。

### 正常转移

```text
Resolving
    │ 引用与策略解析完成
    ▼
Scheduling
    │ 后端逻辑执行已建立并持久化引用
    ▼
Starting
    │ adapter 确认任务主体开始
    ▼
Running ───────────────→ Succeeded
    └──────────────────→ Failed
```

后端在任务主体开始前就确定失败，例如 image pull、runtime 不兼容或 provisioning 失败，可以从
`Scheduling` 或 `Starting` 直接进入 `Failed`，此时 `startTime` 允许为空。

### 取消转移

```text
Resolving  ─┐
Scheduling ─┤
Starting   ─┼→ Cancelling → Cancelled
Running    ─┤
ResultUnknown ─┘
```

尚未创建后端执行时，取消可以立即确认。已经存在或可能存在后端执行时，必须反复执行
Cancel/Observe，确认不会继续运行后才能进入 `Cancelled`。取消请求与成功完成并发时，以先从
后端确认到的不可逆事实为准：已经成功完成的任务保持 `Succeeded`，不能改写成 `Cancelled`。

### 不确定结果与恢复

```text
Ensure/Observe 返回歧义
          ↓
    ResultUnknown
      ├── 找回执行 → Starting / Running
      ├── 找到终态 → Succeeded / Failed / Cancelled
      └── 管理员确认无法继续 → Failed(BackendLost)
```

在 `Ensure` 请求超时且尚未成功写入 external reference 时，adapter 必须使用 Job UID 查询后端，
不能直接再次创建。Controller 重启后遵循相同规则。

### 删除与 TTL 转移

任意状态收到 deletionTimestamp 后进入 `Deleting`。若执行可能存在，先 Cancel/Observe，再
Delete 后端资源并移除 finalizer。TTL controller 只对具有 `completionTime` 的三个终态发起
删除；`Resolving`、`Scheduling`、`Starting`、`Running`、`Cancelling` 和 `ResultUnknown` 均不
具备 TTL 删除资格。

### 状态不变量

- `Succeeded=True/False` 是不可逆终态；终态 reason、`completionTime` 和 result 不再改变。
- `startTime` 和 `completionTime` 一旦设置不可改变；两者都存在时 completionTime 不早于
  startTime。
- `Succeeded=True` 必须具有 `completionTime`，可以没有 exit code，但 adapter 应说明原因。
- `Succeeded=False` 必须具有 `completionTime`；进程失败且能取得退出码时必须保存 exit code。
- 非终态的 `Succeeded` 必须为 `Unknown`，不得省略为具有歧义的空状态。
- `Scheduled=True` 前不得设置 `startTime`；一旦为 True 不再回退。
- execution references 只能由 controller 写入；已有引用不能静默替换成新的逻辑执行。
- Job UID 是执行幂等键；同名但不同 UID 的 Job 必须被视为不同执行。
- `desiredState=Cancelled` 后不得创建新的后端执行。
- reconcile 错误和退避不得修改任务的业务结果。

### 状态机测试矩阵

实现必须至少覆盖以下 table-driven unit tests，并为关键恢复路径提供 envtest：

| 类别 | 场景 | 必要断言 |
|---|---|---|
| 正常 | 创建、开始、退出 0 | 单次 Ensure，时间与成功终态正确 |
| 正常 | 主进程非零退出 | `Succeeded=False/ProcessFailed` 与 exit code |
| 解析 | JobClass 后创建 | 不提前 Ensure，引用出现后继续 |
| 解析 | Secret/ConfigMap 或 key 后创建 | 不泄露值，解析后只启动一次 |
| 后端 | image pull 或 provisioning 失败 | 未设置 startTime 的失败终态合法 |
| 幂等 | Ensure 成功但 status 写入前崩溃 | 通过 UID 找回，不能创建第二次执行 |
| 幂等 | 重复 reconcile 与重复事件 | 不产生额外执行，不改变终态时间 |
| 恢复 | controller 在各非终态重启 | 从持久 status/reference 恢复正确状态 |
| 未知 | Ensure/Observe 超时且结果不明 | 保持非终态，不设 completionTime，不触发 TTL |
| 未知 | 后端恢复后找回运行任务 | 从 ResultUnknown 返回 Running |
| 未知 | 管理员确认执行丢失 | 只在确认后进入 `Failed/BackendLost` |
| 取消 | 在解析、调度、启动、运行阶段取消 | 不再创建或确认停止后才进入 Cancelled |
| 竞态 | 取消与成功完成并发 | 已确认成功不被取消覆盖 |
| 超时 | active deadline 到期 | 请求取消，确认停止后 `DeadlineExceeded` |
| 删除 | 每个非终态阶段删除 | finalizer 清理完成前对象不消失 |
| 删除 | 后端暂时不可达 | finalizer 保留并重试，不误报已清理 |
| TTL | 三种终态到期 | 到期前不删，到期后带 UID precondition 删除 |
| TTL | controller 在等待 TTL 时重启 | informer 恢复计时，最终删除一次 |
| TTL | 到期附近延长 TTL | 最终 GET 重新核对最新 TTL |
| 隔离 | 同名 Job 删除并以新 UID 重建 | 旧队列项和旧后端不得影响新 Job |
| 校验 | 修改不可变字段或取消后恢复 Running | schema/CEL 拒绝请求 |
| 引用 | OpenSandbox 保存 Sandbox 与 Command 引用 | 顺序重试后引用稳定且无凭据 |

### 时间

- `startTime`：adapter 确认任务主体开始执行的时间，而不是 CR 创建或 backend provisioning
  时间；设置后不可改变。
- `completionTime`：进入最终成功、失败或取消状态的时间；设置后不可改变。

TTL 以 `completionTime` 为基准。若后端已经完成但结果暂时无法确认，不得猜测 completionTime。

### Execution reference

`status.execution` 是 execution 领域定义的正式 API 字段，保存 controller 重启后重新 Observe
所需的最小稳定引用：

- `adapter`：实际 adapter 类型；
- `references`：一个或多个由 adapter 定义的不透明外部引用。

```yaml
execution:
  adapter: opensandbox
  references:
    - type: Sandbox
      id: sandbox-123
    - type: Command
      id: command-456
```

单个 `externalID` 不足以表达 OpenSandbox 的 sandbox 与 command 两级资源。`type` 和 `id` 的
值由对应 adapter 定义，调用者只能用于诊断和关联，不能据此实现领域逻辑。execution 领域将
每个引用限制为 `type` 与 `id` 两个非空、有长度上限的字符串，不提供任意 metadata map 或
raw JSON。引用不包含 endpoint、凭据或 Secret 内容。Kubernetes adapter 可以另外通过 owner
reference 管理原生 Job，但仍需把恢复所需引用持久化，并保证同名重建安全。

该结构不提升为跨领域共享的万能 ExternalReference。VM、数据库和 LB 等领域根据真实后端
需要定义自己的受限引用 schema，只有多个领域出现语义完全一致的实际重复后才考虑共享。

### Result

`result.exitCode` 只在后端能够确定主进程退出码时设置。调度失败、取消、后端丢失等情况可以
没有退出码。`result.reason` 提供简短分类；详细诊断写入 Condition message 和 observability，
不得把完整日志写入 status。

Job UID 是跨后端日志、metrics 和 traces 的主要 correlation identity。Adapter 必须将
namespace、name 和 UID 传入执行环境或后端 metadata；高基数字段如何索引由 observability
平台决定，API 不要求把 UID 配置为日志 label。

## 删除与 finalizer

Execution controller 在可能创建外部执行前添加
`execution.ayatori.ddupan.top/job-cleanup` finalizer。

删除一个活动 Job 表示取消并清理，而不是 orphan：

1. 请求 adapter 终止执行；
2. Observe，确认执行不会继续；
3. 删除后端临时资源与短期凭据；
4. 移除 finalizer。

首版不提供用户可选 orphan policy。让一次性任务脱离控制面继续运行既难以观察，也可能产生
副作用。后端长期不可达时由管理员根据 runbook 判断并强制移除 finalizer，该操作必须可审计。

TTL controller 只发起 Job 删除，所有手工删除和 TTL 删除都经过相同 finalizer 路径。

## Adapter contract 对 API 的保证

每个 execution adapter 必须提供以下语义，而非暴露自身 SDK 类型：

```text
Ensure   幂等地建立以 Job UID 标识的一个逻辑执行
Observe  返回尚未开始、运行、成功、失败、取消或结果未知
Cancel   请求停止且可被重复调用
Delete   清理后端临时资源且可被重复调用
```

`Ensure` 的网络超时不能直接触发第二次执行。Adapter 必须能够通过 UID/metadata 查找已创建的
后端对象，或返回 `ResultUnknown` 交由人工处理。

Kubernetes adapter 与 OpenSandbox adapter 实现后，应复审 contract 和 API。只有两个真实
实现都需要且语义相同的字段才提升为通用能力；后端特有功能优先进入 JobClass 或独立
资源，不增加 `rawConfig`。

OpenSandbox 支持从 OCI image 创建 sandbox，但不保证每个 image 都能在所选 runtime、架构或
安全 profile 下成功启动。Adapter 对已知不支持的组合应尽早报告；image pull、进程启动或
运行时不兼容等实际后端失败最终统一表现为 `Succeeded=False`，并以 reason/message 保留可
诊断原因。这不要求 Ayatori 在提交前证明任意 OCI image 一定可运行。

## 待后续设计

- capability-based class 自动选择；
- 私有 image registry 的凭据和统一 workload identity；
- artifact、workspace 与 cache 的独立 API；
- Job 创建速率、并发、quota、公平调度以及是否集成 Kueue；
- observability correlation 的具体 OpenTelemetry/Loki 字段约定；
- 调用者错过 TTL 时是否需要可选的最小审计记录。

这些问题不阻塞首个 Kubernetes adapter 的 API review；image pull 的最小凭据路径必须在实现
前通过 Kubernetes 与 OpenSandbox adapter 测试验证。

## 成熟实现参考

- [Kubernetes Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/)
- [Kubernetes Job API](https://kubernetes.io/docs/reference/kubernetes-api/batch/job-v1/)
- [Tekton Pipeline API](https://tekton.dev/docs/pipelines/pipeline-api/)
- [Kueue Workload](https://kueue.sigs.k8s.io/docs/concepts/workload/)
- [OpenSandbox API specifications](https://github.com/opensandbox-group/OpenSandbox/blob/main/docs/api/index.md)