作业清单

最小示例

apiVersion: odysseus/v1
kind: Job
metadata:
  name: api-migrate
spec:
  image: registry.delta-telematics.ca/acme/api:1.4.2
  command: ["/app/migrate", "up"]
  networks: [acme-network]
  restartPolicy: "no"          # quoted — bare no is YAML false
  backoffLimit: 2
  activeDeadlineSeconds: 600
  ttlAfterFinished: 1h
  secrets:
    - name: DB
      vaultPath: deployments/api/db

Validated against JobManifest · testdata/docs-examples/migration-job.yaml

作业规格

Generated from JobSpec. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

字段	类型	必需	默认	可变性	自
activeDeadlineSeconds	integer	否	—	原地	0.7.6
backoffLimit	integer	否	—	原地	0.7.6
command	string[]	否	—	重建	0.7.6
entrypoint	string[]	否	—	重建	0.7.6
environment	object	否	—	重建	0.7.6
healthCheck	HealthCheckSpec	否	—	重建	0.7.6
image	string	否	—	重建	0.7.6
init	boolean	否	—	重建	0.21.1
networks	string[]	否	—	重建	0.7.6
placement	PlacementSpec	否	—	重建	0.7.6
resources	ResourceSpec	否	—	重建	0.7.6
restartPolicy	string	否	—	重建	0.7.6
secrets	SecretSpec[]	否	—	重建	0.7.6
ttlAfterFinished	string	否	—	原地	0.7.6
ulimits	Ulimit[]	否	—	重建	0.21.1
volumes	VolumeSpec[]	否	—	重建	0.7.6
workingDir	string	否	—	重建	0.7.6

activeDeadlineSeconds: 0 = 无截止时间

backoffLimit: nil → 3 (JD6)

command: 命令覆盖镜像的 CMD，作为 argv。为空则保留镜像默认值。

entrypoint: 入口点覆盖镜像的 ENTRYPOINT，作为 argv。

environment: Environment 是在每个容器上设置的普通环境变量。切勿在此处放置凭据——请使用 secrets:，它会在调度时从 Vault 解析，并且永远不会存储该值。

healthCheck: HealthCheck 是容器探测器。只有 type: exec 会生成真正的健康检查；http 或 tcp 声明会被拒绝，而不是保持惰性。

image: Image 是完全限定的容器镜像引用，包含显式标签。生产环境中切勿使用 “:latest”：未固定的标签会使回滚无法描述。

init: Init 以 PID 1 运行 Docker 的 tiny init，以便回收孤立进程。省略它将采用平台默认值（即开启）；仅当镜像已运行自己的 init 时才设置为 false。

networks: Networks 是容器加入的 Docker 网络。名称已为您添加租户前缀；后端应避免加入 traefik-public。

placement: SP-4；共享：Jobs 也放置

resources: Resources 是 CPU 和内存的限制和请求，写为 limits/requests，而不是四个扁平键。

restartPolicy: RestartPolicy 是容器退出时 Docker 执行的操作。接受的值因类型而异，并由每种类型自己的验证器强制执行。

secrets: Secrets 是对 Vault 中材料的引用，在调度时作为环境变量注入。该值永远不会出现在此文档中。

ttlAfterFinished: 持续时间；“” = 保持

ulimits: Ulimits 是容器的 POSIX 资源限制。每个容器的 ulimit 会覆盖守护进程的默认值，这是提高文件描述符上限的推荐方式——切勿手动编辑 daemon.json。

volumes: Volumes 是附加到每个容器的命名卷和绑定挂载。

workingDir: WorkingDir 是进程启动时所在的目录，覆盖镜像的 WORKDIR。

资源

Generated from ResourceSpec. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

字段	类型	必需	默认	可变性	自
limits	ResourceValues	否	—	重建	0.1.0
requests	ResourceValues	否	—	重建	0.1.0

ulimits

Generated from Ulimit. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

字段	类型	必需	默认	可变性	自
hard	integer	否	—	重建	0.21.1
name	string	否	—	重建	0.21.1
soft	integer	否	—	重建	0.21.1

healthCheck

Generated from HealthCheckSpec. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

字段	类型	必需	默认	可变性	自
command	any	否	—	重建	0.1.0
interval	string	否	—	重建	0.1.0
path	string	否	—	重建	0.1.0
port	integer	否	—	重建	0.1.0
retries	integer	否	—	重建	0.1.0
startPeriod	string	否	—	重建	0.1.0
timeout	string	否	—	重建	0.1.0
type	string	否	—	重建	0.1.0

command: Command 是探测命令，可以是 shell 字符串或 argv 列表形式（参见 ShellOrArgv）。两者都存储为 []string。

interval — 没有下限。将间隔向上钳制会延迟故障检测，因此与超时不同，它不具备安全单调性——更长的超时只能减少误杀，更长的间隔只能减慢检测速度。odysseus spec-audit 报告该值；没有任何机制会拒绝或更改它。

timeout — exec 探针有 10 秒的下限：超时的 exec 会被 SIGKILL 并重新挂接到一个从不回收它的 PID 1 下，因此更短的值在创建时会被直接拒绝（错误码 healthcheck_timeout_below_floor）。在省略了 healthCheck 的部署更新中，存储的值会先被恢复，然后如果它早于此规则，则会被向上钳制到该下限——这是静默进行的，除非您正在读取响应，其中会将其披露为 healthcheck_timeout_clamped。省略超时以采用 Docker 的 30 秒默认值，该值已满足下限；仅当需要设置比默认值更严格的限制时才需显式声明。

type: http, tcp, exec

卷

Generated from VolumeSpec. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

字段	类型	必需	默认	可变性	自
distributedVolumeId	string	否	—	重建	0.63.0
readOnly	boolean	否	—	重建	0.1.0
source	string	否	—	重建	0.1.0
target	string	否	—	重建	0.1.0

distributedVolumeId: DistributedVolumeID 通过其类型化 ID 挂载 DVM 卷 (#414)。它的 存在性是判别器——清单表面刻意没有 type 键（每个普通清单卷都是绑定挂载，参见 convertVolumeSpecs），因此 source/distributedVolumeId 中恰好设置一个， 下游的形状验证器会拒绝两者都设置或都不设置的情况。

机密

Generated from SecretSpec. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

字段	类型	必需	默认	可变性	自
anchor	string	否	—	重建	0.37.0
mountPath	string	否	—	重建	0.1.0
name	string	否	—	重建	0.1.0
rotation	string	否	—	重建	0.1.0
vaultPath	string	否	—	重建	0.1.0

anchor: 锚点：volume(<id>) | process | external — WP18 S10。

放置

Generated from PlacementSpec. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

字段	类型	必需	默认	可变性	自
affinity	PlacementSelector	否	—	重建	0.7.6
antiAffinity	PlacementSelector	否	—	重建	0.7.6
node	string	否	—	重建	0.7.6
preferredZone	string	否	—	重建	0.7.6
residency	ResidencySpec	否	—	重建	0.74.0

affinity: 亲和性引导放置偏向带有某个标签的节点。它是评分器权衡的一种偏好，而非拒绝的过滤器——一个具有无法满足亲和性的工作负载仍然会被放置，只是不会放置在它要求的位置。

antiAffinity: AntiAffinity 引导调度避开带有特定标签的节点，其权重-不拒绝语义与亲和性相同。

node: 节点通过名称将工作负载固定到一个节点，最终落在 Deployment.NodeID 上。 保持未设置状态以允许调度程序选择；空值永远不会清除调度程序已做出的分配。

preferredZone: PreferredZone 指定评分器偏好的边缘区域。

注意，为避免重复调试：目前任何已发布的控制平面配置中均未声明任何区域，因此当前评分针对的是空集。这是一个有其对应问题的真实发现，而非本块的缺陷。

residency: 驻留是工作负载在法律上允许运行的位置（S19, #557）。