Nommer une ressource rendue
Une Recipe doit couramment nommer quelque chose que sa propre sortie a produit : un nom d’hôte à publier via provides:, une référence dans un valuesMapping:, un identifiant écrit dans un corps artifacts:. Deux clés du contexte de template portent les noms disponibles à cet effet, et elles répondent à des questions différentes. Lire la mauvaise produit une sortie silencieusement erronée plutôt que refusée — une adresse nommant une ressource que rien n’a émise — c’est pourquoi cette page expose quelle clé répond à quelle question.
Elle expose aussi la distinction sur laquelle reposent les deux clés : une cible et une référence ne sont pas la même chose, et une cible n’est jamais un nom qu’une plateforme de déploiement résoudra.
Une cible nomme un composant ; une référence nomme une ressource rendue
Une cible est une identité de rédaction. C’est la valeur qu’un développeur écrit pour dire vers quel composant pointe une arête — target: my_db dans un bloc uses — et c’est l’identité que le build utilise pour trouver ce composant, en rendre compte dans les diagnostics et indexer ses faits. Elle se lit de la même façon sous chaque fournisseur, car c’est un fait relatif à vos documents plutôt qu’à une quelconque plateforme.
Une référence est ce qui fait pointer un artefact rendu vers un autre. Elle est écrite dans le vocabulaire propre à un fournisseur : une adresse interne au cluster sous helm, un nom de service sous compose, une interpolation sous terraform, une valeur importée sous cloudformation. Une référence est différente sous chaque fournisseur, car chaque plateforme résout les références à sa manière.
🔴 Une cible n’est jamais écrite dans la sortie rendue. Chaque fournisseur dérive ses propres noms, de sorte qu’une identité rédigée transmise à une plateforme comme nom est erronée chaque fois que les deux graphies diffèrent — et elles diffèrent exactement pour les caractères que l’alphabet propre d’une cible n’admet pas. Une identité ne portant aucun caractère de ce type survit inchangée, ce qui rend l’erreur facile à commettre : l’erreur fonctionne jusqu’à ce que quelqu’un nomme un composant avec un trait de soulignement ou une majuscule.
La référence dont un consommateur a besoin est donc publiée par le producteur, car c’est la Recipe d’un producteur qui connaît le vocabulaire de son propre fournisseur — un consommateur peut lier un fournisseur entièrement différent, et ne peut pas écrire une référence pour une plateforme vers laquelle il n’effectue pas de rendu. Le consommateur lit une chaîne publiée ordinaire.
La paire illustrée
La Recipe du producteur publie l’adresse ; le consommateur la relit via l’alias de l’arête.
# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.# It publishes an in-cluster address built from the name that chart's own# templates render their resources against.spec: capability: helm source: ./charts/postgres provides: host: "{{ .context.rendered_name }}.svc.cluster.local" port: "5432"# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an# authoring identity and stays in the documents. The uses block is keyed by the# socket the catalog entity declares, then by the alias you choose for the edge.spec: components: api: type: core/compute/api-server uses: databases: primary: target: my_db inject: env: - in: DB_HOST from: host - in: DB_PORT from: port# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.# The context keys an edge by its alias, so the socket does not reappear here.spec: capability: helm valuesMapping: | { "db_host": "{{ .context.uses.primary.provides.host }}" }Pour un chart fourni par l’auteur sous helm, un composant nommé my_db rend ses ressources sous le nom de release my-zudb. Le chart du producteur émet donc un Service dont le metadata.name est my-zudb, le host publié est my-zudb.svc.cluster.local, et le consommateur contacte un Service qui existe — qu’il lise la valeur via .context.uses.primary.provides.host ou qu’il la reçoive sous la forme du DB_HOST injecté.
Écrire {{ .context.uses.primary.target }} à cet endroit publierait my_db.svc.cluster.local à la place. Cette valeur n’a pas l’air erronée : c’est l’identité que le développeur a écrite, orthographiée exactement comme il l’a écrite. Elle ne nomme simplement aucun Service, et rien dans le build ne le signale.
Les deux clés, en tant que paire
Aucune des deux clés n’est lisible seule, car chacune est définie par ce que l’autre n’est pas.
| Clé | Ce qu’elle nomme |
|---|---|
{{ .context.instance_id }} | L’identité du nœud, et le nom des ressources construites pour ce nœud pour lesquelles aucun fournisseur ne dérive de nom — un ensemble d’artefacts placé depuis votre bloc artifacts:, et un workload synthétisé depuis votre bloc workload: par un fournisseur qui le nomme d’après l’identité, comme le fait compose. Toujours présent. |
{{ .context.rendered_name }} | Le nom que le fournisseur lié dérive pour les ressources qu’il rend pour ce nœud — pour une source que vous avez fournie, le nom par rapport auquel vos propres templates fournis rendent leurs ressources, comme le nom de release qu’un chart lit ; pour un workload: qu’il synthétise, le nom qu’il donne à ces ressources lorsqu’il les nomme d’après un nom qui lui est propre plutôt que d’après l’identité, comme le fait helm. Présent uniquement là où ce fournisseur en dérive un. Sur les templates propres d’un rattachement de Feature, c’est le nom du composant hôte — voir plus bas. |
La séparation découle de l’endroit où le nom doit être utilisable. Un chart ou un module que vous avez fourni a des templates, et ces templates nomment leurs ressources d’après l’identité que la plateforme leur transmet, quelle qu’elle soit — le nom doit donc être celui que cette plateforme utilisera, écrit dans l’alphabet propre à cette plateforme. Un workload synthétisé n’a aucun template de vous, mais ses ressources doivent tout de même porter des noms que la plateforme accepte : un fournisseur dont les noms admettent tout ce qu’un nom rédigé par l’auteur peut contenir les nomme d’après l’identité, et un fournisseur dont les noms ne l’admettent pas les nomme d’après le nom qu’il dérive — puis signale ce nom ici, de sorte que vous n’ayez jamais à le prévoir.
Un nœud qui déclare à la fois une source fournie et un workload: émet les deux types de sortie en même temps, et n’a besoin d’aucune troisième clé. Sous helm, les deux sont nommés d’après l’unique nom de release, donc rendered_name sert pour l’un comme pour l’autre : les ressources propres du chart le portent, quelle que soit la façon dont ses templates le composent, et chaque Service synthétisé est <rendered_name>-<service key>. Sous un fournisseur qui nomme un workload synthétisé d’après l’identité, nommez les ressources de ce workload avec instance_id et celles de la sortie fournie avec ce que le fournisseur signale pour elle.
Les alphabets sont la raison pour laquelle les deux peuvent différer. Un nom de composant rédigé par l’auteur peut contenir un trait de soulignement ou une lettre majuscule ; le nom de release d’un chart ne le peut pas, et plutôt que de ramener un tel caractère à un caractère semblable — ce qui permettrait à deux composants que vous savez distinguer d’aboutir à un seul nom dans un cluster — la dérivation l’écrit en toutes lettres. Voir ../providers/helm.md « How the release name is derived (Comment le nom de release est dérivé) » pour l’alphabet et la limite de longueur propres à ce fournisseur.
Quels fournisseurs signalent un nom, et pourquoi les autres non
helm en signale un : le nom de release. Un chart fourni comme source le lit sous la forme .Release.Name et nomme couramment ses ressources d’après lui, et le fournisseur nomme d’après lui aussi chaque ressource qu’il synthétise pour un composant — le contrôleur sous le nom de release lui-même, et chaque Service sous la forme <release name>-<service key>. Une adresse publiée pour l’un ou l’autre type de sortie est donc construite à partir de rendered_name. Pour un nœud qui place seul un ensemble d’artefacts, il n’en signale aucun : les noms de cet ensemble sont ceux que son auteur a écrits.
# A synthesized helm Recipe publishing the address of the Service its workload# declares under the key `default`.spec: capability: helm workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "valkey/valkey:8" ports: redis: 6379 services: default: type: ClusterIP ports: redis: 6379 provides: host: "{{ .context.rendered_name }}-default" port: "6379"Un composant nommé cache publie cache-default, et un composant nommé my_cache publie my-zucache-default — dans chaque cas, le nom du Service que le build émet.
Les quatre autres n’en signalent aucun, et les raisons ne sont pas les mêmes. Aucun d’eux n’est un fournisseur en attente de prise en charge — dans chaque cas, soit il n’y a aucun nom dérivé à signaler, soit le nom que vous voulez est déjà accessible autrement.
-
cloudformationetcompose— vous avez écrit les noms, ou l’identité est le nom. Une Recipe cloudformation rédige les identifiants logiques de ses ressources et le fournisseur les lit exactement tels qu’ils sont écrits ; un fichier compose que vous avez fourni nomme ses propres services et le fournisseur fusionne et étiquette ce fichier sans rien y renommer. Un workload quecomposesynthétise est nommé d’après l’identité du nœud, qu’un fichier compose admet telle qu’elle est écrite, donc{{ .context.instance_id }}est ce nom. Il n’y a aucune dérivation à signaler, et les noms sont ceux qui figurent dans vos propres documents. Ce nom est le service principal du workload, celui qu’atteint un pair ; un service sidecar ou d’initialisation qu’il porte est nommé à partir de la même identité et du nom du conteneur, joints par--, comme le décrit Comment un service sidecar ou d’initialisation est nommé. -
terraform— le nom dépend de l’endroit où les fichiers ont été placés. Le blocmoduled’un contributeur est nommé d’après le répertoire de sortie dans lequel sa configuration a été écrite, ce qui est fixé lorsque les fichiers de la frontière sont assemblés plutôt que lorsqu’un nœud est rendu. Au moment où les templates d’une Recipe s’exécutent, cette position n’existe pas encore. -
helm-chart— le nom qu’il dérive est l’adresse propre du chart placé, ce qui est autre chose que le nom par rapport auquel les templates de ce chart effectuent leur rendu. Ce fournisseur fixe le champnamed’un chart que vous avez intégré par vendoring à l’identité encodée de ce qui l’a apporté, qui est aussi l’alias sous lequel l’umbrella lie ce sous-chart et la clé sous laquelle ses valeurs sont délimitées. Pour un composant, cette identité est ce que porte{{ .context.instance_id }}, donc le nom du chart placé est déjà accessible sous la clé qui dit ce qu’il est. Le nom par rapport auquel les propres templates du chart intégré effectuent leur rendu est le nom de release, que la release de l’umbrella fournit au moment de l’installation au lieu que ce fournisseur le dérive — il n’y a donc ici aucun nom de ce type que cette clé puisse signaler. Voir../providers/helm-chart.md« The chart name the umbrella owns (Le nom de chart qui revient au chart parapluie) ».
Lire la clé là où aucun nom n’est signalé
Lire {{ .context.rendered_name }} sur un nœud dont le fournisseur ne signale aucun nom de ce type arrête le build, et le diagnostic indique quelle clé écrire à la place. Aucune valeur vide n’est rendue : une adresse à laquelle il manque un segment est un artefact erroné qui est déployé, ce qui est pire qu’un build qui s’arrête.
Le remède que propose l’arrêt dépend du nœud plutôt que de l’endroit où vous avez écrit la référence :
- Un nœud qui ne fournit aucune source propre, sous un fournisseur qui ne signale aucun nom pour lui, a ses ressources nommées d’après son identité, donc l’arrêt nomme
{{ .context.instance_id }}— il existe une valeur correcte et il le dit. - Un nœud qui fournit bien une source, sous un fournisseur qui ne dérive aucun nom pour lui, n’a aucun substitut. L’arrêt le dit au lieu d’en proposer un, car vous renvoyer à l’identité dans ce cas nommerait des ressources que votre nœud ne porte pas.
Le refus couvre provides: et tout autre template qu’une Recipe écrit en ligne — son valuesMapping:, son corps workload:, chaque entrée artifacts:, et les with: et when: de chaque étape de pipeline.
🔴 Les deux formes d’import en sont exclues. Une entrée valuesMapping:, workload: ou artifacts: fournie via $import: — que l’import nomme un fichier local ou une entrée de bibliothèque — ne porte aucun texte dans votre Recipe tant que le rendu ne la résout pas, donc une référence à cette clé à l’intérieur d’un tel corps n’est pas vérifiée. Elle rend le nom que signale le fournisseur du nœud importateur là où ce fournisseur en signale un, et une valeur vide plutôt qu’un arrêt là où il n’en signale aucun. Un corps importé ne lit donc la clé que lorsque chaque Recipe qui l’importe est liée à un fournisseur qui signale un nom — une entrée de bibliothèque écrite pour des Recipes helm qui prennent un chart comme source, et qui le dit dans sa description. Un corps destiné à des importateurs dont le fournisseur peut n’en signaler aucun prend plutôt le nom au moyen d’une valeur que définit la Recipe importatrice.
Les entrées locals: d’une Recipe ne lisent pas du tout la clé. Un local partage son contexte avec le template source: de la Recipe, et le fait que le nœud fournisse une source est l’une des choses dont dépend le nom, donc le nom n’y est pas proposé. Une référence à {{ .context.rendered_name }} dans un local provoque donc un arrêt quoi que signale le fournisseur, avec le diagnostic d’une référence que le contexte de rendu ne définit pas (E0060), qui indique .context.instance_id comme l’unique clé que .context y propose. Lisez la clé dans l’entrée provides: ou dans le template en ligne qui en a besoin.
Sur les templates propres d’un rattachement de Feature
Sur les templates qu’écrit la FeatureRecipe d’un rattachement de Feature — ses locals:, source:, provides:, injectMapping:, valuesMapping:, workload:, chaque entrée artifacts:, et les with: et when: de chaque étape de pipeline — {{ .context.rendered_name }} est le nom du composant hôte : celui que le fournisseur propre de l’hôte signale pour les ressources qu’il rend pour l’hôte, qui est la valeur que lit la Recipe propre de l’hôte. Il fait la paire avec {{ .context.instance_id }}, qui, sur ces templates, est l’identité du composant hôte ; le rattachement lui-même est .attachment_name. Un rattachement écrit sur l’une des connexions d’un composant lit le nom du composant consommateur, car ce composant est son hôte.
C’est la clé à partir de laquelle construire les noms des ressources propres d’un rattachement. Une FeatureRecipe qui nomme un Secret, une route ou une politique d’après le composant auquel elle est rattachée a besoin d’un nom que la plateforme accepte, et l’identité de l’hôte telle qu’elle est écrite n’en est pas un dès qu’elle contient un trait de soulignement ou une lettre majuscule. Sous helm, un composant nommé my_db signale my-zudb, donc un Secret nommé {{ .context.rendered_name }}-{{ .attachment_name }} pour un rattachement root est rendu sous la forme my-zudb-root, là où {{ .context.instance_id }} donnerait my_db-root, qu’un cluster refuse. La valeur reste celle de l’hôte, quel que soit le fournisseur par lequel le rattachement est rendu.
Elle est présente partout où le fournisseur de l’hôte signale un nom — sous helm, un hôte dont la Recipe fournit un chart ou déclare un workload: — et absente là où il n’en signale aucun : un hôte qui place seul un ensemble d’artefacts, et un hôte sur tout autre fournisseur. La lire sur un rattachement d’un tel hôte arrête le build avec le diagnostic d’une référence que le contexte de rendu ne définit pas (E0060), qui indique les clés que .context y définit. {{ .context.instance_id }} en fait partie, et c’est d’après elle que sont nommées les ressources propres de l’hôte sur un tel hôte, donc une FeatureRecipe écrite pour des hôtes susceptibles de ne signaler aucun nom lit plutôt l’identité.
Le refus couvre les templates qu’une FeatureRecipe écrit en ligne, à l’exception de son injectMapping:. Un injectMapping:, ainsi qu’une entrée valuesMapping:, workload: ou artifacts: que la FeatureRecipe fournit via $import:, ne sont pas vérifiés : sur un hôte qui ne signale aucun nom, une référence à cet endroit rend une valeur vide au lieu de provoquer un arrêt.
Lorsqu’un rattachement livre un chart fourni par son auteur, les templates de ce chart effectuent leur rendu par rapport au nom de release du composant hôte, délibérément : le dériver plutôt du rattachement renommerait des ressources que l’auteur du chart a déclarées et a peut-être déjà déployées. .attachment_name est la valeur qui distingue deux rattachements sur un même hôte — voir ../providers/helm.md « How the release name is derived (Comment le nom de release est dérivé) ».
Noms dérivés du rattachement d’une connexion
Un rattachement que porte une connexion est un rattachement du composant consommateur, nommé <alias>.<slot> — gpt.credential pour le slot credential de la connexion écrite sous l’alias gpt (voir l’entrée de connexion de l’Aggregate). Ce nom composé est le .attachment_name par rapport auquel sa FeatureRecipe effectue son rendu, et il contient le point.
Il en découle deux types de nom, qui traitent le point différemment.
Un nom que compose la FeatureRecipe conserve ce que son template écrit, quoi que ce soit. Les réalisations d’informations d’identification de la bibliothèque standard nomment leur ressource {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, donc les informations d’identification sur la connexion gpt d’un composant nommé router sont rendues sous la forme d’une ressource nommée router-gpt.credential, point compris, ce qui est un nom d’objet Kubernetes valide. Le point subsiste dans un nom de ce type exactement lorsque le template le conserve.
Un nom que le build dérive de l’identité du rattachement écrit le point en toutes lettres. Les labels d’identité et le fichier émis sont composés à partir du composant hôte et du nom du rattachement au moyen du même encodage que traverse tout nom dérivé d’une identité, et celui-ci écrit le point sous la forme zd et une lettre majuscule sous la forme d’un échappement de son point de code, car l’identité sert de nom de ressource aussi bien que de label, et un nom de Service n’admet ni l’un ni l’autre : une connexion écrite sous l’alias gptPro aboutirait à cfr--router--gpt-zx000050ro-zdcredential. La ressource ci-dessus porte le label aggrega.ai/component-id: cfr--router--gpt-zdcredential (et app.kubernetes.io/name de même), et sous le fournisseur helm elle est émise sous la forme router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Voir Conventions de nommage « The separator does not reach a name (Le séparateur n’atteint pas un nom) » pour savoir pourquoi le point est écrit en toutes lettres plutôt que remplacé.
Sujets connexes
- Contrat du contexte de template — la forme complète du contexte dans lequel se trouvent ces clés.
- Matrice d’expansion des templates — quels piliers lit chaque emplacement de template.
- Triade de topologie :
provides,inject,uses— comment une valeur publiée franchit une arête jusqu’à un consommateur. - Conventions de nommage — ce que vous pouvez écrire comme nom de composant, et ce que coûte un nom sous un alphabet plus restreint.
errors/fatal-halts.md— l’arrêt que décrit cette page, avec le message qu’il émet.