Deployment manifest

Minimal example

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

Full example

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

Deployment spec

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

Field	Type	Required	Default	Mutability	Since
dependsOn	DependencyRef[]	no	—	in-place	0.7.6
environment	object	no	—	recreate	0.1.0
healthCheck	HealthCheckSpec	no	—	recreate	0.1.0
image	string	no	—	recreate	0.1.0
ingress	IngressSpec	no	—	recreate	0.9.4
init	boolean	no	—	recreate	0.21.1
networks	string[]	no	—	recreate	0.1.0
onNodeFailure	string	no	—	in-place	0.9.4
placement	PlacementSpec	no	—	recreate	0.7.6
replicas	integer	no	—	recreate	0.1.0
resources	ResourceSpec	no	—	recreate	0.1.0
restartRetries	integer	no	—	recreate	0.7.6
scaling	ScalingSpec	no	—	in-place	0.1.0
secrets	SecretSpec[]	no	—	recreate	0.1.0
ulimits	Ulimit[]	no	—	recreate	0.21.1
update	UpdatePolicy	no	—	in-place	0.11.0
volumes	VolumeSpec[]	no	—	recreate	0.1.0

dependsOn: SP-6, ruling JD4

environment: Environment are plain environment variables set on every container. Never put a credential here — use secrets:, which resolves from Vault at dispatch and never stores the value.

healthCheck: HealthCheck is the container probe. Only type: exec produces a real healthcheck; an http or tcp declaration is refused rather than left inert.

image: Image is the fully-qualified container image reference, including an explicit tag. Never “:latest” in production: an unpinned tag makes a rollback impossible to describe.

ingress: Ingress is the WP3 typed ingress block (IG1/IG3/IG9/IG12). G1: the manifest surface had no ingress support before this task — authors had to hand-write traefik.* labels, which ValidateIngress now rejects outright whenever ingress: is also set.

init: Init runs Docker’s tiny init as PID 1 so orphaned processes are reaped. Omit it to take the platform default, which is on; set false only for an image that already runs its own init.

networks: Networks are the Docker networks the container joins. Names are tenant-prefixed for you; a backend should stay off traefik-public.

onNodeFailure — A node hosting several deployments takes the most conservative policy among them — keep beats approve beats reschedule. The policy is resolved across the node, not per deployment, so setting reschedule on one deployment does not override a keep on another sharing the node.

onNodeFailure: OnNodeFailure is the WP6 (ND5) per-deployment node-failure policy: reschedule | approve | keep (empty = cluster default). #71 NF-4: without this field the manifest surface could not opt into keep/approve.

placement: SP-4; shared: Jobs place too

replicas: Replicas is how many container instances to keep running. 0 is accepted and means “declared but stopped”.

resources: Resources are the CPU and memory limits and requests, written as limits/requests rather than as four flat keys.

restartRetries: RestartRetries caps Docker’s on-failure restart attempts. It is only meaningful for a workload whose restart policy is on-failure.

scaling: Scaling turns on autoscaling between a floor and a ceiling of replicas, driven by the metrics it names.

secrets: Secrets are references to material in Vault, injected as environment variables at dispatch. The value never appears in this document.

ulimits: Ulimits are the container’s POSIX resource limits. A per-container ulimit overrides the daemon’s defaults, which is the supported way to raise a file-descriptor ceiling — never a hand-edited daemon.json.

update: Update embeds types.UpdatePolicy directly (WP4 RM-1, G3 ruling): the types struct carries yaml tags, so the manifest inherits them 1:1 and strict parsing covers the nested fields via registeredKinds.

volumes: Volumes are the named volumes and bind mounts attached to each container.

resources

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

Field	Type	Required	Default	Mutability	Since
limits	ResourceValues	no	—	recreate	0.1.0
requests	ResourceValues	no	—	recreate	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.

Field	Type	Required	Default	Mutability	Since
hard	integer	no	—	recreate	0.21.1
name	string	no	—	recreate	0.21.1
soft	integer	no	—	recreate	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.

Field	Type	Required	Default	Mutability	Since
command	string	no	—	recreate	0.1.0
interval	string	no	—	recreate	0.1.0
path	string	no	—	recreate	0.1.0
port	integer	no	—	recreate	0.1.0
retries	integer	no	—	recreate	0.1.0
startPeriod	string	no	—	recreate	0.1.0
timeout	string	no	—	recreate	0.1.0
type	string	no	—	recreate	0.1.0

interval — There is no floor. Clamping an interval upward would delay failure detection, so unlike the timeout it is not safety-monotonic — a longer timeout can only reduce spurious kills, a longer interval can only slow detection. odysseus spec-audit reports the value; nothing rejects or changes it.

type: http, tcp, exec

volumes

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

Field	Type	Required	Default	Mutability	Since
readOnly	boolean	no	—	recreate	0.1.0
source	string	no	—	recreate	0.1.0
target	string	no	—	recreate	0.1.0

secrets

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

Field	Type	Required	Default	Mutability	Since
anchor	string	no	—	recreate	0.37.0
mountPath	string	no	—	recreate	0.1.0
name	string	no	—	recreate	0.1.0
rotation	string	no	—	recreate	0.1.0
vaultPath	string	no	—	recreate	0.1.0

anchor: Anchor: volume(<id>) | process | external — WP18 S10.

placement

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

Field	Type	Required	Default	Mutability	Since
affinity	PlacementSelector	no	—	recreate	0.7.6
antiAffinity	PlacementSelector	no	—	recreate	0.7.6
node	string	no	—	recreate	0.7.6
preferredZone	string	no	—	recreate	0.7.6

node: explicit target node (Deployment.NodeID)

dependsOn

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

Field	Type	Required	Default	Mutability	Since
condition	string	no	—	in-place	0.7.6
deployment	string	no	—	in-place	0.7.6
job	string	no	—	in-place	0.7.6

condition: deployment: started|healthy; job: complete

job: WP8 JB-6: depend on a job (condition: complete)

scaling

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

Field	Type	Required	Default	Mutability	Since
enabled	boolean	no	—	in-place	0.1.0
maxReplicas	integer	no	—	in-place	0.1.0
metrics	MetricSpec[]	no	—	in-place	0.1.0
minReplicas	integer	no	—	in-place	0.1.0
scaleDownCooldown	string	no	—	in-place	0.1.0
scaleUpCooldown	string	no	—	in-place	0.1.0

ingress

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

Field	Type	Required	Default	Mutability	Since
basicAuth	BasicAuthMiddleware	no	—	recreate	0.9.4
compress	boolean	no	—	recreate	0.9.4
forwardAuth	ForwardAuthMiddleware	no	—	recreate	0.9.4
headers	HeadersMiddleware	no	—	recreate	0.9.4
healthCheck	IngressHealthCheck	no	—	recreate	0.11.0
host	string	no	—	recreate	0.9.4
ipAllowList	IPAllowListMiddleware	no	—	recreate	0.9.4
middlewares	string[]	no	—	recreate	0.9.4
network	string	no	—	recreate	0.9.4
pathPrefix	string	no	—	recreate	0.9.4
port	integer	no	—	recreate	0.9.4
priority	integer	no	—	recreate	0.9.4
rateLimit	integer	no	—	recreate	0.9.4
redirect	RedirectMiddleware	no	—	recreate	0.9.4
retry	RetryMiddleware	no	—	recreate	0.11.0
routerName	string	no	—	recreate	0.9.4
stickySessions	boolean	no	—	recreate	0.9.4
stripPrefix	StripPrefixMiddleware	no	—	recreate	0.9.4
tls	IngressTLSSpec	no	—	recreate	0.9.4

basicAuth: WP3.1 middleware definitions (IM1) — the types structs are reused verbatim (they carry yaml tags), so the manifest surface mirrors IngressConfig 1:1 by construction and cannot drift.

healthCheck: HealthCheck: Traefik LB probes (WP4 RU4) — types struct reused verbatim.

update

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

Field	Type	Required	Default	Mutability	Since
allow_concurrent_versions	boolean	no	—	in-place	0.11.0
failure_action	string	no	—	in-place	0.11.0
health_timeout	integer	no	—	in-place	0.1.0
max_failure_ratio	number	no	—	in-place	0.11.0
max_surge	integer	no	—	in-place	0.1.0
max_unavailable	integer	no	—	in-place	0.1.0
min_healthy_time	integer	no	—	in-place	0.11.0
progress_deadline	integer	no	—	in-place	0.11.0
rollback_on_fail	boolean	no	—	in-place	0.1.0
strategy	string	no	—	in-place	0.1.0

allow_concurrent_versions: AllowConcurrentVersions is the criterion-3 operator attestation (RU3): old and new versions may briefly coexist. REQUIRED for rolling/canary; never inferred.

failure_action: FailureAction: “pause” (default) or “rollback” (to last stable, RU6).

health_timeout: HealthTimeout is the per-instance healthy DEADLINE (WP4 semantics).

max_failure_ratio: MaxFailureRatio is the tolerated failed-instance fraction [0,1].

min_healthy_time: MinHealthyTime: an instance must STAY healthy this long, unbroken, to count (a health flip resets the clock — RU5/G4).

progress_deadline: ProgressDeadline bounds the whole rollout; resets per healthy instance.

rollback_on_fail: RollbackOnFail is honored as FailureAction “rollback” (retained field).