Manifeste de déploiement

Exemple minimal

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

Exemple complet

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

Spécification du déploiement

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

Champ	Type	Requis	Défaut	Mutabilité	Depuis
canary	CanarySpec	non	—	in-place	0.74.0
capAdd	string[]	non	—	recreate	0.74.0
capDrop	string[]	non	—	recreate	0.74.0
command	string[]	non	—	recreate	0.74.0
dependsOn	DependencyRef[]	non	—	in-place	0.7.6
dns	string[]	non	—	recreate	0.74.0
dnsSearch	string[]	non	—	recreate	0.74.0
entrypoint	string[]	non	—	recreate	0.74.0
environment	object	non	—	recreate	0.1.0
expose	integer[]	non	—	recreate	0.74.0
extraHosts	string[]	non	—	recreate	0.74.0
healthCheck	HealthCheckSpec	non	—	recreate	0.1.0
hostname	string	non	—	recreate	0.74.0
image	string	non	—	recreate	0.1.0
imagePullSecret	string	non	—	recreate	0.74.0
ingress	IngressSpec	non	—	recreate	0.9.4
init	boolean	non	—	recreate	0.21.1
logging	LoggingConfig	non	—	recreate	0.74.0
networkAliases	string[]	non	—	recreate	0.74.0
networks	string[]	non	—	recreate	0.1.0
onNodeFailure	string	non	—	in-place	0.9.4
placement	PlacementSpec	non	—	recreate	0.7.6
ports	PortMapping[]	non	—	recreate	0.74.0
privileged	boolean	non	—	recreate	0.74.0
probe	ProbeSpec	non	—	recreate	0.74.0
readOnly	boolean	non	—	recreate	0.74.0
replicas	integer	non	—	in-place	0.1.0
resources	ResourceSpec	non	—	recreate	0.1.0
restartPolicy	string	non	—	recreate	0.74.0
restartRetries	integer	non	—	recreate	0.7.6
scaling	ScalingSpec	non	—	in-place	0.1.0
secrets	SecretSpec[]	non	—	recreate	0.1.0
securityOpt	string[]	non	—	recreate	0.74.0
stack	string	non	—	recreate	0.74.0
stopGracePeriod	integer	non	—	recreate	0.74.0
ulimits	Ulimit[]	non	—	recreate	0.21.1
update	UpdatePolicy	non	—	in-place	0.11.0
user	string	non	—	recreate	0.74.0
volumes	VolumeSpec[]	non	—	recreate	0.1.0
workingDir	string	non	—	recreate	0.74.0

canary: La mise à jour progressive déplace le trafic vers la nouvelle version par étapes pondérées et promeut ou annule selon les seuils qu’elle porte. Voir CanarySpec.

capAdd: CapAdd accorde des capacités Linux individuelles, par ex. NET_ADMIN.

capDrop: CapDrop supprime les capacités que le runtime accorderait autrement. « ALL » suivi d’un capAdd restreint est la forme sûre.

command: La commande remplace le CMD de l’image, sous forme d’argv. Une valeur vide laisse le défaut de l’image.

dependsOn: SP-6, ruling JD4

dns: DNS sont des résolveurs personnalisés pour le conteneur, remplaçant ceux du démon.

dnsSearch: DNSSearch sont les domaines de recherche ajoutés aux noms non qualifiés.

entrypoint: Entrypoint remplace l’ENTRYPOINT de l’image, sous forme de argv.

environment: Environment sont des variables d’environnement simples définies sur chaque conteneur. Ne mettez jamais d’identifiant ici — utilisez secrets:, qui se résout depuis Vault à l’envoi et ne stocke jamais la valeur.

expose: Expose sont des ports accessibles uniquement depuis d’autres conteneurs sur le même réseau.

extraHosts: ExtraHosts sont des entrées /etc/hosts supplémentaires, chacune écrite “nom:adresse”.

healthCheck: HealthCheck est la sonde du conteneur. Seul le type : exec produit une véritable vérification de santé ; une déclaration http ou tcp est refusée plutôt que laissée inerte.

hostname: Hostname est le nom d’hôte du conteneur lui-même. Laissez-le non défini pour utiliser le nom du conteneur.

image: Image est la référence complète de l’image du conteneur, incluant un tag explicite. Jamais “:latest” en production : un tag non épinglé rend un retour en arrière impossible à décrire.

imagePullSecret: ImagePullSecret désigne l’identifiant du registre utilisé pour récupérer l’image.

ingress: Ingress est le bloc ingress typé WP3 (IG1/IG3/IG9/IG12). G1 : la surface de manifeste ne prenait pas en charge ingress avant cette tâche — les auteurs devaient écrire manuellement les labels traefik.*, que ValidateIngress rejette désormais systématiquement lorsque ingress: est également défini.

init: Init exécute le petit init de Docker en tant que PID 1 afin que les processus orphelins soient récupérés. Omettez-le pour utiliser la valeur par défaut de la plateforme, qui est activée ; ne définissez false que pour une image qui exécute déjà son propre init.

logging: La journalisation sélectionne le pilote de journalisation Docker et ses options.

networkAliases: NetworkAliases sont des noms DNS supplémentaires auxquels le conteneur répond sur ses réseaux, pour la découverte par d’autres conteneurs.

networks: Networks sont les réseaux Docker auxquels le conteneur se connecte. Les noms sont préfixés par le locataire pour vous ; un backend doit rester hors de traefik-public.

onNodeFailure — Un nœud hébergeant plusieurs déploiements applique la politique la plus conservatrice parmi elles — keep l’emporte sur approve qui l’emporte sur reschedule. La politique est résolue au niveau du nœud, et non par déploiement, donc définir reschedule sur un déploiement n’écrase pas keep sur un autre partageant le nœud.

onNodeFailure: OnNodeFailure est la politique de défaillance de nœud par déploiement WP6 (ND5) : reschedule | approve | keep (vide = valeur par défaut du cluster). #71 NF-4 : sans ce champ, la surface de manifeste ne pouvait pas opter pour keep/approve.

placement: SP-4 ; partagé : Les jobs placent trop

ports: Les ports publient les ports du conteneur sur l’hôte. Le trafic de conteneur à conteneur n’a pas besoin d’entrée ici — utilisez plutôt un réseau partagé.

privileged: Privilégié donne au conteneur un accès complet aux périphériques et capacités de l’hôte. C’est une échappatoire à l’isolation du conteneur, pas un niveau de permission — préférez capAdd avec la capacité spécifique.

probe: La sonde déclare une cible boîte noire externe pour la surveillance. C’est de l’observabilité UNIQUEMENT et ne bloque jamais une mise à jour progressive — c’est le rôle de healthCheck, et confondre les deux est la façon dont une sonde inerte peut satisfaire une condition de prétention qu’elle était censée protéger.

readOnly: ReadOnly monte le système de fichiers racine du conteneur en lecture seule. Tout ce qui doit être écrit nécessite un volume ou un montage tmpfs.

replicas: Replicas indique combien d’instances de conteneur doivent rester en cours d’exécution. 0 est accepté et signifie « déclaré mais arrêté ».

resources: Resources sont les limites et requêtes de CPU et de mémoire, écrites sous forme de limits/requests plutôt que sous forme de quatre clés plates.

restartPolicy: RestartPolicy est ce que Docker fait lorsque le conteneur se termine. Les valeurs acceptées diffèrent selon le type et sont appliquées par le validateur propre à chaque type.

restartRetries: RestartRetries limite les tentatives de redémarrage en cas d’échec de Docker. Cela n’a de sens que pour un déploiement dont la politique de redémarrage est on-failure.

scaling: Scaling active l’autoscaling entre un plancher et un plafond de réplicas, piloté par les métriques qu’il nomme.

secrets: Secrets sont des références à du matériel dans Vault, injectées en tant que variables d’environnement lors du dispatch. La valeur n’apparaît jamais dans ce document.

securityOpt: SecurityOpt sont les options de sécurité du runtime, par ex. « no-new-privileges:true » ou un profil seccomp.

stack: Stack est le regroupement logique auquel ce déploiement appartient, émis sous la forme de l’étiquette com.docker.compose.project afin que des outils tels que Portainer regroupent ses conteneurs ensemble. Par défaut, la valeur vide est « odysseus ».

stopGracePeriod: StopGracePeriod est le nombre de secondes dont dispose le conteneur pour se terminer après SIGTERM avant d’être arrêté.

ulimits: Ulimits sont les limites de ressources POSIX du conteneur. Une ulimit par conteneur remplace les valeurs par défaut du démon, ce qui est la méthode prise en charge pour augmenter le plafond des descripteurs de fichiers — jamais un daemon.json modifié manuellement.

update: Update intègre directement types.UpdatePolicy (WP4 RM-1, décision G3) : la structure types porte des balises yaml, de sorte que le manifeste les hérite 1:1 et l’analyse stricte couvre les champs imbriqués via registeredKinds.

user: User est l’UID:GID ou le nom d’utilisateur sous lequel le processus du conteneur s’exécute.

volumes: Volumes sont les volumes nommés et les montages liés attachés à chaque conteneur.

workingDir: WorkingDir est le répertoire dans lequel le processus démarre, remplaçant le WORKDIR de l’image.

ressources

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

Champ	Type	Requis	Défaut	Mutabilité	Depuis
limits	ResourceValues	non	—	recreate	0.1.0
requests	ResourceValues	non	—	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.

Champ	Type	Requis	Défaut	Mutabilité	Depuis
hard	integer	non	—	recreate	0.21.1
name	string	non	—	recreate	0.21.1
soft	integer	non	—	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.

Champ	Type	Requis	Défaut	Mutabilité	Depuis
command	any	non	—	recreate	0.1.0
interval	string	non	—	recreate	0.1.0
path	string	non	—	recreate	0.1.0
port	integer	non	—	recreate	0.1.0
retries	integer	non	—	recreate	0.1.0
startPeriod	string	non	—	recreate	0.1.0
timeout	string	non	—	recreate	0.1.0
type	string	non	—	recreate	0.1.0

command: Command est la commande de sonde, sous forme de chaîne shell ou de liste argv (voir ShellOrArgv). Les deux aboutissent au même []string stocké.

interval — Il n’y a pas de valeur minimale. Plafonner un intervalle vers le haut retarderait la détection des défaillances, donc contrairement au délai d’attente, il n’est pas monotone en termes de sécurité — un délai d’attente plus long ne peut que réduire les arrêts intempestifs, un intervalle plus long ne peut que ralentir la détection. odysseus spec-audit rapporte la valeur ; rien ne la rejette ou ne la modifie.

timeout — Il y a une valeur minimale de 10s pour les sondes exec : un exec ayant dépassé le délai reçoit SIGKILL et est reparenté à un PID 1 qui ne le récupère jamais, donc une valeur plus courte est refusée directement à la création (code healthcheck_timeout_below_floor). Sur une mise à jour de DÉPLOIEMENT qui omet healthCheck entièrement, la valeur stockée est d’abord restaurée puis ENSUITE augmentée à la valeur minimale si elle est antérieure à cette règle — silencieusement, sauf si vous lisez la réponse, où elle est révélée comme healthcheck_timeout_clamped. Omettez le délai d’attente pour prendre la valeur par défaut de 30s de Docker, qui dépasse déjà la valeur minimale ; indiquez-la explicitement uniquement pour définir une borne plus stricte que la valeur par défaut.

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.

Champ	Type	Requis	Défaut	Mutabilité	Depuis
distributedVolumeId	string	non	—	recreate	0.63.0
readOnly	boolean	non	—	recreate	0.1.0
source	string	non	—	recreate	0.1.0
target	string	non	—	recreate	0.1.0

distributedVolumeId: DistributedVolumeID monte un volume DVM par son ID typé (#414). Sa PRÉSENCE est le discriminateur — la surface du manifeste n’a délibérément pas de clé type (chaque volume de manifeste simple est un montage de liaison, voir convertVolumeSpecs), donc exactement l’un des source/distributedVolumeId est défini, et le validateur de forme en aval rejette les deux ou aucun.

secrets

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

Champ	Type	Requis	Défaut	Mutabilité	Depuis
anchor	string	non	—	recreate	0.37.0
mountPath	string	non	—	recreate	0.1.0
name	string	non	—	recreate	0.1.0
rotation	string	non	—	recreate	0.1.0
vaultPath	string	non	—	recreate	0.1.0

anchor: Ancrage : volume(<id>) | processus | externe — 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.

Champ	Type	Requis	Défaut	Mutabilité	Depuis
affinity	PlacementSelector	non	—	recreate	0.7.6
antiAffinity	PlacementSelector	non	—	recreate	0.7.6
node	string	non	—	recreate	0.7.6
preferredZone	string	non	—	recreate	0.7.6
residency	ResidencySpec	non	—	recreate	0.74.0

affinity: L’affinité oriente le placement VERS les nœuds portant une étiquette. C’est une préférence que le scoreur pondère, pas un filtre qui refuse — un déploiement avec une affinité insatisfaisable est tout de même placé, juste pas là où il le demandait.

antiAffinity: AntiAffinity oriente le placement LOIN des nœuds portant une étiquette, avec la même sémantique de pondération sans refus que l’affinité.

node: Le nœud épingle la charge de travail à un nœud par son nom, atterrissant sur Deployment.NodeID. Laissez-le non défini pour laisser l’ordonnanceur choisir ; une valeur vide ne supprime jamais une affectation que l’ordonnanceur a déjà faite.

preferredZone: PreferredZone nomme une zone périphérique que le scoreur préfère.

NOTE, pour que personne ne débogue cela deux fois : aucune zone n’est déclarée dans la configuration du plan de contrôle livrée aujourd’hui, donc cela ne s’évalue actuellement contre rien. C’est une constatation réelle avec son propre ticket, pas un défaut dans ce bloc.

residency: La résidence est l’endroit où la charge de travail a le droit légal de s’exécuter (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.

Champ	Type	Requis	Défaut	Mutabilité	Depuis
condition	string	non	—	in-place	0.7.6
deployment	string	non	—	in-place	0.7.6
job	string	non	—	in-place	0.7.6

condition: déploiement : démarré|sain ; tâche : terminée

job: WP8 JB-6 : dépendre d’un 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.

Champ	Type	Requis	Défaut	Mutabilité	Depuis
enabled	boolean	non	—	in-place	0.1.0
maxReplicas	integer	non	—	in-place	0.1.0
metrics	MetricSpec[]	non	—	in-place	0.1.0
minReplicas	integer	non	—	in-place	0.1.0
scaleDownCooldown	string	non	—	in-place	0.1.0
scaleUpCooldown	string	non	—	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.

Champ	Type	Requis	Défaut	Mutabilité	Depuis
basicAuth	BasicAuthMiddleware	non	—	recreate	0.9.4
compress	boolean	non	—	recreate	0.9.4
forwardAuth	ForwardAuthMiddleware	non	—	recreate	0.9.4
headers	HeadersMiddleware	non	—	recreate	0.9.4
healthCheck	IngressHealthCheck	non	—	recreate	0.11.0
host	string	non	—	recreate	0.9.4
ipAllowList	IPAllowListMiddleware	non	—	recreate	0.9.4
middlewares	string[]	non	—	recreate	0.9.4
network	string	non	—	recreate	0.9.4
pathPrefix	string	non	—	recreate	0.9.4
port	integer	non	—	recreate	0.9.4
priority	integer	non	—	recreate	0.9.4
rateLimit	integer	non	—	recreate	0.9.4
redirect	RedirectMiddleware	non	—	recreate	0.9.4
retry	RetryMiddleware	non	—	recreate	0.11.0
routerName	string	non	—	recreate	0.9.4
stickySessions	boolean	non	—	recreate	0.9.4
stripPrefix	StripPrefixMiddleware	non	—	recreate	0.9.4
tls	IngressTLSSpec	non	—	recreate	0.9.4

basicAuth: Définitions de middleware WP3.1 (IM1) — les structs de types sont réutilisées verbatim (elles portent des balises yaml), de sorte que la surface du manifeste reflète IngressConfig 1:1 par construction et ne peut pas dériver.

healthCheck: HealthCheck : sondes Traefik LB (WP4 RU4) — structure de types réutilisée telle quelle.

update

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

Champ	Type	Requis	Défaut	Mutabilité	Depuis
allow_concurrent_versions	boolean	non	—	in-place	0.11.0
failure_action	string	non	—	in-place	0.11.0
health_timeout	integer	non	—	in-place	0.1.0
max_failure_ratio	number	non	—	in-place	0.11.0
max_surge	integer	non	—	in-place	0.1.0
max_unavailable	integer	non	—	in-place	0.1.0
min_healthy_time	integer	non	—	in-place	0.11.0
progress_deadline	integer	non	—	in-place	0.11.0
rollback_on_fail	boolean	non	—	in-place	0.1.0
strategy	string	non	—	in-place	0.1.0

allow_concurrent_versions: AllowConcurrentVersions est l’attestation de l’opérateur critère-3 (RU3) : les anciennes et nouvelles versions peuvent brièvement coexister. REQUIS pour le déploiement progressif/canary ; nunca inféré.

failure_action: FailureAction : “pause” (par défaut) ou “rollback” (vers la dernière version stable, RU6).

health_timeout: HealthTimeout est la DEADLINE de santé par instance (sémantique WP4).

max_failure_ratio: MaxFailureRatio est la fraction tolérée d’instances défaillantes [0,1].

min_healthy_time: MinHealthyTime : une instance doit RESTER en bonne santé aussi longtemps, sans interruption, pour compter (un basculement de santé réinitialise l’horloge — RU5/G4).

progress_deadline: ProgressDeadline délimite l’ensemble de la mise à jour progressive ; se réinitialise par instance saine.

rollback_on_fail: RollbackOnFail est honoré comme FailureAction “rollback” (champ conservé).