部署清单

最小示例

apiVersion: odysseus/v1
kind: Deployment
metadata:
  name: worker
spec:
  image: registry.delta-telematics.ca/acme/worker:2.1.0
  replicas: 2
  networks: [acme-network]
  environment:
    QUEUE: jobs
  resources:
    limits:   {cpu: "1", memory: 512Mi}
    requests: {cpu: 250m, memory: 256Mi}

Validated against Manifest · testdata/docs-examples/minimal-deployment.yaml

完整示例

apiVersion: odysseus/v1
kind: Deployment
metadata:
  name: api
  labels:
    app: api
spec:
  image: registry.delta-telematics.ca/acme/api:1.4.2
  replicas: 3
  environment:
    LOG_LEVEL: info
  networks: [acme-network, traefik-public]
  resources:
    limits:   {cpu: "1", memory: 512Mi}
    requests: {cpu: 250m, memory: 256Mi}
  healthCheck:                      # required for rolling
    type: exec
    command: "wget -qO- http://localhost:8080/healthz"
    interval: 10s
    timeout: 15s
    retries: 3
    startPeriod: 20s
  secrets:
    - name: DB
      vaultPath: deployments/api/db
  dependsOn:
    - job: api-migrate
      condition: complete
  placement:
    affinity: {label: role, value: app}
  onNodeFailure: reschedule
  ingress:
    host: api.example.com
    port: 8080
    tls: {enabled: true, certResolver: letsencrypt}
    healthCheck: {path: /healthz, interval: 10s, timeout: 3s}   # LB probe — the zero-downtime part
    compress: true
    headers:
      response:
        set: {X-Frame-Options: DENY}
    retry: {attempts: 3, initialInterval: 100ms}
  update:
    strategy: rolling
    allow_concurrent_versions: true   # required attestation
    max_surge: 1
    max_unavailable: 0
    health_timeout: 90s
    min_healthy_time: 15s
    progress_deadline: 10m
    failure_action: rollback

Validated against Manifest · testdata/docs-examples/routed-deployment.yaml

部署规格

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

字段	类型	必需	默认	可变性	自
canary	CanarySpec	否	—	原地	0.74.0
capAdd	string[]	否	—	重建	0.74.0
capDrop	string[]	否	—	重建	0.74.0
command	string[]	否	—	重建	0.74.0
dependsOn	DependencyRef[]	否	—	原地	0.7.6
dns	string[]	否	—	重建	0.74.0
dnsSearch	string[]	否	—	重建	0.74.0
entrypoint	string[]	否	—	重建	0.74.0
environment	object	否	—	重建	0.1.0
expose	integer[]	否	—	重建	0.74.0
extraHosts	string[]	否	—	重建	0.74.0
healthCheck	HealthCheckSpec	否	—	重建	0.1.0
hostname	string	否	—	重建	0.74.0
image	string	否	—	重建	0.1.0
imagePullSecret	string	否	—	重建	0.74.0
ingress	IngressSpec	否	—	重建	0.9.4
init	boolean	否	—	重建	0.21.1
logging	LoggingConfig	否	—	重建	0.74.0
networkAliases	string[]	否	—	重建	0.74.0
networks	string[]	否	—	重建	0.1.0
onNodeFailure	string	否	—	原地	0.9.4
placement	PlacementSpec	否	—	重建	0.7.6
ports	PortMapping[]	否	—	重建	0.74.0
privileged	boolean	否	—	重建	0.74.0
probe	ProbeSpec	否	—	重建	0.74.0
readOnly	boolean	否	—	重建	0.74.0
replicas	integer	否	—	原地	0.1.0
resources	ResourceSpec	否	—	重建	0.1.0
restartPolicy	string	否	—	重建	0.74.0
restartRetries	integer	否	—	重建	0.7.6
scaling	ScalingSpec	否	—	原地	0.1.0
secrets	SecretSpec[]	否	—	重建	0.1.0
securityOpt	string[]	否	—	重建	0.74.0
stack	string	否	—	重建	0.74.0
stopGracePeriod	integer	否	—	重建	0.74.0
ulimits	Ulimit[]	否	—	重建	0.21.1
update	UpdatePolicy	否	—	原地	0.11.0
user	string	否	—	重建	0.74.0
volumes	VolumeSpec[]	否	—	重建	0.1.0
workingDir	string	否	—	重建	0.74.0

canary: 金丝雀发布通过加权步骤将流量转移到新版本，并根据其携带的阈值进行提升或中止。参见 CanarySpec。

capAdd: CapAdd 授予单个 Linux 功能，例如 NET_ADMIN。

capDrop: CapDrop 移除运行时原本会授予的功能。“ALL” 后跟一个窄的 capAdd 是安全的形式。

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

dependsOn: SP-6，裁决 JD4

dns: DNS 是容器的自定义解析器，会覆盖守护进程的设置。

dnsSearch: DNSSearch 是附加到非限定名称的搜索域。

entrypoint: Entrypoint 覆盖镜像的 ENTRYPOINT，作为 argv。

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

expose: Expose 是仅可从同一网络上其他容器访问的端口。

extraHosts: ExtraHosts 是额外的 /etc/hosts条目，每条写作 “name:address”。

healthCheck: HealthCheck 是容器探针。唯一类型：exec 会产生真正的健康检查；http 或 tcp 声明会被拒绝，而不是保持惰性。

hostname: 主机名是容器自身的主机名。留空则采用容器名称。

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

imagePullSecret: ImagePullSecret 指定用于拉取镜像的注册表凭据。

ingress: Ingress 是 WP3 类型的 ingress 块（IG1/IG3/IG9/IG12）。G1：在此任务之前，清单表面不支持 ingress — 作者必须手写 traefik.* 标签，而 ValidateIngress 现在会在同时设置 ingress: 时直接拒绝。

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

logging: 日志选择 Docker 日志驱动程序及其选项。

networkAliases: NetworkAliases 是容器在其网络上响应的额外 DNS 名称，供其他容器发现使用。

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

onNodeFailure — 一个承载多个部署的节点会采用其中最保守的策略——keep 优于 approve 优于 reschedule。策略是在节点层面解析的，而非按部署，因此在一个部署上设置 reschedule 不会覆盖共享该节点的另一个部署上的 keep。

onNodeFailure: OnNodeFailure 是 WP6 (ND5) 每个部署的节点故障策略：reschedule | approve | keep（空值 = 集群默认值）。#71 NF-4：没有此字段，清单表面无法选择 keep/approve。

placement: SP-4；共享：作业放置过多

ports: 端口将容器端口发布到主机上。容器之间的流量无需在此处配置——请改用共享网络。

privileged: 特权模式赋予容器对主机设备和功能的完全访问权限。这是对容器隔离的突破，而非权限级别——建议使用 capAdd 来指定具体的能力。

probe: 探针声明一个用于监控的外部黑盒目标。它仅用于可观测性，绝不控制滚动更新——那是 healthCheck 的职责，混淆两者会导致一个本应守护就绪门控的探针反而满足了它。

readOnly: ReadOnly 将容器的根文件系统挂载为只读。任何需要写入的内容都需要使用卷或 tmpfs 挂载。

replicas: Replicas 是要保持运行的容器实例数量。接受 0，表示“已声明但已停止”。

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

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

restartRetries: RestartRetries 限制 Docker 的 on-failure 重启尝试次数。仅当工作负载的重启策略为 on-failure 时才有意义。

scaling: Scaling 启用自动扩缩，在副本数的下限和上限之间运行，由其指定的指标驱动。

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

securityOpt: SecurityOpt 是运行时的安全选项，例如 “no-new-privileges:true” 或 seccomp 配置文件。

stack: 栈是此部署所属的逻辑分组，作为 com.docker.compose.project 标签发出，以便 Portainer 等工具将其容器分组在一起。默认为空时为 “odysseus”。

stopGracePeriod: StopGracePeriod 是容器在收到 SIGTERM 信号后退出所需的秒数，超时后将被强制终止。

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

update: Update 直接嵌入 types.UpdatePolicy（WP4 RM-1, G3 裁定）：types 结构体带有 yaml 标签，因此清单 1:1 继承它们，并且严格解析通过 registeredKinds 覆盖嵌套字段。

user: 用户是容器进程运行时所使用的 UID:GID 或用户名。

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）。

dependsOn

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

字段	类型	必需	默认	可变性	自
condition	string	否	—	原地	0.7.6
deployment	string	否	—	原地	0.7.6
job	string	否	—	原地	0.7.6

condition: 部署：已启动|健康；作业：已完成

job: WP8 JB-6：依赖于作业（条件：完成）

扩缩容

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

字段	类型	必需	默认	可变性	自
enabled	boolean	否	—	原地	0.1.0
maxReplicas	integer	否	—	原地	0.1.0
metrics	MetricSpec[]	否	—	原地	0.1.0
minReplicas	integer	否	—	原地	0.1.0
scaleDownCooldown	string	否	—	原地	0.1.0
scaleUpCooldown	string	否	—	原地	0.1.0

入口

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

字段	类型	必需	默认	可变性	自
basicAuth	BasicAuthMiddleware	否	—	重建	0.9.4
compress	boolean	否	—	重建	0.9.4
forwardAuth	ForwardAuthMiddleware	否	—	重建	0.9.4
headers	HeadersMiddleware	否	—	重建	0.9.4
healthCheck	IngressHealthCheck	否	—	重建	0.11.0
host	string	否	—	重建	0.9.4
ipAllowList	IPAllowListMiddleware	否	—	重建	0.9.4
middlewares	string[]	否	—	重建	0.9.4
network	string	否	—	重建	0.9.4
pathPrefix	string	否	—	重建	0.9.4
port	integer	否	—	重建	0.9.4
priority	integer	否	—	重建	0.9.4
rateLimit	integer	否	—	重建	0.9.4
redirect	RedirectMiddleware	否	—	重建	0.9.4
retry	RetryMiddleware	否	—	重建	0.11.0
routerName	string	否	—	重建	0.9.4
stickySessions	boolean	否	—	重建	0.9.4
stripPrefix	StripPrefixMiddleware	否	—	重建	0.9.4
tls	IngressTLSSpec	否	—	重建	0.9.4

basicAuth: WP3.1 中间件定义（IM1）— 类型结构体被原样重用（它们带有 yaml 标签），因此清单表面通过构造与 IngressConfig 1:1 镜像，不会发生漂移。

healthCheck: HealthCheck：Traefik 负载均衡器探测（WP4 RU4）— 类型结构体被原样重用。

更新

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

字段	类型	必需	默认	可变性	自
allow_concurrent_versions	boolean	否	—	原地	0.11.0
failure_action	string	否	—	原地	0.11.0
health_timeout	integer	否	—	原地	0.1.0
max_failure_ratio	number	否	—	原地	0.11.0
max_surge	integer	否	—	原地	0.1.0
max_unavailable	integer	否	—	原地	0.1.0
min_healthy_time	integer	否	—	原地	0.11.0
progress_deadline	integer	否	—	原地	0.11.0
rollback_on_fail	boolean	否	—	原地	0.1.0
strategy	string	否	—	原地	0.1.0

allow_concurrent_versions: AllowConcurrentVersions 是 criterion-3 操作符的证明 (RU3)： 新旧版本可能短暂共存。滚动/金丝雀部署必需； 永远无法推断。

failure_action: FailureAction：“pause”（默认）或 “rollback”（回滚到上一个稳定版本，RU6）。

health_timeout: HealthTimeout 是每个实例的健康截止期限（WP4 语义）。

max_failure_ratio: MaxFailureRatio 是可容忍的失败实例比例 [0,1]。

min_healthy_time: MinHealthyTime：一个实例必须持续保持健康状态这么长时间，不间断，才能被计入（健康状态翻转会重置计时器 — RU5/G4）。

progress_deadline: ProgressDeadline 限定整个滚动更新；每个健康实例重置。

rollback_on_fail: RollbackOnFail 作为 FailureAction “rollback” 被遵守（保留字段）。