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

Provider Terraform

Le fournisseur terraform rend les Recipes d’Aggrega en configuration Terraform. Il émet de la configuration et n’exécute jamais Terraform : un build d’Aggrega est une compilation ahead-of-time, il ne peut donc pas résoudre les ID de ressources, les adresses IP et les sorties qui n’existent qu’après terraform apply. Les interpolations ${ ... } de Terraform passent intactes sous forme de chaînes de pointeurs déterministes que le runtime Terraform résout plus tard. Le fournisseur est hors ligne et hermétique — il ne touche jamais au réseau et n’invoque jamais terraform ni tofu.

Comment une frontière est organisée

Le fournisseur terraform compose une frontière au lieu d’en émettre les composants côte à côte. Chaque frontière dont il effectue le rendu reçoit une seule configuration racine, aggrega.modules.tf, qui déclare chaque composant rendu à cet endroit comme un bloc module dont le source est le sous-répertoire propre de ce composant sous modules/ :

module "cache" {
source = "./modules/cache"
}
module "db" {
source = "./modules/db"
allocated_storage = 100
db_name = "appdb"
engine_version = "11.4"
}

Les fichiers propres de chaque composant — le module copié localement (vendoring) ou le corps rédigé, ainsi que le tampon de provenance — se trouvent dans le sous-répertoire vers lequel pointe son bloc. C’est la structure standard de Terraform dans laquelle la racine compose les enfants, dont la convention veut que les modules imbriqués se trouvent sous un sous-répertoire modules/, et c’est l’organisation que reçoit chaque frontière terraform, qu’elle contienne un seul composant ou plusieurs. Une Feature rattachée à un composant ou à la frontière est déclarée comme un bloc module à part entière dans la même configuration racine — voir Où aboutit la sortie d’une Feature rattachée.

La forme est structurante et non cosmétique, pour deux raisons.

Un graphe de dépendances Terraform est propre à chaque configuration. Les Components émis dans des répertoires distincts sont des graphes distincts sans aucune relation : ni une référence ni un depends_on ne peut aller de l’un à l’autre, et aucun terraform plan ne les voit tous les deux. Une seule racine qui compose chaque composant comme module enfant place une frontière entière dans un seul graphe et un seul plan.

Les fichiers d’un composant sont adressés par son propre répertoire. Deux composants d’une même frontière peuvent copier localement des modules qui écrivent des fichiers portant le même nom — main.tf, variables.tf — et chaque ensemble se trouve sous le répertoire de son propre composant au lieu de se disputer un même chemin.

Où un fournisseur est configuré

La configuration d’un fournisseur — un bloc provider — est écrite à la racine, jamais à l’intérieur du module d’un composant. La documentation de Terraform indique qu’un module destiné à être appelé par un autre ne doit pas contenir de blocs provider, et qu’un module appelé hérite de la configuration par défaut de la racine pour chaque fournisseur que ce module utilise. Un module portant son propre bloc provider ne peut pas être appelé avec depends_on, count ou for_each, et ce fournisseur écrit depends_on sur le bloc module d’un composant chaque fois qu’un autre composant de la même racine porte un syncWave antérieur, comme le décrit Ordre de déploiement ci-dessous ; Terraform refuse alors toute la configuration pendant son chargement, avant de planifier quoi que ce soit.

Ainsi, une Recipe dont le fournisseur doit être configuré écrit cette configuration sous forme de fichier sous spec.boundary.artifacts. Chacun de ces fichiers est écrit une seule fois à côté de aggrega.modules.tf, où Terraform le lit avec la configuration racine, et le module du composant ne conserve que sa déclaration required_providers de la source et de la version du fournisseur :

infra/terraform/
aggrega.modules.tf
provider-azurerm.tf
modules/
gateway/main.tf

Les Components d’une même racine qui déclarent le même fichier avec les mêmes octets en partagent l’unique copie ; le même nom avec des octets différents arrête le build. Les ressources des modules sont enregistrées par rapport à cette configuration unique, c’est donc aussi avec elle que Terraform les détruit. Une Release qui retire le dernier composant déclarant le fichier retire le fichier avec lui, et Terraform refuse alors de planifier la destruction de ce que ces modules ont créé, en demandant un bloc provider qui configure le fournisseur. Détruisez ces ressources avant de retirer le dernier de ces composants.

Où les entrées d’un composant sont fournies

Les entrées d’un composant sont les arguments de son bloc module dans la configuration racine, et c’est le seul endroit où elles sont écrites. Un bloc porte des arguments lorsque le compilateur fournit les entrées du module — une Recipe qui copie localement un module avec source:. Il est vide lorsque la Recipe a rédigé elle-même le corps de la configuration et y a résolu ses valeurs, de sorte qu’il ne reste rien à transmettre pour le compilateur.

Un argument de module est une position que Terraform évalue, c’est pourquoi c’est là que vont les valeurs. Un pointeur ${ ... } fourni par une Recipe s’y résout au lieu d’arriver au module comme une chaîne littérale. Ce par rapport à quoi il se résout, c’est la configuration racine : une référence nomme quelque chose que cette configuration déclare — l’un de ses blocs module, sous la forme module.<name>.<output> — et une référence à tout ce qu’elle ne déclare pas est une erreur explicite au moment du plan, qui nomme le référent manquant.

Le répertoire propre d’un composant n’est donc pas une configuration que vous pouvez planifier telle qu’elle est déployée. Ses entrées sont indiquées un niveau plus haut, dans la racine, de sorte que se placer dans modules/<component> et y exécuter le moteur planifie autre chose, et laquelle de deux choses se produit dépend des blocs variable propres au module :

  • Lorsqu’au moins une entrée ne déclare aucun default, le plan échoue de manière explicite — No value for required variable, en nommant chaque variable non définie et sa ligne, et en proposant le remède propre à Terraform, -var / -var-file.
  • Lorsque chaque entrée porte un default, le plan réussit et se construit à partir des valeurs par défaut du module plutôt qu’à partir des valeurs que fournit la configuration racine. Rien n’avertit, c’est donc le cas à connaître : un plan qui semble correct décrit une configuration que personne n’a demandée.

Planifiez plutôt le répertoire de sortie propre à la frontière — celui qui contient aggrega.modules.tf, immédiatement au-dessus de modules/. C’est là que se trouvent les valeurs du déploiement, et c’est le seul endroit où un plan unique voit toute la frontière.

Consommer la valeur publiée d’un autre composant

Un composant relié à un autre par une arête uses lit les valeurs publiées de ce composant par son propre pipe .context.inject (ou par .context.uses.<alias>.provides.<name>). Ce qu’il lit est une chaîne que le compilateur achemine sans l’interpréter, et l’endroit où cette chaîne aboutit est du texte que Terraform évalue dans la portée où la Recipe l’a écrit. Une frontière terraform a deux portées de ce type, et une seule d’entre elles déclare les appels de module dont une référence entre composants a besoin :

  • la configuration racine déclare chaque contributeur comme un bloc module, donc module.<name>.<output> s’y résout ;
  • le répertoire propre d’un composant ne déclare aucun appel de module, donc module.<name>.<output> n’y nomme rien — quel que soit <name>. Substituer le nom correct ne change rien, car ce qui manque, c’est la déclaration, pas l’orthographe.

C’est donc le type d’entrée de la Recipe consommatrice qui décide si une référence consommée peut se résoudre, et non la valeur consommée.

Écrivez une Recipe consommatrice comme une Recipe source:. Son valuesMapping: devient les arguments de son propre bloc module dans la configuration racine — la seule position qui soit à la fois évaluée et dans une portée où ses voisins sont déclarés.

Une paire détaillée

Le producteur publie une adresse qui nomme son propre appel de module, c’est-à-dire la forme que la portée de son consommateur déclare. .context.instance_id se trouve sur la surface d’évaluation de provides, et pour un composant que déclare l’Aggregate du déploiement, c’est le nom que porte le bloc module de ce composant :

# Recipe — the producer. Its vendored module declares `output "endpoint"`.
spec:
capability: terraform
implements: example/storage/object-store:1.0.0
source: ./module
valuesMapping: |
bucket: "{{ .values.bucket }}"
provides:
endpoint: "${module.{{ .context.instance_id }}.endpoint}"

Le consommateur copie localement un module qui déclare une entrée, et y fait correspondre la valeur injectée :

# Recipe — the consumer. Its vendored module declares `variable "store_endpoint"`.
spec:
capability: terraform
implements: example/compute/reporting-api:1.0.0
source: ./module
valuesMapping: |
store_endpoint: "{{ .context.inject.env.STORE_ENDPOINT }}"

L’Aggregate les relie, en nommant la clé publiée que porte l’arête :

spec:
components:
store:
type: example/storage/object-store
values:
bucket: app-artifacts
api:
type: example/compute/reporting-api
uses:
store:
store:
target: store
inject:
env:
- in: STORE_ENDPOINT
from: endpoint

Le build émet une seule configuration racine dans laquelle la référence et son référent sont déclarés ensemble :

module "api" {
source = "./modules/api"
store_endpoint = "${module.store.endpoint}"
}
module "store" {
source = "./modules/store"
bucket = "app-artifacts"
}

Terraform résout module.store.endpoint parce que la même configuration déclare module "store", et la valeur atteint le module du consommateur comme une entrée ordinaire.

L’exemple aws-rds-and-ecs-service construit cette paire à partir de Recipes de la bibliothèque standard : une base de données PostgreSQL provisionnée par le module RDS publié et un serveur exécuté sur Amazon ECS, dont l’argument environment porte ${module.db.db_instance_address} dans la configuration racine qui déclare module "db".

Trois façons dont cela tourne mal, et à quoi ressemble chacune

Une Recipe qui rédige son propre corps ne peut pas consommer une référence entre composants. Une Recipe artifacts: résout ses valeurs dans le corps qu’elle écrit, et ce corps est émis dans le répertoire propre du composant. La référence se trouve alors dans une portée qui ne déclare aucun appel de module :

Error: Reference to undeclared module
on modules/api/main.tf line 11, in output "seen":
11: value = "${module.store.endpoint}"
No module call named "store" is declared in module.api.

Aucune orthographe ne corrige cela, car les expressions d’un module imbriqué ne peuvent pas du tout nommer un module frère — un module imbriqué ne reçoit la valeur d’un voisin que comme entrée, c’est-à-dire l’argument du bloc module que le chemin avec source fournit déjà. Un composant qui consomme la valeur publiée d’un autre composant s’écrit comme une Recipe source:.

Une adresse qui nomme quelque chose à l’intérieur du propre module du producteur se résout par rapport à la racine, et non par rapport à ce module. Une entrée provides qui écrit aws_db_instance.this.endpoint nomme une ressource que déclare le module du producteur ; écrite comme une interpolation, elle est évaluée là où se trouve l’argument du consommateur, c’est-à-dire à la racine :

Error: Reference to undeclared resource
on aggrega.modules.tf line 19, in module "api":
19: store_endpoint = "${aws_db_instance.this.endpoint}"
There is no managed resource "aws_db_instance" "this" definition in the root module.

Publiez ${module.<...>.<output>} et donnez au module un bloc output pour la valeur, au lieu d’aller chercher dans ses ressources.

Une entrée provides sans interpolation est livrée comme texte. C’est le cas qui n’échoue pas : le compilateur achemine des chaînes et ne peut pas distinguer un pointeur d’un littéral, donc aws_db_instance.this.endpoint écrit sans ${ ... } est rendu comme une chaîne entre guillemets, le build réussit, le moteur valide, et le consommateur reçoit les caractères aws_db_instance.this.endpoint. Écrivez l’enveloppe ${ ... } chaque fois que la valeur est censée être une référence — c’est elle qui marque la chaîne comme quelque chose que Terraform doit évaluer.

Une limite à connaître avant de vous y fier

.context.instance_id exprime l’identité du composant, et le nom d’un bloc module est dérivé du répertoire dans lequel se trouvent les fichiers du composant. Pour un composant que déclare l’Aggregate propre au déploiement, il s’agit du même nom. Pour un composant intégré par composition depuis un autre Aggregate, ce n’est pas le cas : l’identité composée et le nom du module sont écrits différemment dans leurs deux alphabets, et la référence échoue alors de manière explicite à la racine plutôt qu’en silence :

Error: Reference to undeclared module
on aggrega.modules.tf line 25, in module "api":
25: store_endpoint = "${module.nested-zdinner.endpoint}"
No module call named "nested-zdinner" is declared in the root module.

Déclarez un producteur dont un autre composant résout l’adresse dans l’Aggregate propre au déploiement, à côté du composant qui le consomme.

Où aboutit la sortie d’une Feature rattachée

Un rattachement de Feature qui effectue le rendu d’une configuration qui lui est propre reçoit un module à lui, déclaré dans la même configuration racine que les composants à côté de lui. C’est ce qui fait de sa configuration une partie du déploiement : Terraform ne charge que les fichiers situés directement dans un répertoire et traite un répertoire imbriqué comme un module entièrement distinct qui doit être appelé explicitement, de sorte que les fichiers d’un rattachement sont lus parce que la racine déclare un bloc nommant le répertoire dans lequel ils se trouvent.

Le répertoire de module d’un rattachement se trouve à côté de celui du composant, un niveau sous modules/, et est nommé d’après les deux choses qui l’identifient — le composant qui l’héberge et le nom sous lequel il a été rattaché, joints par --. Ainsi, pour un composant api portant un rattachement nommé aux, la configuration racine déclare deux modules :

module "api--aux" {
source = "./modules/api--aux"
}
module "api" {
source = "./modules/api"
}

Une Feature rattachée à la frontière plutôt qu’à un composant n’a pas de composant hôte à nommer, donc son répertoire est son seul nom : un rattachement nommé aux sur une frontière contenant le composant api donne ./modules/aux à côté de ./modules/api.

Pourquoi à côté plutôt qu’à l’intérieur. Terraform fusionne chaque fichier de premier niveau d’un répertoire de module dans un seul espace de noms — output, variable, resource et locals de la même manière — de sorte que deux contributeurs qui partagent un répertoire entrent en collision sur tout nom qu’ils déclarent tous les deux, quel que soit le nom de leurs fichiers. Un répertoire chacun, c’est ce qui les tient séparés. À côté plutôt qu’à l’intérieur, c’est aussi ce que demandent les recommandations de Terraform lui-même pour les modules imbriqués : qu’ils puissent être composés par l’appelant plutôt que de s’appeler directement les uns les autres en créant une arborescence de modules profondément imbriquée.

La jonction est échappée par coordonnée. Chacune des deux coordonnées est écrite dans l’alphabet des répertoires avant leur jonction, de sorte qu’une coordonnée qui contient elle-même -- ne peut pas être confondue avec la jonction : un hôte nommé a--b avec un rattachement c se distingue d’un hôte a avec un rattachement b--c. Les lettres ASCII, majuscules et minuscules, les chiffres, le point et le trait de soulignement passent tels qu’ils sont écrits ; un tiret que vous avez écrit est conservé partout où le caractère qui le suit est l’un de ceux-là ; tout le reste est échappé. La même règle et le même alphabet produisent les répertoires enfants d’une cible chart, de sorte que le répertoire d’un rattachement s’écrit de la même façon quelle que soit celle des deux cibles qui en effectue le rendu.

Le nom d’un bloc est dérivé du répertoire vers lequel pointe son source, chaque caractère hors de la grammaire de Terraform pour un nom de module étant remplacé par un trait de soulignement. Cette correspondance n’est pas bijective, donc là où deux contributeurs aboutiraient à un même nom de module, le build s’arrête et les nomme tous les deux, plutôt que d’émettre une configuration que Terraform refuserait.

Trois choses découlent du fait qu’un rattachement est un module à part entière.

Ses entrées sont celles de son propre mapping. Pour un rattachement dont la FeatureRecipe prend un module comme source et déclare un valuesMapping, les valeurs que produit ce mapping sont écrites comme arguments de son propre bloc module, de la même façon que le module avec source d’un composant reçoit ses valeurs. Une FeatureRecipe qui ne déclare aucun valuesMapping ne passe aucun argument à son module : une variable que le module déclare avec un default le prend, et une variable déclarée sans valeur par défaut reste non définie, de sorte que Terraform refuse le plan.

Ses ressources se trouvent dans l’unique graphe de dépendances de la frontière. Une référence ou un depends_on relie un rattachement et le composant auquel il est rattaché, dans les deux sens, et un seul terraform plan voit les deux — la même propriété que la forme dans laquelle la racine compose les enfants donne aux composants, pour la même raison.

Ses noms de premier niveau lui appartiennent. Comme la fusion d’espaces de noms décrite plus haut se fait par répertoire, un contributeur situé dans son propre répertoire déclare ses noms output, variable, resource et locals sans entrer en concurrence avec ceux de ses voisins — ainsi un rattachement peut réutiliser un nom que son hôte déclare déjà, et aucun des deux n’a besoin de savoir comment l’autre a nommé quoi que ce soit.

Notez ce qui n’est pas exigé par cette cible, car la contrainte d’une cible chart est différente et l’organisation partagée peut être lue comme impliquant plus qu’elle ne le fait : un module imbriqué dans le répertoire d’un autre contributeur reste accessible ici, puisque la configuration racine lit le source de chaque contributeur à partir de la position que le build a composée plutôt que de le reconstruire à partir d’un identifiant. Ce que cette cible refuse, c’est que deux contributeurs partagent un répertoire. Une cible chart refuse purement et simplement la position imbriquée, car elle découvre un chart enfant un niveau plus bas et pas au-delà.

Types d’entrée pris en charge

Le fournisseur terraform accepte deux des trois types d’entrée de Recipe :

  • Mode artefacts. Une Recipe rédige la configuration Terraform sous forme de corps basé sur un template ; le fournisseur évalue le template Aggrega et émet le résultat sans le réécrire. HCL (main.tf) est le choix par défaut le plus ergonomique, et Terraform JSON (.tf.json) est accepté de manière équivalente. La provenance du build est apposée sous forme d’un bloc de commentaires Terraform en tête d’un corps HCL ; pour un corps JSON — qui n’a pas de syntaxe de commentaire — la provenance est écrite dans un fichier compagnon, aggrega.provenance.tf, plutôt qu’en ligne.
  • Mode avec source. Une Recipe référence un module Terraform avec source:. Les fichiers du module sont copiés localement (vendoring) tels quels dans le répertoire de ce composant, et le valuesMapping: de la Recipe devient les arguments du bloc module de ce composant dans la configuration racine de la frontière. Le corps du module est conservé exactement tel qu’il a été rédigé et rien n’y est écrit ; les valeurs sont indiquées une seule fois, dans la racine, là où Terraform les évalue. Lorsque les feuilles values déclarées du nœud deviennent directement les entrées du module — une Recipe source: sans valuesMapping: — une entrée portant un contenu qu’un auteur a déclaré sensible reçoit aussi un fichier de surcharge généré portant l’attribut de sensibilité propre à Terraform ; un template valuesMapping: invente ses noms de sortie, ce cas ne porte donc aucun marquage et le build le signale par un avis consultatif. Les deux sont décrits sous Entrées de module déclarées sensibles.

Un null dans un valuesMapping: est un argument null. Une clé que le mappage définit à null est écrite sous la forme <name> = null dans le bloc module, et le moteur donne à la variable du module la valeur null, ce qui remplace son default, sauf si la variable déclare nullable = false, auquel cas son default s’applique ; pour donner à une entrée la valeur par défaut du module, omettez la clé du mappage.

Le type d’entrée synthétisé n’est pas proposé. Il n’existe aucune correspondance fidèle et agnostique vis-à-vis des capacités entre le type Workload de la plateforme et des ressources Terraform arbitraires, de sorte qu’une Recipe qui déclare workload: avec le fournisseur terraform est une erreur explicite plutôt qu’une traduction inventée.

Une Recipe déclarant omits: est refusée. La clé omits: exclut du build des documents qu’une source rend, et ce fournisseur ne rend rien à partir d’un module avec source au moment du build : il copie localement les fichiers du module tels quels, et Terraform les évalue lorsque la configuration est planifiée et appliquée. Sans rien de rendu, il n’y a rien à exclure, donc ce fournisseur ne déclare pas qu’il honore la clé, et une Recipe ou une FeatureRecipe qui la déclare est refusée avant que quoi que ce soit ne soit copié localement — voir The provider does not support omits (Le fournisseur ne prend pas en charge omits). Pour un module que vous conservez à côté de la Recipe, une ligne dans le .aggregaignore qui s’y trouve exclut plutôt un fichier du module, à partir du prochain pin de la Recipe.

Utiliser comme source un module publié par un registre

Un registre de modules publie chaque version d’un module sous forme de tag du dépôt git propre au module, et ce qu’il répond lorsqu’on lui demande de télécharger une version est une source git épinglée au commit que ce tag désigne. Une Recipe utilise donc comme source un module publié depuis ce dépôt à ce tag, avec le type de source git-repository :

spec:
capability: terraform
implements: example/storage/database:1.0.0
source:
kind: git-repository
url: https://github.com/terraform-aws-modules/terraform-aws-rds.git
ref: v7.2.2
valuesMapping: |
identifier: "{{ .values.identifier }}"
provides:
host: "${module.{{ .context.instance_id }}.db_instance_address}"
port: "${module.{{ .context.instance_id }}.db_instance_port}"

ref: est le tag de version exactement tel que le dépôt le nomme. valuesMapping: fournit les entrées du module, sous les noms que déclarent ses blocs variable — Terraform exige une valeur pour chaque entrée qui ne déclare aucun default — et elles deviennent les arguments du bloc module de ce composant dans la configuration racine, comme pour tout module avec source.

Ce qui est épinglé. aggrega pin et le pull résolvent le tag vers le commit qu’il désigne et archivent le dépôt à ce commit. Le fichier de verrouillage de la Release enregistre ensuite ce commit comme version épinglée de la source, le tag comme la référence que vous avez écrite, et le digest de l’archive. Chaque build ultérieur lit l’archive depuis le cache et la vérifie par rapport à ce digest avant de copier localement quoi que ce soit, il n’a donc besoin d’aucun réseau, et une archive en cache dont les octets ne correspondent plus arrête le build. Un tag est un nom qu’un dépôt peut déplacer vers un autre commit ; un pull ultérieur qui trouve le vôtre résolu ailleurs s’arrête au lieu d’adopter le nouveau commit, et aggrega pull --upgrade l’adopte délibérément. C’est un épinglage plus strict que le fichier de verrouillage des dépendances propre à Terraform, qui enregistre les fournisseurs qu’une configuration a sélectionnés et aucun module, de sorte qu’un module écrit dans une configuration comme source git à un tag n’est fixé que dans la mesure où le tag l’est. Ici, le commit du module et le digest de ses octets sont fixés dans le fichier de verrouillage, les octets sont copiés localement dans la sortie, et la configuration racine les appelle par un chemin local, de sorte que le moteur ne récupère rien pour charger le module lui-même — un module que celui copié localement appelle par une source de registre ou distante est tout de même récupéré, et le build signale chacun de ces appels, comme le décrit Un appel de module que le moteur récupère lors de son initialisation.

Ce qui est copié localement. L’ensemble du dépôt au commit épinglé, à l’exception de son répertoire .git/, arrive dans le répertoire propre du composant sous modules/, octet pour octet — les fichiers de configuration et les modules enfants propres au module, mais aussi tout ce que le dépôt contient d’autre : ses répertoires examples/ et wrappers/, sa documentation, sa configuration de CI et toutes les fixtures de test, y compris binaires. Le moteur ne lit que ce que le module appelle : lorsque la configuration racine appelle le répertoire du composant, le moteur charge les fichiers de configuration situés directement dans celui-ci et dans chaque répertoire qu’un source local atteint à partir de là. Un répertoire d’exemple qui appelle d’autres modules de registre est donc copié localement et jamais chargé, et rien de ce qu’il appelle n’est récupéré.

Restreindre ce qui est copié localement. Une source récupérée est l’archive sous laquelle elle a été récupérée, donc la seule façon de la restreindre est module_subdir:, qui fait d’un répertoire du dépôt l’artefact. Cela n’aide que lorsque le module voulu se trouve dans un sous-répertoire : un module à la racine du dépôt qui appelle ses propres ./modules/* a besoin de l’arborescence entière. Ni un .terraformignore présent dans le dépôt ni un .aggregaignore à côté de la Recipe ne changent ce qu’une source récupérée copie localement — tous deux façonnent un module conservé à côté de la Recipe, et aucun des deux n’est lu pour un module récupéré depuis un dépôt.

Lire ce que le module publie. Une valeur que le module publie est l’un de ses blocs output, et un consommateur la lit sous la forme ${module.<name>.<output>}, où <name> est le bloc module du producteur — c’est pourquoi le producteur ci-dessus publie ${module.{{ .context.instance_id }}.<output>}. Le moteur résout la référence par rapport aux blocs output propres au module lorsqu’il valide la configuration racine, de sorte qu’un nom de sortie que le module ne déclare pas y est refusé, en le nommant :

Error: Unsupported attribute
on aggrega.modules.tf line 9, in module "api":
9: db_host = "${module.db.db_instance_addresz}"
This object does not have an attribute named "db_instance_addresz".

Le build ne lit aucun des blocs variable ou output du module, n’écrit rien dans le module et ne lui ajoute aucune configuration de fournisseur, de sorte qu’un nom de sortie mal saisi est détecté par le moteur plutôt que par le build. Voir Consommer la valeur publiée d’un autre composant pour le côté du consommateur.

Émission à l’identique et copie locale (vendoring)

Le fournisseur terraform ne transpile pas, ne reformate pas et ne réécrit pas les corps Terraform. Un corps HCL ou .tf.json rédigé est émis exactement tel que son template s’évalue, un corps HCL commençant par les commentaires de provenance, et un module avec source est copié localement fichier par fichier. C’est ce qui garde la sortie terraform déterministe et reproductible : à entrées identiques, la configuration rendue est identique octet pour octet d’une exécution à l’autre, et un module copié localement fait l’aller-retour sans changement. Comme le fournisseur ne résout jamais l’état d’exécution, tout ce qui dépend de l’exécution reste une chaîne d’interpolation que Terraform lie au moment de l’apply.

Annotations de plateforme

Le fournisseur terraform ne lit aucune des annotations aggrega.ai/. Un module copié localement, les fichiers d’artefact d’une Recipe et la configuration racine que le fournisseur écrit n’ont aucun emplacement pour un espace de noms, un préfixe de registre, un secret de pull ou un compte de service, de sorte qu’une valeur définie pour l’un d’eux ne change rien dans la configuration rendue ; un module qui a besoin d’une telle valeur la reçoit comme l’une de ses propres entrées, via les values du composant.

Le fournisseur l’indique dans son entité Plugin, avec readsNoWellKnownAnnotations: true (voir l’entité Plugin), et le build émet donc un avertissement pour chaque annotation aggrega.ai/ qui atteint un rendu par son intermédiaire — une fois par clé et par rendu, en nommant les types d’entrée que ce rendu déclare :

warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored it

La valeur traverse néanmoins le build sans modification, et le build ne s’arrête pas : une annotation de frontière se propage en cascade sur chaque composant placé sous elle, et une frontière dont les composants sont rendus via des cibles différentes est un cas ordinaire et non une erreur. L’avertissement appartient à la classe unsupported-field et se désactive avec l’option de cette classe.

Entrées de module déclarées sensibles

Terraform est la seule cible de la bibliothèque standard dotée d’une primitive native de sensibilité par valeur, de sorte qu’une donnée qu’un auteur a déclarée sensible peut être rendue dans les termes propres de Terraform plutôt que seulement consignée dans ceux d’Aggrega.

Lorsque l’entrée d’un module copié localement porte un contenu qu’un auteur a déclaré sensible, le fournisseur ajoute un fichier supplémentaire à côté du module, aggrega_override.tf.json, qui déclare sensitive = true pour cette entrée :

{
"variable": {
"db_password": {
"sensitive": true
}
}
}

Terraform fusionne un fichier de configuration dont le nom est simplement override ou se termine par _override dans la configuration du même répertoire, de sorte que le bloc variable propre au module acquiert l’attribut tandis que chaque octet copié localement reste exactement tel qu’il a été rédigé. Le type déclaré, la valeur par défaut et la description de l’entrée restent intacts — la surcharge porte l’attribut de sensibilité et rien d’autre. Un nœud non marqué ne reçoit aucun fichier de ce type.

Cette limite est délibérée et n’est pas imposée par le format de fichier : rien dans une surcharge ne refuse un second attribut, et le default d’un bloc variable est l’emplacement le plus proche auquel on penserait pour faire entrer une valeur dans un module copié localement sans en modifier les octets — mais elle n’arriverait pas. Un default dans la syntaxe de configuration JSON dans laquelle ce fichier est écrit n’est pas une position que Terraform évalue, de sorte qu’une valeur portant un pointeur ${ ... } écrit à cet endroit atteint le module sous la forme des caractères littéraux du pointeur, lors d’un plan qui réussit et ne dit rien. Le même pointeur écrit dans un default en HCL natif est rejeté d’emblée, ce qui situe ce silence dans cette syntaxe et non dans les fichiers de surcharge en tant que tels. La surcharge porte donc sensitive seul : sa signification ne dépend pas d’une évaluation.

L’entrée marquée découle d’une déclaration, jamais d’un nom. Le fournisseur lit le marquage calculé par la compilation et n’inspecte rien lui-même : il ne reconnaît ni password, ni secret, ni token, et il ne lit pas le texte du module pour deviner. Une entrée de module nommée db_password dont la valeur ne porte aucune déclaration est émise sans marquage, et une entrée déclarée nommée region est marquée.

Le marquage ne voyage que là où l’identité de l’entrée peut être retrouvée à partir de la déclaration. Une Recipe qui copie localement un module avec source: et laisse les feuilles values déclarées du nœud devenir directement les entrées du module donne à chaque entrée le même nom que celui que l’auteur a déclaré, de sorte que le lien est exact — et il en va de même pour la FeatureRecipe d’une Feature rattachée à un composant qui copie localement un module de la même façon, sur les feuilles que déclare sa Feature. Une Recipe ou une telle FeatureRecipe qui remodèle ces valeurs via un template valuesMapping: invente ses noms de sortie, et aucune déclaration ne les nomme — le marquage est donc absent plutôt qu’approximé, et le build le signale par un avis consultatif par feuille déclarée, en nommant la feuille et l’entité dont c’est le mappage (une Feature rattachée à une frontière est rendue sans aucun values, elle n’a donc rien à marquer et n’en suscite aucun) ; voir A declared-sensitive value reaches the target through a values mapping (Une valeur déclarée sensible atteint la cible par un mappage values). L’absence est délibérée : deviner quelle entrée remodelée portait la donnée déclarée marquerait comme secrète une entrée publique, et Terraform masquerait alors dans la sortie du plan une valeur qui n’a jamais été sensible.

L’exemple détaillé terraform-declared-sensitivity construit cela de bout en bout et est assez petit pour être lu en entier : un composant déclarant trois feuilles values, dont deux portent des identifiants publics et une porte le secret d’authentification. Son rendu montre les arguments du bloc module portant les trois entrées du module et la surcharge ne nommant que l’entrée déclarée, de sorte que les deux moitiés de la règle sont visibles dans le même build — y compris le fait qu’un identifiant d’authentification placé à côté du secret reste non marqué. Supprimer l’unique déclaration et reconstruire n’émet plus aucun fichier de surcharge.

Ce que le sensitive de Terraform garantit et ne garantit pas

Aggrega promet exactement ce que fournit l’attribut propre à Terraform, et rien de plus.

Il limite l’affichage. Une valeur sensible apparaît comme (sensitive value) dans la sortie du plan et comme <sensitive> dans la sortie de l’apply. Le marquage se propage à travers les expressions, de sorte qu’une valeur dérivée d’une entrée sensible est elle aussi sensible, et Terraform refuse d’en exporter une depuis un output racine qui n’est pas lui-même marqué comme sensible — une erreur explicite plutôt qu’une divulgation silencieuse.

Il ne change pas le stockage, et ce n’est pas du chiffrement. Terraform enregistre une valeur sensible en clair dans l’état. Lire sensitive = true comme la promesse que l’état peut être commité ou partagé sans risque est le seul contresens à éviter : protéger l’état reste une question de configuration du backend d’état, exactement comme pour un module ne portant aucun marquage. L’attribut ne restreint pas non plus qui peut lire la valeur, n’affecte pas ce qu’un fournisseur transmet et ne modifie la configuration rendue d’aucune autre manière.

Le marquage rend donc plus difficile la divulgation accidentelle d’une entrée déclarée sensible lorsque quelqu’un lit un plan. Il ne rend pas sûre la publication de ce qui est déployé. Voir Déclarer une feuille sensible pour le mot-clé et pour ce qu’une déclaration apporte sur chaque cible.

Validation structurelle des entrées

Le fournisseur terraform valide la structure d’un module avec source avant d’en effectuer le rendu. Il analyse les fichiers HCL et .tf.json du module et signale les erreurs d’analyse, en arrêtant le build avec un message clair qui nomme le nœud en cause et le fournisseur. L’analyse vérifie la forme, pas la sémantique — elle ne résout pas les fournisseurs, n’évalue pas d’expressions et ne contacte aucun registre. La validation est hermétique : elle utilise un analyseur HCL autonome compilé dans le fournisseur, sans binaire terraform ni accès réseau. Un module malformé est intercepté à la frontière de la rédaction plutôt que d’apparaître comme une erreur déroutante lors d’une exécution ultérieure de terraform.

Un appel de module que le moteur récupère lors de son initialisation

La même lecture signale, sous forme d’avertissement qui ne refuse rien, chaque bloc module dont Terraform télécharge la source lors de l’initialisation de la configuration. Le commit et le digest d’archive d’un module copié localement sont fixés dans le fichier de verrouillage, mais un bloc module qu’il contient et dont le source est une adresse de registre, une URL git, Mercurial ou d’archive HTTP, un bucket S3 ou GCS, ou un chemin absolu, désigne un module que le moteur récupère à l’initialisation, dans la version qu’il sélectionne alors — et le fichier de verrouillage des dépendances propre à Terraform n’enregistre que les fournisseurs, si bien que rien n’épingle ce module. Un source local qui sort du module copié localement est également signalé, car il désigne des fichiers que le build n’a pas copiés localement. Chaque constat nomme le nœud et le fournisseur, puis le bloc, le fichier et la ligne où il se trouve, et la source telle qu’écrite :

warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that module

Ce qui est lu. Les fichiers que le moteur charge lorsque le module est appelé : les fichiers de configuration situés directement dans le répertoire propre du module, puis ceux de chaque répertoire qu’un source local — commençant par ./ ou ../, ou leurs graphies avec barre oblique inverse — atteint à partir de là, suivis de répertoire en répertoire et lus chacun une seule fois. Un répertoire que rien n’appelle n’est pas lu, de sorte que les appels que font les répertoires examples/ ou tests/ d’un module ne sont pas signalés : le moteur ne les charge jamais lorsque le module est appelé, et rien de ce qu’ils appellent n’est récupéré. La vérification d’analyse ci-dessus analyse tout de même chaque fichier de configuration copié localement. Le corps rédigé d’une Recipe est lu de la même façon lors de son rendu, en partant du répertoire dans lequel le corps est écrit, de sorte qu’un bloc module qu’un corps rédigé écrit avec une source de registre est lui aussi signalé. Un fichier sous spec.boundary.artifacts est évalué et écrit par le compilateur lui-même et n’est remis à aucun fournisseur, de sorte qu’un bloc module écrit dans l’un d’eux n’est pas lu et ne suscite aucun avertissement.

Ce qui n’est pas lu. Seul ce que dit un source est lu. Le build ne lit pas le module qu’un appel désigne, ne juge pas ce que fait ce module et ne décide pas si l’appel est acceptable. Un source que le moteur évalue au lieu de le lire tel qu’écrit — l’un portant une interpolation, ou une référence — est jugé d’après son texte initial : celui qui commence par une adresse est signalé tel qu’écrit, tandis que celui qui commence par un préfixe local, ou par l’interpolation elle-même, n’est ni signalé ni suivi, car l’endroit où il mène ne figure pas dans le texte. Un source à l’intérieur de required_providers désigne un fournisseur plutôt qu’un module et n’est pas un appel de module.

Pourquoi c’est signalé plutôt que refusé. Un module qui appelle un autre module est une entrée légitime : Terraform récupère le module appelé et la configuration fonctionne. Ce à quoi l’auteur renonce, c’est l’épinglage du module appelé par le build, ce qui est un fait bon à savoir plutôt qu’un défaut à corriger, et l’acceptabilité de cette récupération relève du jugement de l’auteur. Une configuration qui doit rester entièrement épinglée ne copie localement que des modules qui ne font aucun appel de ce type. L’avertissement, son code de classe et les autres endroits qu’il atteint sont décrits dans Avertissements et sortie du linter.

Frontière des patchs de FeatureRecipe

Une étape pipeline post-rendu d’une FeatureRecipe ne patche que la sortie que le fournisseur rend sous forme d’arbre structuré. Pour terraform, cela signifie :

  • Le Terraform rédigé en JSON est patchable. Un module .tf.json est un document structuré, donc le JSONPatch d’une étape du pipeline modifie sur place les valeurs adressées et laisse intact tout autre octet — ordre, mise en forme, clés environnantes.
  • Le HCL natif est opaque. Un corps en HCL natif (main.tf) n’est pas une cible de patch structurée. Un patch visant un corps opaque arrête le build avec un diagnostic au lieu de modifier du texte qu’il ne peut pas adresser structurellement ; rédiger une étape du pipeline visant un corps HCL est une erreur de conception signalée par un arrêt explicite, et non une absence d’effet silencieuse.
  • Les entrées d’un module avec source ne sont pas du tout une cible de patch. Ce sont les arguments du bloc module du composant, qui se trouve dans la configuration racine : du HCL natif, donc opaque, et un artefact de la frontière entière plutôt que d’un nœud particulier. Une étape pipeline patche la sortie rendue propre d’un nœud, il n’existe donc aucune position depuis laquelle les adresser.

Un auteur qui a besoin qu’un corps Terraform puisse être patché par le pipeline le rédige donc en .tf.json. Voir FeatureRecipe pour la frontière générale des cibles de patch entre les fournisseurs.

Ordre de déploiement

La valeur syncWave: de la frontière d’une Release ordonne les blocs module de la configuration racine dans laquelle cette frontière est assemblée. Chaque composant de la frontière hérite de la vague de la frontière, et lorsque plusieurs frontières se résolvent dans le même répertoire de sortie — de sorte que leurs composants sont composés dans une seule configuration racine — cette racine contient plus d’une vague et le fournisseur exprime l’ordre entre elles sous forme de depends_on sur les blocs module.

Chaque module nomme chaque module de la vague immédiatement précédente qui a des composants, et aucune vague antérieure à celle-ci. Terraform enchaîne le reste : un module de la vague 2 dépend de la vague 1, qui dépend de la vague 0, de sorte que toute la séquence est ordonnée tandis que la liste propre de chaque module reste de la taille d’une vague plutôt que de la frontière entière. Les vagues n’ont pas besoin d’être contiguës, et les valeurs négatives sont ordinaires — -1 est un choix courant pour un bucket ou un rôle que le reste de la configuration lit. La vague la plus basse ne nomme rien, car rien ne la précède.

Ce qu’est l’ordre : l’ordre dans lequel Terraform effectue ses actions. Terraform construit un graphe de dépendances et le parcourt en parallèle dans la mesure où le graphe le permet. depends_on ajoute une arête à ce graphe, de sorte que Terraform termine ses actions sur les modules nommés avant de commencer celles sur le module qui déclare la dépendance. Une vague échelonne donc l’exécution : on agit sur les composants de la vague antérieure avant de commencer ceux de la vague ultérieure.

Ce n’est pas un ordre de disponibilité. Une configuration Terraform n’exprime aucune notion de ressource opérationnelle, donc rien ici n’attend qu’une ressource devienne prête — seulement que Terraform ait fini d’agir sur elle. C’est une vraie différence par rapport à la même vague sur compose, où un service qui déclare un healthcheck est attendu jusqu’à ce qu’il se signale en bonne santé : compose dispose d’une primitive de disponibilité sur laquelle s’appuyer, et une configuration Terraform n’en a aucune. L’ordre des actions est ce que cette cible offre, et l’énoncer clairement est plus utile qu’une mise en garde attachée à une promesse qu’elle ne peut pas tenir.

Aucun ordre de démantèlement n’est promis. Ce que depends_on énonce, c’est que Terraform termine les actions de la dépendance avant de commencer celles du dépendant ; l’ordre dans lequel un destroy les supprime ne fait pas partie de cet énoncé, donc rien n’est affirmé ici sur la séquence de démantèlement. C’est une promesse plus étroite que celle que porte la même vague sur cloudformation, dont l’attribut régit les deux sens — bon à savoir si vous comptez sur une vague pour ordonner un démantèlement, car sur cette cible elle ne le fait pas.

Une frontière dont tous les composants portent une même vague n’en tire rien. Il en va de même pour une Release qui ne déclare aucun syncWave : chaque contributeur porte la valeur par défaut du champ, 0, la configuration racine contient une seule vague, et les octets émis sont exactement ceux qu’ils seraient si le fournisseur n’exprimait aucun ordre par vagues.

L’ordre entre deux configurations racines n’est pas exprimable, et il n’est pas approximé. Un graphe de dépendances Terraform est propre à chaque configuration et depends_on nomme un module à l’intérieur de la configuration qui le déclare, donc une vague ordonne chaque composant composé dans cette racine et rien au-delà. Ordonner deux configurations relève de l’opérateur, de la même façon qu’une référence à un état distant est une résolution au moment du déploiement et non au moment du build.

La vague est enregistrée autant qu’appliquée : elle voyage avec le reste de la provenance du build du nœud, sous la forme aggrega.ai/sync-wave dans le bloc de commentaires tamponné, ou dans le fichier de provenance compagnon lorsque le corps est du JSON ou un module copié localement. Ainsi, une configuration rendue enregistre quelle vague sa frontière a déclarée, en plus d’être ordonnée par elle.

L’ordre que les vagues n’expriment pas reste l’affaire de Terraform lui-même, et les références entre ressources en portent déjà une grande partie : une référence à un attribut d’une autre ressource indique à Terraform d’agir d’abord sur cette ressource. Un module qui a besoin d’une contrainte que ni les références ni les vagues n’impliquent écrit son propre depends_on à l’intérieur du module, que le fournisseur émet tel quel comme toute autre partie du corps.