# JobClass API v1alpha1 草案

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

## 目标

`JobClass` 是平台管理员提供给 Job 调用者的执行服务等级。名称表达稳定的用户语义，
例如 `default`、`rootless`、`microvm` 或 `trusted-infra`；调用者不需要知道它当前由 Kubernetes
还是 OpenSandbox 实现。

JobClass 负责：

- 选择拥有该 class 的 adapter/controller；
- 引用 adapter 自己的强类型参数对象；
- 限制允许使用该 class 的 namespace；
- 提供跨后端一致的资源默认值与范围；
- 向 Job controller 报告配置是否被接受、后端是否可用。

它不负责保存队列状态、并发配额、Job history 或任意后端 raw config。

## 设计依据

- Kubernetes `RuntimeClass` 使用 cluster-scoped class 将调用者与具体 runtime handler、调度约束
  和 overhead 隔离。
- `StorageClass` 允许管理员用稳定名称提供不同服务等级，并由调用者显式或默认选择。
- Gateway API `GatewayClass` 使用 `controllerName + parametersRef` 将稳定 class API 与实现专用
  参数分离，并通过 `Accepted` Condition 报告配置有效性。
- Kueue `ResourceFlavor` 将资源规格与具体节点标签、taint 等 placement 细节分开。

Ayatori 采用 GatewayClass 风格的参数引用，不在 JobClass 中建立随 adapter 数量膨胀的
union，也不使用 `map[string]any`。

## 示例

### Kubernetes execution

```yaml
apiVersion: execution.ayatori.ddupan.top/v1alpha1
kind: JobClass
metadata:
  name: rootless
  annotations:
    execution.ayatori.ddupan.top/is-default-job-class: "true"
spec:
  controllerName: execution.ayatori.ddupan.top/kubernetes
  parametersRef:
    group: execution.ayatori.ddupan.top
    kind: KubernetesExecutionParameters
    name: rootless
  allowedNamespaces:
    matchLabels:
      ayatori.ddupan.top/execution: enabled
  resources:
    defaults:
      requests:
        cpu: 250m
        memory: 256Mi
      limits:
        cpu: "2"
        memory: 2Gi
    maximum:
      limits:
        cpu: "8"
        memory: 16Gi
---
apiVersion: execution.ayatori.ddupan.top/v1alpha1
kind: KubernetesExecutionParameters
metadata:
  name: rootless
spec:
  serviceAccountName: ayatori-job
  runtimeClassName: runc
  scheduling:
    nodeSelector:
      ayatori.ddupan.top/node-role: execution
    tolerations:
      - key: ayatori.ddupan.top/execution
        operator: Equal
        value: "true"
        effect: NoSchedule
  podSecurityContext:
    runAsNonRoot: true
    seccompProfile:
      type: RuntimeDefault
```

### OpenSandbox execution

```yaml
apiVersion: execution.ayatori.ddupan.top/v1alpha1
kind: JobClass
metadata:
  name: microvm
spec:
  controllerName: execution.ayatori.ddupan.top/opensandbox
  parametersRef:
    group: execution.ayatori.ddupan.top
    kind: OpenSandboxExecutionParameters
    name: microvm
  allowedNamespaces:
    matchLabels:
      ayatori.ddupan.top/microvm-access: "true"
  resources:
    defaults:
      requests:
        cpu: "1"
        memory: 1Gi
      limits:
        cpu: "2"
        memory: 2Gi
    maximum:
      limits:
        cpu: "8"
        memory: 16Gi
---
apiVersion: execution.ayatori.ddupan.top/v1alpha1
kind: OpenSandboxExecutionParameters
metadata:
  name: microvm
spec:
  endpoint: https://opensandbox-api.example.internal
  apiKeySecretRef:
    namespace: ayatori-system
    name: opensandbox-api
    key: api-key
  poolRef: microvm
  requestMapping: AdmissionOnly
  allowSecretEnv: true
  allowImageAuth: true
```

## JobClass spec

```yaml
spec:
  controllerName: string
  parametersRef: ParametersReference
  allowedNamespaces: LabelSelector
  resources: ExecutionResourcePolicy
```

### `controllerName`

必填、创建后不可变。使用 domain-prefixed path 标识负责处理该 class 和 Job 的 controller，例如：

```text
execution.ayatori.ddupan.top/kubernetes
execution.ayatori.ddupan.top/opensandbox
```

它是 controller 所有权标识，不是任意可执行插件名称。一个 controller 只能处理自己明确支持
的名称。未来 adapter 拆成独立 Deployment 时，class 和 Job API 无需改变。

### `parametersRef`

必填、创建后不可变：

```yaml
parametersRef:
  group: execution.ayatori.ddupan.top
  kind: KubernetesExecutionParameters
  name: rootless
```

v1alpha1 只允许引用 cluster-scoped 参数对象，并限制 `group`、`kind`、`name` 的长度与格式。
每个 controller 明确列出支持的 kind；引用 ConfigMap、Secret 或未知 CRD 不被接受。

参数引用只有一层，参数 CRD 可以进一步引用 Secret 等运行配置。禁止嵌套通用参数链和 raw
JSON，避免 class 成为无法校验的配置转发器。

### `allowedNamespaces`

可选 Kubernetes `LabelSelector`。Job 所在 namespace 必须匹配才可使用该 class。省略表示允许
所有 namespace；这是显式的管理员选择，而不是用户能力。

该检查由 Job controller 执行，并应尽可能增加 CEL/admission policy 作为快速反馈。用户即使
知道 privileged class 名称，也不能仅靠设置 `jobClassName` 绕过授权。

Namespace label 在 Job 被接受后发生变化，不中断已经运行的 Job，但影响新的 Job。紧急终止
使用独立管理员操作，不通过修改 selector 隐式杀死任务。

### `resources`

可选，定义后端无关的 CPU、内存策略：

```yaml
resources:
  defaults:
    requests: {cpu, memory}
    limits: {cpu, memory}
  minimum:
    requests: {cpu, memory}
    limits: {cpu, memory}
  maximum:
    requests: {cpu, memory}
    limits: {cpu, memory}
```

规则为：

1. Job 未设置的值由 defaults 补齐；
2. 解析结果必须满足 minimum/maximum；
3. CPU 与内存 request 不得大于对应 limit；
4. 解析后的 effective resources 写入 Job status；
5. 后续修改 class 不改变已经接受的 Job；
6. adapter 不能静默降低 effective resources。

只支持 CPU 和内存。GPU、临时磁盘等资源在出现真实后端需求后增加，不先复制完整 Kubernetes
ResourceList。

Runtime/VM overhead 是 adapter 参数或后端调度实现，不计入用户请求的 task resources。
Kubernetes adapter 应优先利用 RuntimeClass Pod overhead；OpenSandbox adapter 在其 capacity
profile 中计算 microVM overhead。

## 默认 class 选择

Job 显式设置 `spec.jobClassName` 时始终优先使用该值。省略时按以下顺序解析：

1. Job namespace annotation
   `execution.ayatori.ddupan.top/default-job-class`；
2. 唯一带有
   `execution.ayatori.ddupan.top/is-default-job-class: "true"` annotation 的 JobClass。

若不存在默认 class，Job 保持 `Accepted=False/NoDefaultJobClass`。若存在多个全局默认值，
Job 保持 `Accepted=False/AmbiguousDefaultJobClass`，同时产生平台告警；不得模仿
StorageClass 选择最新创建对象，因为执行隔离与权限不应随创建时间变化。

解析后 Job status 保存：

```yaml
resolvedJobClass:
  name: rootless
  uid: 8aa4...
  controllerName: execution.ayatori.ddupan.top/kubernetes
  parametersRef:
    group: execution.ayatori.ddupan.top
    kind: KubernetesExecutionParameters
    name: rootless
    uid: c413...
```

Job 后续 reconcile 使用已解析引用，不能因 namespace 默认值或全局默认 class 改变而切换
adapter。若同名 class 被删除并重建，UID 不匹配，现存 Job 不得自动采用新对象。

## Status

```yaml
status:
  observedGeneration: 1
  conditions:
    - type: Accepted
      status: "True"
      reason: Accepted
      observedGeneration: 1
      lastTransitionTime: ...
    - type: Ready
      status: "True"
      reason: BackendReachable
      observedGeneration: 1
      lastTransitionTime: ...
```

### `Accepted`

表示 controller 已识别 controllerName，parametersRef 指向受支持且 schema 有效的对象，通用
resource policy 自洽。无效 class 使用 `Accepted=False` 和稳定 reason，例如：

- `UnsupportedController`；
- `InvalidParametersReference`；
- `ParametersNotFound`；
- `InvalidResourcePolicy`。

### `Ready`

表示该 class 当前具备接受新执行的基本条件。Kubernetes adapter 检查 RuntimeClass 等集群级
依赖；具体 namespace 中的 ServiceAccount 在 Job 调度时检查。OpenSandbox adapter 检查参数
引用、认证材料和后端健康端点。

`Ready=False` 阻止创建新的后端执行，但不改变已经开始 Job 的终态。Controller 仍必须尝试
Observe、Cancel 和 Delete 已存在执行，不能因 class 不 Ready 而停止清理。

Ready 是观测值，不是容量预留。容量不足、排队和并发配额属于调度系统，不通过 Ready 频繁
抖动。

## 生命周期与修改

- `controllerName` 和 `parametersRef` 不可变；切换后端必须创建新 class 名称。
- `allowedNamespaces` 与 resource policy 可以修改，只影响尚未接受的新 Job。
- adapter 参数对象允许更新 endpoint、Secret 引用和其他运维配置，以支持凭据轮换与故障切换。
- 参数更新不得使 adapter 为现存 Job 创建新的逻辑执行；Job 中已持久化的 execution reference
  始终优先。

JobClass controller 添加保护 finalizer。删除 class 前必须确认不存在引用其 UID 的非终态
Job。终态 Job 已完成后端清理，不阻塞 class 删除；其 TTL 回收不再需要 class 后端配置。

参数对象删除保护由各 adapter controller 负责。在仍有 class 引用时，参数对象不得被无提示
删除。强制移除 finalizer 是管理员恢复操作，必须有 runbook 和审计记录。

## KubernetesExecutionParameters

这是 Kubernetes adapter 自己拥有的 cluster-scoped 管理员 API，不是 Job 用户 API。首版字段：

```yaml
spec:
  serviceAccountName: string
  runtimeClassName: string
  scheduling:
    nodeSelector: map[string]string
    tolerations: []Toleration
  podSecurityContext: PodSecurityContext
  imagePullPolicy: Always | IfNotPresent | Never
```

首版原生 `batch/v1 Job` 与 Ayatori Job 位于同一 namespace，因此 Secret/ConfigMap、ResourceQuota、
NetworkPolicy、日志和 owner reference 都保持原生语义。普通调用者只拥有 Ayatori Job 权限，
不应拥有修改生成的 batch Job/Pod 的权限。

`serviceAccountName` 是每个允许 namespace 中预先提供的同名 ServiceAccount。缺失时 Job 保持
未调度并报告原因，不回退到 `default` ServiceAccount。

参数允许使用 Kubernetes 强类型的 Toleration 和 PodSecurityContext，因为这是明确属于
Kubernetes adapter 的管理员 API；这不构成向 Job API 透传 PodSpec。

## OpenSandboxExecutionParameters

这是 OpenSandbox adapter 自己拥有的 cluster-scoped 管理员 API。首版字段：

```yaml
spec:
  endpoint: string
  apiKeySecretRef:
    namespace: string
    name: string
    key: string
  poolRef: string
  requestMapping: AdmissionOnly | Native
  allowSecretEnv: bool
  allowImageAuth: bool
```

- endpoint 必须为 HTTPS，Dev 显式允许的本地配置除外；不得包含认证信息。
- API key 只通过 namespaced Secret 引用，status/Event 不显示内容。
- poolRef 映射为 OpenSandbox 支持的 pool/profile 选择，不允许 Job 覆盖。
- `requestMapping=Native` 要求后端忠实接受 requests 与 limits；`AdmissionOnly` 表示 requests
  只参与 Ayatori 准入，limits 映射为 OpenSandbox resourceLimits。
- Secret env 与 per-request image auth 都会使 adapter 读取 Kubernetes Secret 并把解析值发送
  到 OpenSandbox API，必须由管理员分别显式启用。

OpenSandbox 参数不暴露任意 `extensions` map。未来确需使用某项 extension 时，将其提升为该
参数 CRD 中经过校验的命名字段。

## Condition 与 Job 状态机交互

Job 只有在以下条件同时满足时进入 `Accepted=True`：

- class 已按默认或显式名称解析；
- class UID 与已解析引用一致；
- class `Accepted=True`；
- namespace 符合 allowedNamespaces；
- Job resources 成功解析并处于允许范围；
- Job 使用的 Secret/ConfigMap 存在且可以按 optional 语义解析。

`JobClass Ready=False` 时，Job 保持 `Accepted=True`、`Scheduled=False`，等待后端恢复。
这样 class 配置合法性与当前可用性不会混成同一状态。

若 Job 已经 Scheduled，后续 class Ready 或 namespace label 变化不撤销执行。若 class 或参数
对象意外消失，controller 仍以 Job status 中的 controllerName、参数 UID 和 execution
references 尝试恢复；无法安全观察时进入非终态 `ResultUnknown`，不能切换 class 重跑。

## 测试矩阵

实现至少覆盖：

- 显式 class、namespace 默认和全局默认的优先级；
- 零个与多个全局默认 class；
- allowedNamespaces 允许、拒绝及接受后 label 变化；
- unsupported controllerName 和错误 parameters kind；
- parameters 不存在、稍后出现、UID 删除重建；
- resource defaults、min/max、request 大于 limit 和 quantity 边界；
- class policy 更新不改变已接受 Job 的 effective resources；
- class Ready=False 阻止新 Ensure，但不阻止现存执行 Observe/Cancel/Delete；
- Kubernetes ServiceAccount/runtime 配置缺失且不回退；
- OpenSandbox API key Secret 缺失、轮换及后端健康恢复；
- allowSecretEnv/allowImageAuth 拒绝不允许的 Job；
- class 删除被非终态 Job 阻止，终态清理后允许删除；
- 同名 class 或参数对象以新 UID 重建时不劫持现存 Job。

## 延后事项

- class 级并发和速率限制；
- Kueue LocalQueue/ClusterQueue 映射；
- capability-based 自动 class 选择；
- 多集群 Kubernetes executor；
- GPU、临时磁盘和其他扩展资源；
- workload identity 与 OpenSandbox Credential Vault；
- class 成本、优先级与抢占策略。

## 成熟实现参考

- [Kubernetes RuntimeClass](https://kubernetes.io/docs/concepts/containers/runtime-class/)
- [Kubernetes StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/)
- [Gateway API GatewayClass](https://gateway-api.sigs.k8s.io/reference/api-types/gatewayclass/)
- [Kueue ResourceFlavor](https://kueue.sigs.k8s.io/docs/concepts/resource_flavor/)