Quand recourir à une étape de pipeline
Une FeatureRecipe vous offre deux manières de façonner la sortie qu’apporte une Feature : une FeatureRecipe à base de templates qui génère ses propres documents, et une étape de pipeline (pipeline:) qui exécute un plugin Wasm sur la sortie rendue. Elles résolvent des problèmes différents. Cette page est le guide de décision : recourez à une étape de pipeline sur exactement deux déclencheurs, et utilisez une FeatureRecipe à base de templates pour tout le reste.
Les deux outils
Une FeatureRecipe à base de templates est locale et générative. Elle produit ses propres documents à partir de ses propres valeurs au moyen d’un template Go — la ConfigMap d’un sidecar, une CRD de politique, un objet d’autoscaling. Tout ce qu’elle émet est fonction des values: et infra: de la Feature et du contexte de rendu remis à ses templates. Elle n’intervient jamais dans la sortie d’une autre entité ; elle ajoute des documents qui lui sont propres. Si ce que vous devez produire peut s’écrire à partir de ce que la Feature sait déjà, une FeatureRecipe à base de templates est l’outil juste et le plus simple — ni plugin, ni pipeline.
Une étape de pipeline est globale et transformatrice. Elle s’exécute après le rendu, sur l’ensemble réel de documents que le build a déjà émis. L’hôte remet à l’étape cet ensemble de documents indexé par clé, en entier ; l’étape lit le contenu réel, sélectionne les documents qu’elle cible et renvoie des patchs RFC 6902 précis sur leur structure — ou émet de nouveaux documents comme effets de bord. Une étape raisonne sur ce qui a été rendu, pas seulement sur ce que la Feature a déclaré. Cette portée est toute sa raison d’être, et c’est aussi pourquoi vous l’utilisez avec parcimonie.
Les deux déclencheurs d’une étape de pipeline
Ne recourez à une étape de pipeline que lorsque l’un de ces cas s’applique. Si aucun ne s’applique, générez plutôt le document avec une FeatureRecipe à base de templates.
-
Patch à portée de l’hôte — vous devez intervenir dans la structure d’une autre entité déjà rendue. Le cas classique est l’injection d’une variable d’environnement, d’un montage de volume ou d’un conteneur sidecar dans la charge de travail du composant consommateur — un document que la Feature elle-même n’a pas rédigé. Une FeatureRecipe à base de templates ne peut pas le faire : elle produit ses propres documents, elle ne modifie pas ceux d’un autre. Une étape de pipeline le peut, car elle opère sur l’ensemble rendu et peut désigner par clé les documents du composant hôte.
-
Émission ou patch dépendant du contenu — la sortie dépend de ce que contient l’ensemble rendu. Lorsque la ressource que vous émettez, ou le patch que vous appliquez, est fonction du contenu que le build a produit — les ports réels qu’un Deployment a déclarés, les noms de conteneurs qui se sont retrouvés dans le manifeste, les ressources en lesquelles un chart s’est étendu — la décision a besoin du contenu rendu en main. Une FeatureRecipe à base de templates effectue le rendu à partir des valeurs propres de la Feature et ne voit jamais l’ensemble final, si bien qu’elle ne peut pas faire un choix dépendant du contenu ; une étape de pipeline lit d’abord le contenu, puis agit.
Les deux déclencheurs partagent une forme : ils ont besoin d’informations qui n’existent qu’après le rendu — la structure d’une autre entité, ou le contenu émis lui-même. La génération locale n’en a jamais besoin, donc la génération locale n’a jamais besoin d’une étape de pipeline.
Une étape transforme ; une politique valide
Une étape de pipeline est un transformateur : elle modifie l’ensemble rendu. Ce n’est pas l’endroit où vérifier si un résultat est acceptable. Pour valider un build — pour affirmer qu’une charge de travail patchée a le sidecar, qu’aucun secret en clair n’a atteint la sortie, qu’un label requis est présent — rattachez une politique de l’étape de rendu : un plugin de gouvernance au rôle render-verdict, qui s’exécute après le rendu sur les artefacts émis et renvoie un verdict. Un verdict halt arrête le build ; un verdict warn ou info informe sans bloquer.
Gardez les deux séparés. N’intégrez pas de logique de validation dans une étape de pipeline, et ne recourez pas à une politique pour modifier la sortie — un plugin de gouvernance rattaché à un rôle de verdict renvoie des verdicts et n’applique jamais de patch, et l’hôte ne lit la sortie d’un rôle de verdict que comme une décision. Une étape façonne la sortie ; une politique render-verdict la juge. La page du socket de gouvernance couvre les quatre rôles de gouvernance et les niveaux de gravité des verdicts.
Les étapes se composent
Une étape de pipeline peut déclarer un contrat d’entrée et de sortie typé, si bien que son entrée with: et les sorties qu’elle renvoie sont des formes validées plutôt que des blobs libres. Une étape renvoie aussi des outputs nommées, et une étape déclarée plus loin dans le même pipeline lit les sorties d’une étape précédente depuis son propre template with: sous la forme .steps.<id>.outputs.<key>. C’est ainsi qu’un motif en deux parties se compose sans couplage : une étape Fetcher émet une ressource d’identifiants et publie le nom du Secret obtenu comme sortie ; une étape Injector lit ce nom et patche la charge de travail consommatrice pour le monter. Chaque étape porte une seule préoccupation, et le pipeline enchaîne leurs sorties dans l’ordre déclaré.
Références croisées
entities/featurerecipe.md— la surface de création de la FeatureRecipe, y comprispipeline:.plugins/plugin-contract.md— la forme de transmission de l’étape de pipeline : en entrée, l’ensemble de documents indexé par clé ; en sortie, des patchs RFC 6902, des effets de bord, des diagnostics et les sorties de l’étape.plugins/policy-socket.md— le socket de gouvernance, y compris le rôle de verdict de l’étape de rendu qui valide la sortie d’un build.templates/template-context-contract.md— le champ.steps.<id>.outputsque lit une étape ultérieure.examples/04-secrets.md— la forme de pipeline Fetcher + Injector.