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

Composition des entrées d’une Recipe — trois types d’entrées, Workload, artefacts

Une Recipe produit des fichiers de manifeste pour son fournisseur cible. Ce chapitre décrit comment les Recipes composent leur sortie à partir de trois types d’entrées orthogonaux — sourced, synthesized et artifacts —, comment chaque type d’entrée est structuré et quel fournisseur produit quelle sortie. Le rôle conceptuel de l’entité Recipe (le modèle de traduction écrit par l’équipe Ops qui fait correspondre l’intention du développeur à un seul fournisseur physique) est décrit dans 04-entity-taxonomy.md ; la surface d’authoring de la Recipe au niveau des mots-clés est décrite dans ../language-reference/entities/recipe.md.

Justification

L’outil de rendu natif de chaque fournisseur — Helm, Docker Compose — sait déjà rendre des manifestes natifs du fournisseur. Le rôle d’une Recipe est de déclarer CE QUE ces manifestes doivent dire : quelles images de conteneur, quels ports, quelles variables d’environnement, quels volumes, quels services, quelles limites de ressources.

Une Recipe doit exprimer davantage que ce que peut porter un ensemble fixe de clés (p. ex. image, environment, ports, replicas) appliqué à un Deployment et à un Service, notamment :

  • resources (requêtes/limites de CPU/mémoire)
  • Sondes de liveness, de readiness ou de startup
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • Pods multi-conteneurs, sidecars
  • Ressources ConfigMap / Secret / PVC / CRD
  • Services autres que ClusterIP (LoadBalancer, NodePort, Headless)

La couche d’abstraction doit décrire la forme complète d’une charge de travail, et non un ensemble fixe de clés. Les trois types d’entrées décrits ci-dessous constituent cette abstraction : une Recipe compose sa sortie de manière additive à partir d’un chart ou d’un module chargé de l’extérieur (source:), d’une spécification abstraite de Workload que le fournisseur synthétise en manifestes natifs du fournisseur (workload:) et de manifestes natifs du fournisseur fondés sur des modèles que la Recipe émet directement (artifacts:).

Les trois types d’entrées

Composition par addition

Il existe trois façons de produire des fichiers de manifeste natifs du fournisseur à partir d’une Recipe, et elles se composent par addition plutôt que par exclusion mutuelle :

  1. source: — un artefact chargé de l’extérieur (chart Helm, fichier compose) que le fournisseur rend nativement, valuesMapping: fournissant les valeurs de surcharge.
  2. workload: — une spécification abstraite de Workload (type appartenant à la plateforme) que le fournisseur synthétise en manifestes natifs du fournisseur. Le champ accepte un block scalar YAML inline ou un $import: vers un seul fichier local ou une entrée de bibliothèque ; l’aiguillage est déterminé par la forme du contenu.
  3. artifacts: — une map de manifestes natifs du fournisseur, inline ou chargés par $import:, traités comme modèles Go d’après le contexte complet des piliers. Chaque entrée peut être écrite inline (la valeur de l’entrée est un block scalar) ou via $import: vers un seul fichier ou un contenu de bibliothèque.

Les trois produisent des fichiers que le compilateur émet dans le répertoire de sortie du boundary. Les trois peuvent coexister dans une même Recipe, sous réserve des règles de validation ci-dessous. La sémantique de fusion porte uniquement sur le premier niveau : chaque type d’entrée produit des fichiers complets ; les fichiers sont émis côte à côte ; une collision sur le nom d’un fichier de sortie est une erreur fatale.

Noms descriptifs des modes

Les trois « modes » sont un vocabulaire descriptif destiné à la documentation et aux diagnostics. Les auteurs de Recipe ne déclarent pas de mode ; ils écrivent les mots-clés dont ils ont besoin. Une Recipe se caractérise par son entrée dominante :

Mot(s)-clé(s) dominant(s)Nom descriptif du mode
source: + valuesMapping: (pas de workload:, pas d’artefacts)sourced
workload: (pas de source:, pas d’artefacts)synthesized
artifacts: (pas de source:, pas de workload:)artifacts-only (de manière informelle : « inline »)
Toute combinaison de deux ou plusdécrit explicitement (p. ex. « sourced avec artifacts », « synthesized avec artifacts »)

Il n’existe aucun mot-clé nommé mode: ni aucune énumération. Le mode est une propriété émergente des entrées présentes.

La forme d’une Recipe en un coup d’œil

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

Chaque champ ci-dessus est accepté par le schéma de la Recipe, et le compilateur consomme les trois types d’entrées — le rendu sourced, la synthèse de Workload et l’émission d’artifacts. Ce qui diffère, c’est la prise en charge par fournisseur — quel fournisseur rend quel type d’entrée —, consignée dans la matrice des capacités par Provider à la fin de ce chapitre.

Règles de validation au chargement

Le schéma de la Recipe et la validation au chargement appliquent ces règles de composition :

  1. valuesMapping: exige source:. Sans source: à surcharger, rien ne peut recevoir les valeurs mises en correspondance. Une Recipe avec valuesMapping: et sans source: est une erreur au chargement. (Un source: sans valuesMapping: est autorisé — le chart ou le module est rendu avec ses propres valeurs par défaut.)
  2. workload: accepte une seule source — inline ou $import:, pas les deux. Une Recipe spécifie le Workload soit sous forme de block scalar inline, soit sous forme de $import: vers un seul fichier. La forme $import: est à source unique selon le vocabulaire unifié d’importation de fichiers ; la fusion de plusieurs sources n’est pas prise en charge dans workload:. Un aiguillage mal formé est une erreur au chargement.
  3. workload: exige un fournisseur capable de synthèse. La prise en charge de la synthèse est une propriété du fournisseur lui-même, et non d’un champ déclaré. Une Recipe workload: liée à un fournisseur incapable de synthétiser est rejetée lors du rendu du nœud — par le contrôle des capacités du fournisseur (voir la matrice des capacités par Provider) — avec un diagnostic clair. Le catalogue de la bibliothèque standard déclare workloadSchema sur les fournisseurs capables de synthèse par convention, en tant que contrat de traduction documenté, mais le contrôle se fonde sur la capacité que signale le fournisseur lui-même plutôt que sur la présence de ce champ.
  4. Au moins un type d’entrée doit être présent. Une Recipe ne comportant aucun de source:+valuesMapping:, workload: ou artifacts: ne produit aucune sortie et constitue une erreur au chargement.
  5. Les entrées d’artefacts inline et $import: peuvent coexister. Une Recipe peut déclarer certaines entrées artifacts: inline et d’autres via des directives $import: par entrée. La clé de chaque entrée nomme sa propre sortie, de sorte que les entrées des deux formes n’entrent jamais en collision les unes avec les autres (voir Ce qui nomme chaque fichier de sortie).
  6. Les collisions de noms de fichiers entre types d’entrées sont des erreurs au rendu. Si deux des types d’entrées d’une Recipe — sortie rendue depuis la source, sortie synthétisée depuis la charge de travail ou sortie émise depuis les artefacts — produisent un fichier portant le même nom, le compilateur émet une erreur fatale identifiant chaque contributeur. Cette vérification s’exécute après la traduction du Workload ; elle a donc lieu au rendu plutôt qu’au chargement.

Le type Workload

Propriété et emplacement

Workload est un type appartenant à la plateforme sous apiVersion: aggrega.ai/v1beta1. Sa déclaration JSON Schema 2020-12 est intégrée au binaire du compilateur lors du build ; les auteurs de catalogue ne modifient pas le schéma du Workload et n’écrivent pas non plus de fichiers YAML Workload autonomes en tant qu’entités de catalogue. La grammaire du Workload est consommée à l’intérieur du champ workload: d’une Recipe ou d’une FeatureRecipe (inline, ou via $import: vers un seul fichier ou une entrée de WorkloadLibrary) et nulle part ailleurs.

Le Workload est un type de la plateforme et un concept du compilateur, et non une entité distincte de la taxonomie des entités. La Recipe est l’entité d’authoring ; le Workload est la forme que prend l’entrée synthétisée de la Recipe.

Un Workload par Recipe

Une Recipe déclare au plus un workload:. Le Workload représente l’unité de calcul unique associée au Component qu’implémente cette Recipe. De même, une FeatureRecipe déclare au plus un workload: qui lui est propre — une unité de calcul appartenant à la Feature, synthétisée au moyen du même type Workload —, voir FeatureRecipe. Les cas d’usage nécessitant des charges de travail annexes supplémentaires s’expriment via :

  • artifacts: — des manifestes supplémentaires à côté de la charge de travail, dans la même Recipe (inline ou via $import: par entrée).
  • Features avec génération de ressources — des charges de travail annexes transversales (p. ex. un sidecar de sauvegarde rattaché aux bases de données) déclarées comme entités de catalogue distinctes, où la FeatureRecipe synthétise son propre workload: (ou effectue le rendu via source: / artifacts:). Voir 14-extensibility.md pour la génération de ressources par la FeatureRecipe.

Cela préserve le modèle d’une unité de calcul par auteur : une Recipe synthétise la charge de travail du Component ; une FeatureRecipe synthétise la sienne.

La surface complète

L’ensemble des champs du Workload est vaste et ne cesse de croître. Plutôt que de le reproduire ici, où une copie prendrait du retard sur le contrat sans que rien ne le signale, ce chapitre renvoie aux deux surfaces qui le portent dans son intégralité :

  • La référence générée du schéma du Workload — chaque champ, son type, sa valeur par défaut et ses contraintes, générée à partir du JSON Schema publié et comparée à celui-ci à chaque build, de sorte qu’elle ne peut pas décrire une forme que le compilateur n’accepte pas.
  • La page d’authoring du Workload — des indications d’authoring au niveau des champs : ce que signifie chaque champ, ce en quoi chaque fournisseur le rend, et quelles combinaisons le build refuse.

La déclaration JSON Schema 2020-12 du Workload fait autorité et est livrée intégrée au binaire du compilateur. Les providers helm et compose synthétisent le workload: d’une Recipe, inline ou chargé via $import: ; voir la matrice des capacités par Provider pour la prise en charge par fournisseur.

Intégration des secrets avec featuresSchema

Le bloc containers.<name>.attachments du Workload fait référence à des slots déclarés par le featuresSchema du Component ; il ne déclare pas de nouveaux slots. Voir ../language-reference/entities/component.md pour la surface d’authoring de featuresSchema.

Le contrat de validation :

  • Chaque valeur attachments.<KEY>.from doit correspondre à un nom de slot déclaré dans le featuresSchema du Component — ou, pour une entrée désignant une connexion avec connection: <alias>, à un slot que le socket de cette connexion déclare dans usesSchema.<socket>.featuresSchema. Une telle entrée est réécrite sur le nom que prend le rattachement de la connexion sur le composant (<alias>.<slot>) avant l’application de l’une quelconque de ces règles, de sorte que chaque règle ci-dessous la lit comme elle lit une entrée désignant un slot propre au Component.
  • Le mécanisme de livraison as: (env ou file) doit figurer dans la liste autorisée du tableau inject: de ce slot.
  • Les slots marqués inject: [] (boîte noire) dans le featuresSchema du Component ne peuvent pas apparaître dans les blocs attachments: du Workload — ces slots sont livrés par la plomberie interne de la Recipe (p. ex. via existingSecret de Helm), et non par une exposition dans le Workload.

Exemple :

# In the Component
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
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

Sondes de santé : l’intention, pas le mécanisme

Les sondes Kubernetes et les healthchecks Docker Compose ont des formes différentes. Une seule forme d’intention abstraite se traduit proprement dans les deux :

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

Les Providers traduisent chaque intention dans leur forme native :

IntentionHelm (K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

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, sur les deux cibles. Un conteneur ne déclarant aucun port nommé ne peut pas porter de sonde HTTP, et le build s’arrête en nommant la sonde.

Compose dégrade les sondes HTTP/TCP en commandes shell de healthcheck, et un service compose ne porte qu’un seul healthcheck : lorsque plusieurs sondes sont déclarées, une seule est traduite et un avertissement nomme celles qui sont abandonnées.

Types de volumes

Cinq types de volumes ; aucun composé :

TypeSémantiqueK8s (helm)Compose
ephemeralTmpfs / emptyDir ; disparaît avec le podemptyDir: { sizeLimit }montage tmpfs:, sans taille (un avertissement signale un sizeLimit rédigé)
configmapFichiers de configuration en lecture seuleRéférence à un volume ConfigMapréférence configs: au niveau du service vers une config de premier niveau que déclarent les artifacts: de la Recipe
secretFichiers de secrets en lecture seuleRéférence à un volume Secretfichier de secret en lecture seule monté en bind
persistentPVC unique ; survit aux redémarrages du podRessource PVC + volume.persistentVolumeClaimvolume nommé
persistentTemplatePVC par réplica ; compagnon de form: statefulStatefulSet.volumeClaimTemplatesvolume nommé (dégradé ; avertissement émis)

Compose ne peut pas exprimer de modèles par réplica. Lorsque persistentTemplate est traduit en compose, il est dégradé en un seul volume nommé partagé par tous les réplicas, et un avertissement signale la dégradation. Un volume persistentTemplate exige form: stateful ; le déclarer sur toute autre forme arrête le build.

Expositions multi-services

Chaque service est une exposition indépendante. Un schéma courant : un service HTTP sur le port 8080 (ClusterIP interne) + un service de métriques sur le port 9090 (ClusterIP) + un point de terminaison d’administration sur le port 9901 (LoadBalancer) :

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

Chacun devient un objet Service Kubernetes distinct lorsqu’il est rendu avec le fournisseur helm, qui s’arrête en revanche sur une entrée Loopback. Dans compose, les services NodePort et LoadBalancer publient leurs ports sur chaque interface hôte du service compose, les services Loopback sur la seule adresse de loopback de l’hôte, et les services ClusterIP et Headless ne publient rien.

Dans la sortie K8s, les noms de services sont préfixés par l’instance_id du composant afin de garantir leur unicité. Les noms de ports doivent correspondre aux noms de ports du conteneur déclarés dans containers.<name>.ports.

Contrat de traduction côté Provider : workloadSchema

Un Plugin de rendu de fournisseur (pluginType: provider) déclare un spec.provider.workloadSchema — une déclaration JSON Schema 2020-12 documentant la manière dont les champs du Workload se traduisent dans la sortie native de ce fournisseur. C’est le contrat de traduction autodocumenté. Voir ../language-reference/entities/plugin.md pour la surface d’authoring du Plugin, y compris le bloc spec.provider.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

Le champ workloadSchema communique l’intention de traduction aux auteurs de catalogue et aux outils IDE. C’est le contrat de traduction documenté, déclaré par convention sur les fournisseurs qui synthétisent — mais la prise en charge de la synthèse est déterminée par le fournisseur lui-même, et non par la présence de ce champ. Une Recipe ciblant avec workload: un fournisseur incapable de synthétiser est rejetée lors du rendu du nœud — par le contrôle des capacités du fournisseur — avec une erreur claire, que le fournisseur déclare ou non workloadSchema.

Le schéma du Plugin déclare spec.provider.workloadSchema — son corps est compilé en JSON Schema 2020-12 lors du chargement du Plugin — et la consommation de workload: côté Recipe est livrée. La prise en charge de la synthèse est appliquée au moment du rendu par le contrôle des capacités du fournisseur, fondé sur la capacité que signale le fournisseur lié ; workloadSchema est le contrat documenté que le catalogue de la bibliothèque standard maintient synchronisé avec cette capacité, et non l’entrée du contrôle elle-même. aggrega validate, exécuté sur l’ensemble du catalogue, signale en outre en amont, avant un build, une Recipe workload: liée à un fournisseur qui ne synthétise pas, lorsque le catalogue contient l’entité Plugin de ce fournisseur.

Les ressources auxiliaires vivent hors du Workload

La spécification du Workload ne comporte aucun champ additionalResources, aucun extras, aucune déclaration inline de ConfigMap/Secret/CRD. Le Workload modélise uniquement la forme de la charge de travail : conteneurs, volumes, services, réplicas, ordonnancement, contexte de sécurité, compte de service — tout ce qui décrit la façon dont s’exécute l’unité de calcul unique.

Les ressources auxiliaires ont deux emplacements légitimes hors du Workload :

  1. Features + FeatureRecipes — le mécanisme des préoccupations transversales. Un ServiceMonitor rattaché à « tout serveur exposant des métriques » est core/prometheus-exporter en tant que Feature. La ressource de routage qui publie un serveur sous un nom d’hôte est elle aussi une Feature, et la forme de routage décide laquelle : core/public-ingress là où la cible réconcilie un Ingress, core/http-route là où elle exécute la Gateway API — chacune réalisée par une FeatureRecipe que le Manifest sélectionne pour chaque Release. Une NetworkPolicy appliquée à toutes les charges de travail de production est une Feature que la Release de production rattache à l’ensemble du boundary. Les Features se composent de manière orthogonale et peuvent être réutilisées entre plusieurs Recipes. Voir 14-extensibility.md pour la génération de ressources par la FeatureRecipe.
  2. artifacts: au niveau de la Recipe — pour les ressources qui appartiennent à l’implémentation de cette Recipe précise et pour lesquelles il ne vaut pas la peine de créer une Feature. Un enregistrement de CRD ponctuel dont la Recipe a besoin. Un PodDisruptionBudget propre à la Recipe qui ne s’applique que lorsque cette Recipe est utilisée. Une ConfigMap à laquelle fait référence le Workload de la Recipe. Chaque entrée est inline ou chargée par $import: ; voir la section sur le mécanisme des artefacts ci-dessous.

La limite entre Feature et artefact est une convention sociale. Si une ressource auxiliaire est transversale (elle s’applique à de nombreuses Recipes, ou est rattachée de manière conditionnelle via des sélecteurs), c’est une Feature. Si elle est intrinsèque à cette seule Recipe (la Recipe ne peut pas faire son travail sans émettre cette ressource), c’est un artefact. Les auteurs choisissent en fonction de la réutilisation et de la sémantique de rattachement ; le compilateur ne contrôle pas ce choix.

Les Features et les artefacts de Recipe couvrent ensemble les ressources auxiliaires dont une Recipe a besoin.

Le mécanisme des artefacts

Artefacts inline et chargés depuis un fichier

Le type d’entrée artifacts émet des fichiers de manifeste natifs du fournisseur fondés sur des modèles directement dans la sortie du boundary, à côté de toute sortie rendue depuis la source ou synthétisée depuis la charge de travail. Les auteurs le déclarent via deux surfaces :

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

Les chemins $import: sont relatifs au répertoire de la Recipe et doivent rester à l’intérieur de celui-ci, car chaque fichier qu’emporte une publication de la Recipe est pris dans ce répertoire — chaque fichier que nomme une importation voyage avec elle — et un fichier situé à l’extérieur ne le ferait pas. Une convention courante les place dans un sous-répertoire ./artifacts/, bien que le compilateur ne l’impose pas. La clé de la map nomme chaque fichier émis — la section suivante explique ce que cela signifie dans chacune des trois formes.

Chaque entrée (inline ou chargée par $import:) est traitée comme modèle Go d’après le contexte de modèle complet avant d’être émise dans le répertoire de sortie.

Ce qui nomme chaque fichier de sortie

La map est indexée par nom d’entrée, et la clé nomme ce qu’émet l’entrée dans chaque forme d’authoring. Pour une entrée inline, la clé est le nom du fichier de sortie, utilisé tel qu’il est écrit :

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

Produit configmap-config.yaml et pdb.yaml. La clé fixe le nom du fichier ; l’endroit où le fichier aboutit relève de la cible, et la section sur l’émission par fournisseur ci-dessous le décrit.

Pour une entrée $import: de fichier, la clé est également le nom du fichier de sortie. Le fichier importé fournit le contenu ; il ne fournit pas le nom, de sorte qu’un auteur qui souhaite un nom de fichier de sortie précis écrit ce nom comme clé :

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

Produit .../monitor.yaml et .../netpol.yaml. Le fichier importé par la deuxième entrée s’appelle some-other-name.yaml, et ce nom n’atteint pas la sortie — c’est la clé qui l’atteint. Deux entrées important des fichiers différents qui portent par hasard le même nom, ./extras/shared.yaml et ./overrides/shared.yaml, sont donc deux sorties distinctes, chacune nommée par sa propre clé.

Pour une entrée $import: de bibliothèque, qui importe un lot de fichiers comme une seule unité, l’entrée se développe en une sortie par fichier du lot, chacune imbriquée sous la clé sous la forme <key>/<filename>. Une clé nomme plusieurs fichiers, si bien que la clé seule ne peut pas les nommer : elle est le répertoire où aboutissent les fichiers du lot plutôt que le nom de l’un d’entre eux.

Comme chaque forme nomme sa sortie d’après la clé, la clé est limitée, au niveau de la surface d’authoring, à ce que peut être un seul nom de fichier : une lettre ou un chiffre initial, puis des lettres, des chiffres, des points, des tirets et des tirets bas. Les points portent l’extension qu’attend un consommateur, ce qui rend une clé directement utilisable comme nom de fichier ; et l’alphabet ne contient ni / ni . initial, de sorte qu’une clé ne peut jamais former plus d’un segment de chemin ni jamais être le segment du répertoire parent. Une clé hors de l’alphabet échoue à la validation de l’enveloppe au chargement de l’espace de travail, dans aggrega validate et dans les diagnostics de l’éditeur.

Deux sorties artifacts: portant le même nom de fichier arrêtent le build lors du rendu du nœud, quelles que soient les formes qui les ont produites. Deux entrées d’une même map artifacts: ne nomment jamais une même sortie : une clé est unique au sein d’un document et constitue un seul nom de fichier, de sorte que le nom de sortie d’une entrée à fichier unique est sa clé et que les sorties d’une entrée de lot se trouvent toutes sous un répertoire nommé d’après sa clé. Le premier segment de chaque chemin émis est donc la clé qui l’a produit, et des clés distinctes restent des noms de sortie distincts. Ce que couvre l’arrêt, c’est le cas qui traverse les types d’entrées — un nom de fichier fourni par deux d’entre eux, un modèle du chart et une entrée d’artefact produisant tous deux servicemonitor.yaml —, avec un diagnostic nommant chaque origine contributrice.

Contexte de modèle pour les artefacts

Les modèles d’artefacts ont accès au contexte complet des piliers :

  • .values, .infra, .context.*, .locals, .provides, .features, .metadata — les piliers standard d’Aggrega décrits dans 06-data-taxonomy-and-composition.md.
  • .workload — la spécification du Workload analysée pour cette Recipe (si elle est présente). Permet aux artefacts de faire référence aux valeurs du Workload sans duplication, p. ex. un ServiceMonitor faisant référence à .workload.services.metrics.ports.prom.
  • .source — le contenu résolu du champ source: (s’il est présent).

Les artefacts sont évalués après l’analyse du Workload, de sorte que .workload est disponible lorsqu’il est présent. Pour les Recipes sans workload:, .workload vaut nil ; un modèle qui tente de le déréférencer échoue avec une erreur claire. Pour les Recipes sans source:, .source vaut nil, avec le même mode d’échec.

L’invariant d’autonomie

Les artefacts doivent être autonomes. Ils ne peuvent faire référence qu’aux entrées déclarées de la Recipe : le contexte des piliers, le Workload propre à la Recipe (lorsqu’il est présent) et la valeur source: propre à la Recipe. Ils ne peuvent pas faire référence :

  • Aux sorties d’autres Recipes dans le même boundary.
  • Aux ressources Kubernetes ambiantes que la Recipe n’a pas déclarées.
  • Aux Secrets, ConfigMaps ou autres ressources supposées exister à l’extérieur (sauf si elles sont référencées via un pilier déclaré).

Un artefact ConfigMap référencé par volumes.*.configmap.source du Workload doit être émis par CETTE Recipe (via des artifacts: produisant cette ConfigMap) ou par une Feature rattachée à ce nœud. Les dépendances entre une Recipe et une autre au sein d’un boundary ne sont pas prises en charge.

Cet invariant préserve la réutilisabilité de la Recipe : une Recipe peut être insérée dans n’importe quelle combinaison Aggregate + Release qui satisfait son contrat de piliers, sans dépendance cachée.

Labels de provenance

Après la traduction, chaque fichier émis porte la provenance aggrega.ai/* dans ses métadonnées — qu’il ait été rendu depuis la source, synthétisé depuis la charge de travail ou émis depuis un modèle d’artefact. Chaque surface d’émission l’appose à partir d’un même ensemble partagé de builders, de sorte que le même fichier porte toujours la même provenance, quel que soit le type d’entrée qui l’a produit. L’ensemble se divise selon qu’une valeur respecte ou non le jeu de caractères des valeurs de labels Kubernetes : les clés sûres pour les labels sont des labels (interrogeables) ; les clés incompatibles avec le jeu de caractères — recipe-uri (contient un :), boundary-path (un chemin imbriqué contient /) et sync-wave (le - initial d’une vague négative) — sont des annotations, dont les valeurs ne sont soumises à aucune contrainte. Une valeur d’identité que le build ne soumet pas aux règles des labels — le nom de l’agrégat, l’environnement, le nom du fournisseur, les versions du compilateur et du fournisseur — est un label écrit sous une forme qu’un label admet et, lorsque cette forme diffère de la valeur, la valeur telle quelle est aussi une annotation sous la même clé (un Aggregate nommé imported/flow reçoit le label imported-flow et l’annotation imported/flow). Tous les fichiers portant la sortie d’une même Recipe partagent la même provenance :

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

Cette répartition est uniforme pour les trois types d’entrées. (Le fournisseur Compose n’a pas de notion d’annotation et ses valeurs de labels ne sont soumises à aucune contrainte ; il émet donc l’ensemble complet sous forme de labels de service.) Voir 11-governance-and-compliance.md pour l’apposition de la provenance à la compilation.

Comme un fournisseur appose la provenance là où son propre format de sortie la porte, un fournisseur dont le format n’offre pas un tel emplacement pour un fichier donné émet ce fichier sans le modifier et le signale. Compose est le cas à connaître : son emplacement de provenance est le bloc labels: d’un service, de sorte qu’un fragment d’artefact compose qui ne fournit que des volumes:, configs: ou models: de premier niveau ne porte aucune provenance, et le build émet un avertissement « skipped provenance label injection (injection des labels de provenance ignorée) » nommant l’artefact. Cet avertissement est attendu pour un fragment de cette forme et n’est pas le signe d’un problème — les services qu’émet le même composant portent l’ensemble complet, et rien ne change dans les octets émis. Ce qu’il exclut, c’est la troisième possibilité : un fichier quittant le build sans provenance sans être nommé.

CloudFormation est l’autre cas à connaître, et il diffère par l’endroit où la provenance aboutit plutôt que par le fait qu’elle aboutisse ou non. Un modèle CloudFormation ne comporte aucun bloc de métadonnées au niveau du document qui accompagne une ressource ; la provenance est donc placée sur l’attribut Metadata propre à chaque ressource, sous une seule clé aggrega.ai/provenance contenant l’ensemble complet :

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

Trois propriétés découlent de cet emplacement. L’attribut Metadata est disponible sur chaque ressource, quel que soit son type, de sorte que chaque ressource que porte une pile assemblée reçoit la provenance — y compris les nombreux types de ressources qui n’acceptent aucun tag, sur lesquels une provenance fondée sur les tags n’aurait trouvé aucune place. La provenance est ajoutée à tout Metadata que l’auteur a écrit au lieu de le remplacer, de sorte que les entrées propres à l’auteur restent à côté d’elle. Et comme elle est apposée par ressource plutôt que par modèle, une pile assemblée à partir de plusieurs composants porte l’identité contributrice propre à chaque ressource — son composant, sa Recipe et son boundary —, ce qu’une entrée unique valable pour tout le modèle ne pourrait pas exprimer.

L’ensemble complet voyage groupé sous cette clé. Une valeur Metadata est du JSON sans contrainte, il n’y a donc aucune répartition par jeu de caractères à effectuer ; les deux clés que seul un runtime Kubernetes lit — le nom du label recommandé standard et l’annotation d’ordonnancement du déploiement que consomme un contrôleur GitOps — sont omises, car aucune ne nomme quoi que ce soit dans une pile. L’entrée de provenance simple aggrega.ai/sync-wave est conservée, car elle consigne la vague que le composant a déclarée plutôt que de donner une instruction à un contrôleur.

La forme qui n’a pas d’emplacement ici est un modèle ou un fragment ne déclarant aucune ressource — un qui ne fournit que Parameters, Mappings, Conditions ou Rules. Il ne porte aucune provenance, atteint la pile assemblée avec son propre contenu intact, et le build émet un avertissement « skipped provenance injection (injection de la provenance ignorée) » qui le nomme. Comme pour compose, cet avertissement est attendu pour une contribution de cette forme : les ressources que le même composant fournit ailleurs portent l’ensemble complet, et les octets émis sont les mêmes, que quelque chose soit à l’écoute ou non.

Sémantique des artefacts par Provider

La sémantique par provider décrite ci-dessous explique comment chaque provider intègre les artefacts dans sa sortie native.

provider helm : les artefacts sont des documents YAML Kubernetes écrits dans un répertoire portant le nom du composant qui les a déclarés, à l’intérieur du répertoire de sortie qui contient les manifestes rendus à partir du chart et synthétisés à partir du Workload. La raison tient au nommage : un manifeste rendu ou synthétisé est nommé par le provider d’après le composant auquel il appartient, tandis qu’un artefact est nommé d’après la clé écrite par son auteur, qui ne dit rien du composant concerné — deux composants liés à une même Recipe écriraient donc un seul chemin sans qu’aucun des deux auteurs puisse les séparer. Le répertoire porte le nom propre du composant, de sorte que le fichier que l’auteur retrouve dans la sortie porte le nom qu’il a écrit, un niveau plus bas.

Un opérateur qui souhaite une autre disposition dispose du modèle subDirectory: de la boundary, qui déplace chaque fichier émis par un contributeur et pas seulement les artefacts. Voir ../language-reference/path-template-variables.md.

provider compose : les artefacts sont des fragments compose. Les clés de premier niveau (services:, volumes:, configs:, models:) sont fusionnées dans le docker-compose.yaml combiné de chaque boundary lors de l’étape de composition de la boundary.

provider helm-chart (cas particulier) : les artefacts ne sont pas écrits dans le répertoire de sortie en tant que fichiers autonomes — c’est Helm qui possède le pipeline de rendu. Le provider helm-chart place plutôt chaque entrée artifacts: à l’intérieur du chart lui-même, et la forme sous laquelle l’entrée est rédigée décide où elle atterrit. Chaque entrée est d’abord traitée comme template Go avec le contexte des piliers d’Aggrega, AVANT tout placement ; à partir de là, les deux formes divergent. Une entrée chargée par $import: est un fichier de template pré-Helm : elle est injectée dans le répertoire templates/ du chart AVANT le rendu Helm, de sorte que Helm la rend avec les templates propres du chart sourcé. Un scalaire de bloc inline est un fichier libre du chart : il est placé à la racine du chart sous sa clé rédigée, sans préfixe templates/ ni labels de provenance fusionnés, de sorte que les templates propres du chart peuvent le lire via .Files.Get / .Files.Glob de Helm — le motif ConfigMap à partir de fichiers. Cela donne au provider helm-chart un mécanisme d’extension équivalent à ce que artifacts: offre au provider helm simple, tout en respectant le modèle de chart de Helm.

Le fichier injecté atterrit dans boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — les fichiers d’un bundle imbriqués sous cette clé — de sorte qu’il se trouve à côté des templates du chart sourcé et que Helm le prend en compte lors de la passe de rendu en aval. Un scalaire de bloc inline atterrit dans boundaries/<bp>/charts/<nodeID>/<authored-key> — la racine du chart, un niveau au-dessus de templates/ — parce qu’un fichier lu via .Files doit se trouver là où le chart le cherche, et qu’un fichier placé sous templates/ est rendu comme un manifeste. Les deux formes sont nommées d’après la clé sous laquelle elles sont rédigées ; ce qui les distingue est le répertoire dans lequel le provider les place.

Convention de délimiteurs de helm-chart. La passe de pré-template d’Aggrega sur les entrées d’artefact helm-chart, chargées par $import: comme inline, utilise les délimiteurs [[ ]] au lieu des {{ }} par défaut, afin que la syntaxe {{ ... }} propre à Helm dans le fichier parvienne intacte à la passe de rendu de Helm. Les auteurs écrivent les substitutions côté Aggrega sous la forme [[ .context.instance_id ]], [[ .values.name ]], etc. ; les substitutions côté Helm restent {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }}, etc. Mélanger les deux paires de délimiteurs dans un même fichier est la forme de rédaction prise en charge.

Provenance et artefacts helm-chart. La provenance est fusionnée dans metadata.labels et metadata.annotations (selon la répartition par jeu de caractères décrite plus haut) pour les fichiers chargés par $import: qui supportent un aller-retour YAML en conservant leurs jetons Helm — fichiers n’utilisant que le contexte Aggrega [[ ]] ou contenant des {{ }} Helm uniquement à des positions de scalaires entre guillemets. Les fichiers comportant des actions de template Helm structurelles ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} à des positions où elles émettent de la structure YAML plutôt que des feuilles scalaires), ou des {{ ... }} sans guillemets à des positions de valeur, ne survivent pas à l’aller-retour YAML d’Aggrega ; le build émet un avertissement « skipped provenance label injection (injection des labels de provenance ignorée) » qui nomme l’artefact et laisse passer le fichier inchangé. Cet avertissement est attendu pour tout fichier d’artefact helm-chart chargé par $import: qui utilise des actions de template Helm structurelles ou des substitutions de valeurs Helm sans guillemets — c’est le cas courant dans la rédaction Helm en production, pas le cas limite. Les auteurs qui ont besoin de labels de provenance sur de tels fichiers les injectent via un template nommé qu’ils écrivent dans le propre _helpers.tpl du chart (par exemple un template appelé aggrega.commonLabels) ou un mécanisme équivalent côté Helm, et non via l’injection pré-template d’Aggrega.

Collisions avec les noms de fichiers de la racine du chart. Un artefact chargé par $import: dont la clé rédigée entre en collision avec un nom de fichier de la racine du chart (Chart.yaml, values.yaml, .helmignore, etc.) n’est pas détecté par la vérification de collision de noms de fichiers d’Aggrega — l’artefact atterrit dans templates/<authored-key> tandis que le fichier racine atterrit à la racine du chart, et le préfixe de chemin les rend distincts du point de vue d’Aggrega. Les auteurs évitent ces noms de clés ; la conséquence de leur utilisation est que Helm voit les deux fichiers (l’un à la racine du chart, l’autre dans templates/) et peut rendre de façon inattendue la copie côté templates.

provider terraform : les artefacts sont des fichiers de configuration Terraform, émis tels quels dans le répertoire propre du composant sous l’arborescence modules/ de la boundary. HCL (main.tf) est le choix par défaut le plus ergonomique et Terraform JSON (.tf.json) est accepté de manière équivalente ; aucun des deux n’est transpilé ni reformaté. La configuration racine de la boundary déclare ce composant comme un bloc module dont le source pointe vers ce répertoire, de sorte qu’une boundary entière reste un seul graphe de dépendances ; c’est le même répertoire qu’occupent les fichiers d’un module vendorisé, si bien qu’une Recipe déclarant à la fois source: et artifacts: les écrit côte à côte. La provenance est portée par un bloc de commentaires Terraform en tête ; lorsqu’un composant fournit un corps JSON, qui n’a pas de syntaxe de commentaire, chaque corps est émis inchangé et la provenance voyage dans un fichier .tf compagnon ne contenant que des commentaires, placé à côté, de sorte que le marquage n’est jamais dupliqué entre les deux. Voir la page du provider terraform.

provider cloudformation : les artefacts sont des fragments de stack — les ressources qu’un composant fournit plutôt qu’un template complet. Le provider normalise chaque fragment en fonctions intrinsèques longues en pur JSON et le fusionne dans la stack unique assemblée pour ce répertoire de sortie, où les ressources rejoignent une seule map Resources et où les provides du composant apparaissent comme Outputs de la stack sous des noms limités au composant qui les publie. Les autres sections de premier niveau d’un fragment qui survivent à l’assemblage sont décrites sous Ce qu’un document fusionné reprend de artifacts:. Voir la page du provider cloudformation.

La portée boundary : fichiers pour la sortie partagée d’une boundary

Le mécanisme des artefacts a une seconde portée. Tout ce qui précède est écrit à la position propre du composant dans la sortie de sa boundary ; le spec.boundary.artifacts d’une Recipe est la même map — les trois mêmes formes, la même règle de clé à nom de fichier, le même contexte de template — écrite à la place une seule fois pour la boundary dans son ensemble. Elle existe pour un fichier que la cible lit une seule fois pour tout ce qu’une boundary déploie, et qu’aucune position propre d’un composant ne peut contenir : la documentation de Terraform indique qu’un module destiné à être appelé ne doit pas contenir de blocs provider, et qu’un module qui en contient ne peut pas être appelé avec depends_on, count ou for_each ; la configuration d’un provider appartient donc à la configuration racine de la boundary plutôt qu’au module d’un composant.

Où il atterrit. Dans le répertoire qui contient la sortie assemblée du groupe de dispatch, à côté des fichiers que l’assemblage propre du provider y écrit — pour terraform, à côté de la configuration racine. Le compilateur évalue chaque entrée une fois par composant rendu par la Recipe, par rapport au contexte de ce composant, et écrit lui-même le fichier : aucun de ces fichiers n’est transmis au provider, et rien n’y est apposé pour indiquer de quel composant il provient, car il appartient à chaque contributeur qui l’a déclaré.

Comment les contributeurs se rejoignent. Les fichiers déclarés par chaque contributeur d’un même groupe de dispatch sont fusionnés par nom. Un nom déclaré avec des octets identiques donne un seul fichier ; un nom déclaré avec des octets différents, ou un nom que l’assemblage du provider écrit lui-même, arrête le build en nommant le fichier et chaque contributeur — le même refus que rencontrent deux contributeurs écrivant un même chemin de sortie. Ainsi, une configuration de provider dont deux Recipes ont besoin est écrite par les deux sous un même nom, et le build vérifie qu’elles concordent.

Qui l’accepte. Le fait qu’un fichier placé à côté de la sortie assemblée d’une boundary ait un sens est une propriété de la cible du provider ; c’est donc une déclaration propre au provider, lue dans la propre déclaration du provider comme ses types d’entrée. Une Recipe qui déclare le bloc pour un provider qui ne le revendique pas est refusée avant tout rendu. La grille ci-dessous porte cette déclaration dans sa dernière colonne ; parmi les providers distribués avec le compilateur, terraform la fait.

Ce que les artefacts ne sont pas

Trois distinctions structurelles :

Pas multi-provider au sein d’une même Recipe. Une Recipe déclare exactement une capability: en tête de sa spec. Tout ce que la Recipe produit — sortie rendue depuis la source, sortie synthétisée depuis le workload et émissions d’artefacts — est dans le format natif de ce provider. Les artefacts d’une Recipe helm contiennent du YAML Kubernetes. Les artefacts d’une Recipe compose contiennent des fragments compose. Une Recipe cible un seul provider ; chaque sortie est dans le format natif de ce provider.

La composition multi-provider se fait au niveau de la Release. Les boundaries contiennent des composants à providers mixtes ; les contributeurs de chaque provider au chemin évalué d’une boundary sont répartis et assemblés indépendamment par (chemin, provider). Une Release dont les composants ciblent respectivement helm, helm-chart et compose peut placer les trois dans une même boundary ; le regroupement de dispatch les partitionne par provider, les contributeurs de chaque provider atterrissent dans leur propre sortie assemblée sous le chemin de la boundary, et l’opérateur rédige la coordination entre providers via la structure de boundary qu’il choisit. La coordination entre providers relève de la responsabilité de l’auteur de la Release.

Pas de Recipes dans des Recipes. Les artefacts ne chargent ni ne composent d’autres Recipes. Ce sont des manifestes inline (ou des chemins de fichiers vers des manifestes inline), traités comme templates avec les piliers de cette Recipe et émis dans la sortie de cette Recipe. La réutilisation d’une Recipe passe par trois mécanismes : l’extends: d’un Component (une Recipe écrite pour un Component de base sert tout Component qui l’étend ; ce qui est hérité, ce sont les métadonnées et les schémas, pas les fichiers de sortie — une Recipe elle-même ne déclare aucun extends:) ; le mappage à URI plats du Manifest (le même Component peut se résoudre en Recipes différentes selon les catalogues — voir ../language-reference/entities/manifest.md) ; et Features + FeatureRecipes (préoccupations transversales attachées de manière orthogonale).

Pas une couche de liaison inter-Recipe. Les artefacts ne peuvent pas référencer des noms, des ressources ou un état que la Recipe n’a pas elle-même déclarés. Un artefact ConfigMap référencé par le Workload de la Recipe doit être émis par cette Recipe. Un artefact qui attend un Secret provisionné en externe doit obtenir le nom de ce Secret via le pilier .features — à partir des provides résolus de l’attachement qui l’émet — et non supposer qu’il existe. C’est l’invariant d’autonomie (voir plus haut) énoncé du point de vue de la rédaction d’artefacts : chaque Recipe émet des fichiers dans un seul format, appliqués par un seul outil, dans le répertoire de sortie d’une seule boundary.

Matrice des capacités par Provider

Chaque provider déclare les types d’entrée qu’il rend ; un gate central des types d’entrée accepte les combinaisons prises en charge et rejette les autres avec un diagnostic uniforme au moment du rendu du nœud. La capacité est une propriété du provider, pas de la Recipe — un provider rend un sous-ensemble des trois types. La colonne artifacts: distingue les artefacts qui accompagnent à côté une entrée principale sourced/synthesized d’une Recipe autonome composée uniquement d’artefacts (ni source:, ni workload:). Les deux dernières colonnes sont les déclarations du provider selon lesquelles il respecte omits: et accepte les fichiers qu’une Recipe fournit à la sortie partagée de sa boundary sous boundary.artifacts: (plus haut) ; aucune des deux n’est un type d’entrée.

Lisez chaque colonne isolément. Une ligne indique quels types un provider rend, pris un par un. Elle n’indique pas que deux types cochés peuvent être déclarés ensemble. Comme les types se composent par addition, chaque type déclaré est réparti et émis séparément, de sorte qu’une paire peut être refusée pour une raison qu’aucune des deux colonnes ne porte — le plus souvent parce que les deux types produisent un fichier sous le même nom de sortie. Les combinaisons que chaque provider accepte réellement sont décrites en prose sous Ce que chaque provider accepte, en détail.

Providersource: + valuesMapping:workload:artifacts: (à côté)artefacts seuls (autonome)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ traité comme template avec les délimiteurs [[ ]]❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

Cette grille couvre les providers distribués avec le compilateur. Un provider fourni séparément déclare de la même manière les types d’entrée qu’il accepte, s’il respecte omits: et s’il accepte boundary.artifacts:, et le compilateur lit cette déclaration par la même voie — il n’est pas listé ici, car une page publiée ne peut pas énumérer des providers qu’elle n’a jamais vus.

Les cellules marquées ✅ sont rendues ; ❌ est un refus de capacité du provider signalé par le gate. Les fragments compose par nœud sont fusionnés par chemin d’assemblage, de sorte que les boundaries partageant un directory: partagent un même fichier.

Ce que chaque provider accepte, en détail

helm — toutes les combinaisons. source: + valuesMapping:, workload:, artifacts:, deux quelconques d’entre eux, ou les trois. C’est le seul provider distribué avec le compilateur qui ne refuse aucune combinaison, et la raison tient à la façon dont il nomme sa sortie : chaque fichier émis est nommé d’après la ressource qu’il contient, de sorte que les manifestes rendus d’un chart et les manifestes d’un Workload synthétisé n’atterrissent jamais sous un même nom. Une Recipe déclarant les trois émet les fichiers du chart, les fichiers du Workload et les fichiers d’artefacts côte à côte dans le répertoire de sortie de la boundary.

compose — toutes les combinaisons sauf les deux dans lesquelles source: et workload: apparaissent ensemble. Chaque type seul se construit, et artifacts: peut accompagner l’un ou l’autre. source: avec workload: ne peut pas se construire, pas plus que les trois ensemble ; Pourquoi compose ne peut pas combiner une source avec un workload explique pourquoi, et il ne s’agit pas d’un refus de capacité.

helm-chart — source: + valuesMapping:, seul ou avec artifacts: à côté. Rien d’autre. Il ne synthétise pas de workload: et n’a pas de forme composée uniquement d’artefacts : une Recipe dont le seul type d’entrée est artifacts: s’arrête. La raison est l’endroit où ce provider place un artefact — à l’intérieur du chart propre du composant — si bien qu’une Recipe sans source: ne lui laisse aucun chart où le placer.

terraform — trois formes : source: + valuesMapping: seul, artifacts: seul, ou les deux ensemble. Il ne synthétise pas de workload:.

cloudformation — les trois mêmes formes que terraform, avec la même unique exclusion. source: + valuesMapping: seul, artifacts: seul, ou les deux ensemble ; pas de workload:.

À quoi ressemble un type d’entrée refusé

Une Recipe qui déclare un type d’entrée que son provider lié ne rend pas arrête le build au moment du rendu du nœud, et elle l’arrête quoi que la Recipe déclare d’autre à côté de ce type — associer un workload: à un source: que le provider peut rendre ne fait pas passer le workload. L’arrêt nomme le provider, le type qu’il ne peut pas rendre et les types qu’il rend :

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

Le refus de la forme composée uniquement d’artefacts se lit de la même manière et nomme cette forme : provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 est l’identifiant à consigner lorsque cet arrêt doit être nommé de façon durable — dans un gate d’intégration continue, un ticket ou un runbook ; la table de toutes les conditions le résout.

Pourquoi compose ne peut pas combiner une source avec un workload

Le provider compose produit un fragment par composant et nomme ce fragment d’après le composant. Le rendu depuis une source et la synthèse du Workload produisent chacun le fragment de ce composant sous ce nom unique, si bien qu’une Recipe déclarant les deux produit deux fichiers portant le même nom, et le build s’arrête sur la collision :

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

Le nom du fragment provient de l’identifiant propre du composant et aucune surface de rédaction ne permet de le définir, de sorte qu’aucune modification du contenu de la Recipe n’évite la collision. L’arrêt est une propriété de la paire et non de l’un des deux types — compose rend une source, compose synthétise un Workload, et la grille a raison de cocher les deux. Pour utiliser les deux formes pour un composant sous compose, répartissez-les entre deux composants, ou intégrez le contenu de la source dans le Workload.

Ce qu’un document fusionné reprend de artifacts:

Deux providers fusionnent leurs contributeurs en un seul document par chemin d’assemblage : compose en un seul docker-compose.yaml, cloudformation en un seul template de stack. Un document fusionné ne peut porter que les sections que son assembleur modélise ; une coche artifacts: indique donc où le contenu d’un fragment est placé, et non que chaque clé du fragment survit.

compose reprend services:, volumes:, configs: et models: d’un fragment d’artefact, ainsi que ses clés d’extension préfixées par x-. Un fragment qui déclare autre chose au premier niveau arrête le build en nommant la clé — networks:, parce que les réseaux sont dérivés par boundary plutôt qu’accumulés à partir des contributeurs, et de même un bloc secrets: ou un name: de premier niveau. La page du provider compose donne les règles de fusion par clé et l’alternative pour le routage entre réseaux.

cloudformation reprend Resources, Outputs, Parameters, Mappings, Conditions, Metadata et Rules, et construit Transform à partir de ceux de chaque contributeur. Les transformations sont jointes dans l’ordre documenté par CloudFormation, les Globals de SAM accompagnant la transformation qui les lit, et une transformation qui changerait la façon dont le contenu d’un autre contributeur est déployé arrête le build en la nommant. Description n’est pas reprise, et le build le signale : il émet un avertissement de champ non pris en charge qui nomme la section et le composant, comme pour toute autre clé de premier niveau que la stack ne reprend pas, de sorte que rien n’est supprimé silencieusement. L’avertissement est indicatif — le template émis est identique octet pour octet à ce qu’il serait sans lui, et --no-unsupported-field-warnings fait taire cette classe. Outputs est repris sous un nom que le provider limite au composant contributeur, de sorte que deux composants fournissant à une même stack une sortie de même nom les gardent séparées. Sections de premier niveau dans la stack assemblée rend compte de chaque section une par une.

Les trois autres providers ne fusionnent pas, si bien qu’aucune clé d’artefact ne risque d’être supprimée par un assembleur. helm n’assemble rien : les manifestes de chaque composant parviennent tels quels au répertoire de sortie de la boundary. terraform et helm-chart imbriquent — les fichiers de chaque composant atterrissent dans un répertoire qui leur est propre, un répertoire de module Terraform ou un subchart, et un document racine au niveau de la boundary les référence — de sorte qu’une entrée d’artefact est placée comme un fichier entier plutôt que lue dans un document partagé. L’endroit où atterrit une entrée d’artefact helm-chart, et la raison pour laquelle sa paire de délimiteurs diffère, sont décrits sous Sémantique des artefacts par Provider.