Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Terraform Provider

Provider terraform renderuje Aggrega Recipes do konfiguracji Terraform. Emituje konfigurację i nigdy nie uruchamia Terraform: budowanie Aggrega to kompilacja z wyprzedzeniem (ahead-of-time), więc nie może rozwiązać identyfikatorów zasobów, adresów IP ani wyjść, które istnieją dopiero po terraform apply. Interpolacje Terraform ${ ... } przechodzą nietknięte jako deterministyczne ciągi wskaźnikowe, które środowisko uruchomieniowe Terraform rozwiązuje później. Provider działa offline i hermetycznie — nigdy nie korzysta z sieci i nigdy nie wywołuje terraform ani tofu.

Jak zorganizowana jest granica

Provider terraform składa granicę, zamiast emitować jej komponenty obok siebie. Każda renderowana przez niego granica otrzymuje jedną konfigurację główną, aggrega.modules.tf, która deklaruje każdy renderowany w niej komponent jako blok module, którego source jest własnym podkatalogiem tego komponentu w modules/:

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

Własne pliki każdego komponentu — dołączony moduł lub napisana treść oraz znacznik pochodzenia — znajdują się w podkatalogu, na który wskazuje jego blok. Jest to standardowa struktura Terraform, w której katalog główny składa moduły podrzędne, a jej konwencja zakłada, że moduły zagnieżdżone znajdują się w podkatalogu modules/; taki układ otrzymuje każda granica terraform, niezależnie od tego, czy zawiera jeden komponent, czy kilka. Encja Feature dołączona do komponentu lub do granicy jest deklarowana jako osobny blok module w tej samej konfiguracji głównej — zob. Gdzie trafia wynik dołączonej encji Feature.

Ten kształt ma znaczenie konstrukcyjne, a nie kosmetyczne, z dwóch powodów.

Graf zależności Terraform jest osobny dla każdej konfiguracji. Components emitowane do osobnych katalogów to osobne grafy bez żadnego związku: ani referencja, ani depends_on nie może sięgnąć z jednego do drugiego i żaden pojedynczy terraform plan nie widzi obu. Jeden katalog główny, który składa każdy komponent jako moduł potomny, umieszcza całą granicę w jednym grafie i jednym planie.

Pliki komponentu są adresowane przez jego własny katalog. Dwa komponenty w jednej granicy mogą dołączać moduły zapisujące pliki o identycznych nazwach — main.tf, variables.tf — a każdy zestaw znajduje się w katalogu swojego komponentu, zamiast rywalizować o jedną ścieżkę.

Gdzie konfigurowany jest provider

Konfiguracja providera — blok provider — jest zapisywana w katalogu głównym, nigdy w module komponentu. Dokumentacja Terraform stwierdza, że moduł przeznaczony do wywołania przez inny moduł nie może zawierać bloków provider, a wywoływany moduł dziedziczy domyślną konfigurację katalogu głównego dla każdego używanego providera. Modułu zawierającego własny blok provider nie można wywołać z depends_on, count ani for_each, a ten provider zapisuje depends_on w bloku module komponentu zawsze, gdy inny komponent tego samego katalogu głównego ma wcześniejszy syncWave, jak opisano poniżej w części o kolejności wdrażania; Terraform odrzuca wtedy całą konfigurację już podczas jej ładowania, zanim cokolwiek zaplanuje.

Dlatego encja Recipe, której provider wymaga konfiguracji, zapisuje tę konfigurację jako plik w spec.boundary.artifacts. Każdy taki plik jest zapisywany raz obok aggrega.modules.tf, gdzie Terraform odczytuje go razem z konfiguracją główną, a moduł komponentu zachowuje jedynie deklarację required_providers ze źródłem i wersją providera:

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

Components jednego katalogu głównego, które deklarują ten sam plik o tych samych bajtach, współdzielą jedną kopię; ta sama nazwa z innymi bajtami zatrzymuje kompilację. Zasoby modułów są rejestrowane względem tej jednej konfiguracji, więc to także za jej pomocą Terraform je niszczy. Release, który usuwa ostatni komponent deklarujący ten plik, usuwa wraz z nim plik, a Terraform odmawia wtedy zaplanowania zniszczenia tego, co utworzyły te moduły, żądając bloku provider konfigurującego dostawcę. Należy zniszczyć te zasoby przed usunięciem ostatniego takiego komponentu.

Gdzie dostarczane są wejścia komponentu

Wejścia komponentu to argumenty jego bloku module w konfiguracji głównej i jest to jedyne miejsce, w którym są zapisywane. Blok zawiera argumenty tam, gdzie kompilator dostarcza wejścia modułu — w przypadku encji Recipe dołączającej moduł za pomocą source:. Jest pusty tam, gdzie encja Recipe sama napisała treść konfiguracji i rozwiązała w niej swoje wartości, więc kompilator nie ma już czego przekazać.

Argument modułu to pozycja, którą Terraform ewaluuje, i dlatego właśnie tam trafiają wartości. Wskaźnik ${ ... } dostarczony przez encję Recipe jest tam rozwiązywany, zamiast trafiać do modułu jako dosłowny ciąg znaków. To, względem czego jest rozwiązywany, to konfiguracja główna: referencja wskazuje coś, co ta konfiguracja deklaruje — jeden z jej bloków module, jako module.<name>.<output> — a referencja do czegokolwiek, czego nie deklaruje, kończy się głośnym błędem w czasie planowania, wskazującym brakujący obiekt.

Własny katalog komponentu nie jest więc konfiguracją, którą można zaplanować tak, jak jest wdrażana. Jego wejścia są określone poziom wyżej, w katalogu głównym, więc uruchomienie silnika w modules/<component> planuje coś innego, a która z dwóch rzeczy nastąpi, zależy od własnych bloków variable modułu:

  • Jeśli co najmniej jedno wejście nie deklaruje default, plan kończy się głośnym błędem — No value for required variable (Brak wartości dla wymaganej zmiennej), wskazując każdą nieustawioną zmienną i jej wiersz oraz proponując własne rozwiązanie Terraform: -var / -var-file.
  • Jeśli każde wejście ma default, plan kończy się powodzeniem i buduje z wartości domyślnych modułu, a nie z wartości dostarczanych przez konfigurację główną. Nic nie ostrzega, więc o tym przypadku trzeba wiedzieć: plan, który wygląda poprawnie, opisuje konfigurację, o którą nikt nie prosił.

Zamiast tego należy planować własny katalog wyjściowy granicy — ten zawierający aggrega.modules.tf, bezpośrednio nad modules/. Tam znajdują się wartości wdrożenia i jest to jedyne miejsce, w którym pojedynczy plan widzi całą granicę.

Korzystanie z wartości opublikowanej przez inny komponent

Komponent połączony z innym krawędzią uses odczytuje opublikowane wartości tamtego komponentu przez własny potok .context.inject (lub przez .context.uses.<alias>.provides.<name>). Odczytuje ciąg znaków, który kompilator przekazuje bez interpretacji, a miejsce, w które ten ciąg trafia, to tekst ewaluowany przez Terraform w zakresie, w którym zapisała go encja Recipe. Granica terraform ma dwa takie zakresy i tylko jeden z nich deklaruje wywołania modułów, których potrzebuje referencja między komponentami:

  • konfiguracja główna deklaruje każdego współtwórcę jako blok module, więc module.<name>.<output> jest tam rozwiązywane;
  • własny katalog komponentu nie deklaruje żadnych wywołań modułów, więc module.<name>.<output> nic tam nie wskazuje — niezależnie od tego, czym jest <name>. Podstawienie poprawnej nazwy niczego nie zmienia, ponieważ brakuje deklaracji, a nie pisowni.

To więc rodzaj wejścia konsumującej encji Recipe decyduje, czy konsumowana referencja może zostać rozwiązana, a nie konsumowana wartość.

Konsumującą encję Recipe należy pisać jako Recipe z source:. Jej valuesMapping: staje się argumentami jej własnego bloku module w konfiguracji głównej — jedynej pozycji, która jest zarówno ewaluowana, jak i znajduje się w zakresie, w którym zadeklarowani są jej sąsiedzi.

Przykładowa para

Producent publikuje adres wskazujący jego własne wywołanie modułu, czyli formę, którą deklaruje zakres konsumenta. .context.instance_id jest dostępne w powierzchni ewaluacji provides, a dla komponentu deklarowanego przez encję Aggregate wdrożenia jest to nazwa, którą nosi blok module tego komponentu:

# 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}"

Konsument dołącza moduł deklarujący wejście i mapuje na nie wstrzykniętą wartość:

# 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 }}"

Encja Aggregate łączy je, wskazując opublikowany klucz, który przenosi krawędź:

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

Kompilacja emituje jedną konfigurację główną, w której referencja i obiekt, na który wskazuje, są zadeklarowane razem:

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

Terraform rozwiązuje module.store.endpoint, ponieważ ta sama konfiguracja deklaruje module "store", a wartość trafia do modułu konsumenta jako zwykłe wejście.

Przykład aws-rds-and-ecs-service buduje tę parę z encji Recipes biblioteki standardowej: bazy danych PostgreSQL udostępnianej przez opublikowany moduł RDS oraz serwera uruchamianego w Amazon ECS, którego argument environment zawiera ${module.db.db_instance_address} w konfiguracji głównej deklarującej module "db".

Trzy sposoby, w jakie to zawodzi, i jak każdy z nich wygląda

Encja Recipe, która sama tworzy swoją treść, nie może konsumować odwołania między komponentami. Encja Recipe typu artifacts: rozwiązuje swoje wartości w treści, którą zapisuje, a ta treść trafia do własnego katalogu komponentu. Odwołanie znajduje się wtedy w zakresie, który nie deklaruje żadnych wywołań modułów:

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.

Żadna pisownia tego nie naprawi, ponieważ wyrażenia modułu zagnieżdżonego w ogóle nie mogą wskazywać modułu równorzędnego — moduł zagnieżdżony otrzymuje wartość sąsiada wyłącznie jako wejście, czyli argument bloku module, który ścieżka ze źródłem już dostarcza. Komponent, który konsumuje wartość opublikowaną przez inny komponent, tworzy się jako encję Recipe typu source:.

Adres wskazujący coś wewnątrz własnego modułu producenta jest rozwiązywany względem korzenia, a nie względem tego modułu. Wpis provides zapisany jako aws_db_instance.this.endpoint wskazuje zasób deklarowany przez moduł producenta; zapisany jako interpolacja jest obliczany tam, gdzie znajduje się argument konsumenta, czyli w korzeniu:

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.

Należy publikować ${module.<...>.<output>} i dodać do modułu blok output dla tej wartości, zamiast sięgać do jego zasobów.

Wpis provides bez interpolacji jest dostarczany jako tekst. To jedyny przypadek, który nie kończy się błędem: kompilator przekazuje ciągi znaków i nie odróżnia wskaźnika od literału, więc aws_db_instance.this.endpoint zapisane bez ${ ... } jest renderowane jako ciąg w cudzysłowie, kompilacja się udaje, silnik przechodzi walidację, a konsument otrzymuje znaki aws_db_instance.this.endpoint. Opakowanie ${ ... } należy zapisywać zawsze, gdy wartość ma być odwołaniem — to ono oznacza ciąg jako coś, co Terraform ma obliczyć.

Jedno ograniczenie, które warto znać, zanim się na tym polega

.context.instance_id zapisuje tożsamość komponentu, a nazwa bloku module jest wyprowadzana z katalogu, w którym znajdują się pliki komponentu. Dla komponentu deklarowanego przez własną encję Aggregate wdrożenia jest to ta sama nazwa. Dla komponentu dołączonego z innej encji Aggregate tak nie jest: złożona tożsamość i nazwa modułu są zapisywane w swoich dwóch alfabetach inaczej, a odwołanie zawodzi wtedy głośno w korzeniu, a nie po cichu:

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.

Producenta, którego adres rozwiązuje inny komponent, należy deklarować we własnej encji Aggregate wdrożenia, obok komponentu, który go konsumuje.

Gdzie trafia wynik dołączonej encji Feature

Dołączenie encji Feature, które renderuje własną konfigurację, otrzymuje własny moduł, zadeklarowany w tej samej konfiguracji głównej co komponenty obok niego. To właśnie sprawia, że jego konfiguracja w ogóle staje się częścią wdrożenia: Terraform wczytuje tylko pliki znajdujące się bezpośrednio w katalogu i traktuje katalog zagnieżdżony jako całkowicie odrębny moduł, który trzeba jawnie wywołać, więc pliki dołączenia są odczytywane dlatego, że korzeń deklaruje blok wskazujący katalog, w którym się znajdują.

Katalog modułu dołączenia znajduje się obok katalogu komponentu, jeden poziom pod modules/, a jego nazwa pochodzi od dwóch rzeczy, które je identyfikują — komponentu, który je hostuje, i nazwy, pod jaką zostało dołączone, połączonych przez --. Zatem dla komponentu api z dołączeniem o nazwie aux konfiguracja główna deklaruje dwa moduły:

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

Encja Feature dołączona na poziomie granicy, a nie komponentu, nie ma komponentu hostującego, który można by nazwać, więc jej katalog nosi wyłącznie jej własną nazwę: dołączenie o nazwie aux na granicy zawierającej komponent api daje ./modules/aux obok ./modules/api.

Dlaczego obok, a nie wewnątrz. Terraform scala wszystkie pliki najwyższego poziomu w katalogu modułu w jedną przestrzeń nazw — output, variable, resource i locals jednakowo — więc dwóch współtwórców dzielących katalog koliduje na każdej nazwie, którą obaj deklarują, niezależnie od nazw ich plików. Osobny katalog dla każdego utrzymuje ich rozdzielnie. Układ obok, a nie wewnątrz, jest też tym, czego wymagają wytyczne samego Terraform dla modułów zagnieżdżonych: aby dało się je składać przez wywołującego, zamiast wywoływać się nawzajem bezpośrednio i tworzyć głęboko zagnieżdżone drzewo modułów.

Połączenie jest escapowane dla każdej współrzędnej osobno. Każda z dwóch współrzędnych jest zapisywana w alfabecie katalogów przed połączeniem, więc współrzędnej, która sama zawiera --, nie da się pomylić z połączeniem: host o nazwie a--b z dołączeniem c jest odróżnialny od hosta a z dołączeniem b--c. Litery ASCII obu wielkości, cyfry, kropka i podkreślenie przechodzą bez zmian; zapisany myślnik jest zachowywany wszędzie tam, gdzie następny znak należy do tej grupy; wszystko inne jest escapowane. Ta sama reguła i ten sam alfabet wytwarzają katalogi podrzędne celu chart, więc katalog danego dołączenia jest zapisywany tak samo niezależnie od tego, który z dwóch celów go renderuje.

Nazwa bloku jest wyprowadzana z katalogu, na który wskazuje jego source, przy czym każdy znak spoza gramatyki Terraform dla nazwy modułu jest zastępowany podkreśleniem. To odwzorowanie nie jest różnowartościowe, więc gdy dwóch współtwórców otrzymałoby tę samą nazwę modułu, kompilacja zatrzymuje się i wskazuje obu, zamiast emitować konfigurację, którą Terraform by odrzucił.

Z tego, że dołączenie jest osobnym modułem, wynikają trzy rzeczy.

Jego wejścia pochodzą z jego własnego odwzorowania. Dołączenie, którego encja FeatureRecipe pobiera moduł ze źródła i deklaruje valuesMapping, ma wartości wytworzone przez to odwzorowanie zapisane jako argumenty własnego bloku module, tak jak moduł ze źródłem komponentu otrzymuje swoje wartości. Encja FeatureRecipe niedeklarująca valuesMapping nie przekazuje modułowi żadnych argumentów: zmienna zadeklarowana przez moduł z default przyjmuje tę wartość, a zadeklarowana bez wartości domyślnej pozostaje nieustawiona, więc Terraform odrzuca plan.

Jego zasoby należą do jedynego grafu zależności granicy. Odwołanie lub depends_on sięga między dołączeniem a komponentem, do którego zostało dołączone, a jedno terraform plan widzi oba — to ta sama właściwość, którą układ, w którym korzeń składa moduły podrzędne, daje komponentom, z tego samego powodu.

Jego nazwy najwyższego poziomu należą do niego. Ponieważ opisane wyżej scalanie przestrzeni nazw odbywa się w obrębie katalogu, współtwórca w osobnym katalogu deklaruje swoje nazwy output, variable, resource i locals bez konfliktu z nazwami sąsiadów — więc dołączenie może ponownie użyć nazwy, którą jego host już deklaruje, i żaden z nich nie musi wiedzieć, jak drugi cokolwiek nazwał.

Warto zauważyć, czego ten cel nie wymaga, ponieważ ograniczenie celu chart jest inne, a wspólny układ można odczytać jako sugerujący więcej, niż faktycznie oznacza: moduł zagnieżdżony w katalogu innego współtwórcy jest tu nadal osiągalny, ponieważ konfiguracja główna odczytuje source każdego współtwórcy z pozycji złożonej przez kompilację, zamiast odtwarzać ją z identyfikatora. Ten cel odrzuca natomiast sytuację, w której dwóch współtwórców dzieli katalog. Cel chart odrzuca pozycję zagnieżdżoną całkowicie, ponieważ wykrywa chart podrzędny jeden poziom niżej i nie dalej.

Obsługiwane rodzaje wejścia

Provider terraform akceptuje dwa z trzech rodzajów wejścia encji Recipe:

  • Tryb artifacts. Encja Recipe definiuje konfigurację Terraform jako szablonową treść; provider wylicza szablon Aggrega i emituje wynik bez przepisywania go. HCL (main.tf) jest wygodnym domyślnym wyborem, a Terraform JSON (.tf.json) jest akceptowany równorzędnie. Pochodzenie kompilacji jest zapisywane jako blok komentarzy Terraform na początku treści HCL; dla treści JSON — która nie ma składni komentarzy — pochodzenie jest zapisywane w pliku towarzyszącym aggrega.provenance.tf zamiast w treści.
  • Tryb sourced. Encja Recipe odwołuje się do modułu Terraform za pomocą source:. Pliki modułu są dosłownie dołączane (vendoring) do katalogu danego komponentu, a valuesMapping: encji Recipe staje się argumentami bloku module tego komponentu w konfiguracji głównej granicy. Treść modułu jest zachowywana dokładnie w postaci, w jakiej ją napisano, i nic nie jest do niej zapisywane; wartości są podawane raz, w konfiguracji głównej, gdzie Terraform je wylicza. Gdy zadeklarowane liście values węzła stają się bezpośrednio wejściami modułu — encja Recipe z source: bez valuesMapping: — wejście niosące materiał zadeklarowany przez autora jako wrażliwy otrzymuje także wygenerowany plik nadpisujący z własnym atrybutem wrażliwości Terraform; szablon valuesMapping: sam wymyśla nazwy swoich wyjść, więc w tym przypadku oznaczenia nie ma, a kompilacja zgłasza to ostrzeżeniem. Oba przypadki opisano w sekcji Wejścia modułu zadeklarowane jako wrażliwe.

null w valuesMapping: jest argumentem null. Klucz, któremu mapowanie przypisuje null, jest zapisywany w bloku modułu jako <name> = null, a silnik nadaje zmiennej modułu wartość null, nadpisując jej default, chyba że zmienna deklaruje nullable = false — wtedy obowiązuje jej default; aby wejście otrzymało wartość domyślną modułu, należy pominąć klucz w mapowaniu.

Rodzaj wejścia synthesized nie jest oferowany. Nie istnieje wierne, agnostyczne wobec możliwości mapowanie rodzaju Workload platformy na dowolne zasoby Terraform, dlatego encja Recipe deklarująca workload: dla providera terraform powoduje głośny błąd zamiast wymyślonego tłumaczenia.

Encja Recipe deklarująca omits: jest odrzucana. Klucz omits: pomija w kompilacji dokumenty renderowane przez źródło, a ten provider w czasie kompilacji nie renderuje niczego z modułu sourced: dołącza dosłownie pliki modułu, a Terraform wylicza je podczas planowania i stosowania konfiguracji. Skoro nic nie jest renderowane, nie ma czego pomijać, więc ten provider nie deklaruje obsługi tego klucza, a encja Recipe lub FeatureRecipe, która go deklaruje, jest odrzucana, zanim cokolwiek zostanie dołączone — zob. The provider does not support omits (Provider nie obsługuje omits). W przypadku modułu przechowywanego obok encji Recipe można zamiast tego pominąć plik modułu wierszem w znajdującym się tam .aggregaignore, począwszy od następnego przypięcia encji Recipe.

Korzystanie z modułu publikowanego przez rejestr

Rejestr modułów publikuje każdą wersję modułu jako tag w repozytorium git tego modułu, a na żądanie pobrania wersji odpowiada źródłem git przypiętym do commita wskazywanego przez ten tag. Dlatego encja Recipe pobiera opublikowany moduł z tego repozytorium przy tym tagu, używając rodzaju źródła 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: to tag wydania dokładnie w postaci, w jakiej nazywa go repozytorium. valuesMapping: dostarcza wejścia modułu pod nazwami deklarowanymi przez jego bloki variable — Terraform wymaga wartości dla każdego wejścia, które nie deklaruje default — i stają się one argumentami bloku module tego komponentu w konfiguracji głównej, jak w przypadku każdego modułu sourced.

Co jest przypinane. aggrega pin oraz pull rozwiązują tag do wskazywanego przez niego commita i archiwizują repozytorium w tym commicie. Plik blokady encji Release zapisuje następnie ten commit jako przypiętą wersję źródła, tag jako napisaną referencję oraz skrót archiwum. Każda późniejsza kompilacja odczytuje archiwum z pamięci podręcznej i weryfikuje je względem tego skrótu przed dołączeniem czegokolwiek, więc nie potrzebuje sieci, a archiwum w pamięci podręcznej, którego bajty już się nie zgadzają, zatrzymuje kompilację. Tag to nazwa, którą repozytorium może przenieść na inny commit; późniejszy pull, który stwierdzi, że tag wskazuje gdzie indziej, zatrzymuje się zamiast przyjąć nowy commit, a aggrega pull --upgrade przyjmuje go świadomie. To ściślejsze przypięcie niż własny plik blokady zależności Terraform, który zapisuje wybrane przez konfigurację providery i żadnych modułów, więc moduł zapisany w konfiguracji jako źródło git przy tagu jest ustalony tylko na tyle, na ile ustalony jest tag. Tutaj commit modułu i skrót jego bajtów są ustalone w blokadzie, bajty są dołączane do wyniku, a konfiguracja główna wywołuje je ścieżką lokalną, więc silnik niczego nie pobiera, by wczytać sam moduł — moduł wywoływany przez dołączony moduł ze źródła rejestru lub zdalnego jest nadal pobierany, a kompilacja zgłasza każde takie wywołanie, jak opisano w sekcji Wywołanie modułu pobierane przez silnik podczas inicjalizacji.

Co jest dołączane. Całe repozytorium w przypiętym commicie, z wyjątkiem katalogu .git/, trafia bajt po bajcie do katalogu komponentu w modules/ — własne pliki konfiguracyjne modułu i moduły podrzędne, a także wszystko inne, co zawiera repozytorium: katalogi examples/ i wrappers/, dokumentacja, konfiguracja CI oraz wszelkie dane testowe, w tym binarne. Silnik odczytuje tylko to, co moduł wywołuje: gdy konfiguracja główna wywołuje katalog komponentu, silnik wczytuje pliki konfiguracyjne bezpośrednio w nim oraz w każdym katalogu osiągalnym stamtąd przez lokalne source. Katalog przykładów wywołujący inne moduły z rejestru jest więc dołączany, ale nigdy nie jest wczytywany, i nic z tego, co wywołuje, nie jest pobierane.

Zawężanie tego, co jest dołączane. Pobrane źródło to archiwum w postaci, w jakiej je pobrano, więc jedynym sposobem zawężenia jest module_subdir:, które czyni artefaktem jeden katalog repozytorium. Pomaga to tylko wtedy, gdy potrzebny moduł znajduje się w podkatalogu: moduł w katalogu głównym repozytorium, który wywołuje własne ./modules/*, potrzebuje całego drzewa. Ani .terraformignore zawarty w repozytorium, ani .aggregaignore obok encji Recipe nie zmienia tego, co dołącza pobrane źródło — oba kształtują moduł przechowywany obok encji Recipe i żaden nie jest odczytywany dla modułu pobranego z repozytorium.

Odczyt tego, co publikuje moduł. Wartość publikowana przez moduł to jeden z jego bloków output, a konsument odczytuje ją jako ${module.<name>.<output>}, gdzie <name> to blok modułu producenta — dlatego powyższy producent publikuje ${module.{{ .context.instance_id }}.<output>}. Silnik rozwiązuje referencję względem własnych bloków output modułu podczas walidacji konfiguracji głównej, więc nazwa wyjścia, której moduł nie deklaruje, jest tam odrzucana z jej podaniem:

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".

Kompilacja nie odczytuje żadnych bloków variable ani output modułu, niczego do modułu nie zapisuje i nie dodaje do niego konfiguracji providera, więc błędnie wpisaną nazwę wyjścia wychwytuje silnik, a nie kompilacja. Stronę konsumenta opisano w sekcji Korzystanie z wartości opublikowanej przez inny komponent.

Emisja dosłowna i vendoring

Provider terraform nie transpiluje, nie formatuje ponownie ani nie przepisuje treści Terraform. Napisana treść HCL lub .tf.json jest emitowana dokładnie tak, jak wylicza ją szablon, przy czym treść HCL zaczyna się od komentarzy o pochodzeniu, a moduł ze źródła jest włączany (vendoring) plik po pliku. To właśnie zapewnia deterministyczność i powtarzalność wyjścia terraform: przy tych samych danych wejściowych wyrenderowana konfiguracja jest identyczna bajt po bajcie między uruchomieniami, a włączony moduł przechodzi w obie strony bez zmian. Ponieważ provider nigdy nie rozwiązuje stanu środowiska uruchomieniowego, wszystko, co od niego zależy, pozostaje ciągiem interpolacji, który Terraform wiąże w czasie apply.

Adnotacje platformowe

Provider terraform nie odczytuje żadnej z adnotacji aggrega.ai/. Moduł vendorowany, pliki artefaktów encji Recipe i konfiguracja główna zapisywana przez providera nie mają miejsca na przestrzeń nazw, prefiks rejestru, sekret pobierania obrazów ani konto usługi, więc wartość ustawiona dla któregokolwiek z nich niczego nie zmienia w renderowanej konfiguracji; moduł, który potrzebuje takiej wartości, przyjmuje ją jako jedno ze swoich własnych wejść, poprzez values komponentu.

Provider deklaruje to w swojej encji Plugin za pomocą readsNoWellKnownAnnotations: true (zob. encja Plugin), dlatego budowanie ostrzega o każdej adnotacji aggrega.ai/, która dociera przez niego do renderowania — raz na klucz i na renderowanie, wymieniając rodzaje wejścia, które to renderowanie deklaruje:

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

Wartość nadal przechodzi przez budowanie nietknięta, a budowanie nie zostaje przerwane: adnotacja granicy przechodzi kaskadowo na każdy komponent pod nią, a granica, której komponenty są renderowane przez różne cele, jest czymś zwykłym, a nie błędem. Ostrzeżenie należy do klasy unsupported-field i jest wyciszane flagą tej klasy.

Dane wejściowe modułu zadeklarowane jako wrażliwe

Terraform jest jedynym celem z biblioteki standardowej, który ma natywny mechanizm wrażliwości na poziomie pojedynczej wartości, dzięki czemu daną zadeklarowaną przez autora jako wrażliwa można wyrenderować w kategoriach samego Terraform, a nie tylko zapisać w kategoriach Aggrega.

Gdy dane wejściowe modułu dołączonego (vendored) niosą materiał zadeklarowany przez autora jako wrażliwy, provider dopisuje obok modułu jeszcze jeden plik, aggrega_override.tf.json, deklarujący sensitive = true dla tych danych wejściowych:

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

Terraform scala plik konfiguracyjny, którego nazwa to samo override lub kończy się na _override, z konfiguracją w tym samym katalogu, więc własny blok variable modułu zyskuje ten atrybut, a każdy dołączony bajt pozostaje dokładnie taki, jak go napisano. Zadeklarowany typ, wartość domyślna i opis danych wejściowych pozostają nietknięte — nadpisanie niesie atrybut wrażliwości i nic więcej. Węzeł bez oznaczenia nie otrzymuje takiego pliku.

To ograniczenie jest zamierzone, a nie narzucone przez format pliku: nic w nadpisaniu nie odrzuca drugiego atrybutu, a default bloku variable to najbliższe miejsce, po które można by sięgnąć, aby przekazać wartość do dołączonego modułu bez edytowania jego bajtów — ale ta wartość by nie dotarła. default w składni konfiguracji JSON, w której zapisany jest ten plik, nie jest miejscem, które Terraform ewaluuje, więc wartość zawierająca zapisany tam wskaźnik ${ ... } trafia do modułu jako dosłowne znaki wskaźnika, przy planie, który kończy się powodzeniem i niczego nie zgłasza. Ten sam wskaźnik zapisany w default w natywnym HCL jest od razu odrzucany, co umiejscawia tę ciszę w tej składni, a nie w plikach nadpisań jako takich. Dlatego nadpisanie niesie wyłącznie sensitive: jego znaczenie nie zależy od ewaluacji.

O tym, które dane wejściowe zostaną oznaczone, decyduje deklaracja, nigdy nazwa. Provider odczytuje oznaczenie obliczone podczas kompilacji i sam niczego nie analizuje: nie rozpoznaje password, secret ani token i nie czyta tekstu modułu, aby zgadywać. Dane wejściowe modułu o nazwie db_password, których wartość nie ma deklaracji, są emitowane bez oznaczenia, a zadeklarowane dane wejściowe o nazwie region są oznaczane.

Oznaczenie jest przenoszone tylko tam, gdzie tożsamość danych wejściowych da się odtworzyć z deklaracji. Encja Recipe, która dołącza moduł za pomocą source: i pozwala, by zadeklarowane liście values węzła stały się bezpośrednio danymi wejściowymi modułu, nadaje każdym danym wejściowym tę samą nazwę, którą zadeklarował autor, więc powiązanie jest dokładne — podobnie jak encja FeatureRecipe encji Feature dołączonej do komponentu, który w ten sam sposób dołącza moduł, w odniesieniu do liści deklarowanych przez jej encję Feature. Encja Recipe lub taka encja FeatureRecipe, która przekształca te wartości za pomocą szablonu valuesMapping:, wymyśla własne nazwy wyjściowe i żadna deklaracja ich nie nazywa — dlatego oznaczenia brak, zamiast stosować przybliżenie, a kompilacja informuje o tym jednym komunikatem doradczym na każdy zadeklarowany liść, podając liść i encję, do której należy mapowanie (encja Feature dołączona do granicy renderuje się bez żadnych values, więc nie ma czego oznaczać i nie generuje komunikatów); zob. A declared-sensitive value reaches the target through a values mapping (Wartość zadeklarowana jako wrażliwa trafia do celu przez mapowanie wartości). Brak jest zamierzony: zgadywanie, które przekształcone dane wejściowe niosły zadeklarowaną daną, oznaczyłoby publiczne dane wejściowe jako tajne, a Terraform ukrywałby wtedy w wyniku planu wartość, która nigdy nie była wrażliwa.

Przykład terraform-declared-sensitivity realizuje to od początku do końca i jest na tyle mały, że można go przeczytać w całości: jeden komponent deklaruje trzy liście values, z których dwa niosą publiczne identyfikatory, a jeden dane uwierzytelniające. Jego wyrenderowany wynik pokazuje argumenty bloku module niosące wszystkie trzy dane wejściowe modułu oraz nadpisanie wskazujące tylko zadeklarowane, więc obie połowy reguły są widoczne w tej samej kompilacji — łącznie z tym, że identyfikator danych uwierzytelniających obok sekretu pozostaje nieoznaczony. Usunięcie tej jednej deklaracji i ponowna kompilacja nie emituje żadnego pliku nadpisania.

Co sensitive w Terraform gwarantuje, a czego nie

Aggrega obiecuje dokładnie to, co zapewnia własny atrybut Terraform, i nic więcej.

Ogranicza wyświetlanie. Wartość wrażliwa jest widoczna jako (sensitive value) w wyniku planu i jako <sensitive> w wyniku apply. Oznaczenie propaguje się przez wyrażenia, więc wartość wyprowadzona z wrażliwych danych wejściowych też jest wrażliwa, a Terraform odmawia jej eksportu z głównego output, który sam nie jest oznaczony jako wrażliwy — jest to głośny błąd zamiast cichego ujawnienia.

Nie zmienia przechowywania i nie jest szyfrowaniem. Terraform zapisuje wartość wrażliwą w stanie jawnym tekstem. Odczytywanie sensitive = true jako obietnicy, że stan można bezpiecznie commitować lub udostępniać, to jedyne błędne odczytanie, którego należy unikać: ochrona stanu pozostaje kwestią konfiguracji backendu stanu, dokładnie tak jak w przypadku modułu bez żadnego oznaczenia. Atrybut nie ogranicza też tego, kto może odczytać wartość, nie wpływa na to, co przesyła provider, i w żaden inny sposób nie zmienia wyrenderowanej konfiguracji.

Oznaczenie utrudnia więc przypadkowe ujawnienie danych wejściowych zadeklarowanych jako wrażliwe, gdy ktoś czyta plan. Nie sprawia, że artefakt wdrożeniowy można bezpiecznie opublikować. Zob. Deklarowanie liścia jako wrażliwego, aby poznać słowo kluczowe i to, co deklaracja daje we wszystkich celach.

Strukturalna walidacja danych wejściowych

Provider terraform waliduje strukturę modułu wskazanego źródłem przed renderowaniem. Parsuje pliki HCL i .tf.json modułu i zgłasza błędy parsowania, zatrzymując kompilację z czytelnym komunikatem, który wskazuje problematyczny węzeł i provider. Parsowanie sprawdza kształt, a nie semantykę — nie rozwiązuje providerów, nie oblicza wyrażeń i nie łączy się z rejestrem. Walidacja jest hermetyczna: używa samodzielnego parsera HCL wkompilowanego w provider, bez pliku binarnego terraform i bez dostępu do sieci. Błędnie sformułowany moduł zostaje wychwycony na granicy tworzenia, zamiast ujawnić się jako mylący błąd przy późniejszym uruchomieniu terraform.

Wywołanie modułu pobieranego przez silnik podczas inicjalizacji

Ten sam odczyt zgłasza, jako ostrzeżenie, które niczego nie odrzuca, każdy blok module, którego źródło Terraform pobiera podczas inicjalizacji konfiguracji. Commit i skrót archiwum modułu dołączonego do projektu są ustalone w pliku blokady, ale blok module wewnątrz niego, którego source jest adresem rejestru, adresem URL repozytorium git, Mercurial lub archiwum HTTP, zasobnikiem S3 lub GCS albo ścieżką bezwzględną, wskazuje moduł pobierany przez silnik podczas inicjalizacji, w wersji, którą silnik wtedy wybierze — a własny plik blokady zależności Terraform rejestruje wyłącznie providery, więc nic nie przypina tego modułu. Zgłaszane jest również lokalne source, które wychodzi poza dołączony moduł, ponieważ wskazuje pliki, których kompilacja nie dołączyła. Każde zgłoszenie wskazuje węzeł i provider, następnie blok, plik i wiersz, w którym się znajduje, oraz źródło w zapisanej postaci:

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

Co jest odczytywane. Pliki, które silnik ładuje przy wywołaniu modułu: pliki konfiguracyjne bezpośrednio w katalogu samego modułu, a następnie pliki w każdym katalogu, do którego stamtąd prowadzi lokalne source — zaczynające się od ./ lub ../ albo ich zapisów z ukośnikiem wstecznym — śledzone od katalogu do katalogu, przy czym każdy jest odczytywany raz. Katalog, którego nic nie wywołuje, nie jest odczytywany, więc wywołania z katalogów examples/ lub tests/ modułu nie są zgłaszane: silnik nigdy ich nie ładuje przy wywołaniu modułu i nic, co wywołują, nie jest pobierane. Opisane wyżej sprawdzenie nadal parsuje każdy dołączony plik konfiguracyjny. Treść utworzona w encji Recipe jest odczytywana w ten sam sposób podczas renderowania, począwszy od katalogu, do którego jest zapisywana, więc zgłaszany jest również blok module ze źródłem w rejestrze zapisany w takiej treści. Plik w spec.boundary.artifacts jest obliczany i zapisywany przez sam kompilator i nie trafia do żadnego providera, więc zapisany w nim blok module nie jest odczytywany i nie powoduje ostrzeżenia.

Co nie jest odczytywane. Odczytywane jest tylko to, co mówi source. Kompilacja nie odczytuje modułu wskazanego przez wywołanie, nie ocenia, co ten moduł robi, i nie rozstrzyga, czy wywołanie jest dopuszczalne. source, które silnik oblicza zamiast odczytać w zapisanej postaci — zawierające interpolację lub odwołanie — jest oceniane po początkowym tekście: zaczynające się od adresu jest zgłaszane w zapisanej postaci, a zaczynające się od lokalnego prefiksu lub od samej interpolacji nie jest ani zgłaszane, ani śledzone, ponieważ to, dokąd prowadzi, nie wynika z tekstu. source wewnątrz required_providers wskazuje provider, a nie moduł, i nie jest wywołaniem modułu.

Dlaczego jest to zgłaszane, a nie odrzucane. Moduł wywołujący inny moduł jest prawidłowym wejściem: Terraform pobiera wywoływany moduł i konfiguracja działa. Autor rezygnuje z przypięcia wywoływanego modułu przez kompilację, co jest faktem wartym poznania, a nie usterką do naprawienia, a to, czy takie pobranie jest dopuszczalne, pozostaje oceną autora. Konfiguracja, która musi pozostać w pełni przypięta, dołącza tylko moduły, które nie wykonują takich wywołań. Ostrzeżenie, jego kod klasy oraz inne miejsca, do których trafia, opisano w Warnings and Linter Output.

Granica łatek FeatureRecipe

Krok pipeline encji FeatureRecipe wykonywany po renderowaniu łata wyłącznie dane wyjściowe, które provider renderuje do ustrukturyzowanego drzewa. Dla terraform oznacza to:

  • Terraform zapisany w JSON można łatać. Moduł .tf.json jest ustrukturyzowanym dokumentem, więc JSONPatch kroku potoku edytuje wskazane wartości w miejscu, a każdy inny bajt — kolejność, formatowanie, otaczające klucze — pozostawia nietknięty.
  • Natywny HCL jest nieprzezroczysty. Treść w natywnym HCL (main.tf) nie jest ustrukturyzowanym celem łatki. Łatka skierowana na nieprzezroczystą treść zatrzymuje budowanie z diagnostyką, zamiast modyfikować tekst, którego nie da się zaadresować strukturalnie; napisanie kroku potoku skierowanego na treść HCL jest błędem projektowym ujawnianym jako głośne zatrzymanie, a nie cicha operacja bez efektu.
  • Dane wejściowe modułu pobranego ze źródła w ogóle nie są celem łatki. Są to argumenty bloku module komponentu, który znajduje się w konfiguracji głównej: w natywnym HCL, a więc nieprzezroczystej, i będącej artefaktem całej granicy, a nie pojedynczego węzła. Krok pipeline łata własne wyrenderowane dane wyjściowe węzła, więc nie ma miejsca, z którego można by je zaadresować.

Autor, który potrzebuje, aby treść Terraform dała się łatać w potoku, zapisuje ją zatem jako .tf.json. Ogólną granicę celów łatek dla wszystkich providerów opisuje strona FeatureRecipe.

Kolejność wdrażania

Wartość syncWave: granicy encji Release porządkuje bloki module konfiguracji głównej, w którą ta granica jest składana. Każdy komponent w granicy dziedziczy falę granicy, a tam, gdzie kilka granic rozwiązuje się do tego samego katalogu wyjściowego — więc ich komponenty są składane w jedną konfigurację główną — taka konfiguracja zawiera więcej niż jedną falę, a provider wyraża kolejność między nimi jako depends_on w blokach module.

Każdy moduł wskazuje każdy moduł bezpośrednio poprzedzającej fali, która ma jakiekolwiek komponenty, i żadnej wcześniejszej fali. Resztę łańcucha tworzy Terraform: moduł w fali 2 zależy od fali 1, która zależy od fali 0, więc cała sekwencja jest uporządkowana, a lista każdego modułu ma rozmiar jednej fali, a nie całej granicy. Fale nie muszą być ciągłe, a wartości ujemne są czymś zwyczajnym — -1 to częsty wybór dla bucketu lub roli, z których korzysta reszta konfiguracji. Najniższa fala nie wskazuje niczego, ponieważ nic jej nie poprzedza.

Czym jest ta kolejność: kolejnością, w jakiej Terraform wykonuje swoje akcje. Terraform buduje graf zależności i przetwarza go równolegle w zakresie, na jaki graf pozwala. depends_on dodaje do tego grafu krawędź, więc Terraform kończy akcje na wskazanych modułach, zanim rozpocznie akcje na module deklarującym zależność. Fala dzieli więc przebieg na etapy: akcje na komponentach wcześniejszej fali są wykonywane przed rozpoczęciem akcji na komponentach późniejszej.

Nie jest to kolejność gotowości. Konfiguracja Terraform nie wyraża pojęcia zasobu zdolnego do obsługi, więc nic tutaj nie czeka, aż zasób stanie się gotowy — jedynie, aż Terraform zakończy na nim akcje. To realna różnica względem tej samej fali w compose, gdzie na usługę deklarującą healthcheck czeka się, dopóki nie zgłosi poprawnego stanu: compose ma prymityw gotowości, na którym można się oprzeć, a konfiguracja Terraform go nie ma. Ten cel oferuje kolejność akcji, a jasne jej określenie jest bardziej użyteczne niż zastrzeżenie dołączone do obietnicy, której nie może złożyć.

Kolejność usuwania nie jest obiecywana. depends_on stwierdza, że Terraform kończy akcje zależności, zanim rozpocznie akcje elementu zależnego; kolejność, w jakiej destroy je usuwa, nie jest częścią tego stwierdzenia, więc nic nie jest tu deklarowane w kwestii sekwencji usuwania. To węższa obietnica niż ta, którą ta sama fala niesie w cloudformation, gdzie atrybut obejmuje oba kierunki — warto o tym wiedzieć, jeśli fala ma ustalać kolejność usuwania, ponieważ w tym celu tego nie robi.

Granica, której wszystkie komponenty mają jedną falę, nic z tego nie zyskuje. Podobnie encja Release, która w ogóle nie deklaruje syncWave: każdy element składowy ma domyślną wartość pola 0, konfiguracja główna zawiera jedną falę, a wygenerowane bajty są dokładnie takie, jakie byłyby, gdyby provider nie wyrażał kolejności fal.

Kolejności między dwiema konfiguracjami głównymi nie da się wyrazić i nie jest ona przybliżana. Graf zależności Terraform jest osobny dla każdej konfiguracji, a depends_on wskazuje moduł wewnątrz konfiguracji, która go deklaruje, więc fala porządkuje każdy komponent złożony w tę konfigurację główną i nic poza nią. Ustalanie kolejności dwóch konfiguracji należy do operatora, tak samo jak odwołanie do zdalnego stanu jest rozwiązywane w czasie wdrożenia, a nie w czasie budowania.

Fala jest zarówno zapisywana, jak i wykorzystywana: przenoszona jest wraz z resztą informacji o pochodzeniu kompilacji węzła, jako aggrega.ai/sync-wave w dołączonym bloku komentarza lub w towarzyszącym pliku pochodzenia, gdy treść jest w formacie JSON albo jest włączonym modułem. Wygenerowana konfiguracja zapisuje więc, jaką falę zadeklarowała jej granica, a także jest według niej uporządkowana.

Kolejność, której fale nie wyrażają, pozostaje sprawą samego Terraform, a odwołania między zasobami już w dużej mierze ją określają: odwołanie do atrybutu innego zasobu każe Terraform najpierw wykonać akcje na tamtym zasobie. Moduł potrzebujący ograniczenia, którego nie wynikają ani odwołania, ani fale, zapisuje własne depends_on wewnątrz modułu, a provider emituje je dosłownie, jak każdą inną część treści.