Provider Helm
Le fournisseur helm produit du YAML Kubernetes rendu à plat pour les consommateurs GitOps (ArgoCD, Flux). Le fournisseur assemble par (path, provider) : le YAML rendu de chaque nœud ciblant helm est acheminé vers l’assembleur indexé sur le directory: évalué de la frontière joint au subDirectory: de chaque composant, et cet assembleur émet un fichier YAML par ressource Kubernetes. L’outillage en aval compare et applique directement les fichiers, sans étape d’installation Helm.
Là où le syncWave: <integer> de la frontière n’est pas 0, chaque ressource Kubernetes émise le porte sous la forme de l’annotation argocd.argoproj.io/sync-wave: "<N>" ; les hooks Helm portent en outre helm.sh/hook-weight: "<N>". ArgoCD lit l’annotation sync-wave, et Helm lit le poids d’un hook, chacun ordonnant les ressources selon cette valeur ; une frontière à la vague par défaut 0 ne porte ni l’une ni l’autre, ce que les deux outils lisent comme la vague 0.
Cette page est la référence de rédaction du fournisseur helm. Pour le modèle de composition des entrées commun aux fournisseurs, voir architecture/16-recipe-input-composition.md. Pour la disponibilité de chaque fournisseur, voir État du langage → Providers.
Types d’entrée pris en charge
Le fournisseur helm accepte les trois types d’entrée de la Recipe, dans des rôles différents :
- Mode avec source. Une Recipe avec
source: <chart-path>pointe vers un répertoire de chart Helm sur disque. Le SDK Go de Helm charge le chart, le dictionnaire de valeurs du rendu de base est fusionné avec les valeurs par défaut du chart, et les templates du chart sont rendus en YAML Kubernetes plat. - Mode Workload (synthétisé). Une Recipe avec
workload:(en ligne ou chargé via$import:) déclare un document Workload. Le fournisseur synthétise une ou plusieurs ressources Kubernetes par nœud — un objet contrôleur choisi par leformdu Workload, plus des Services par service et des PVC par volume persistant — directement à partir de la spécification du Workload ; voir Mode Workload (synthétisé). - Mode artefacts uniquement. Une Recipe avec
artifacts:et sanssource:niworkload:émet les manifestes que son auteur a écrits, avec les labels et annotations de provenance du build insérés dans les propres métadonnées de chaque ressource.
Les trois se combinent : une Recipe peut déclarer ensemble un chart, un Workload et artifacts:, et chacun est rendu et émis indépendamment, côte à côte dans la sortie du nœud — voir Ce que chaque provider accepte, en détail.
Jeu de clés de source:
Le source: du fournisseur helm nomme un chart, et il accepte les deux formes que prend le champ source: : une simple chaîne de chemin du système de fichiers, et un objet structuré dont le url: porte l’emplacement. Partout où cet emplacement est un chemin du système de fichiers, il est ancré au répertoire contenant le recipe.yaml qui le déclare, et non au répertoire depuis lequel le build est lancé, et il doit rester à l’intérieur de ce répertoire : un chemin qui en sort, ou un chemin absolu, est refusé, car chaque fichier que porte une publication de la Recipe est pris dans son répertoire — voir entities/recipe.md « Content paths stay inside the Recipe’s own directory (Les chemins de contenu restent dans le répertoire propre de la Recipe) ». Un chart nommé de cette façon est publié avec la Recipe, avec chaque fichier qu’il contient que conservent les règles d’exclusion enregistrées lorsque la Recipe a été épinglée — le fournisseur helm écarte les répertoires de contrôle de version et les fichiers cachés sous le templates/ du chart, respecte le propre .helmignore du chart, et le .aggregaignore de l’auteur a le dernier mot, comme le décrit Quels fichiers sont livrés avec une entité — tandis qu’un fichier à côté de la Recipe que rien de ce qu’elle déclare ne nomme ne l’est pas. Le rendu lit les mêmes fichiers que porte la publication, de sorte qu’un chart est rendu de la même façon depuis votre répertoire et depuis un registre. La forme dans laquelle vous l’avez écrit n’y change rien : un source: structuré dont le url: est ./charts/api-server est ancré exactement comme la simple chaîne ./charts/api-server.
spec: capability: helm source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicas: {{ optional .infra `replicas` 2 }}Un source: structuré dit la même chose avec des champs nommés, et ce que porte son url: décide si quelque chose est récupéré. Là où url: porte un schéma de transport — oci://… pour un chart OCI, un https://….tgz pour une archive de chart directe, ou une racine de dépôt https:// associée à chart: — le chart est récupéré : le type vient du schéma de l’URL ou d’un kind: explicite, aggrega pull récupère et épingle le chart dans le fichier de verrouillage, et le build l’extrait du cache. Là où url: nomme un chemin du système de fichiers, rien n’est récupéré ni épinglé — le chart est lu sur le disque, ancré exactement comme la forme en simple chaîne ci-dessus.
spec: capability: helm source: kind: helm-oci-chart url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned version: "1.0.0"Seul url: décide d’où un chart est lu. Les autres champs sélectionnent ce qui serait récupéré, de sorte que pour un chemin ils ne sélectionnent rien — ils atteignent néanmoins les propres templates de la Recipe sous la forme .source.*.
Copier un chart localement (vendoring) est pris en charge comme alternative à la récupération, et n’est pas obligatoire. Le schéma accepte un objet structuré ouvert.
Le chart situé au chemin source doit contenir un Chart.yaml valide. Les rendus avec source qui échouent à charger le chart remontent mot pour mot l’erreur sous-jacente du SDK Helm. Un source: "" vide n’est pas une affaire de helm : il ne nomme ni le mode sans source ni le mode avec source, de sorte que le refus qu’il reçoit est le même quel que soit le fournisseur que cible la Recipe, et il intervient à la lecture de la Recipe, avant le chargement de tout chart et avant la distribution vers ce fournisseur. Les commandes qui le signalent sont exposées dans entities/recipe.md « Source field scheme inventory (Inventaire des schémas du champ source) » et errors/fatal-halts.md « Recipe source: is an empty string (Le champ source de la Recipe est une chaîne vide) ».
Mode avec source
Une Recipe avec source: <chart-path> et valuesMapping: exécute le pipeline suivant lors du rendu de base :
- Le chart situé à
<chart-path>est chargé via le SDK Go de Helm. - Le template
valuesMappingest évalué par rapport au contexte de template de la Recipe. Sa sortie YAML est traitée comme une surcouche de valeurs pour le chart. - La surcouche est fusionnée une seule fois avec les valeurs par défaut du
values.yamldu chart ; en cas de collision, les clés de la surcouche l’emportent (la sémantique standard dehelm install --valuesde Helm). Une clé que la surcouche définit ànullsupprime la valeur par défaut du chart pour cette clé — au niveau supérieur, à l’intérieur d’une table ou dans les valeurs d’une dépendance — comme le faithelm install --values, de sorte que les templates du chart lisent la clé comme absente ; unnullsur une clé à laquelle le chart ne donne aucune valeur par défaut atteint les templates sous la formenull. - Le SDK Helm effectue le rendu des templates du chart par rapport aux valeurs fusionnées.
- Aggrega injecte ses métadonnées de provenance dans les manifestes rendus par une réécriture YAML post-rendu, ce qui garantit que la sortie avec source porte les mêmes labels que la sortie en mode Workload. Les valeurs d’identité deviennent des labels (
app.kubernetes.io/name,aggrega.ai/component-id,aggrega.ai/provider,aggrega.ai/provider-version,aggrega.ai/environmentet — lorsqu’elles sont définies —aggrega.ai/aggregate-name,aggrega.ai/compiler-version), chacun écrit sous une forme que Kubernetes accepte comme valeur de label ; les valeurs qu’un label Kubernetes ne peut pas représenter deviennent des annotations (aggrega.ai/recipe-uri,aggrega.ai/boundary-path,aggrega.ai/sync-wavelà où la vague n’est pas0, et la valeur littérale de tout label dont la valeur a dû être réécrite — un Aggregate nomméimported/flowreçoit le labelimported-flowet l’annotationimported/flowsous la même clé). La règle de réécriture est énoncée dans well-known-annotations.md « Labels de provenance émis par les fournisseurs ». - Les fichiers de sortie arrivent à plat dans le répertoire de sortie de la Recipe, un par ressource rendue, nommés
<name-basis>-<kind>[-<namespace>]-<name>.yaml— la même base que celle dont est dérivé le nom de release décrit plus bas, suivie du type propre de la ressource, de son espace de noms lorsqu’elle en a un, et de son nom, chacun mis en minuscules, chaque suite d’autres caractères étant réduite à un seul tiret. Pour un composant ordinaire, cette base est l’identité propre du composant, qui est aussi ce que porte le labelaggrega.ai/component-idde la ressource ; pour un chart fourni par l’auteur d’un rattachement de Feature, elle reste celle du composant hôte, tandis que le label porte l’identité propre du rattachement. Un document qui ne porte aucun type ou aucun nom est nommé d’après le chemin de son template. La structure de répertoires du chart est aplatie : il n’y a pas de sous-répertoiretemplates/dans la sortie rendue, et deux templates situés dans des sous-répertoires différents qui partagent un nom de fichier restent deux fichiers, car le nom vient de la ressource plutôt que du template. Un fichier que nomme le blocartifacts:de la Recipe n’arrive pas ici : il se trouve un répertoire plus bas, dans un répertoire nommé d’après le composant qui l’a déclaré, car un tel fichier est nommé d’après la clé que son auteur a écrite plutôt que d’après la ressource qu’il porte — ainsi, sans ce répertoire, deux composants liés à une même Recipe écriraient un seul chemin, sans qu’aucun des deux auteurs puisse les séparer.
L’espace de noms par rapport auquel le chart est rendu est lu dans l’annotation aggrega.ai/namespace qui descend en cascade depuis la frontière, et atteint le chart comme espace de noms de sa release ; lorsqu’aucune frontière n’en déclare un, le chart est rendu par rapport à default. Là où une frontière en déclare un, chaque ressource à espace de noms que le chart rend sans espace de noms — aucun metadata.namespace, ou un espace de noms écrit vide ou null — est émise dans l’espace de noms déclaré, c’est-à-dire là où l’installation du chart avec Helm sous cet espace de noms de release la place, et son fichier est nommé avec le segment d’espace de noms exactement comme une ressource dont le template écrit le champ. Une ressource dont le template écrit un espace de noms le conserve, quel que soit l’espace de noms qu’il nomme. Une ressource de portée cluster reste sans espace de noms. Le fait qu’un type soit à espace de noms relève de la portée propre de l’API Kubernetes pour un type que l’API sert elle-même et, pour un type personnalisé, du scope qu’une CustomResourceDefinition du même rendu déclare pour lui — à partir des templates du chart ou de son répertoire crds/. Une ressource d’un type qu’aucun des deux ne classe est laissée telle que le chart l’a écrite, et le build la signale, une fois par type, en nommant le type et son groupe d’API ; il en va de même pour un document kind: List, dont les éléments ne sont pas placés. Là où aucune frontière ne déclare d’espace de noms, rien n’est placé et rien n’est signalé : une ressource que le chart écrit sans espace de noms est émise sans, placée par ce que sélectionne l’outil qui l’applique.
Le signalement est un avertissement sur le build, qui se termine malgré tout :
warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places themLà où le chart possède une valeur qui rend la CustomResourceDefinition du type, ou une valeur qui écrit elle-même l’espace de noms, la définir via le valuesMapping de la Recipe place une telle ressource.
La version de Kubernetes pour laquelle un chart est rendu
Les templates d’un chart lisent la version de Kubernetes pour laquelle ils sont rendus sous la forme .Capabilities.KubeVersion, et beaucoup choisissent en fonction d’elle une version d’API, un champ ou un mécanisme entier — un jeton de compte de service projeté à partir de 1.21, par exemple, et un jeton de première partie en dessous. Le build n’a pas de cluster à interroger, donc la version est une version que vous indiquez, là où la Release dit où un composant est déployé : l’annotation aggrega.ai/kubernetes-version sur une frontière, ou sur un composant, où elle l’emporte sur celle de sa frontière, en cascade exactement comme aggrega.ai/namespace.
spec: boundaries: production: annotations: aggrega.ai/kubernetes-version: "1.31" components: api: {} legacy: annotations: aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older clusterLa valeur est lue comme helm template --kube-version lit son option, elle accepte donc les formes que cette option accepte et un chart lit exactement ce que cette option lui donnerait : "1.31" se lit comme v1.31, "v1.31.2" comme v1.31.2, et le texte qui suit les nombres reste dans .Capabilities.KubeVersion.Version tel qu’il est écrit — "1.29.3-gke.100" se lit comme v1.29.3-gke.100 — tandis que .Capabilities.KubeVersion imprimé en entier lit la version sans lui. Un chart qui compare .Capabilities.KubeVersion.Version avec semverCompare lit un tel suffixe comme une préversion, de sorte qu’une contrainte sans plancher -0, comme ">=1.21", ne lui correspond pas, et une valeur entourée d’espaces se lit avec ces espaces — " 1.30 " se lit comme "v 1.30 " — et échoue d’emblée à une telle comparaison : écrivez la version nue là où un chart la compare. Une valeur qui n’est pas une version — "one.two", "latest", un nombre seul — arrête le build sous la condition d’une valeur qu’un plugin ne peut pas représenter, en nommant la valeur, le composant et sa frontière ; le chart n’est jamais rendu pour une autre version à sa place. Voir A Kubernetes version the helm provider cannot render a chart for (Une version de Kubernetes pour laquelle le fournisseur helm ne peut pas effectuer le rendu d’un chart). Une valeur vide est traitée comme non définie.
Là où aucune annotation ne nomme de version, un chart est rendu pour la version pour laquelle effectue le rendu le helm template standard de la même release de helm, c’est-à-dire la version de la bibliothèque cliente Kubernetes avec laquelle le fournisseur est construit : un fournisseur construit avec la bibliothèque cliente v0.37 effectue le rendu pour Kubernetes v1.37.0. Ainsi, un chart est rendu dans Aggrega comme le rend le helm template de ses propres auteurs, et la valeur par défaut ne change que lorsque change la bibliothèque cliente avec laquelle le fournisseur est construit. Nommez la version du cluster sur lequel vous déployez chaque fois qu’elle diffère : un chart rendu pour une version plus récente que celle qu’exécute le cluster peut émettre une version d’API que ce cluster ne sert pas.
Seule la version est définie de cette façon. Toute autre capacité que lit un chart — .Capabilities.APIVersions et .Capabilities.HelmVersion — est celle intégrée à la bibliothèque helm, de sorte qu’une API qu’un cluster sert à partir d’une CustomResourceDefinition installée n’est pas signalée au chart. La plage kubeVersion propre d’un chart dans son Chart.yaml n’est pas comparée à la version : helm template refuse un chart dont la plage exclut la version pour laquelle il effectue le rendu, et le build le rend. L’annotation façonne un chart rendu depuis une source et rien d’autre : un Workload synthétisé et un corps artifacts: ne lisent pas .Capabilities, et le fournisseur helm-chart transmet son chart sans le rendre, pour qu’il soit rendu lors de son installation.
Exclure des documents rendus. Ce fournisseur respecte les entrées omits: qu’une Recipe ou une FeatureRecipe déclare, dans ce mode et dans aucun autre : un Workload synthétisé et un corps artifacts: sont rendus sans elles. Chaque document que rend le chart — à partir d’un template ou d’un fichier de son répertoire crds/ — est comparé à chaque entrée qui s’applique au build, et un document que nomme une entrée quelconque est exclu. Une entrée nomme un document par les mots que porte le document lui-même, les mêmes mots à partir desquels sont construits son nom de fichier de sortie et ses faits de rendu : son kind, son metadata.name et, uniquement là où l’entrée en nomme un, l’espace de noms dans lequel se trouve le document — celui qu’écrit son template, ou l’espace de noms déclaré de la frontière là où ce fournisseur place le document comme décrit ci-dessus. Ce n’est jamais l’espace de noms par rapport auquel le chart est simplement rendu : sans espace de noms déclaré, le chart est rendu par rapport à default, et pourtant un document dont le template n’écrit aucun espace de noms n’est dans aucun, de sorte qu’une entrée nommant default ne lui correspond pas. Un document qui ne porte aucun type ou aucun nom ne correspond à aucune entrée. Les documents exclus sont rendus puis écartés une fois le nom de chaque fichier fixé, de sorte que chaque document conservé est nommé et écrit exactement comme il le serait sans les entrées, et qu’un document exclu n’atteint rien de ce que le build fait ensuite — aucun fichier, aucun nom dans la comparaison qui refuse deux contributeurs aboutissant au même nom, aucun fait de rendu que lit une Feature, rien de ce qui est remis à une étape du pipeline. Le fournisseur indique combien de documents chaque entrée a trouvés, et une entrée qui n’en a trouvé aucun arrête le build ; voir An omits entry left out nothing the source rendered (Une entrée omits n’a rien laissé de côté de ce que la source a rendu).
La release Helm sous laquelle un chart est rendu
Le fournisseur effectue le rendu avec le SDK de Helm 4, en v4.3, de sorte qu’un chart lit ce que lui donne le helm template propre à Helm 4, et que le même chart avec les mêmes valeurs produit les mêmes octets à chaque build. Un chart écrit et vérifié avec Helm 3 peut observer ces comportements de Helm 4 :
.Capabilities.HelmVersionindique la version de Helm 4,v4.3.- La version de Kubernetes par défaut est v1.37.0, car Helm 4 en v4.3 est construit avec la bibliothèque cliente v0.37, et
.Capabilities.APIVersionsest l’ensemble des versions d’API de cette bibliothèque cliente. Nommez la version qu’exécute votre cluster, comme le décrit La version de Kubernetes pour laquelle un chart est rendu. - Une valeur par défaut
nulldu chart est supprimée. Une clé que levalues.yamldu chart définit ànull— au niveau supérieur ou à l’intérieur d’une table — est absente de.Valuessauf si les valeurs que fournit la Recipe la définissent, de sorte quehasKeyla signale comme manquante, quetoYamll’omet et que levalues.schema.jsondu chart est vérifié par rapport aux valeurs sans elle. - Un scalaire de bloc conserve son saut de ligne final avant
---. Un document qui se termine par un scalaire de bloc et qui est suivi d’un autre document du même template conserve le dernier saut de ligne de ce scalaire, qui est donc écrit|plutôt que|-. .Chartest une map indexée par nom de champ..Chart.Name,.Chart.Version,.Chart.AppVersionet les autres champs se lisent comme avant, maistoYaml .ChartoutoJson .Chart.Maintainersimpriment les clés sous la formeName,AppVersionet ainsi de suite, avec les champs vides présents, et un champ que les métadonnées du chart ne portent pas se lit comme vide au lieu de faire échouer le rendu..Capabilities.KubeVersion.Versionconserve le texte d’une version tel qu’il est écrit, comme décrit ci-dessus pour l’annotationaggrega.ai/kubernetes-version.- Un
values.yamlcontenant plusieurs documents YAML est lu en entier, les documents ultérieurs étant fusionnés par-dessus les précédents. .Files.Linesd’un fichier vide ne renvoie aucune ligne au lieu de faire échouer le rendu.- Les fonctions de template ajoutées par Helm 4 —
mustToYaml,mustToJson,mustToToml,mustToDurationet les conversionsduration…— sont disponibles pour les templates d’un chart. - Une dépendance avec deux alias donne à chaque alias sa propre copie des dépendances de cette dépendance.
- La validation du schéma des valeurs accepte ou refuse différemment uniquement aux marges : une partie locale d’adresse e-mail entre guillemets,
NaNet les nombres infinis, un nombre comparé à un non-nombre dansenumetconst, et l’emplacement signalé pour unpropertyNames, uncontentSchemaou un élément de tableau ultérieur en échec.
Un template que le moteur lui-même ne parvient pas à exécuter — une valeur lue à travers une table manquante, par exemple — est signalé sous la forme de Helm 4 : le fichier, la ligne et la colonne du template sur une ligne à part, puis ce qui était en cours d’exécution et le message, en retrait, pour chaque template par lequel l’échec est passé. Le fail ou le required propre à un chart conserve sa forme sur une ligne execution error at (<file>:<line>:<col>): <message>, tout comme une erreur que renvoie une fonction de template.
Comment le nom de release est dérivé
Un chart avec source est rendu par rapport à un nom de release, qui parvient à chaque template sous la forme .Release.Name. Les charts nomment couramment des ressources d’après lui, de sorte qu’un nom de release est une identité à l’intérieur du cluster plutôt qu’une étiquette apposée sur le build.
Le nom de release est la forme encodée de la même base que celle qui préfixe le nom du fichier de sortie de la ressource rendue, de sorte que les deux sont un seul nom écrit deux fois. Cette base est un instance_id pour un composant ordinaire, et l’identité composée que porte une Feature rattachée à une frontière. Pour un chart fourni par l’auteur d’un rattachement de Feature, c’est le nom du composant hôte : les propres templates du chart sont rendus par rapport au nom de release, de sorte que le dériver plutôt du rattachement renommerait des ressources que le chart déclare, dans un cluster où elles sont déjà déployées. Ces ressources portent néanmoins la propre identité du rattachement dans leur label aggrega.ai/component-id — comment s’appelle une ressource et à quoi elle appartient sont ici des questions distinctes, et ce n’est que pour un composant ordinaire qu’elles ont la même réponse. Un nom de release Helm accepte un ensemble de caractères plus restreint que ce qu’une identité peut contenir : lettres minuscules, chiffres, tirets et points, commençant et se terminant par une lettre minuscule ou un chiffre, jusqu’à 53 caractères. Plutôt que de remplacer un caractère que la cible n’accepte pas, la dérivation l’écrit en toutes lettres, de sorte que deux identités de composant qui ne diffèrent que par la ponctuation ou par la casse aboutissent toujours à deux noms de release.
- Une lettre minuscule et un chiffre sont conservés exactement tels que rédigés.
- Un trait d’union est conservé tel qu’il a été écrit partout où le caractère qui le suit est repris directement et n’est pas un
zminuscule. Un trait d’union suivi d’unzminuscule ouvre une séquence d’échappement, de sorte qu’un trait d’union écrit à cette position est lui-même écrit en toutes lettres —api-zonedevientapi-zhzone, ce qui permet de relire n’importe quel nom sans deviner. Un trait d’union suivi de rien est écrit en toutes lettres pour la même raison, de sorte quedb-donnedb-zh. - Tout autre caractère est écrit
-zsuivi d’une lettre qui le nomme :dpour un point,upour un trait de soulignement,spour un séparateur de chemin,hpour un tiret que la règle ci-dessus ne conserve pas. Tout le reste — une lettre majuscule comprise — est écritxsuivi du point de code hexadécimal à six chiffres du caractère, et un octet qui ne commence aucun caractère est écritbsuivi de sa propre valeur à deux chiffres. - Une valeur vide est écrite
-ze, ce qu’aucune valeur non vide ne peut produire.
Un point est écrit en toutes lettres plutôt que conservé, bien que Helm en accepte un dans un nom de release, car Helm exige une lettre minuscule ou un chiffre de chaque côté d’un point et la dérivation place ses propres tirets.
Comme deux Features rattachées à un même composant sont toutes deux rendues par rapport au nom de release de ce composant, deux charts qui nomment chacun une ressource d’après .Release.Name émettent deux ressources portant un même nom. Ce fournisseur signale le nom que porte chaque ressource produite par son propre rendu, circonscrit au type de cette ressource et, pour un type que le cluster conserve dans un espace de noms, à son espace de noms, et le build refuse deux contributeurs aboutissant à l’un de ces noms plutôt que d’émettre une sortie où appliquer les deux ne laisse que le dernier — voir ../errors/fatal-halts.md « The same name is derived more than once inside the output (Le même nom est dérivé plus d’une fois à l’intérieur de la sortie) ». Un type que le cluster conserve en dehors de tout espace de noms — un ClusterRole, une CustomResourceDefinition, ou un type personnalisé qu’une CustomResourceDefinition du même rendu déclare avec la portée Cluster — est circonscrit à son seul type, classé exactement comme le classe le placement dans les espaces de noms décrit ci-dessus, de sorte que deux composants d’une même sortie qui écrivent chacun un tel objet sous un même nom sont refusés même lorsque la Release les place dans des espaces de noms différents. La correction consiste à composer le nom, et la coordonnée dont il a besoin dépend de l’agencement. Deux rattachements sur un même composant partagent déjà l’hôte, c’est donc le rattachement qui doit atteindre le template : passez .attachment_name dans le chart via le valuesMapping: de la FeatureRecipe et définissez-le sur celle des propres valeurs du chart à partir de laquelle sont construits les noms de ses ressources. Un même chart rattaché à deux composants est le cas inverse — le nom de release diffère déjà par hôte, de sorte qu’une ressource nommée d’après .Release.Name porte un nom qui lui est propre sur chacun d’eux, alors qu’un nom littéral non. Une FeatureRecipe qui livre ses ressources via artifacts: est signalée dans les mêmes conditions : ce fournisseur lit le nom que porte chaque document émis, que ce document provienne d’un template de chart ou d’un corps d’artefacts, de sorte qu’un nom littéral dans un tel corps rattaché à deux composants arrête lui aussi le build. Un corps d’artefacts est un template : composez donc le nom à partir de .context.rendered_name — le nom de release de l’hôte, qui diffère par hôte et s’écrit dans les caractères qu’un nom Kubernetes autorise — et de .attachment_name là où il doit être distinct par hôte ; sur un hôte qui place seul un ensemble d’artefacts, et qui ne signale aucun nom de release, composez-le plutôt à partir de .context.instance_id. Tous les noms ne sont pas signalés, de sorte qu’un build qui ne s’arrête pas n’a pas comparé tout ce que sa sortie finira par porter. Celui que vous avez le plus de chances de rencontrer en écrivant un chart est une ressource déclarant generateName, dont le nom est laissé au cluster à compléter et qui n’a donc encore rien à comparer. La page liée ci-dessus présente l’ensemble complet.
Ainsi, un instance_id valant api donne le nom de release api, data.main-db donne data-zdmain-db, et db_host donne db-zuhost. Une identité construite uniquement de lettres minuscules, de chiffres et de tirets que la dérivation conserve apparaît exactement telle que rédigée. Une entrée identique produit toujours le nom identique.
Deux des conditions de Helm sont des propriétés de la base plutôt que de la dérivation : un nom de release doit commencer par une lettre minuscule ou un chiffre, et il doit compter au plus 53 caractères. Une base dont le premier caractère est écrit en toutes lettres commence son nom par le tiret par lequel s’ouvre chaque séquence d’échappement, et une base contenant des caractères écrits en toutes lettres est, une fois encodée, plus longue qu’elle n’a été rédigée. Le build interroge ce fournisseur sur les deux, et agit d’après la réponse au moment du build plutôt que de laisser le refus au cluster au moment de l’application — voir ../errors/fatal-halts.md « The target will not accept a name derived from an authored identity (La cible n’accepte pas un nom dérivé d’une identité rédigée) ». Ce qu’il fait de la réponse dépend de qui a écrit la base. Un nom que vous avez écrit est refusé plutôt que modifié, et le refus nomme le champ que vous avez écrit et le budget dont vous disposez ; un nom composé par Aggrega est raccourci jusqu’à ce que ce fournisseur l’accepte.
Le cluster soumet les ressources nommées d’après un composant à une règle plus stricte que celles de Helm : un nom de Service doit commencer par une lettre, alors qu’un nom de release peut commencer par un chiffre. Un chart nomme couramment ses Services d’après le nom de release, et les Services d’une charge de travail synthétisée commencent eux aussi par lui, de sorte que ce fournisseur refuse également un nom de composant commençant par un chiffre, en le signalant comme un Service name que la cible ne peut pas utiliser. Aucune longueur ne corrige un premier caractère, si bien que ce refus n’en indique aucune. Commencez donc un instance_id par une lettre minuscule, et gardez-le assez court pour que sa forme encodée tienne encore.
Changer la base dont un nom de release est dérivé renomme les ressources du cluster qu’un chart nomme d’après .Release.Name, ainsi que chaque ressource que ce fournisseur synthétise pour le composant, et Kubernetes ne renomme pas une ressource sur place. L’outil qui applique la sortie crée la ressource sous son nouveau nom et supprime celle qui porte l’ancien nom, ce qui, pour les ressources avec état, signifie que le stockage lié à l’ancien nom est libéré. Traitez un tel changement comme un remplacement à planifier — vidé, migré ou programmé — plutôt que comme une mise à jour à déployer.
Mode Workload (synthétisé)
Une Recipe avec workload: (en ligne ou chargé via $import:) synthétise des ressources Kubernetes à partir de l’intention abstraite du Workload. Le schéma du Workload est documenté dans entities/workload.md ; cette section couvre ce qu’émet le fournisseur helm.
Pour chaque nœud :
- Un objet contrôleur choisi par le
formdu Workload :stateless(et la valeur par défaut) émet un Deployment,statefulun StatefulSet,daemonun DaemonSet,taskun Job,scheduledun CronJob dont lespec.scheduleest le champscheduledu Workload (une expression cron à 5 champs ou une macro@) ; une charge de travailscheduledsans planification, ou avec une planification mal formée, arrête le build de manière explicite. Une charge de travailscheduledqui déclaresuspend: trueémet son CronJob avecspec.suspend: true, de sorte qu’aucune exécution ne démarre à partir de la planification tant qu’elle n’est pas reprise, alors qu’un Job peut toujours être créé à la main à partir du CronJob ; une charge de travail qui ne le déclare pas n’émet aucune clésuspend. Le Deployment et le StatefulSet portent le nombre de réplicas ; DaemonSet, Job et CronJob n’en portent aucun. Un Workloadstatefulexige exactement un Servicetype: Headlessdéclaré dans le Workload pour gouverner le StatefulSet ; le fournisseur relie leserviceNamedu StatefulSet au nom rendu de ce Service, et le build s’arrête si aucun Service headless n’est déclaré (ou s’il y en a plus d’un). Un volumepersistentTemplateest un complément deform: stateful— en déclarer un sur toute autre forme arrête le build avec un message qui nomme la correction. - Un Service par entrée
services:déclarée sur le Workload, exposant les ports nommés que liste la spécification du service. Letypede l’entrée devient le type du Service —ClusterIP,NodePortetLoadBalancertels quels, etHeadlesssous la forme d’un ServiceClusterIPavecclusterIP: None. Une entréeLoopbackarrête plutôt le build, en nommant le nœud et le service : un Service Kubernetes n’a aucun type qui se lie à l’adresse de loopback d’un hôte, et les adresses de nœud sur lesquelles écoute un ServiceNodePortsont un réglage de l’ensemble du cluster, de sorte que l’entrée est refusée plutôt que rendue avec une portée qu’elle n’a pas demandée. Voir A service type the helm provider cannot render (Un type de service que le fournisseur helm ne peut pas rendre). - Un PersistentVolumeClaim par volume
persistent, dimensionné et façonné à partir de la spécification du volume. Un volumepersistentTemplaten’émet aucune claim autonome : il devient une entréevolumeClaimTemplatesdans la propre spécification du StatefulSet, ce qui explique qu’il soit un complément deform: stateful.
Noms des ressources. Chaque ressource que ce mode émet pour un composant est nommée d’après le nom de release du composant — le même nom que celui par rapport auquel est rendu un chart avec source, dérivé comme l’expose Comment le nom de release est dérivé — et le fournisseur signale ce nom au build sous la forme {{ .context.rendered_name }}. L’objet contrôleur porte le nom de release lui-même ; chaque Service est <release name>-<service key> ; chaque claim autonome est <release name>-<volume>, et le volume du pod référence exactement cette claim ; un secret livré sous forme de fichier est monté à partir d’un volume de pod nommé <release name>-secret-<slot>, le slot étant écrit dans l’alphabet que le cluster accepte, comme l’est le nom de release — ainsi un slot server_certificate est monté à partir de <release name>-secret-server-zucertificate, et pour un slot lu via une connexion, le point qui suit le nom de la connexion est écrit de la même manière ; le serviceName d’un StatefulSet est le nom du Service headless qu’il émet ; et un Workload exposé uniquement par un nom externe émet un seul Service portant le nom de release. Ainsi un composant api émet un Deployment api et un Service default api-default, et un composant my_api émet my-zuapi et my-zuapi-default — des noms que le cluster accepte, là où l’identité telle qu’écrite ne le serait pas. Une Recipe qui publie l’adresse de l’un de ces Services la construit à partir de {{ .context.rendered_name }}, comme le montre ../templates/rendered-resource-names.md ; pour un composant dont le nom ne contient ni trait de soulignement ni majuscule, le nom de release est égal à son instance_id, de sorte que ses noms se lisent exactement comme l’identité. Une charge de travail que synthétise un rattachement de Feature est la seule exception : elle est nommée d’après la propre identité composée du rattachement — la valeur que porte son label aggrega.ai/component-id — car le rattachement est rendu par rapport à son composant hôte, et un nom de release dérivé à cet endroit nommerait la charge de travail du rattachement d’après l’hôte et entrerait en collision avec celle de l’hôte. Cette identité ne contient jamais de majuscule : une majuscule dans le nom de l’hôte ou dans celui du rattachement est écrite en toutes lettres sous forme de séquence d’échappement, comme l’est tout autre caractère qu’un nom de ressource refuse, de sorte qu’un rattachement worker sur un composant myApi émet un Deployment cfr--my-zx000041pi--worker et un Service default cfr--my-zx000041pi--worker-default, et chaque nom que porte la charge de travail est un nom que le cluster accepte.
Longueurs de noms qui dépendent du Workload. Deux de ces noms sont soumis par le cluster à des limites qui leur sont propres, et le build vérifie les deux une fois le Workload résolu plutôt que de laisser le refus au cluster au moment de l’application. Le nom d’un CronJob compte au plus 52 caractères, moins que les autres noms du cluster parce que le contrôleur nomme le Job de chaque exécution d’après le CronJob en y ajoutant un suffixe ; il n’est vérifié que pour un Workload scheduled. Le nom de chaque Service, <release name>-<service key>, compte au plus 63 caractères. Au-delà de l’une ou l’autre limite, ce qui se passe dépend de qui a écrit le nom, exactement comme pour le nom de release : un nom de composant que vous avez écrit est refusé, le build s’arrêtant à la clé spec.components que vous avez écrite, avec le type de nom, sa longueur et le budget dont dispose votre nom — voir ../errors/fatal-halts.md « The target will not accept a name derived from an authored identity (La cible n’accepte pas un nom dérivé d’une identité rédigée) » ; une identité composée, comme celle d’après laquelle est nommé le workload d’un rattachement de Feature, est raccourcie jusqu’à ce que chaque nom tienne. Un nom de Service est construit à partir de votre nom de composant et d’une clé que le workload déclare — dans la Recipe, ou dans une FeatureRecipe — de sorte qu’un refus nomme cette clé et l’endroit où le workload la déclare, spec.workload.services.<key> ; une clé qui ne laisse de place à aucun nom de composant doit elle-même être raccourcie. Ainsi, un composant portant un Workload scheduled peut avoir un nom encodé d’au plus 52 caractères, et un composant web peut porter des clés de Service d’au plus 59. Une Feature rattachée à une frontière entière voit son identité fixée avant que son Workload soit résolu, car l’endroit où sa sortie est assemblée peut dépendre de cette identité ; aucune des deux limites n’est donc vérifiée pour les ressources qu’elle synthétise.
Chaque ressource émise porte l’ensemble complet des labels et annotations de provenance d’Aggrega plus une paire de sélecteurs (app: <instance_id>) reliée entre le Deployment/StatefulSet et ses Services. Une valeur de label admet l’identité telle qu’écrite, de sorte que le sélecteur la conserve tandis que les noms ci-dessus prennent le nom de release. Les noms des conteneurs dans le Deployment rendu sont les clés de conteneur du Workload dont les caractères . et _ sont remplacés par - (assainissement des noms Kubernetes).
Transport des ports. Un port de conteneur qui déclare un transport l’émet tel quel sous la forme protocol: sur le containerPort rendu, et chaque port de Service nommant ce port de conteneur porte la même valeur — le transport est déclaré une seule fois, sur le port de conteneur, de sorte que l’exposition ne peut pas le contredire. Un port qui ne déclare aucun transport n’émet de clé protocol sur aucune des deux ressources, laissant en vigueur la valeur par défaut du cluster. Les trois valeurs qu’admet le Workload (TCP, UDP, SCTP) sont émises telles quelles ; helm n’a besoin d’aucune dégradation, puisque Kubernetes exprime chacune d’elles directement.
Exécution sur le réseau du nœud. Un Workload qui déclare hostNetwork: true émet hostNetwork: true sur la spécification de pod rendue, de sorte que le pod s’exécute dans le propre namespace réseau du nœud et que les ports qu’ouvrent ses conteneurs sont joignables sur les adresses du nœud. Kubernetes exprime ce choix directement, donc rien n’est dégradé. La déclaration atteint la spécification du pod et rien d’autre : elle n’ajoute, ne supprime et ne réécrit aucun port, et les Services émis sont identiques avec et sans elle. Un Workload qui ne la déclare pas n’émet aucune clé hostNetwork.
Quantités de ressources. Chaque quantité que le fournisseur copie dans les manifestes est émise telle quelle, et chacune est d’abord vérifiée par rapport à la forme de quantité exposée dans Workload → Quantités de ressources : les valeurs resources.requests et resources.limits de chaque conteneur et de chaque init container — cpu, memory et toute ressource étendue telle que nvidia.com/gpu — ainsi que ephemeral.sizeLimit, persistent.size et persistentTemplate.size de chaque volume. La vérification s’exécute sur le Workload tel que les templates de la Recipe l’ont évalué, de sorte qu’une valeur arrivée via infra ou un paramètre de la Release est jugée sur ce en quoi elle a été rendue. Une valeur hors de cette forme arrête le build avec une erreur TRANSLATION_ERROR nommant le nœud, le chemin du champ dans le Workload et la valeur — par exemple containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number — là où le chart serait sinon construit sans erreur et refusé par le cluster à l’installation. Un cpu, memory ou sizeLimit laissé vide est omis des manifestes et n’est donc pas vérifié ; une valeur de ressource étendue ou une taille persistante laissée vide serait tout de même émise, elle est donc refusée. La vérification ne juge que la forme : savoir si le cluster peut planifier la quantité n’est pas quelque chose que le fournisseur peut connaître au moment du build.
Le nommage des fichiers de sortie a deux formes. L’objet contrôleur est nommé d’après le nom de release et son type — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. Un fichier par ressource est nommé d’après la ressource qu’il porte, avec le type en dernier : <release name>-<svcName>-service.yaml et <release name>-<volName>-pvc.yaml, chacun tiré du propre metadata.name de cette ressource selon la convention des noms synthétisés décrite dans entities/workload.md. Un Workload exposé uniquement par un nom externe émet <release name>-service.yaml, faute de clé de service à porter.
Faits de rendu
En plus des fichiers qu’il rend, ce fournisseur signale quatre faits de rendu sur chaque nœud : ce que les documents Kubernetes qu’il a émis disent de leurs pods, de leurs sélecteurs, de leurs ports et de l’espace de noms dans lequel chacun est émis. Une FeatureRecipe rattachée au composant lit les propres faits du composant dans .context.render_facts ; celle qui définit readsCallerRenderFacts: true lit aussi, sur chaque entrée de .context.used_by, les faits d’un composant qui se connecte à son hôte, et celle qui définit readsTargetRenderFacts: true lit, sur chaque entrée de .context.uses, les faits d’un composant auquel son hôte est relié. C’est ainsi qu’une Feature peut nommer les pods des composants qui appellent son hôte, ou des composants que son hôte atteint — une politique réseau admettant exactement ceux-là, par exemple — à partir de ce que leurs rendus ont réellement émis, sans que personne ne réécrive un label à la main. Les noms et les entrées ci-dessous constituent le contrat de ce fournisseur.
| Fait | Une entrée par | Chaque entrée porte |
|---|---|---|
pod_template_labels | template de pod émis : le spec.template d’un Deployment, StatefulSet, DaemonSet, ReplicaSet ou Job, le template de job d’un CronJob, et un Pod isolé, qui est son propre template | kind, name et namespace de la ressource qui porte le template ; labels, les labels du template |
controller_selectors | Deployment, StatefulSet, DaemonSet, ReplicaSet, Job et CronJob émis | kind, name, namespace ; match_labels, les matchLabels de son sélecteur |
service_selectors | Service émis | name, namespace ; selector, les labels vers lesquels il envoie le trafic |
container_ports | conteneur d’un template de pod qui déclare une liste ports, init containers compris | kind, name et namespace de la ressource qui porte le template ; container, le nom du conteneur ; ports, une entrée par port avec son name, son container_port et son protocol |
Comment se lisent les faits :
- Chaque fait est une liste. Un template parcourt toujours un fait, même lorsqu’il contient une seule entrée ; il n’y a pas de valeur unique à lire isolément.
- Les quatre, à chaque rendu. Chacun est signalé chaque fois que ce fournisseur rend un nœud, sous forme de liste vide lorsque le rendu n’a rien émis de ce qu’il décrit — un composant dont le chart n’émet qu’une ConfigMap signale quatre listes vides. Le rendu d’un autre fournisseur ne signale aucun de ces noms, et un nom que personne n’a signalé se lit comme rien.
- Lus à partir de ce qui a été émis, sur chaque chemin. Les faits proviennent des documents que le rendu a émis, quel que soit le mode qui les a produits : les manifestes rendus d’un chart, ceux d’un Workload synthétisé, et les manifestes qu’un auteur a placés via
artifacts:, qui signalent exactement ce que portent ces manifestes. Ils sont lus dans la même passe, sur les mêmes documents, que les noms de ressources que ce fournisseur signale pour la vérification des noms en double du build. Les propres labels de provenance d’une ressource font partie de ce qu’elle porte, de sorte que leslabelsd’un Pod isolé les incluent ; le template de pod d’un chart ou d’un artefact conserve les labels que son auteur a écrits. - Les entrées peuvent provenir du propre rendu du composant et des rendus de ses Features. Un composant peut être rendu par plus d’un appel — un chart et un placement
artifacts:, par exemple — et les listes qu’un nom reçoit de ces appels sont réunies en une seule, dans l’ordre dans lequel les appels se sont exécutés. Sur.context.used_byet.context.uses, les faits du composant situé à l’autre extrémité d’une connexion réunissent aussi ce qu’ont rendu les Features qui lui sont rattachées, après les siens ;.context.render_factsne porte que le propre rendu du composant. - Dans l’ordre d’émission. Les entrées suivent l’ordre dans lequel le rendu a émis les ressources. Une map de labels est une map à clés comme toutes les autres du contexte, de sorte qu’un template qui en parcourt une rencontre ses clés dans l’ordre des clés.
- Ce qu’un document omet, son entrée l’omet. Une ressource nommée par
generateNamen’a pas dename; une ressource qui n’écrit aucunmetadata.namespacen’a pas denamespace, pas plus qu’une ressource qui l’écrit vide ou null, ce qui ne nomme pas non plus d’espace de noms ; un contrôleur écrit sansmatchLabels— un Job qui s’appuie sur le sélecteur généré par le cluster — n’a pas dematch_labels; un Service sans sélecteur n’a pas deselector; un port sans nom ou sans protocole n’a ni l’un ni l’autre. Toute autre partie écrite vide est signalée vide.protocoln’est signalé que là où le document en écrit un, de sorte qu’un template qui en a besoin écrit lui-même la valeur par défaut propre du cluster,TCP.container_portest un nombre partout où le document en écrit un. namespaceest celui que le document écrit, jamais une supposition. C’est le propremetadata.namespacede la ressource — pour un template de pod, celui de la ressource qui le porte, c’est-à-dire là où ses pods s’exécutent ; un espace de noms écrit à l’intérieur du template de pod lui-même n’est pas lu. Un Workload synthétisé écrit l’espace de noms que déclare sa frontière sur chaque ressource qu’il émet, de sorte que ses entrées portent cet espace de noms. Les entrées d’un chart portent ce qu’écrivent ses documents émis : là où une frontière déclare un espace de noms, cet espace de noms — que les templates du chart le projettent ou que le fournisseur y place la ressource (voir Mode avec source) — sauf si un template en fixe un qui lui est propre, que l’entrée porte à la place ; là où aucun n’est déclaré, l’espace de noms de release,default, là où les templates le projettent, et rien là où ils n’en écrivent aucun. Là où rien n’est écrit, l’entrée ne porte aucunnamespaceplutôt que la valeur par défaut de la frontière ou du cluster, car une telle ressource arrive là où la place l’outil qui applique la sortie, ce qui n’est pas connu lorsque le build s’exécute. Un template distingue les deux cas avecoptional:{{ optional . "namespace" "" }}est vide exactement là où le document n’en a écrit aucun, de sorte qu’une Feature plaçant quelque chose à côté des pods d’un composant peut distinguer un composant dont l’espace de noms des pods est connu d’un composant dont il ne l’est pas.- Reconnus par type et groupe d’API.
PodetServicesont lus dans le groupe core, les quatre contrôleurs dansapps,JobetCronJobdansbatch, à n’importe quelle version du groupe. Une ressource personnalisée d’un autre groupe qui porte par hasard l’un de ces noms de type n’est pas lue comme telle. LesmatchExpressionsd’un sélecteur ne sont pas signalées, pas plus qu’une ressource enveloppée dans un documentkind: Listou qu’une valeur écrite au moyen d’une clé de fusion YAML.
Ce que les faits ne peuvent pas voir. Ils décrivent les documents que le build émet, et rien de ce que le cluster crée ensuite. Les pods qu’un contrôleur crée à l’exécution à partir d’une ressource personnalisée — le cluster de base de données d’un opérateur, par exemple — n’apparaissent dans aucun document émis, ils sont donc absents par construction ; il en va de même de tout label qu’un contrôleur d’admission de mutation ajoute lorsque les manifestes sont appliqués. Une Feature qui doit admettre de tels pods prend leurs labels dans la propre documentation de la ressource personnalisée, comme le ferait un auteur sans ces faits.
Une FeatureRecipe qui admet dans les pods de son hôte exactement les pods des composants qui l’appellent, en sélectionnant les propres pods de l’hôte par le sélecteur du contrôleur de l’hôte :
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: admit-callers version: 1.0.0spec: capability: helm implements: example/admit-callers:1.0.0 readsCallerRenderFacts: true artifacts: allow-callers.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: {{ .context.rendered_name }}-allow-callers spec: podSelector: matchLabels: {{- range .context.render_facts.controller_selectors }} {{- range $k, $v := .match_labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} policyTypes: - Ingress ingress: - from: {{- range .context.used_by }} {{- range .render_facts.pod_template_labels }} - podSelector: matchLabels: {{- range $k, $v := .labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} {{- end }}Pour un hôte api appelé par un composant web dont ce fournisseur a synthétisé le Workload, la politique sélectionne app: "api" et admet un podSelector portant chaque label du template de pod de web — les mêmes labels que contient le spec.template.metadata.labels de son Deployment émis. Comme la FeatureRecipe définit la clé, son rattachement est rendu une fois que chaque composant a été rendu, de sorte que les faits sont présents quel que soit celui de api et web que le build atteint en premier ; sans la clé, un template lisant render_facts sur .context.used_by arrête le build avant que quoi que ce soit ne soit rendu.
Un podSelector dans le from d’une politique correspond aux pods de l’espace de noms propre de la politique, de sorte que la politique ci-dessus admet les appelants émis dans l’espace de noms où elle est appliquée. Un appelant dont les entrées portent un autre namespace est admis en associant son podSelector à un namespaceSelector sur le label kubernetes.io/metadata.name de cet espace de noms, que Kubernetes définit sur chaque espace de noms.
Particularités spécifiques au Provider
-
Les téléchargements de charts n’utilisent que les gestionnaires intégrés de Helm. Un chart récupéré depuis un dépôt Helm est téléchargé avec les propres gestionnaires intégrés
httpethttpsde Helm. Un plugin de téléchargement de Helm — installé pour la commandehelm, ou présent dans le répertoire depuis lequel le build s’exécute — n’est jamais consulté, de sorte que ce qui se trouve dans ce répertoire ne peut pas changer la façon dont un chart est récupéré. -
Injection de la provenance. Les chemins avec source et synthétisé convergent vers le même ensemble de labels et d’annotations ; les rendus avec source les injectent par une réécriture YAML post-rendu (après que le SDK Helm a déjà effectué le rendu), de sorte que les auteurs de charts n’ont pas besoin de faire passer les labels d’Aggrega par leurs propres templates.
-
Ordre de l’environnement — les entrées lues depuis un Secret d’abord. La liste
envd’un conteneur synthétisé porte deux sortes d’entrées : chaque entréeattachmentslivréeas: envlit sa valeur depuis un Secret viavalueFrom.secretKeyRef, et chaque entréevariablesporte une simplevalue. Le fournisseur écrit d’abord chaque entrée lue depuis un Secret et ensuite chaque variable simple, chaque sorte dans l’ordre où elle est rédigée, et liste séparément les sourcesenvFromsousenvFrom. Kubernetes développe une référence$(NAME)dans une valeurenvà partir des entrées listées avant elle dans le même conteneur, jamais à partir d’une entrée listée après, de sorte que cet ordre permet à une variable simple de composer par référence une valeur lue depuis un Secret tandis que le secret lui-même reste dans le Secret :containers:api:image: "api:1.0"variables:DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"attachments:DB_PASSWORD: { from: db-credentials, as: env }Le conteneur rendu liste
DB_PASSWORDavantDATABASE_URL, de sorte que le processus reçoit l’URL avec le mot de passe en place. Une variable peut aussi référencer toute variable rédigée avant elle, ce qui garde son sens à l’ordre de rédaction au sein devariables. Les init containers suivent le même ordre. Un conteneur qui donne un même nom à la fois comme entréevariableset comme entréeattachmentslivréeas: envarrête le build au lieu d’écrire les deux entrées, car cet ordre seul déciderait alors de la valeur que voit le processus (voir A container gives one environment variable two values (Un conteneur donne deux valeurs à une même variable d’environnement)). -
Cascade de l’espace de noms — les deux modes atteignent la ressource différemment. Les deux lisent
aggrega.ai/namespacedans la cascade d’annotations de la frontière, et aucun n’invente d’espace de noms lorsqu’aucune frontière n’en déclare. En mode synthétisé, le fournisseur écrit directementmetadata.namespace, et omet entièrement le champ lorsque la cascade ne produit aucune valeur. En mode avec source, le fournisseur fournit la valeur comme espace de noms de release du chart —defaultlorsque la cascade n’en produit aucun — et le propre template du chart décide s’il le projette ; là où un espace de noms est déclaré, le fournisseur l’écrit ensuite dans chaque ressource à espace de noms que le chart a rendue sans espace de noms (voir Mode avec source). Ainsi, avec un espace de noms déclaré, les deux modes placent chaque ressource à espace de noms dans celui-ci — exception faite d’un espace de noms qu’un chart fixe lui-même, et d’un type que le fournisseur ne peut pas classer. Sans espace de noms déclaré, ils divergent : un chart qui projette l’espace de noms de release place ses ressources dansdefault, là où la sortie synthétisée n’en écrit aucun, et un chart qui n’écrit aucun espace de noms ne les place dans aucun, de sorte qu’elles arrivent là où l’outil qui applique les manifestes les met. Les charts locaux que portent les FeatureRecipes de la bibliothèque standard lisent plutôt la valeur de la cascade directement via leurvaluesMapping: cela leur permet d’omettre le champ lorsqu’aucune frontière ne déclare d’espace de noms, comme la sortie synthétisée, ce que l’espace de noms de release seul ne peut pas exprimer car il n’est jamais vide.
Exemples détaillés
Mode avec source — Recipe pointant vers un chart copié localement :
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helm version: 1.0.0spec: capability: helm implements: core/api-server source: ./vendor/charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }} service: type: ClusterIP port: {{ .values.port }} env: LOG_LEVEL: "{{ optional .values `log_level` "info" }}"Mode Workload — Recipe déclarant un Workload en ligne :
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-workload version: 1.0.0spec: capability: helm implements: core/api-server workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: api: image: "{{ .values.image }}" ports: web: {{ .values.port }} services: svc: type: ClusterIP ports: web: {{ .values.port }}Références croisées
entities/recipe.md— surface de rédaction de la Recipe et les trois types d’entrée.entities/workload.md— schéma du Workload pour le mode synthétisé.providers/helm-chart.md— fournisseur frère qui émet un squelette de chart Helm plutôt que des manifestes à plat.providers/well-known-annotations.md— annotations bien connues que le fournisseur helm applique (aggrega.ai/namespace, etc.).architecture/16-recipe-input-composition.md— Matrice des capacités par Provider commune aux fournisseurs.10-status.md#providers— classification actuelle de la disponibilité.