Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Workload

Le rôle architectural du type Workload — pourquoi il existe, comment il se compose avec les deux autres types d’entrée de Recipe (sourced et artifacts), et toute la surface du schéma — se trouve dans ../../architecture/16-recipe-input-composition.md. Cette page couvre la surface de rédaction du Workload : comment un auteur de Recipe écrit le contenu d’un Workload, ce que le compilateur évalue et quand, comment les champs du Workload interagissent avec le featuresSchema du Component, et quels piliers les templates à l’intérieur d’un Workload peuvent lire.

Emplacement de rédaction

Le contenu d’un Workload se rédige en ligne ou depuis un fichier, à l’intérieur d’une Recipe ou d’une FeatureRecipe (voir FeatureRecipe). Une Recipe déclare au plus un workload: ; une FeatureRecipe déclare de même au plus un qui lui est propre :

# Inline (block scalar)
spec:
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
# ...

ou

# File-loaded via $import: (path relative to the Recipe directory)
spec:
workload:
$import: ./workload/workload.yaml

Les deux formes produisent le même objet Workload après l’analyse ; le choix relève de l’ergonomie de rédaction. Une troisième forme importe un Workload partagé entre Recipes depuis une entrée d’une WorkloadLibrary, par son identité à nom nu : $import: <Library>#/workloads/<entry>. Selon le vocabulaire unifié d’import de fichiers, $import: accepte une seule source — voir ../vocabulary/cross-document-ref.md pour la distinction plus large entre $ref: / $import:.

Le YAML d’un Workload ne se rédige pas comme une entité de catalogue autonome. Il n’existe aucun répertoire catalog/workload/ ; la grammaire Workload n’existe que comme contenu qu’une Recipe ou une FeatureRecipe consomme — écrit en ligne, dans un fichier à côté, ou dans une entrée d’une WorkloadLibrary. Les déclarations apiVersion et kind à l’intérieur du YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) identifient le contenu intégré pour la validation du schéma ; elles ne rendent pas le Workload adressable de manière indépendante.

Évaluation des templates

Le contenu d’un Workload est traité comme un template Go par rapport au contexte complet des piliers avant l’analyse. Lorsqu’un auteur de Recipe écrit un template comme le suivant…

replicas: {{ optional .infra `replicas` 1 }}

…le compilateur évalue ce template pendant la sous-passe Workload du rendu, résout .infra.replicas par rapport à la charge utile infra du nœud, et analyse le YAML obtenu comme un document Workload. Les locals de la Recipe sont résolus avant l’évaluation du Workload, de sorte qu’un template de Workload les lit, déjà résolus, sous .locals.

Accès aux piliers dans les templates de Workload :

  • .values — charge utile cognitive rédigée par le développeur et déclarée dans l’Aggregate.
  • .infra — dimensionnement physique rédigé par Ops et déclaré dans la Release.
  • .parameters — déjà interpolés lors de la résolution ; visibles via .values / .infra partout où le développeur ou Ops ont fait référence à .parameters.<name> dans ce qu’ils ont rédigé.
  • .locals — état privé de la Recipe résolu dans le préambule locals et publié lors de la résolution des sources ; disponible à chaque point d’évaluation des templates de Workload.
  • .context.instance_id — l’ID d’instance aplati du nœud ; le préfixe des noms de ressources qu’émet un fournisseur qui nomme les ressources synthétisées d’après l’identité.
  • .context.rendered_name — le nom que donne aux ressources synthétisées un fournisseur qui en dérive lui-même le nom, comme le nom de release de helm ; présent uniquement là où le fournisseur en indique un. Voir ../templates/rendered-resource-names.md.
  • .context.inject — le pipe d’injection après interception, déjà réécrit par tout injectMapping de FeatureRecipe pendant le mappage de l’injection.
  • .context.uses — les arêtes de topologie enrichies sortant de ce nœud, chacune portant les provides, labels et annotations en cascade résolus de la cible et, sous .context.uses.<alias>.features.<slot>, les rattachements que porte cette connexion.
  • .features — les rattachements propres du nœud, chacun portant son type, ses values, son infra et ses provides résolus. Un rattachement nommé d’après un slot que le Component déclare dans featuresSchema remplit ce slot (voir ci-dessous). Un rattachement que porte une connexion n’en fait pas partie ; il se lit sous sa connexion, et un Workload le délivre en nommant la connexion (voir Délivrer un identifiant que porte une connexion).

Voir ../vocabulary/data-pillars.md pour le contrat complet d’accès aux piliers et ../templates/expansion-matrix.md pour la place de l’évaluation du Workload dans la séquence d’évaluation des templates.

Notions essentielles sur la sémantique des champs

Le schéma complet du Workload se trouve dans ../../architecture/16-recipe-input-composition.md, sous « Le type Workload ». Les conventions de rédaction ci-dessous couvrent les décisions au niveau des champs que prend l’auteur d’une Recipe.

form

form déclare la forme abstraite de contrôleur de la charge de travail — le type de cycle de vie d’exécution qu’elle a, indépendamment de toute plateforme cible. C’est une chaîne unique, l’une de stateless, stateful, daemon, scheduled, task, reference, qui vaut stateless par défaut lorsqu’elle est omise :

  • stateless — des réplicas interchangeables, mis à l’échelle horizontalement, sans identité propre à chaque réplica (le service courant de longue durée).
  • stateful — des réplicas dotés d’une identité stable par réplica et d’un stockage par réplica. Un volume persistentTemplate est un compagnon de cette forme.
  • daemon — une instance par hôte éligible.
  • scheduled — des exécutions récurrentes, déclenchées dans le temps.
  • task — une exécution unique jusqu’à son achèvement.
  • reference — aucun conteneur propre : le composant représente un endpoint externe, donné par endpoint (un hôte ou une URL, transmis tel qu’il est écrit) et un port facultatif. Le fournisseur helm l’émet sous la forme d’un Service de type ExternalName ; le fournisseur compose n’émet rien pour lui.

La forme ne porte elle-même aucun type de ressource natif de la plateforme. Chaque fournisseur cible qui synthétise un Workload fait correspondre la forme à sa propre forme native :

formKubernetes (helm)Compose
statelessDeploymentservice (sans volume persistant)
statefulStatefulSetservice + volume nommé
daemonDaemonSetinterrompt le build
scheduledCronJobinterrompt le build
taskJobinterrompt le build

Les fournisseurs terraform et cloudformation effectuent le rendu des Recipes avec source et des Recipes composées uniquement d’artefacts, et ne synthétisent aucun Workload : une Recipe déclarant workload: liée à l’un ou l’autre interrompt le build, en nommant les types d’entrée que le fournisseur prend en charge.

Lorsqu’un fournisseur cible n’a pas de correspondance nette pour une forme, le build s’interrompt explicitement plutôt que de dégrader la charge de travail en une forme qui dénature l’intention — choisir une forme qu’une frontière cible ne peut pas exprimer est une erreur au moment du build, pas une rétrogradation silencieuse. Le fournisseur compose s’interrompt sur daemon, scheduled et task. Le fournisseur helm émet un CronJob pour scheduled (voir schedule ci-dessous) et ne s’interrompt que lorsque sa planification est absente ou mal formée.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule est la planification cron d’une charge de travail form: scheduled — le champ compagnon qui donne sa récurrence à la forme récurrente. C’est une chaîne unique dans un format canonique unique :

  • une expression crontab standard à 5 champs — minute, heure, jour du mois, mois, jour de la semaine (par exemple 0 0 * * * pour tous les jours à minuit, */15 * * * * pour toutes les quinze minutes), ou
  • l’une des macros @hourly, @daily, @weekly, @monthly, @yearly.

schedule est obligatoire lorsque form: scheduled et n’a de sens que dans ce cas. Une charge de travail form: scheduled sans planification, une planification qui n’est ni une expression à 5 champs ni une macro reconnue (une expression à 6 champs préfixée par les secondes, un jeton @ non reconnu, ou un champ contenant des caractères interdits), ou un schedule défini sur toute autre forme constitue un arrêt au moment du build qui nomme la correction. Le fournisseur helm transmet la valeur telle quelle dans le spec.schedule du CronJob émis.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
report:
image: "reporter:1.0"
command: ["/report"]

suspend

suspend suspend la planification récurrente d’une charge de travail form: scheduled. C’est un booléen, qui vaut false par défaut. Avec suspend: true, la ressource planifiée est toujours rendue avec son schedule en place, mais aucune exécution ne démarre à partir de cette planification tant qu’elle n’est pas reprise, et une exécution peut toujours être lancée à la main depuis la ressource. C’est la forme qui convient à une tâche qui ne doit s’exécuter que lorsque quelqu’un le demande.

Le fournisseur helm émet le champ sous la forme du spec.suspend: true du CronJob. Sur Kubernetes, kubectl create job <name> --from=cronjob/<cronjob> lance une exécution à partir du CronJob suspendu, et la planification reprend dès que spec.suspend vaut de nouveau false. suspend: false produit exactement le même rendu qu’un suspend omis, de sorte que le champ ne modifie aucune sortie tant qu’il n’est pas défini. Le fournisseur compose n’a pas de forme planifiée et s’interrompt sur toute charge de travail form: scheduled, suspendue ou non.

suspend: true sur toute autre forme est un arrêt au moment du build qui nomme la correction : aucune autre forme ne porte de planification qu’il pourrait suspendre.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
report:
image: "reporter:1.0"
command: ["/report"]

replicas

Un entier unique pour le nombre de réplicas de la charge de travail. Vaut 1 par défaut lorsqu’il est omis. Utilisez une expression de template pour piloter les réplicas à partir du dimensionnement déclaré par les Ops :

replicas: {{ optional .infra `replicas` 1 }}

containers face à initContainers

containers est une map ordonnée dont la clé est le nom du conteneur. Le conteneur 0 (la première clé de la map) compte pour l’ordre de la spécification du pod dans la sortie Kubernetes et pour la sémantique du conteneur par défaut. initContainers est une liste ordonnée d’entrées d’init containers, chacune portant name, image et la même forme de rédaction pour les variables, les secrets et les montages de volumes que les conteneurs principaux.

name est facultatif sur une entrée initContainers. Une entrée qui l’omet est nommée init-<index>, où l’index est la position de l’entrée dans la liste, en comptant à partir de 0. Comme le nom identifie le conteneur dans la sortie rendue et dans tout diagnostic qui le nomme, une entrée à laquelle il vaut la peine de faire référence mérite d’être nommée explicitement.

La préservation de l’ordre de l’auteur est un contrat structurant du modèle Workload — le compilateur émet containers, volumes, services, les ports des conteneurs, les variables des conteneurs et les attachments des conteneurs, chacun dans l’ordre où l’auteur de la Recipe les a déclarés, à chaque build. Les auteurs de Recipe peuvent s’appuyer sur la forme ordonnée : lorsque ce qui se passe à l’exécution dépend de l’ordre (démarrage des sidecars, chaînage $(VAR) dans les variables d’environnement, volumeMounts faisant référence à des volumes déclarés précédemment), l’ordre de rédaction EST l’ordre d’exécution au sein de chacune de ces collections. L’environnement d’un conteneur combine deux d’entre elles, et entre les deux, les fournisseurs qui synthétisent écrivent d’abord les entrées lues depuis les rattachements (attachments livrés as: env) puis les variables simples, chaque type dans l’ordre écrit — de sorte que, sur une cible Kubernetes, une variable peut faire référence, sous la forme $(NAME), à toute variable lue depuis un rattachement de son conteneur et à toute variable déclarée avant elle (voir l’ordre de l’environnement du fournisseur helm). Un conteneur qui donne un même nom à la fois comme entrée de variables et comme entrée d’attachments livrée as: env interrompt le build, car cet ordre seul déciderait laquelle des deux valeurs le processus voit (voir A container gives one environment variable two values (Un conteneur donne deux valeurs à une même variable d’environnement)).

La rédaction des champs de conteneur suit ces conventions :

  • image est généralement une expression de template faisant référence à .values.image (l’image choisie par le développeur) avec des surcharges .infra.* facultatives pour préfixer le registre selon l’environnement.
  • variables est une simple map string → string pour les variables d’environnement. La map combine deux sources de données distinctes au moyen d’expressions de template Go : des littéraux du pilier développeur (entrées dont les expressions de template lisent .values / .infra / .locals — une charge utile provenant des piliers du Component) et des données du pipe inter-composants (entrées dont les expressions de template lisent .context.inject.env.<KEY> — une charge utile provenant du provides: d’un autre composant et acheminée par le pipe de la topologie). Les deux sources alimentent la même map variables ; les auteurs choisissent l’une ou l’autre pour chaque entrée selon que la valeur est locale au composant ou dérivée d’un autre composant. Motifs courants : LOG_LEVEL: "{{ .values.log_level }}" relève du pilier développeur (local au composant) ; DB_HOST: "{{ .context.inject.env.DB_HOST }}" relève du pipe inter-composants (la valeur provient du provides.host d’un composant cible, acheminée par la déclaration uses[].inject.env.DB_HOST de l’appelant). Les deux formes se compilent en une seule liste Kubernetes env: sur le Deployment rendu ; la sémantique à double source n’existe qu’au moment de la rédaction.
  • attachments fait référence à des slots déclarés dans le featuresSchema du Component ou, en nommant une connexion, à un slot que déclare le socket de cette connexion (voir la section sur l’intégration ci-dessous).
  • ports est une map de ports nommés (web: 8080, admin: 9901) ; les noms de ports correspondent aux noms de ports à portée du conteneur et sont référencés par services.<service>.ports.<portname>. Un port qui utilise un transport autre que celui par défaut de la cible s’écrit plutôt sous la forme développée — voir Protocoles de transport des ports ci-dessous.
  • volumeMounts fait référence par leur nom à des volumes déclarés ailleurs dans la section volumes: du Workload.
  • resources déclare les requests et les limits du conteneur — les quantités cpu et memory, et éventuellement des clés de ressources étendues pour les GPU et d’autres périphériques (voir Charges de travail GPU et périphériques ci-dessous).
  • health utilise la forme d’intention (http: /path, tcp: <port>, exec: [cmd, ...]) — voir la section sur les sondes de santé ci-dessous.

volumes

Chaque volume est d’exactement un type : ephemeral, configmap, secret, persistent ou persistentTemplate. Les types s’excluent mutuellement au sein d’une même déclaration de volume ; chaque type porte ses propres champs obligatoires :

volumes:
app-config:
configmap:
source: "{{ .locals.app_cm }}"
data:
persistent:
size: "10Gi"
class: "gp3"
cache:
ephemeral:
sizeLimit: "1Gi"

persistentTemplate produit un PVC par réplica pour une traduction en forme de StatefulSet ; dans une traduction compose, il se dégrade en un seul volume nommé partagé, avec un avertissement signalé avec le build. Le fichier généré lui-même ne porte aucune mention de cette dégradation — il est identique octet pour octet à ce qu’il serait sans l’avertissement.

Traduction par fournisseur. Chaque fournisseur traduit les cinq variantes de volume dans sa forme native :

VarianteHelm / helm-chart (K8s)ComposeNotes sur les pertes
ephemeralemptyDir: { sizeLimit }entrée tmpfs: au niveau du service nommant le chemin de montage (en mémoire)Le tmpfs de Compose est adossé à la RAM ; l’emptyDir de helm est adossé par défaut au disque du nœud — une divergence sémantique dans le support de stockage sous-jacent. sizeLimit n’atteint aucune partie de la sortie compose : l’entrée émise est le seul chemin de montage. Un sizeLimit écrit par l’auteur déclenche un avertissement unsupported-field qui le nomme, signalé avec le build plutôt qu’écrit dans le fichier généré.
configmapRéférence à un volume ConfigMap (consomme une ressource ConfigMap émise par les artifacts: de la Recipe ou par une Feature)Référence configs: au niveau du service nommant la configmap, montée au chemin du montage de volume ; l’entrée configs: de premier niveau correspondante provient des artifacts: de la RecipeLes deux cibles font référence à la configmap par son nom et aucune ne lit son contenu, de sorte que la forme de rédaction est symétrique. Ce que compose perd, c’est la sémantique de mise à jour lors du rollout de la ConfigMap K8s : une config compose est figée au contenu que le build a émis. Une référence qu’aucune entrée de premier niveau ne résout interrompt le build plutôt que d’émettre un montage qui pointerait dans le vide à l’exécution.
secretRéférence à un volume Secret (consomme le Secret que nomme un rattachement d’identifiants — un Secret que sa FeatureRecipe émet, ou un Secret qui existe déjà)env_file: pour les secrets en forme de variables d’environnement, ou un fichier de secret monté en bind pour les secrets en forme de cheminCompose ne dispose pas d’une sémantique native de Secret Kubernetes. Un secret en forme de chemin ne prend délibérément pas la voie configs: de la variante configmap : une entrée de config inline écrirait la valeur du secret en clair dans le fichier compose émis, et le compilateur ne résout jamais un secret en clair. La source du bind est un chemin que l’opérateur rend accessible sur l’hôte compose, en dehors de tout cycle de vie de CRD de récupération depuis un vault.
persistentRessource PVC + volume.persistentVolumeClaimVolume nomméLes volumes nommés de Compose sont une abstraction plate côté hôte ; le PVC de helm prend en charge la déclaration de la classe de stockage, du mode d’accès et de la capacité, que compose ignore.
persistentTemplateStatefulSet.volumeClaimTemplates (PVC par réplica ; compagnon de form: stateful)Volume nommé (dégradé — un seul volume partagé entre les réplicas, avec un avertissement signalé)Compose ne peut pas exprimer de templates par réplica. Lorsque persistentTemplate est traduit pour compose, un seul volume nommé est émis et la fidélité réduite est signalée par un avertissement avec le build plutôt qu’écrite dans le fichier généré. Les Workloads qui reposent sur l’isolation des volumes par réplica ne devraient pas cibler des frontières uniquement compose.

La forme du contrôleur est choisie par le form de la charge de travail, pas par ses volumes. Un StatefulSet est émis lorsque form: stateful ; un volume persistentTemplate est un compagnon de cette forme — il déclare un stockage par réplica sur une charge de travail qui possède déjà l’identité par réplica que fournit un StatefulSet. Déclarer un volume persistentTemplate sur toute autre forme (ou sur le stateless par défaut) est une erreur au moment du build qui nomme la correction : declare form: stateful. L’inverse est autorisé — une charge de travail form: stateful n’a pas besoin de déclarer de volume persistentTemplate. Les auteurs qui veulent la sémantique d’un StatefulSet définissent directement form: stateful.

Une charge de travail form: stateful sur le fournisseur helm nécessite un Service gouvernant headless : déclarez exactement un service avec type: Headless dans le même Workload. Le fournisseur relie le serviceName du StatefulSet à ce Service headless (il fournit les identités réseau stables par pod dont un StatefulSet a besoin). Le build s’interrompt si aucun service headless n’est déclaré — un StatefulSet n’aurait alors aucun Service gouvernant à nommer — ou si plusieurs le sont, ce qui rend le Service gouvernant ambigu. Une charge de travail StatefulSet peut toujours déclarer des services supplémentaires non headless (par exemple un service ClusterIP pour l’accès des clients) à côté de l’unique service gouvernant headless.

Quantités de ressources

Ces valeurs du Workload sont des quantités — des montants écrits dans la notation que Kubernetes utilise pour les ressources : les valeurs resources.requests et resources.limits d’un conteneur (ou d’un init container) pour cpu, pour memory et pour chaque clé de ressource étendue, ainsi que ephemeral.sizeLimit, persistent.size et persistentTemplate.size d’un volume. Le schéma du Workload type chacune comme une chaîne et n’en contraint pas la forme. Le fournisseur qui synthétise le Workload pour une cible vérifie chaque quantité qu’il émet, et il vérifie le Workload tel que les templates de la Recipe l’ont évalué, de sorte qu’une valeur arrivée par infra, par un paramètre de Release ou par toute autre entrée de template est jugée sur la chaîne produite par son rendu.

Une quantité est, sans rien avant ni après :

  • un signe facultatif, + ou - ;
  • un nombre comportant au moins un chiffre — 2, 0.5, .5 ou 1. ;
  • au plus l’un des deux : un exposant — e ou E, un signe facultatif, puis des chiffres, comme dans 1e3 ou 5E-2 — ou un suffixe d’unité : un suffixe décimal n, u, m, k, M, G, T, P ou E (de 10⁻⁹ à 10¹⁸, par paliers de mille), ou un suffixe binaire Ki, Mi, Gi, Ti, Pi ou Ei (de 1024 à 1024⁶).

500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n et 4u sont des quantités ; lots, 1.5 cores, 1 gigabyte, 10 GB et 1e1.5 n’en sont pas — un exposant est un nombre entier. Un E isolé après le nombre est le suffixe décimal de 10¹⁸ (12E) ; suivi de chiffres, il ouvre un exposant (1E3).

C’est la forme qu’accepte l’analyseur de quantités de Kubernetes lui-même, à une différence délibérée près : une chaîne dont le nombre ne comporte aucun chiffre — m, Ki, +, ., e5 — est refusée, là où Kubernetes la lit comme zéro. Cette chaîne est exactement ce qu’un template laisse derrière lui lorsque la valeur qu’il interpole est vide : "{{ .infra.cpu }}m" avec un cpu vide produit m. La refuser transforme une entrée vide en un arrêt qui nomme le champ, plutôt qu’en une demande de taille nulle que rien ne signale.

Ce que chaque cible fait d’une quantité :

  • helm émet chaque quantité telle quelle, après avoir vérifié chacune par rapport à la forme ci-dessus. Une valeur qui en sort interrompt le build avec une erreur nommant le nœud, le chemin du champ dans le Workload — containers.main.resources.requests.cpu, initContainers[0].resources.limits.memory, volumes.data.persistent.size — et la valeur. Voir Helm Provider → Mode Workload (synthétisé).
  • compose convertit cpu et memory dans ses propres unités à partir de la valeur analysée : cpus devient un nombre décimal de cœurs (500m → 0.5) et memory un nombre exact d’octets (1.5Gi → 1610612736). Une valeur qui n’est pas une quantité interrompt le build, tout comme une quantité que compose ne peut pas représenter exactement — un montant négatif, un montant de mémoire qui n’est pas un nombre entier d’octets (1500m), ou un montant de cpu plus fin que neuf décimales d’un cœur — et l’erreur indique lequel des deux cas elle a rencontré. Un nombre nvidia.com/gpu est lu de la même façon et devient un nombre de périphériques, de sorte qu’un nombre qui n’est pas un nombre entier de périphériques interrompt aussi le build. compose n’émet aucune autre ressource étendue ni aucune taille de volume, il ne vérifie donc ni l’une ni l’autre : toute autre clé de ressource étendue et un ephemeral.sizeLimit sont abandonnés avec un avertissement, et une taille persistante ne façonne rien dans sa sortie. Voir Compose Provider → Ressources des conteneurs.

La vérification ne juge que la forme. Savoir si un cluster peut planifier le montant, ou si le montant convient à son périphérique, ne relève pas d’elle.

services

Une map ordonnée d’expositions de service. Chaque service déclare son type (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — jusqu’où portent ses ports — et une map de ports nommés. Les noms de ports doivent correspondre aux noms des ports de conteneur déclarés ailleurs dans le Workload :

services:
http:
type: ClusterIP
ports:
web: 8080 # must exist in containers.<name>.ports

Plusieurs services sur un même Workload sont courants pour exposer séparément le trafic interne et le trafic externe (ClusterIP interne pour les consommateurs dans le cluster, LoadBalancer pour le trafic externe, ClusterIP pour le scraping Prometheus).

Jusqu’où portent les ports d’un service. Le type l’indique, et chaque cible le rend dans ses propres termes :

typePortéehelmcompose
ClusterIPles pairs de la charge de travail, sur le réseau propre de la cibleun Service de type ClusterIPne publie rien ; les pairs atteignent le port sur le réseau compose
Headlessidem, sans adresse de clusterun Service de type ClusterIP avec clusterIP: Nonene publie rien
NodePortau-delà du réseau propre de la cibleun Service de type NodePortchaque port publié sur toutes les interfaces de l’hôte, sous la forme <service port>:<container port>
LoadBalancerau-delà du réseau propre de la cibleun Service de type LoadBalancercomme pour NodePort
Loopbackuniquement l’adresse de loopback propre à l’hôtearrête le build, en nommant le servicechaque port publié sur l’adresse de loopback IPv4, sous la forme 127.0.0.1:<service port>:<container port>

Le numéro d’un port de service et le port de conteneur qu’il nomme sont deux numéros, comme le sont port et targetPort d’un Service Kubernetes : helm écrit le numéro de l’entrée comme port du Service et cible le port de conteneur par son nom, et compose publie le numéro de l’entrée sur l’hôte vers le numéro du port de conteneur. Lorsque les deux numéros sont égaux, compose écrit ce numéro des deux côtés.

Loopback sert à un port qu’atteint quelque chose sur la même machine — un navigateur ou un agent exécuté sur l’hôte — et que rien d’autre ne devrait atteindre. Sur compose, la liaison se fait sur la seule adresse de loopback IPv4 : l’adresse de loopback IPv6 ::1 n’est pas liée, adressez donc le port par 127.0.0.1 plutôt que par un nom qui pourrait se résoudre en ::1. Un transport déclaré s’écrit sur l’entrée comme sur tout port publié, par exemple 127.0.0.1:5514:5514/udp.

Lorsque deux entrées nomment le même port, la portée la plus large l’emporte : un port qu’une entrée NodePort ou LoadBalancer publie est publié sur toutes les interfaces même lorsqu’une entrée Loopback le nomme aussi, quelle que soit celle des deux qui est déclarée en premier.

Sur helm, une entrée Loopback arrête le build au lieu d’être rendue comme quelque chose qu’elle n’est pas. Un Service Kubernetes n’a aucun type qui se lie à l’adresse de loopback d’un hôte — les adresses de nœud sur lesquelles écoute un Service NodePort sont un réglage de tout le cluster, pas d’un seul Service — si bien qu’un Service ClusterIP abandonnerait la portée que demande l’entrée, et qu’un Service NodePort publierait le port sur toutes les adresses de nœud que le cluster autorise. L’arrêt nomme le nœud et le service ; voir A service type the helm provider cannot render (Un type de service que le fournisseur helm ne peut pas rendre).

Convention de nommage synthétisé. Lorsque le fournisseur helm synthétise les services d’un Workload, le metadata.name de chaque Service est dérivé de manière déterministe du nom que porte le contrôleur propre de la charge de travail et de la clé d’authoring du service. Pour le Workload d’un composant, ce nom est le nom de release du nœud : <release name>-<service-key>. Le nom de release est l’identité du composant écrite dans l’alphabet qu’admet un nom Kubernetes — le même nom contre lequel un chart est rendu, lisible dans les templates d’une Recipe sous la forme {{ .context.rendered_name }} — de sorte qu’il est égal à l’instance_id partout où l’identité ne contient ni tiret bas ni majuscule. Un Workload qui déclare services.http sur le nœud api-server produit un Service nommé api-server-http ; le même Workload sur le nœud billing produit billing-http, et sur le nœud my_api produit my-zuapi-http. Le nom du fichier de sortie suit la même convention : <release name>-<service-key>-service.yaml. Une Recipe qui publie l’adresse d’un tel Service la construit à partir de {{ .context.rendered_name }}, jamais de {{ .context.instance_id }}, qui ne nomme aucun Service partout où les deux diffèrent — voir ../templates/rendered-resource-names.md.

Un Workload que synthétise la FeatureRecipe d’un rattachement de Feature est nommé d’après l’identité composée propre au rattachement plutôt que d’après un nom de release : la valeur que ses ressources portent dans leur label aggrega.ai/component-id, composée du composant hôte et de la clé écrite sous features: derrière le cfr-- initial. Un nom de release dérivé à cet endroit serait celui de l’hôte, et nommerait les ressources du rattachement d’après celles de l’hôte. Ainsi, une FeatureRecipe dont le Workload déclare services.scrape, pour un rattachement stats sur le nœud front-door, produit un Deployment cfr--front-door--stats et un Service cfr--front-door--stats-scrape. Ce premier segment n’est jamais égal à l’instance_id, et aucune clé du contexte de template de la FeatureRecipe ne le contient : dans les templates d’un rattachement, {{ .context.rendered_name }} et {{ .context.instance_id }} nomment tous deux l’hôte (front-door) et {{ .attachment_name }} est la clé seule (stats), de sorte que {{ .context.rendered_name }}-scrape nomme le Service scrape propre à l’hôte là où l’hôte en déclare un, et jamais celui du rattachement — voir ../templates/rendered-resource-names.md. Le fichier de sortie se trouve derrière le préfixe que porte chaque fichier émis par un rattachement — le nom de l’hôte et celui du rattachement, chacun suivi de -- — si bien que ce Service est écrit dans front-door--stats--cfr--front-door--stats-scrape-service.yaml.

La convention a deux conséquences pratiques. D’abord, les collisions entre nœuds sont impossibles par construction — le préfixe du nom distingue les services entre tous les nœuds de la frontière, car deux identités distinctes aboutissent toujours à deux noms de release distincts, l’identité d’un rattachement porte à la fois son hôte et sa clé, et aucun nom de composant ne peut commencer par cfr-- (le build s’arrête sur un nom qui le fait — voir Component identity cannot be stamped on what it emits (L’identité du Component ne peut pas être estampillée sur ce qu’il émet)), de sorte que deux Workloads déclarant chacun services.http produisent des ressources Service K8s distinctes aux noms qui ne se chevauchent pas. Le seul résidu est une identité de rattachement trop longue pour la cible : elle est raccourcie autour d’un condensé de l’ensemble, et deux identités raccourcies peuvent en principe se rencontrer — voir Labels de provenance émis sur la sortie rendue. Ensuite, un Workload ne peut pas déclarer deux fois une même clé de service — une map services: nommant une clé deux fois est refusée lors de l’analyse du YAML du Workload, et le build s’arrête en nommant la clé et sa ligne.

Le risque de collision qui subsiste se situe à la limite de longueur des noms K8s : les noms de Service Kubernetes sont plafonnés à 63 caractères, et la forme synthétisée <release name>-<service-key> peut dépasser cette limite lorsque les deux segments sont longs. Le compilateur Aggrega n’impose pas la limite ; le build émet le Service, et Kubernetes le rejette lorsqu’il est appliqué. Les auteurs dont les ID d’instance sont profondément imbriqués (p. ex. data-layer.regional.eu-west.primary) et les clés de service longues devraient maintenir la longueur combinée sous 63 caractères. Il en va de même pour le Workload d’un rattachement : une identité composée trop longue pour la cible est raccourcie, mais la clé de service qui lui est ajoutée ne l’est pas, de sorte qu’un Service de rattachement portant une clé longue peut tout de même dépasser 63 caractères et être construit sans arrêt.

Note spécifique au Provider (compose). Le fournisseur compose dérive depends_on automatiquement des arêtes uses de l’IR. Ces entrées sont émises sans condition — elles portent la sémantique service_started, que la cible déclare ou non un healthcheck — de sorte qu’un service dont toutes les dépendances proviennent d’arêtes uses émet la liste en forme courte (depends_on: [<target>]). Conditionner une entrée dérivée d’une arête à la santé de la cible n’est pas implémenté. La forme longue est émise là où une entrée porte bien une condition, et c’est ainsi que s’exprime une attente sur un conteneur d’initialisation ; voir providers/compose.md.

Protocoles de transport des ports

Un port de conteneur s’écrit sous l’une de deux formes équivalentes. Le nombre seul est la forme courte et ne déclare aucun transport, si bien que la cible applique sa propre valeur par défaut — TCP sur toute cible qui en a une :

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080

La forme développée porte ensemble le numéro et le transport, et c’est ce dont un port a besoin lorsqu’il transporte autre chose que cette valeur par défaut :

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080 # short form — no transport declared
dns:
port: 53
protocol: UDP # TCP | UDP | SCTP
sigtran:
port: 2905
protocol: SCTP

Les deux formes peuvent être librement mélangées dans une même map ports, et un port sans transport à déclarer reste sous la forme courte.

Le transport se déclare une seule fois, sur le port de conteneur. Une entrée services.<service>.ports nomme un port de conteneur et en reprend le transport, de sorte qu’une exposition de service ne peut pas contredire le port qu’a ouvert le conteneur. Il n’existe pas de clé protocol sur un port de service, et en écrire une est refusé.

Pourquoi ce champ existe. Les cibles de déploiement traitent un transport non spécifié comme le transport en flux. Un composant qui a besoin d’un port datagramme — médias en temps réel, téléphonie, résolution de noms, réseau privé, serveur de jeu — ne pourrait sinon déclarer que le numéro, et la pile serait déployée en passant tous les contrôles sans qu’aucun client ne se connecte, car le trafic est en datagrammes et le port ouvert ne l’est pas. Déclarer le transport est ce qui rend cela exprimable.

Le compilateur n’interprète pas la valeur. Il ne déduit aucun transport du nom d’un port et ne vérifie pas le transport déclaré par rapport à ce que parle réellement le processus derrière le port : la valeur est une donnée que vous déclarez et que le moteur de la cible émet. Un port nommé dns sans clé protocol est un port TCP, et un port nommé web déclarant protocol: UDP est un port UDP.

Comportement par cible.

CibleUn port sans transport déclaréUn transport déclaré
helmcontainerPort et le port du Service ne portent aucune clé protocolémis tel quel comme protocol: sur le port de conteneur et sur chaque port de Service qui le nomme
composepublié sous la forme <host>:<container>, inchangépublié sous la forme <host>:<container>/tcp ou /udp ; SCTP n’a pas d’écriture compose et arrête le build plutôt que de publier un port qui porterait un autre transport

Un port de conteneur qu’aucun service ne publie n’atteint aucune partie d’un fichier compose — c’est le comportement habituel de compose pour les ports de conteneur — de sorte qu’un transport déclaré sur un tel port n’a nulle part où s’écrire et ne provoque pas d’arrêt.

Sondes de santé — forme d’intention

Chaque conteneur déclare ses sondes sous sa propre clé health: (containers.<name>.health), dans une forme d’intention abstraite ; le Workload n’a pas de health de premier niveau. Chaque fournisseur traduit l’intention dans sa forme de sonde native au moment de la synthèse.

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Trois formes d’intention (http:, tcp:, exec:) s’excluent mutuellement au sein d’une même déclaration de sonde. La résolution du port pour http: sans port explicite prend le premier nom de port, dans l’ordre alphabétique, que le conteneur déclare sous containers.<name>.ports — la même règle sur les deux cibles, de sorte qu’une sonde lit le même port quelle que soit celle qui la rend. Un conteneur qui ne déclare aucun port nommé ne peut pas porter de sonde HTTP : le build s’arrête avec une erreur de traduction nommant la sonde en cause.

Traduction par fournisseur. Chaque fournisseur traduit l’intention de sonde abstraite dans sa forme native au moment de la synthèse :

IntentionHelm (K8s)ComposeNotes sur les pertes
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"Compose n’a pas de forme native de sonde HTTP ; l’enveloppe CMD-SHELL suppose que curl est présent dans l’image du conteneur.
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"Compose n’a pas de forme native de sonde TCP ; l’enveloppe CMD-SHELL suppose que nc est présent dans l’image du conteneur.
exec: [cmd, ...]exec.command: [cmd, ...]CMD [cmd, ...]Correspondance un pour un ; les deux fournisseurs reprennent la liste de commandes telle quelle.

Les enveloppes CMD-SHELL de Compose approchent les sondes HTTP et TCP au moyen de prédicats évaluables par le shell. Ce qui manque à compose, c’est la forme de sonde native, pas les champs de temporisation : les periodSeconds, timeoutSeconds, failureThreshold et initialDelaySeconds écrits par l’auteur sont reportés sur le healthcheck sous la forme interval, timeout, retries et start_period — la section « Sondes » de providers/compose.md donne la correspondance champ par champ. La forme native exec: n’a besoin d’aucune enveloppe et se traduit un pour un sur les deux cibles.

Une sonde enveloppée est traduite silencieusement : rien dans le docker-compose.yaml émis ne la signale, et aucun diagnostic ne rapporte l’enveloppement. Ce que le build rapporte bien sur ce chemin, c’est un emplacement de sonde qui n’atteint aucune sortie — un service compose porte un seul healthcheck, si bien que là où un Workload déclare plus d’un de ready:, live: et startup:, seul l’emplacement préféré est traduit (live avant ready avant startup) et un avertissement unsupported-field nomme l’emplacement traduit et les emplacements abandonnés.

Note spécifique au Provider (compose). Écrire un bloc health: sur un Workload ciblant compose ne conditionne pas l’ordre depends_on à la santé : les entrées depends_on du fournisseur compose dérivées des arêtes uses: utilisent toujours la sémantique service_started, que le Workload cible déclare ou non des sondes de santé. Conditionner ces entrées à la santé de la cible n’est pas implémenté — la forme longue qui porterait une telle condition est elle-même émise, pour les attentes sur les conteneurs d’initialisation, de sorte que ce qui manque est le choix de conditionner une arête à la santé, et non la forme pour l’exprimer. Voir providers/compose.md pour l’ensemble des règles d’inférence.

Champs transmis tels quels au format K8s — scheduling, serviceAccount, podSecurityContext

Le schéma Workload accepte trois champs facultatifs de premier niveau qui existent principalement pour faire passer des primitives natives de Kubernetes à travers le fournisseur helm tout en préservant la forme structurelle d’Aggrega. Le fournisseur compose traduit le sous-ensemble qui a un équivalent Compose et ignore le reste en émettant un avertissement. Aggrega valide la forme externe mais ne contrôle pas le contenu interne (voir Surface de validation ci-dessous) — les valeurs internes natives de K8s sont transmises telles quelles au pod spec rendu par helm.

scheduling

scheduling regroupe quatre primitives d’ordonnancement natives de K8s — nodeSelector, affinity, tolerations, topologySpreadConstraints — en un seul bloc organisé par finalité. Chaque sous-champ a exactement la forme du champ de pod spec Kubernetes correspondant :

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
nodeSelector:
disktype: ssd
region: us-east-1
tolerations:
- key: dedicated
operator: Equal
value: gpu-workloads
effect: NoSchedule
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels: { app: "{{ .context.instance_id }}" }
topologyKey: kubernetes.io/hostname
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
containers:
app: { image: "..." }

Traduction par le Provider. Le fournisseur helm transmet chaque sous-champ tel quel dans le pod spec rendu. Le fournisseur compose ne traduit aucun des quatre : il omet tout le bloc scheduling, et un avertissement le nomme.

serviceAccount

serviceAccount est une simple chaîne portant le nom du ServiceAccount sous lequel s’exécute la charge de travail :

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .context.rendered_name }}-runner"
containers:
app: { image: "..." }

Le nom est construit à partir de {{ .context.rendered_name }}, le nom de release d’après lequel le fournisseur helm nomme les ressources propres de la charge de travail, de sorte que c’est un nom que le cluster accepte quel que soit le nom du composant. Le champ référence un ServiceAccount existant ; il n’en crée pas. Les ressources RBAC associées (l’objet ServiceAccount lui-même, plus Role / RoleBinding / ClusterRole / ClusterRoleBinding) devraient être livrées par l’un de deux canaux :

  • artifacts: de la Recipe — lorsque le RBAC est intrinsèque à cette Recipe (la Recipe sait qu’elle a besoin d’un Role précis pour une tâche précise).
  • Features avec génération de ressources — lorsque le RBAC est transversal (une FeatureRecipe Workload-Identity qui rattache des ServiceAccounts liés à IAM à chaque composant portant un label donné).

Définir serviceAccount: sans faire en sorte que le ServiceAccount nommé existe produit une erreur K8s à l’exécution, au moment de l’application, et non une erreur au build — la validation du schéma de la charge de travail ne vérifie pas l’existence du ServiceAccount (aucun accès à l’état du cluster à la compilation, selon l’invariant de pureté AOT).

Le fournisseur compose ignore serviceAccount: avec un avertissement ; Compose n’a pas de concept équivalent de liaison d’identité.

podSecurityContext

podSecurityContext porte des primitives de sécurité au niveau du pod — UID, GID, fsGroup, supplementalGroups — qui s’appliquent à chaque conteneur du pod :

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
supplementalGroups: [4000, 5000]
containers:
app: { image: "..." }

Sémantique des champs. Les quatre champs sont des entiers (UID/GID numériques, pas des chaînes) ; runAsUser et runAsGroup définissent l’UID/GID effectif des processus du conteneur ; fsGroup définit le groupe propriétaire des volumes montés dans le pod ; supplementalGroups ajoute des GID supplémentaires au groupe de processus de chaque conteneur.

Traduction par le Provider. Le fournisseur helm transmet le bloc tel quel dans le pod spec rendu. Le fournisseur compose n’a pas d’équivalent pour fsGroup ni supplementalGroups et omet chacun avec un avertissement ; runAsUser/runAsGroup se traduisent par la forme Compose user: 1000:3000 sur chaque service que produit le Workload, sidecars et conteneurs d’initialisation compris, et un runAsGroup sans runAsUser à côté est omis avec un avertissement. Chaque conteneur et conteneur d’initialisation porte aussi son propre securityContext — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation, et capabilities.add / capabilities.drop. Le fournisseur helm l’émet sur le conteneur ; le fournisseur compose émet readOnlyRootFilesystem comme read_only, capabilities.add / capabilities.drop comme cap_add / cap_drop, et runAsUser / runAsGroup comme le user propre du conteneur, qui prend la place de celui du pod ; il omet runAsNonRoot, allowPrivilegeEscalation et un runAsGroup écrit sans runAsUser, avec un avertissement chacun, et avertit aussi lorsque le runAsUser propre d’un conteneur laisse de côté le runAsGroup du pod. providers/compose.md donne la correspondance champ par champ.

Charges de travail GPU et à périphériques

Une charge de travail qui a besoin de matériel spécialisé — un GPU, ou un autre périphérique fourni par un fabricant — exprime deux préoccupations indépendantes : le runtime au niveau du pod qu’expose le nœud équipé du périphérique (runtimeClassName), et la quantité du périphérique, par conteneur, que réclame la charge de travail (une clé de ressource étendue sous resources d’un conteneur). Une charge de travail GPU typique déclare les deux ensemble, mais chacune tient seule et l’une peut apparaître sans l’autre.

Les deux champs décrivent du calcul — le pod et le conteneur qui s’exécute sur le périphérique — et ont donc leur place sur une charge de travail qui exécute des conteneurs. Une charge de travail qui ne porte qu’un point de terminaison externe et ne déclare aucun conteneur propre n’a ni pod ni conteneur auquel les rattacher : définir runtimeClassName sur une telle charge de travail limitée à un point de terminaison arrête le build, en nommant runtimeClassName et la Recipe dont le Workload l’a déclaré, et sans conteneur il n’y a nulle part où placer une demande de ressource de périphérique.

runtimeClassName

runtimeClassName est une chaîne unique nommant la RuntimeClass sous laquelle s’exécute le pod — le runtime de conteneurs qu’expose un nœud équipé d’un périphérique, par exemple un runtime GPU nommé nvidia. C’est un sélecteur au niveau du pod : il s’applique à chaque conteneur de la charge de travail. Le compilateur transmet le nom tel quel comme pointeur déterministe ; le cluster le résout, au moment de l’ordonnancement, en une RuntimeClass que son administrateur a configurée. Aggrega ne vérifie pas qu’une RuntimeClass correspondante existe — il n’a pas accès à l’état du cluster à la compilation — de sorte qu’un nom sans RuntimeClass configurée se manifeste par une erreur d’ordonnancement au moment de l’application, et non par une erreur au build.

Clés de ressources étendues

Les resources.requests et resources.limits d’un conteneur portent les quantités ordinaires cpu et memory et, à côté d’elles, des clés de ressources étendues : des quantités de périphériques propres à un fabricant ou à un domaine, désignées par un nom pleinement qualifié <domain>/<name> tel que nvidia.com/gpu ou amd.com/gpu. Le segment de domaine contient au moins un point, et c’est ce point qui distingue une clé étendue (nvidia.com/gpu) des quantités simples cpu et memory. Chaque valeur est une quantité sous forme de chaîne ("1", "2") que le compilateur transmet telle quelle, et le fournisseur helm en vérifie la forme avant de l’émettre (voir Quantités de ressources) ; le device plugin du cluster résout et alloue le périphérique au moment de l’ordonnancement.

Exemple détaillé — une charge de travail d’inférence GPU

apiVersion: aggrega.ai/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

La charge de travail sélectionne le runtime nvidia pour son pod et réclame un GPU pour le conteneur inference. La quantité de GPU apparaît à la fois dans requests et dans limits : un périphérique ne peut pas être sursouscrit, donc sa demande et sa limite sont fixées à la même valeur.

Traduction par le Provider. Ce sont des concepts natifs de Kubernetes. Le fournisseur helm émet runtimeClassName sur le pod spec rendu et chaque clé de ressource étendue telle quelle sous resources.requests / resources.limits du conteneur, de sorte qu’elles atteignent le cluster par la sortie Kubernetes. Le fournisseur compose réserve un nombre nvidia.com/gpu comme autant de GPU NVIDIA sur le service du conteneur (voir Compose Provider → Ressources des conteneurs) ; un hôte unique n’a aucun concept de runtime class ni d’équivalent pour toute autre clé de ressource étendue, de sorte qu’une charge de travail qui déclare runtimeClassName ou une autre clé est rendue sur une cible compose sans elle.

Exécution sur le réseau du nœud

Par défaut, une charge de travail s’exécute dans un espace de noms réseau qui lui est propre : ses conteneurs ne voient que leurs propres interfaces, et le trafic les atteint au travers de la traduction d’adresses de la cible. hostNetwork: true demande l’autre disposition — la charge de travail s’exécute dans l’espace de noms réseau du nœud lui-même, de sorte qu’elle voit les interfaces du nœud et que les ports ouverts par ses conteneurs sont joignables sur les propres adresses du nœud, sans aucune traduction intermédiaire.

C’est ce dont toute une classe de logiciels a besoin. Les médias en temps réel, la téléphonie, les réseaux privés virtuels et les trafics similaires transportent l’adresse du pair dans la charge utile, si bien qu’une adresse réécrite en transit arrive en décrivant un endroit que le pair ne peut pas atteindre ; s’exécuter sur les adresses du nœud est ce qui maintient la cohérence entre les deux.

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

Ce qu’il déclare, et ce qu’il ne déclare pas

hostNetwork choisit un espace de noms réseau, et c’est tout.

  • Il ne déclare aucun port. Les ports qu’ouvre une charge de travail se déclarent toujours sous containers.<name>.ports, exactement comme sans lui, et ils signifient toujours la même chose. Déclarer hostNetwork n’ajoute aucun port et ne supprime pas la nécessité d’en déclarer un.
  • Il ne déclare aucun nombre de ports. Une application qui veut de nombreux ports contigus — un serveur multimédia qui dimensionne une plage selon le nombre de processeurs d’une machine, par exemple — configure cette plage dans son propre contenu de configuration, à partir de valeurs que fournit son exploitant, de la même manière qu’elle configure tout ce qu’elle lit au démarrage. Il s’agit d’un réglage de l’application et non de la charge de travail, et ce n’est pas dans le contrat de la charge de travail qu’il se trouve.
  • Rien n’est déduit. Le compilateur ne lit aucune signification dans la valeur et ne la tire de rien d’autre : ni du nom d’un port, ni du type ou des labels d’un composant, ni du nombre de ports déclarés. Une charge de travail s’exécute sur le réseau du nœud quand, et seulement quand, elle le dit.

Comme il décrit des ressources de calcul, hostNetwork a sa place sur une charge de travail qui exécute des conteneurs. Une charge de travail qui ne porte qu’un point de terminaison externe ne déclare aucun conteneur et n’a donc aucun espace de noms réseau à choisir : déclarer hostNetwork sur une charge de travail limitée à un point de terminaison interrompt la compilation, en nommant hostNetwork et la Recipe dont le Workload l’a déclaré.

Traduction par le Provider

Le fournisseur helm émet hostNetwork: true dans la spécification de pod rendue, ce qui est la manière dont Kubernetes exprime le même choix. La déclaration atteint la spécification de pod et rien d’autre — les Services émis sont identiques avec et sans elle.

Le fournisseur compose émet network_mode: host sur le service propre de la charge de travail. Une conséquence découle de la manière dont compose modélise les réseaux : un service dans ce mode n’est pas rattaché au réseau de la frontière, car compose traite le rattachement à un réseau et l’adoption de l’espace de noms de l’hôte comme des alternatives plutôt que comme des ajouts. Ses pairs l’atteignent donc sur les propres adresses de l’hôte plutôt que par le nom du service — ce que signifie le réseau de l’hôte sur n’importe quelle cible — et tous les autres services de la frontière ne sont pas affectés.

Deux formes se combinent avec lui sur cette cible. Un conteneur sidecar suit le service principal sur le réseau de l’hôte sans rien déclarer, car il prend l’espace de noms du service principal en le nommant. Un conteneur d’initialisation ne le fait pas : il devient un service que le service principal attend, et rejoint donc le réseau de la frontière de plein droit plutôt que d’adopter un espace de noms qui rendrait cette attente circulaire. Une charge de travail qui déclare à la fois hostNetwork et initContainers exécute donc son propre service sur le réseau du nœud tandis que ses services d’initialisation restent sur le réseau de la frontière — une disposition plus étroite que l’espace de noms unique partagé qu’offre la forme pod, et que le fournisseur compose signale dans un avertissement unsupported-field plutôt que de la laisser se découvrir à l’exécution.

Une charge de travail qui ne déclare pas hostNetwork ne porte aucune clé de ce type dans sa sortie : la clé est absente plutôt qu’émise avec la valeur false.

Intégration des rattachements avec le featuresSchema du Component

Le bloc containers.<name>.attachments du Workload référence des emplacements d’identifiants déclarés dans le featuresSchema du Component — ou, pour une entrée qui nomme une connexion, un emplacement que déclare le socket de cette connexion (voir Livrer un identifiant que porte une connexion) ; il ne déclare pas de nouveaux emplacements. Voir ../entities/component.md pour la surface de rédaction de featuresSchema. from nomme l’emplacement ; ce n’est pas le nom du Secret généré.

Une entrée containers.<name>.attachments est rendue en une référence à une ressource Secret — un secretKeyRef Kubernetes (pour as: env) ou un volume adossé à un secret (pour as: file) — qui pointent tous deux vers le Secret par son nom. Le synthétiseur résout ce nom et la clé de données à partir des provides exposés de l’emplacement : le secretKeyRef.name rendu de l’entrée est le .features.<slot>.provides.name de l’emplacement et la clé de données est .features.<slot>.provides.key. L’auteur de la Recipe n’écrit que from: <slot> et as: env ; le synthétiseur lit les provides résolus — il ne redérive pas le nom. C’est la même lecture .features.<slot>.provides.<key> qu’une Recipe source utilise pour un existingSecret : un seul emplacement d’identifiant alimente de manière identique un consommateur Recipe source et un consommateur Workload synthétisé (symétrie source/workload).

Quatre règles de validation régissent l’intégration :

  • Chaque valeur attachments.<KEY>.from doit correspondre à un nom d’emplacement déclaré dans le featuresSchema du Component — ou, sur une entrée qui nomme une connexion, dans le socket de cette connexion. Un nom d’emplacement inconnu est une erreur au chargement.
  • Le mécanisme de livraison as: (env ou file) doit figurer dans la liste d’autorisation inject: de l’emplacement déclarée par le Component. Un Workload qui déclare as: file pour un emplacement dont l’entrée featuresSchema spécifie inject: [env] est une erreur au chargement.
  • Les emplacements marqués inject: [] (livraison en boîte noire) dans le featuresSchema du Component ne peuvent pas du tout apparaître dans les blocs attachments: d’un Workload. Ces emplacements sont livrés par la tuyauterie interne de la Recipe (le paramètre existingSecret d’un chart Helm, par exemple), et non par l’exposition dans le Workload.
  • L’emplacement référencé doit être référençable — son remplissage doit publier un localisateur provides (name, key) pour une ressource Secret, une que sa réalisation émet ou une qui existe déjà. Un emplacement rempli par un identifiant livré par inject (qui écrit une valeur dans le canal d’inject et ne publie aucun localisateur) n’a rien vers quoi pointer ; le référencer depuis une entrée attachments: d’un Workload est une erreur au chargement. Un identifiant livré par inject atteint le conteneur par le canal d’inject de l’emplacement (une entrée variables qui lit .context.inject.env.<KEY>), et non par une entrée attachments:.

Note sur le Provider. Helm rend la référence secretKeyRef/volume secret décrite ci-dessus. Le fournisseur compose n’a pas de primitive native d’environnement depuis un secret ; une entrée de rattachement as: env sur un Workload ciblant compose est rendue comme une entrée d’environnement avec une valeur vide et un avertissement qui nomme l’entrée (voir la page du fournisseur compose), tandis que la règle de référençabilité (agnostique vis-à-vis des capacités) continue de s’appliquer.

Exemple :

# In the Component catalog entity
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe's Workload
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected at load time: blackbox slot

Livrer un identifiant que porte une connexion

Le socket d’un Component peut déclarer, dans usesSchema.<socket>.featuresSchema, les emplacements que remplit chaque connexion câblée par son intermédiaire — de sorte qu’un composant qui atteint plusieurs cibles détient un identifiant par connexion plutôt qu’un seul pour toutes. Un tel rattachement ne fait pas partie des .features propres du composant ; il se trouve sous sa connexion, dans .context.uses.<alias>.features.<slot>. Une entrée du Workload le livre en nommant la connexion à côté de l’emplacement :

  • sur une entrée attachments d’un conteneur, connection: <alias> à côté de from: <slot> ;
  • sur une entrée envFrom d’un conteneur, connection: <alias> à côté de secret: <slot> — connection n’est accepté qu’à côté de secret.

Les deux formes sont acceptées sur chaque conteneur et chaque conteneur d’initialisation. <alias> est le nom sous lequel la connexion est écrite dans le bloc uses du composant, dans l’Aggregate ou dans la Release — la clé par laquelle une Recipe lit la connexion sous .context.uses — et <slot> est un emplacement que déclare le socket par lequel cette connexion est câblée.

Avant qu’une règle ci-dessus ne lise le Workload, chaque entrée qui nomme une connexion est réécrite sur le nom que prend sur le composant le rattachement que porte cette connexion dans cet emplacement : l’alias, un point et l’emplacement (gpt.credential). Chaque règle s’exécute ensuite sur l’entrée réécrite exactement comme sur une entrée qui nomme l’un des emplacements propres du Component : la liste d’autorisation inject: de l’emplacement du socket régit as:, un emplacement de socket qui déclare inject: [] ne peut pas être référencé, le rattachement qui le remplit doit être référençable, et le fournisseur résout le nom du Secret et la clé de données à partir des provides résolus de ce rattachement — de sorte que l’entrée de chaque connexion référence l’identifiant propre à cette connexion. Un emplacement de socket qui déclare sensitive: true est lu pour l’entrée exactement comme l’est la déclaration d’un emplacement du Component. L’entrée réécrite est ce que reçoit le fournisseur ; la clé connection ne l’atteint pas.

Trois entrées sont refusées, chacune en nommant ce qu’elle nommait :

  • une entrée qui nomme une connexion que le composant ne trace pas — le refus nomme la connexion, l’emplacement et les connexions que trace le composant ;
  • une entrée qui nomme un emplacement que le socket de la connexion ne déclare pas — le refus nomme l’emplacement, la connexion, le socket et les emplacements qu’il déclare ;
  • une entrée qui écrit elle-même le nom composé (from: gpt.credential). L’emplacement d’une connexion se nomme en nommant la connexion, de sorte que le nom composé n’est jamais une seconde manière de l’atteindre.

Une connexion qui ne porte aucun rattachement dans l’emplacement laisse l’entrée sans rien à référencer, et la règle de référençabilité la refuse. Un Workload que rend une FeatureRecipe est limité aux emplacements que déclare la Feature qu’elle implémente, lesquels n’atteignent aucune des connexions du composant hôte ; une entrée qui y nomme une connexion est donc refusée comme nommant une connexion que le composant ne trace pas.

Exemple :

# In the Component catalog entity
spec:
usesSchema:
models:
featuresSchema:
credential:
sensitive: true
inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`
# through the `models` socket, each carrying its own `credential`
workload: |
containers:
main:
attachments:
MODEL_KEY_GPT:
from: credential
connection: gpt
as: env
MODEL_KEY_NIM:
from: credential
connection: nim
as: env

Sur helm, MODEL_KEY_GPT est rendu comme un secretKeyRef qui nomme le Secret qu’a publié l’identifiant de la connexion gpt, et MODEL_KEY_NIM celui qu’a publié l’identifiant de la connexion nim. Sur compose, une entrée as: env qui nomme une connexion est émise avec une valeur vide et le même avis de prise en charge partielle que reçoit une entrée qui nomme l’un des emplacements propres du Component.

Surface de validation

Chaque Workload est validé au chargement de la Recipe, avant qu’aucun rendu ne s’exécute. La validation comporte deux étapes :

  • Validation du schéma. La valeur du Workload est unifiée avec le schéma Workload aggrega.ai/v1beta1 embarqué. Les erreurs indiquent le chemin du champ et la contrainte violée (par exemple, .containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). La validation du schéma impose chaque type, énumération, plage et disjonction déclarés dans le schéma — y compris le form de contrôleur à ensemble fermé (l’un de stateless, stateful, daemon, scheduled, task, reference), le type de service à ensemble fermé (l’un de ClusterIP, Headless, NodePort, LoadBalancer, Loopback), la plage entière de ports (1..65535), la disjonction de forme de sonde (exactement l’un de http, tcp, exec) et la disjonction de variante de volume (exactement l’un de ephemeral, configmap, secret, persistent, persistentTemplate).
  • Validation des références croisées. Les références de rattachement du Workload sont vérifiées par rapport au featuresSchema du Component — et, pour une entrée qui nomme une connexion, par rapport aux emplacements que déclare le socket de cette connexion — (appartenance à l’emplacement, liste d’autorisation de livraison as:, exclusion boîte noire) et par rapport aux provides résolus de chaque emplacement référencé (référençabilité — le remplissage doit publier name/key). Ce sont des vérifications inter-entités qu’une validation fondée uniquement sur le schéma ne peut pas effectuer.

Les deux étapes produisent la même forme de message préfixée par CATALOG_ERROR ; les échecs arrêtent la compilation avant que toute sortie de rendu ne soit produite. Les auteurs de Recipe reçoivent un retour ciblé qui identifie le champ exact en échec et la contrainte qui l’a rejeté.

Les champs transmis tels quels de forme K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, les listes items à l’intérieur des volumes ConfigMap et Secret, les hooks de cycle de vie httpGet) ne sont validés que structurellement — le schéma d’Aggrega contraint leur présence et leur forme externe, mais la forme interne de ces valeurs définies par l’API K8s relève de la responsabilité du fournisseur (le fournisseur helm les transmet tels quels à la spécification de pod K8s ; le fournisseur compose les rejette ou les dégrade selon le cas). Un Workload qui utilise une valeur affinity mal formée passe la validation d’Aggrega, et l’erreur se manifeste plutôt pendant la synthèse par le fournisseur.

Les quantités de ressources sont de la même façon des chaînes pour le schéma : aucune des deux étapes ne vérifie leur forme. C’est le fournisseur qui synthétise qui le fait, sur le Workload évalué, et il s’arrête sur une valeur hors de la forme de quantité — voir Quantités de ressources.

Les ressources auxiliaires ont leur place hors du Workload

Le Workload décrit uniquement la forme de la charge de travail — conteneurs, volumes, services, réplicas, ordonnancement, contexte de sécurité, compte de service. Il ne comporte aucun champ additionalResources ni aucune déclaration inline de ConfigMap / Secret / CRD.

Les auteurs de Recipe émettent les ressources auxiliaires par deux canaux extérieurs au Workload :

  • artifacts: au niveau de la Recipe — pour les ressources propres à cette Recipe (une ConfigMap spécifique que référence le Workload de la Recipe, un enregistrement ponctuel de CRD dont la Recipe a besoin). Le champ est une map d’entrées nommées ; chaque entrée est écrite inline ou chargée par un $import: par entrée. Voir la section sur le mécanisme des artefacts dans ../../architecture/16-recipe-input-composition.md pour les trois modes de rédaction.
  • Features avec génération de ressources — pour les préoccupations transversales rattachées par les sélecteurs de la Release (une Feature ServiceMonitor rattachée à chaque composant exposant des métriques, une Feature NetworkPolicy rattachée à chaque charge de travail de production). Voir ../entities/featurerecipe.md pour la surface de rédaction de la FeatureRecipe.

Le Workload reste concentré sur la forme de la charge de travail ; les manifestes auxiliaires transversaux et ceux propres à la Recipe ont leurs propres lieux de rédaction.

Modèles courants de Workload

Le schéma Workload est vaste — il couvre les serveurs HTTP à conteneur unique, les modèles sidecar multi-conteneurs, les chaînes de conteneurs d’initialisation, les jobs batch et les services avec état dotés de volumes persistants. Trois modèles reviennent assez souvent pour qu’écrire le code de base à partir de zéro pour chaque Recipe soit du gaspillage. Les blocs ci-dessous sont des gabarits à copier-coller que les auteurs de Recipe peuvent adapter à des composants spécifiques.

Un modèle que partagent plusieurs Recipes peut être publié une fois comme entrée d’une WorkloadLibrary et importé avec $import: <Library>#/workloads/<entry> ; les gabarits présentés ici sont des points de départ à adapter, ou à publier de cette manière.

Modèle 1 — Serveur avec exposition de métriques

Une application web typique qui sert le trafic applicatif sur un port et expose des métriques collectées par Prometheus sur un port distinct. Deux services dans le Workload — l’un pour l’application, l’autre pour les métriques — permettent de séparer proprement la politique du service mesh et la configuration de l’équilibreur de charge.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
metrics: {{ optional .values `metrics_port` 9090 }}
variables:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"
health:
ready:
http: /healthz
timeoutSeconds: 5
live:
http: /healthz
timeoutSeconds: 5
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}
metrics:
type: ClusterIP
ports:
metrics: {{ optional .values `metrics_port` 9090 }}

Le service de métriques est généralement annoté pour la découverte par Prometheus au moyen d’un rattachement de Feature sur la surface de la Release (par ex. feature.aggrega.ai/prometheus-scrape: "true") ; le Workload lui-même reste exempt d’annotations de collecte propres au fournisseur.

Modèle 2 — Job batch

Une charge de travail qui s’exécute jusqu’à son terme plutôt que de servir du trafic indéfiniment. Le modèle définit form: task, omet entièrement services: — les jobs batch n’exposent pas de ports — et s’appuie sur la forme de tâche du fournisseur cible (un Job Kubernetes sur le fournisseur helm ; le fournisseur compose n’a pas de forme de tâche et s’arrête sur form: task). Le fournisseur helm fixe une restartPolicy de pod valide pour un Job (Never sauf si le conteneur déclare OnFailure), car un pod de Job ne peut pas utiliser la valeur par défaut Always.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]
args:
- "--config"
- "/etc/config/job.yaml"
variables:
JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}"
volumeMounts:
- name: config
path: /etc/config
volumes:
config:
configmap:
source: "{{ .context.instance_id }}-config"

Le volume de configuration référence une ConfigMap que la Recipe est censée émettre à côté du Workload via artifacts: (voir « Les ressources auxiliaires ont leur place hors du Workload » ci-dessus) — le Workload lui-même ne déclare que le côté consommation. L’identité la nomme sur un fournisseur qui nomme la charge de travail d’après l’identité, comme le fait compose ; sous helm, qui nomme les ressources de la charge de travail d’après le nom de release, construisez plutôt le nom de la ConfigMap — ici et dans l’artefact — à partir de {{ .context.rendered_name }}, afin que ce soit un nom que le cluster accepte, quel que soit le nom du composant.

Modèle 3 — Paire avec sidecar

Un pod à deux conteneurs dans lequel le conteneur principal gère la logique applicative et le sidecar gère une préoccupation transversale (terminaison TLS, expédition des journaux, proxy de service mesh, garde-fou d’IA). L’ordre de rédaction dans containers: est déterminant — le fournisseur helm émet les conteneurs dans l’ordre déclaré ; la première clé (ici, main) est le conteneur cible par défaut de kubectl logs et des outils similaires.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
main:
image: "{{ .values.app_image }}"
ports:
app: {{ optional .values `app_port` 8080 }}
variables:
UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}"
sidecar:
image: "{{ .values.sidecar_image }}"
ports:
proxy: {{ optional .values `proxy_port` 9000 }}
variables:
PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"
services:
external:
type: ClusterIP
ports:
proxy: {{ optional .values `proxy_port` 9000 }}

Le Service expose le port du sidecar (et non celui du conteneur principal), en acheminant le trafic externe à travers le sidecar vers le conteneur principal via localhost. Les deux conteneurs partagent l’espace de noms réseau du pod, de sorte que localhost:<port> atteint directement le conteneur pair. Pour les sidecars qui ont besoin d’une injection d’identifiants (le modèle canonique du garde-fou d’IA), l’identifiant se trouve généralement dans le bloc attachments: du sidecar plutôt que dans celui du conteneur principal — ce qui limite l’identifiant au périmètre du processus du sidecar.

Choix du modèle

Les trois modèles correspondent à des préoccupations distinctes de forme de livraison :

  • Serveur avec métriques — services de longue durée que le cluster maintient actifs ; plusieurs expositions de Service pour séparer le trafic.
  • Job batch — exécution bornée ; aucune exposition de Service ; s’appuie sur une ConfigMap émise par la Recipe ou sur un état externe pour ses entrées.
  • Paire avec sidecar — pod multi-conteneurs avec un espace de noms réseau partagé ; le Service du sidecar expose la préoccupation transversale.

Un quatrième modèle — serveur avec état et volume persistant — définit form: stateful et déclare un stockage par réplica via volumes.<name>.persistentTemplate ; le fournisseur helm émet un StatefulSet pour la forme avec état (voir providers/helm.md). Le modèle a une forme identique à « serveur avec métriques » avec form: stateful, un volume persistentTemplate supplémentaire et exactement un service type: Headless qui gouverne le StatefulSet (la compilation s’arrête sans lui) ; les auteurs qui en ont besoin adaptent le Modèle 1 avec les trois déclarations.

Références croisées