CloudFormation Provider
Provider cloudformation renderuje encje Recipes Aggrega do szablonów stosów AWS CloudFormation. Każdy komponent renderowany do tego samego katalogu wyjściowego w ramach tego providera jest składany w jeden stos, emitowany jako pojedynczy szablon w czystym JSON, który używa długiej formy funkcji wewnętrznych (intrinsics). Granica staje się więc w typowym przypadku jednym stosem — a dwie granice, których directory: wskazuje tę samą ścieżkę, składają się razem w jeden stos i współdzielą nazwy tego szablonu. Jak każdy provider Aggrega działa offline i hermetycznie — kompilacja Aggrega jest kompilacją z wyprzedzeniem (ahead-of-time), więc provider nigdy nie wywołuje AWS, nigdy nie rozwiązuje identyfikatorów generowanych przez konto i nigdy nie uruchamia CloudFormation. Wartości dostępne wyłącznie w czasie działania pozostają odwołaniami do funkcji wewnętrznych CloudFormation (Fn::GetAtt, Fn::ImportValue, Fn::GetStackOutput), które CloudFormation rozwiązuje w czasie wdrożenia.
Recipes fragmentów składane w stos
Recipe dostawcy cloudformation definiuje fragment — zasoby CloudFormation wnoszone przez pojedynczy komponent — a nie cały szablon. Gdy renderowane są komponenty granicy, dostawca składa wszystkie fragmenty z grupy dystrybucji w jeden szablon stosu: zasoby są scalane w jednej mapie Resources, wartości provides każdego komponentu pojawiają się jako Outputs stosu, a pozostałe sekcje najwyższego poziomu szablonu są omówione kolejno w części Sekcje najwyższego poziomu w złożonym stosie. Akceptowane są dwie postacie definicji:
- Wejście fragmentowe (artefakty). Recipe definiuje fragmenty zasobów bezpośrednio; dostawca normalizuje je do długiej postaci funkcji wewnętrznych w czystym JSON i scala je w złożony stos.
- Wejście źródłowe. Recipe odwołuje się do istniejącego szablonu CloudFormation (YAML lub JSON); dostawca normalizuje go do długiej postaci JSON i przed złożeniem sprawdza jego strukturę, wypełnia parametry deklarowane przez szablon na podstawie
valuesMappingencji Recipe — zob. Wartości parametrów szablonu źródłowego — i pomija każdy zasób wskazany we wpisachomits:encji Recipe — zob. Pomijanie zasobów w szablonie źródłowym.
Złożony szablon to czysty JSON. Funkcje wewnętrzne są emitowane dosłownie i nigdy nie są obliczane w czasie budowania — kompilator nie może rozwiązać wartości, która istnieje dopiero po wdrożeniu stosu, a jej obliczanie złamałoby kontrakt kompilacji z wyprzedzeniem.
Feature dołączona do komponentu wnosi zasoby do tego samego stosu
Encja Feature dołączona do komponentu wnosi swoje zasoby do stosu, w który składa się jej komponent macierzysty, na tych samych zasadach co własna encja Recipe komponentu macierzystego. Obok nie ma osobnego szablonu: złożony stos to całość tego, co ten dostawca emituje dla katalogu wyjściowego, więc zasoby dołączonej encji Feature albo znajdują się w tym stosie, albo nie są wdrażane wcale. Odłączenie encji Feature usuwa dokładnie te zasoby i pozostawia własne zasoby komponentu macierzystego bez zmian.
Ponieważ trafiają do złożonego stosu, współdzielą jego nazwy. Identyfikatory logiczne zasobów dołączonej encji Feature należą do tej samej przestrzeni co identyfikatory komponentu macierzystego i każdej innej encji Feature dołączonej obok niej, więc Nazwy w złożonym stosie mają do nich zastosowanie bez zmian. Gdy dwóch współtwórców trafi na jedną nazwę, zatrzymanie wskazuje komponent i klucz, pod którym dołączono encję Feature, dzięki czemu oba końce kolizji można odnaleźć we własnych plikach.
Wyjścia dołączonej encji Feature są publikowane pod nazwą jej komponentu macierzystego, a identyfikatory logiczne jej zasobów — nie. Obie połowy stosu są nazywane według różnych zasad, więc odpowiadają na to inaczej. Identyfikator logiczny zasobu jest emitowany dokładnie tak, jak zdefiniowała go encja FeatureRecipe, tak jak w przypadku każdej encji Recipe. Wyjście jest nazywane od komponentu publikującego i wpisu łącznie — a dla encji Feature dołączonej do komponentu komponentem publikującym jest komponent macierzysty: encja Feature dołączona do payments-db publikująca alarm otrzymuje nazwę paymentsXzhdbXXalarm, tę samą, którą otrzymałby wpis opublikowany przez sam komponent macierzysty. Zatem nazwa wpisu publikowana również przez komponent macierzysty spotyka się z nazwą dołączenia w jednej nazwie wyjścia, a budowanie zatrzymuje się, wskazując komponent i klucz, pod którym dołączono encję Feature, obok samego komponentu. Wybór nazw wpisów, które wyraźnie należą do encji Feature — backup-alarm zamiast alarm — zapobiega kolizjom z nazwami komponentu macierzystego.
Każdy zasób wniesiony przez encję Feature zachowuje w zapisywanych na nim przez budowanie informacjach o pochodzeniu tożsamość złożoną dla tego dołączenia, a nie tożsamość komponentu macierzystego, dzięki czemu oba pozostają rozróżnialne w stosie, do którego oba się przyczyniły. Sposób budowania tej tożsamości opisano w części Etykiety i adnotacje.
Sekcje najwyższego poziomu w złożonym stosie
Kilka komponentów składa się w jeden stos, więc złożenie musi uwzględnić każdą sekcję najwyższego poziomu, jaką dopuszcza szablon CloudFormation — łącznie z Globals i Hooks, dwiema sekcjami, które do języka szablonów dodaje transformacja hostowana przez CloudFormation. Każda z nich należy do dokładnie jednej z poniższych grup, a klucz najwyższego poziomu zapisany przez komponent, który nie jest żadną sekcją, powoduje ostrzeżenie podające komponent i klucz, dzięki czemu nic nie zostaje pominięte bez informacji.
Składane pod nazwami, którym provider nadaje zakres, lub odczytywane tak, jak zapisano. Resources i Outputs, które w pełni omawia sekcja Nazwy w złożonym stosie. AWSTemplateFormatVersion zapisuje provider, zamiast odczytywać go z któregokolwiek komponentu: język szablonów dopuszcza dla niego jedną wartość, więc komponent nie ma tu nic do rozstrzygnięcia.
Przenoszone dokładnie pod nazwami, które zostały zapisane. Parameters, Mappings, Conditions, Metadata i Rules. Każda z nich jest mapą, której kluczami są wybrane przez autora nazwy, więc wpisy każdego komponentu trafiają do złożonego stosu pod tymi nazwami, bez przepisywania — dzięki temu Condition: zasobu, Fn::FindInMap lub Ref do parametru rozwiązuje się względem deklaracji, która dotarła razem z nim. Każda jest przenoszona osobno, ponieważ każda jest osobno tworzona: reguła formułuje asercję o parametrze tego samego dokumentu, warunek może nie odwoływać się do żadnego parametru, a CloudFormation nie dopuszcza odwołania do parametru wewnątrz mapowania.
Jedno słowo obejmuje tu dwa różne miejsca i tylko pierwsze z nich należy do autora. Metadata z powyższej listy to własna sekcja najwyższego poziomu szablonu, mapa wybranych przez autora nazw. Pojedynczy zasób ma również własny atrybut Metadata i to tam kompilacja zapisuje pochodzenie — pod jednym zarezerwowanym kluczem aggrega.ai/, dodawanym obok tego, co już tam zapisano, a nie w jego miejsce. Wpis o pochodzeniu widoczny wewnątrz zasobu nie jest więc czymś, co napisał autor, ani czymś, co przeniosła sekcja najwyższego poziomu.
Parameters, Mappings, Conditions i Rules nazywają swoje wpisy identyfikatorem logicznym. Ponieważ provider przenosi nazwę dokładnie tak, jak ją zapisano, alfabet dopuszczany przez identyfikator logiczny obowiązuje również w tych sekcjach: nazwa w jednej z tych czterech sekcji zawierająca cokolwiek poza literami i cyframi zatrzymuje kompilację — zob. A carried section name outside the alphabet halts (Przenoszona nazwa sekcji spoza alfabetu zatrzymuje kompilację). Provider nie ogranicza do tego alfabetu nazw sekcji najwyższego poziomu Metadata: nazywają one przechowywane informacje, a nie coś, do czego odwołuje się szablon.
Dwa komponenty deklarujące różne nazwy w jednej z tych sekcji trafiają do stosu oba. Dwa deklarujące jedną nazwę z identyczną treścią scalają się w jeden wpis i kompilacja przebiega dalej. Dwa deklarujące jedną nazwę z różną treścią zatrzymują kompilację, która podaje sekcję, nazwę i oba komponenty — ponieważ w przeciwnym razie jedna z dwóch treści zostałaby odrzucona, a komponent, który ją zapisał, zostałby z deklaracją, której stos nie zawiera. To samo uzgadnianie obowiązuje nazwy zasobów i wyjść, a zmiana nazwy w którymkolwiek z nich usuwa problem.
Wskazywane zamiast przenoszenia. Description jest pojedynczym stwierdzeniem o całym szablonie, a nie mapą wybranych nazw, więc złożenie oparte na kilku komponentach nie ma dla niego odpowiedzi: dwa opisy to dwie odpowiedzi na jedno pytanie i żadna nie jest odpowiedzią stosu. Hooks odczytuje tylko transformacja AWS::CodeDeployBlueGreen, której złożony stos nigdy nie przenosi (zob. niżej). Złożony stos nie przenosi więc żadnej z nich, a każdy komponent, który zapisał którąś, otrzymuje ostrzeżenie podające komponent i sekcję. To samo dotyczy komponentu, który zapisuje Globals bez deklarowania odczytującej ją transformacji AWS::Serverless-2016-10-31. Ostrzeżenie ma charakter informacyjny i jest przekazywane poza szablonem: emitowany szablon jest bajt w bajt taki, jaki byłby bez niego, a --no-unsupported-field-warnings wycisza je wraz z resztą tej klasy.
Transform powstaje z transformacji wszystkich komponentów. Transformacja to makro, które CloudFormation uruchamia na całym szablonie przed wdrożeniem czegokolwiek, więc Transform złożonego stosu jest sumą transformacji deklarowanych przez jego komponenty — zarówno w szablonie źródłowym, jak i we fragmencie — w kolejności opisanej w dokumentacji CloudFormation: makro zdefiniowane na koncie przed transformacjami hostowanymi przez CloudFormation, a AWS::LanguageExtensions przed AWS::Serverless-2016-10-31. Kolejność w obrębie każdego komponentu jest zachowywana, a dwie transformacje, których nic nie porządkuje, działają w kolejności, w jakiej komponenty po raz pierwszy je deklarują, więc te same komponenty dają ten sam stos. Jedną transformację zapisuje się jako ciąg znaków, a kilka jako listę. Stos z tylko jednym komponentem, który deklaruje swój Transform w jednym szablonie lub fragmencie, zachowuje go dokładnie tak, jak go zapisano, wszędzie tam, gdzie poniższa tabela go przenosi, a stos, którego komponenty nie deklarują żadnej transformacji, nie przenosi żadnej. Transformacja komponentu nie powoduje ostrzeżenia: jest przenoszona albo kompilacja zatrzymuje się, podając ją.
Ponieważ transformacja przetwarza cały szablon, przeniesienie jej zmienia sposób wdrażania treści każdego innego komponentu, chyba że jej działanie ogranicza się do treści napisanej dla niej. Dlatego każda transformacja otrzymuje traktowanie, na jakie pozwala jej własna dokumentacja CloudFormation, a kombinacja, której stos nie może przenieść, zatrzymuje kompilację, która podaje transformację i każdy komponent w stosie:
| transformacja | w złożonym stosie |
|---|---|
AWS::Serverless-2016-10-31 | przenoszona wraz z Globals komponentu, który ją deklaruje. Zatrzymuje kompilację tam, gdzie te Globals sięgnęłyby do zasobów serverless innego komponentu, oraz tam, gdzie źródło zdarzeń jednego z jej zasobów wskazuje zasób deklarowany przez inny komponent, ponieważ transformacja przepisuje zasób wskazany przez zdarzenie. |
AWS::LanguageExtensions | przenoszona samodzielnie lub obok AWS::Serverless-2016-10-31 z tego samego komponentu. Zatrzymuje kompilację obok treści serverless innego komponentu, ponieważ transformacja serverless inaczej nazywa to, co generuje, gdy rozszerzenia języka rozwiążą już jej wartości. |
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16 | przenoszone: przetwarzają tylko te harmonogramy rotacji, które o nie proszą. |
AWS::ServiceCatalog | przenoszona w stosie z tylko jednym komponentem. Obok dowolnego innego zatrzymuje kompilację, ponieważ podstawia swój wzorzec odwołania w dowolnym miejscu szablonu. |
AWS::CodeDeployBlueGreen | zatrzymuje kompilację, nawet samodzielnie: CloudFormation odrzuca Outputs i Fn::ImportValue w dowolnym miejscu szablonu, który ją deklaruje, a złożony stos przenosi wyjścia publikowane przez jego komponenty. |
AWS::Include | zatrzymuje kompilację, nawet samodzielnie: wstawia treść pobieraną z S3 podczas wdrażania stosu, której kompilacja nie może odczytać. |
| makro zdefiniowane na koncie | przenoszone w stosie z tylko jednym komponentem. Obok dowolnego innego zatrzymuje kompilację, ponieważ jego wpływ na resztę szablonu jest dla kompilacji nieznany. |
Dwa komponenty deklarujące jedną parę transformacji w przeciwnych kolejnościach również zatrzymują kompilację, która podaje obie kolejności i oba komponenty, ponieważ stos uruchamia je w jednej kolejności. Komponent potrzebujący transformacji, której stos nie może przenieść, należy umieścić we własnej granicy.
Nazwy w złożonym stosie
Identyfikator logiczny CloudFormation jest unikalny w obrębie jednego szablonu i dopuszcza wyłącznie litery i cyfry, a każdy komponent składany do tego szablonu współdzieli jego nazwy — w tym komponenty z drugiej granicy, gdy obie wskazują ten sam katalog wyjściowy. Dlatego każda nazwa, przez którą stos się do czegoś odwołuje, musi być odrębna we wszystkich komponentach, które ją wniosły, a zbiór tych komponentów nie zawsze jest pojedynczą granicą.
Identyfikatory logiczne zasobów pochodzą z encji Recipe. Provider emituje je dokładnie tak, jak zostały zapisane, i żadnego nie przepisuje, więc nazwa widoczna w złożonym szablonie jest nazwą zapisaną przez Recipe. Standardowe Recipes dla CloudFormation wyprowadzają ją z nazwy samej instancji komponentu, traktując separatory tej nazwy jako granice słów: instancja payments-db nadaje swojemu zasobowi nazwę PaymentsDb. Dwie instancje tego samego typu opisują więc dwa zasoby, zamiast rywalizować o jeden.
Nazwy wyjść mają zasięg komponentu, który je opublikował. Każdy wpis provides pojawia się jako wyjście nazwane łącznie od publikującego komponentu i wpisu — komponent payments-db publikujący host daje wyjście paymentsXzhdbXXhost — więc dwa komponenty publikujące ten sam wpis trafiają do dwóch osobnych wyjść, a znaczenie wyjścia nie zmienia się, gdy do stosu dołącza inny komponent. Konsument między stosami na tym samym koncie i w tym samym regionie importuje według nazwy eksportu, a nie tej nazwy, więc nazwa eksportu pozostaje bez zmian; odczyt między kontami lub regionami wskazuje to wyjście, w postaci zapisanej za użytkownika przez dostawcę (zob. Połączenia między stosami).
Jak budowana jest nazwa wyjścia
Identyfikator logiczny nie dopuszcza żadnego znaku separatora, więc nazwa zbudowana z czegoś, co zostało zapisane przez autora, musi jakoś przenieść jego separatory. Ich pominięcie powodowałoby utratę informacji: payments-db i payments_db to dwa komponenty, a nazwa pozbawiona interpunkcji nie identyfikowałaby żadnego z nich. Dlatego provider zamiast tego koduje to, czego alfabet nie dopuszcza, zapisując każdy niedopuszczalny znak za pomocą znaków, które alfabet dopuszcza.
Schemat rezerwuje jeden znak do otwierania sekwencji ucieczki — wielką literę X — a wszystko inne zapisuje tak, jak zostało wpisane, łącznie z wielkimi literami. Zarezerwowana jest tylko wielka litera, więc mała litera x w nazwie takiej jak nginx-proxy jest przenoszona bez zmian:
| co zostało zapisane | na co się zmienia | dlaczego |
|---|---|---|
litera lub cyfra, z wyjątkiem X | pozostaje sobą | alfabet ją dopuszcza |
- | Xzh | alfabet nie dopuszcza łącznika |
_ | Xzu | alfabet nie dopuszcza podkreślenia |
. | Xzd | alfabet nie dopuszcza kropki |
/ | Xzs | alfabet nie dopuszcza ukośnika, który zawiera tożsamość zagnieżdżonego komponentu |
X | Xzx000058 | zarezerwowany do otwierania sekwencji ucieczki, więc jest zapisywany przez punkt kodowy |
| cokolwiek innego | Xzx i punkt kodowy znaku | jedna reguła obejmuje wszystkie pozostałe znaki |
| miejsce styku dwóch połówek | XX | dwa znaki otwierające z rzędu, których żadna połówka nie może zawierać |
Odczyt jest jednoznaczny i to jest celem, a nie drobną zaletą. X pozostaje sobą tylko wtedy, gdy następujący po nim znak jest dopuszczany przez alfabet, więc zakodowana połówka nigdy się nim nie kończy i nigdy nie zawiera dwóch z rzędu — dzięki czemu XX może oznaczać styk, i wyłącznie styk.
Dlatego trzy nazwy różniące się tylko położeniem interpunkcji pozostają rozróżnialne:
component payments-db publishing host → paymentsXzhdbXXhostcomponent payments_db publishing host → paymentsXzudbXXhostcomponent payments publishing db-host → paymentsXXdbXzhhostNazwy są dłuższe i mniej czytelne na pierwszy rzut oka niż zapisana nazwa komponentu — i to jest cena tego rozwiązania. Nazwa identyfikująca dokładnie jeden wpis jest warta więcej niż krótsza, która nie identyfikuje żadnego z dwóch — a do wyjścia odwołuje się przez nazwę eksportu, a nie wpisując tę nazwę, więc kosztem jest jedynie drugie spojrzenie przy czytaniu wyemitowanego szablonu.
Identyfikatory logiczne zasobów podlegają innej regule, ponieważ provider ich nie buduje: emituje to, co zapisała Recipe. Standardowe Recipes dla CloudFormation wyprowadzają je, traktując separatory nazwy instancji jako granice słów — instancja payments-db nadaje swojemu zasobowi nazwę PaymentsDb — a to wyprowadzenie pomija separatory, więc dwie nazwy instancji różniące się tylko interpunkcją lub tylko wielkością litery nadal dają jedną nazwę zasobu. Kompilacja zostaje wtedy przerwana, z podaniem każdej instancji, która doszła do tej nazwy, oraz samej nazwy, zamiast emitować jeden zasób tam, gdzie zadeklarowano dwa komponenty. Podawane są wszystkie, a nie tylko niektóre, ponieważ nic w kolizji nie czyni wyprowadzenia jednej instancji tym zamierzonym. Zmiana nazw wszystkich oprócz jednej usuwa problem.
Identyfikator logiczny zasobu spoza alfabetu przerywa kompilację
Unikalność i alfabet to dwa odrębne wymagania, a zbiór nazw może spełniać pierwsze i nie spełniać drugiego. Ponieważ provider emituje identyfikator logiczny zasobu dokładnie tak, jak zapisała go Recipe, identyfikator tworzony przez Recipe musi być taki, jaki szablon CloudFormation może przyjąć sam w sobie: litery i cyfry, nic więcej.
W tym miejscu drogi nazwy wyprowadzanej i przekazywanej bez zmian się rozchodzą. Nazwę wyjścia buduje provider, który koduje publikujący komponent i wpis, więc nazwa wyjścia mieści się w alfabecie niezależnie od zapisu którejkolwiek połówki. Identyfikator logiczny zasobu jest przekazywany bez zmian, więc szablon otrzymuje dokładnie to, co zapisała Recipe.
To czyni go także ograniczeniem dla nazw komponentów, gdy Recipe wpisuje nazwę instancji komponentu wprost do identyfikatora logicznego. Nazwa komponentu może zawierać łącznik lub podkreślenie; identyfikator logiczny nie może. Komponent kierowany do tego providera przez taką Recipe należy więc nazwać wyłącznie literami i cyframi — paymentsdb zamiast payments-db — a wszystko inne przerywa kompilację.
Komunikat przerwania podaje komponent, którego Recipe utworzyła identyfikator, sam identyfikator i każdy znak, który nie może się w nim znaleźć, oraz mówi, co można zapisać zamiast tego. Problem usuwają dwie rzeczy, a pierwsza jest zawsze dostępna:
- Sprawić, by Recipe tworzyła własny identyfikator logiczny, zamiast przekazywać nazwę wprost. Tę drogę wybierają standardowe Recipes dla CloudFormation — traktują separatory nazwy instancji jako granice słów, więc instancja
payments-dbnadaje swojemu zasobowi nazwęPaymentsDb, a wybrana nazwa komponentu zostaje zachowana. Wyprowadzanie identyfikatora w ten sposób zamienia to przerwanie na opisaną wyżej regułę kolizji: dwie nazwy instancji różniące się tylko interpunkcją dają jedną nazwę zasobu. - Tam, gdzie Recipe przekazuje nazwę wprost, należy zmienić to, co przekazuje, na nazwę złożoną wyłącznie z liter i cyfr. Dla własnej Recipe komponentu jest to nazwa komponentu. Encja Feature dołączona do komponentu nazywa swoje zasoby na podstawie własnej encji FeatureRecipe, więc zmiana nazwy komponentu nadrzędnego do nich nie sięga — zmienić trzeba identyfikator zapisywany przez tę Recipe.
Provider odmawia; nie naprawia po cichu. Przepisanie identyfikatora w imieniu autora wyglądałoby na pomocne, ale takie nie jest. Identyfikator logiczny to sposób, w jaki CloudFormation rozpoznaje zasób między aktualizacjami, więc jego zmiana nie jest zmianą nazwy — wskazuje inny zasób. Identyfikator podstawiony przez providera wskazywałby coś innego niż zasób już wdrożony pod zapisanym identyfikatorem, a o podstawieniu, o które nikt nie prosił, trzeba by się dowiadywać z wyemitowanego szablonu. Przerwana kompilacja wskazuje problem, póki jeszcze można go samodzielnie naprawić.
Przenoszona nazwa sekcji spoza alfabetu zatrzymuje kompilację
Identyfikatory logiczne zasobów nie są jedynymi nazwami, które provider przenosi dokładnie w zapisanej postaci. Parameters, Mappings, Conditions i Rules również nazywają swoje wpisy identyfikatorem logicznym, a każda z tych czterech sekcji trafia do złożonego stosu pod nazwą wybraną przez autora. Wymaganie jest więc to samo, tylko na czterech kolejnych powierzchniach: nazwa musi być taka, jaką szablon CloudFormation może przechować samodzielnie — litery i cyfry, nic więcej — a wszystko inne zatrzymuje kompilację.
Istnieje jedna konsekwencja wykraczająca poza sekcję, która przenosi nazwę, i to ona sprawia, że kompilacja zostaje zatrzymana, a nie kończy się ostrzeżeniem. Względem tych nazw rozwiązywane są Condition: zasobu, Fn::FindInMap czy Ref do parametru. Nazwa, której alfabet nie dopuszcza, usuwa zatem z wdrażalnego szablonu zarówno samą deklarację, jak i wskazujące na nią odwołanie, więc jedna zapisana nazwa czyni oba niedostępnymi naraz — a bez zatrzymania wychodzi to na jaw dopiero podczas wdrożenia, i to u osoby wdrażającej, a nie u autora nazwy.
Komunikat zatrzymania wskazuje kontrybutora, którego Recipe zapisał nazwę, sekcję, w której ją zapisano, samą nazwę oraz każdy znak, który nie może się w niej znaleźć. Sekcja jest terminem, którego należy szukać w swoich Recipes: nazwy te są przenoszone dokładnie pod sekcją, w której je zapisano, więc jest to jedyne słowo występujące zarówno w komunikacie, jak i we własnych plikach. Problem usuwa zmiana nazwy wpisu na złożoną wyłącznie z liter i cyfr i jest to całe rozwiązanie — w przypadku identyfikatora logicznego zasobu alternatywą jest wyprowadzenie identyfikatora przez Recipe zamiast przekazywania nazwy, a tutaj nie ma czego wyprowadzać, bo nazwa w sekcji jest tym, co zapisano.
Alfabetowi podlegają wyłącznie własne nazwy sekcji, nigdy klucze wewnątrz wpisu. Klucze drugiego poziomu w mapowaniu można wybierać dowolnie — us-east-1 w mapie RegionCidr to typowy przypadek i trafia do wygenerowanego szablonu bez zmian. Klucze w treści parametru, warunku lub reguły nazywają atrybuty, asercje i funkcje wewnętrzne, a nie cokolwiek, do czego odwołuje się stos: Assertions reguły oraz zapisany w niej Fn::Contains są kluczami tego rodzaju. Żaden z nich nie jest identyfikatorem logicznym i żaden nie jest sprawdzany.
Dwie nazwy wpisów zapisane odmiennie pozostają rozróżnione
Trzy rodzaje nazw wpisów są na tyle bliskie, że mogłyby spotkać się w jednej nazwie wyjścia, i żaden z nich nie jest egzotyczny. Ponieważ obie połowy są kodowane, a nie upraszczane, i łączą się sekwencją, której żadna z nich nie może zawierać, wszystkie trzy otrzymują własne nazwy:
- Wpisy różniące się wyłącznie interpunkcją. Komponent publikujący zarówno
db-host, jak idb_hostotrzymujedbXzhhostorazdbXzuhost. - Wpisy różniące się wyłącznie wielkością litery.
hostiHostdająhostiHost, ponieważ litera jest przenoszona w zapisanej wielkości. - Wpisy, które spotykają się na złączeniu. Component
payments-dbpublikującyhostdajepaymentsXzhdbXXhost; Componentpaymentspublikującydb-hostdajepaymentsXXdbXzhhost.
Dwa wpisy nadal się spotykają, gdy rzeczywiście nazywają jedną rzecz. Nazwa wyjścia jest budowana z komponentu publikującego i wpisu, więc wszystko, co ma oba wspólne, daje jedną nazwę niezależnie od kodowania. Najczęściej spotykany przypadek to jedna encja Feature dołączona dwukrotnie do jednego komponentu: dołączenie publikuje pod swoim hostem, więc dwa dołączenia jednej encji Feature do jednego komponentu publikują alarm-id z payments-db i w tej parze nie ma niczego, co by je odróżniało. Kompilacja zatrzymuje się zamiast emitować jedno wyjście tam, gdzie zapisano dwa, wskazując komponent oraz klucz dołączenia, który niosła każda ze stron, dzięki czemu oba końce można wyszukać we własnych plikach. Należy albo dołączyć Feature raz, albo użyć encji Feature, której nazwy publikowanych wpisów są właściwe dla danego dołączenia.
Dotyczy to zarówno sytuacji, gdy oba wpisy mają tę samą wartość, jak i gdy jej nie mają. Dwa wpisy o tej samej wartości nadal opisują dwa wyjścia, o które poprosił autor, więc scalenie ich w jedno spowodowałoby brak w stosie jednego z dwóch zapisanych wyjść.
Nie dotyczy to nazwy, którą Recipe składa w szablonie
Opisane wyżej kodowanie należy do providera i dotyczy nazw wyjść budowanych przez providera. Nie jest ono dostępne wewnątrz szablonu Recipe, więc nazwa składana przez szablon nie ma żadnej z jego gwarancji. Warto to powiedzieć wprost, ponieważ zagrożenie jest niewidoczne z wnętrza szablonu: dostępna tam funkcja upraszczająca odczytuje argument jako słowa i odrzuca wszystko, co jest między nimi, więc połączenie dwóch wartości przed uproszczeniem gubi złączenie razem z interpunkcją.
Na uwagę zasługuje FeatureRecipe nazywający zasób na podstawie instancji i klucza dołączenia, połączonych spacją, a następnie uproszczonych — app z cache oraz app-cache bez niczego dają po uproszczeniu AppCache, a obie nazwy kolidują, zanim zadziała jakakolwiek właściwość uproszczenia. Rozróżnienie takiej nazwy zapewniają dwie rzeczy, obie po stronie autora, a nie providera:
- Składane części powinny zawierać tylko litery i cyfry, aby nic nie zostało odrzucone i nie trzeba było niczego rozróżniać.
- Nie należy łączyć dwóch wartości, z których każda może zawierać separator drugiej. Gdy nazwa musi składać się z dwóch części, jedna z nich powinna być stałym literałem, którego druga nie może zawierać.
Gdy złożona nazwa jednak koliduje, koliduje jako identyfikator logiczny zasobu, a nie jako nazwa wyjścia, więc pojawia się opisane wyżej zatrzymanie dotyczące nazw zasobów.
Klucz zapisany dwukrotnie w jednym mapowaniu zatrzymuje kompilację
Fragment CloudFormation jest odczytywany jako mapowanie, a mapowanie przechowuje jedną wartość na klucz, więc klucz zapisany dwukrotnie zachowałby treść podaną jako ostatnia i odrzucił drugą. Gdy mapowaniem jest blok Resources lub Outputs, odrzucona treść to zapisany zasób lub wyjście, którego po prostu nie byłoby w stosie.
Zamiast tego kompilacja zatrzymuje się, wskazując powtórzony klucz oraz oba wiersze, w których go zapisano. Jest to reguła dotycząca całego fragmentu, a nie nazw stosu: obejmuje każde mapowanie we fragmencie, w tym Properties zasobu. Najczęściej dochodzi do tego, gdy Recipe wyprowadza identyfikator logiczny z zapisanej wartości, a dwie zapisane wartości różnią się tylko interpunkcją — app-cache i app_cache dają AppCache, więc fragment zapisuje AppCache dwukrotnie.
Nazwa klucza powtarzająca się w różnych miejscach dokumentu jest czymś zwyczajnym i pozostaje nietknięta: Type występuje raz na zasób, a Value raz na wyjście, niezależnie od liczby zasobów i wyjść we fragmencie. Treść gubi tylko powtórzenie wewnątrz jednego mapowania.
Jeden komponent może zająć jedną nazwę dwukrotnie. Recipe dostarcza kilka fragmentów — kilka wpisów artifacts: lub katalog źródłowy z kilkoma szablonami — a każdy z nich trafia do tego samego stosu, więc własne fragmenty komponentu dzielą między sobą nazwy stosu dokładnie tak, jak dzielą je różne komponenty. Dwa fragmenty nadające jednej nazwie dwie różne treści zatrzymują kompilację, a komunikat wskazuje przestrzeń kluczy, do której należy nazwa — identyfikatory logiczne zasobów lub nazwy wyjść — wraz z komponentem i samą nazwą. Obie przestrzenie są w ten sposób osiągalne: dwa fragmenty mogą zapisać jeden identyfikator logiczny zasobu dla różnych zasobów, a komponent dochodzi do swoich nazw wyjść dwiema drogami, przez jawny blok Outputs: i przez wpisy provides:, więc wpisy z obu dróg o tej samej nazwie również się tam spotykają.
Ponowne podanie nazwy samo w sobie nie jest konfliktem. Nazwa zapisana więcej niż raz z identyczną treścią i tak odnosi się do jednej rzeczy, więc powtórzenia są scalane w jeden wpis, a kompilacja przebiega dalej — zwykłe powtórzenie nic nie kosztuje. Zatrzymanie następuje w przypadku utraty treści: jedną z dwóch treści trzeba by odrzucić, a zasobu lub wyjścia zadeklarowanego przez Recipe zabrakłoby wtedy w stosie. Problem usuwa zmiana nazwy jednego z nich.
Strukturalna walidacja danych wejściowych
Wskazany jako źródło szablon CloudFormation jest walidowany strukturalnie przed renderowaniem: provider parsuje szablon i normalizuje jego funkcje wewnętrzne (intrinsics), a gdy szablon jest niepoprawny, zatrzymuje kompilację z czytelnym komunikatem wskazującym błędny węzeł. Parsowanie sprawdza kształt, a nie semantykę — nie łączy się z AWS, nie rozwiązuje referencji ani nie oblicza funkcji wewnętrznych.
Szablon, który się parsuje, nie jest przez to przenoszony w całości. Parsowanie stwierdza, że dokument jest poprawnie zbudowany; to, co trafia do złożonego stosu, rozstrzyga się osobno i dla każdej sekcji z osobna, zgodnie z Sekcje najwyższego poziomu w złożonym stosie — szablon wskazany jako źródło podlega temu samemu rozliczeniu co fragment.
Parsowanie nie sprawdza też, czy referencje szablonu dają się rozwiązać. To, czy Ref wskazuje parametr, a Fn::FindInMap mapę, jest pytaniem o złożony stos, a nie o pojedynczy dokument wejściowy, i odpowiada na nie CloudFormation w czasie wdrożenia. Kompilacja zamiast oceniać, do czego odnosi się wynik, informuje o tym, czego nie przeniosła. Referencje, które ocenia, to te, które sama kompilacja pozostawiła bez celu: referencja do parametru wypełnionego przez powiązanie szablonu wskazanego jako źródło, opisana w następnej sekcji, oraz referencja do zasobu pominiętego w szablonie przez wpis omits:, opisana w sekcji kolejnej.
Wartości parametrów szablonu źródłowego
Szablon źródłowy przyjmuje wartości tak, jak sam CloudFormation przekazuje wartości szablonowi: przez zadeklarowane w nim Parameters. valuesMapping tego, co go wskazuje jako źródło — encji Recipe komponentu lub encji FeatureRecipe dołączonej encji Feature — zapisuje jeden klucz na każdy wypełniany parametr, a provider wiąże każdy z nich w każdym szablonie źródła: każde Ref do parametru w Resources, Outputs, Conditions, Rules i Globals SAM staje się wartością, każde Fn::Sub, które nazywa parametr jako zmienną, otrzymuje wartość przez swoją mapę zmiennych, a parametr znika z Parameters każdego szablonu, który go deklaruje. Parametr, którego nie nazywa żaden klucz, pozostaje dokładnie taki, jak zapisał go szablon — dla wartości przekazanej przy wdrażaniu stosu lub dla jego Default.
Jednostką, która deklaruje parametr, jest źródło. Szablony źródła katalogowego składają się w jeden stos, więc jeden szablon może odwoływać się do parametru zadeklarowanego przez inny szablon tego samego źródła. Wypełnienie parametru wypełnia go także tam: szablon, który tylko się do niego odwołuje, otrzymuje wartość w postaci przekonwertowanej przez pierwszy szablon źródła, który go deklaruje, i nic w źródle nie pozostaje z odwołaniem do parametru, którego deklarację usunęło wiązanie.
Nic innego w stosie nie może odwoływać się do wypełnionego parametru. Treść spoza źródła — fragment lub szablon źródłowy innego komponentu w tym samym stosie — która nazywa parametr wypełniony przez wiązanie źródła, przez Ref, zmienną Fn::Sub lub Fn::ValueOf reguły, nazywałaby coś, czego złożony stos już nie deklaruje, a to CloudFormation odrzuca przy wdrażaniu stosu. Dlatego kompilacja zostaje zatrzymana z podaniem każdego komponentu, jego szablonu i parametru oraz komponentu, którego valuesMapping go wypełniło — należącego do encji Recipe lub do encji FeatureRecipe dołączonej encji Feature; encję Feature dołączoną do komponentu identyfikuje ten komponent, a dołączoną do granicy — tożsamość, którą jej zasoby niosą jako aggrega.ai/component-id, złożona ze ścieżki granicy i nazwy dołączenia (bfr--stack--aux dla dołączenia aux na granicy stack). Kompilację zatrzymuje także fragment komponentu, do którego dołączona jest encja Feature, lub komponentu w granicy, do której jest dołączona, odwołujący się do parametru wypełnionego przez wiązanie dołączenia. Nie dotyczy to nazwy, którą stos nadal deklaruje: gdy inny komponent sam deklaruje parametr o tej nazwie lub zasób nosi ją jako swój identyfikator logiczny, odwołania do niej rozwiązują się do tej deklaracji i pozostają bez zmian. Aby przekazać wartość dalej, należy sprawić, by wypełniający komponent ją opublikował, zadeklarować parametr w szablonie, który się do niego odwołuje, lub usunąć klucz z valuesMapping.
spec: capability: cloudformation implements: core/delivery-stream:1.0.0 source: kind: git-repository url: https://github.com/aws-cloudformation/aws-cloudformation-templates.git ref: a0f43bc6d20813052892546f445037cf84c75b54 module_subdir: DataFirehose valuesMapping: | CloudWatchLogGroupRetention: {{ .values.retention_days }} DestinationBucketName: "{{ .context.inject.env.BUCKET_NAME }}"Parametry wypełnia tylko valuesMapping. Zapisywane w nim klucze to nazwy parametrów przeznaczone dla szablonu, więc każdy musi nazywać parametr zadeklarowany przez któryś szablon źródła: klucz, który nie nazywa żadnego, zatrzymuje kompilację z podaniem klucza i parametrów deklarowanych przez każdy szablon — to ten sam błąd, który CloudFormation zgłosiłby dla nieznanego parametru, zgłoszony wtedy, gdy wciąż można go poprawić. Encja Recipe lub FeatureRecipe bez valuesMapping niczego nie wypełnia: własne wartości komponentu lub dołączenia trafiają do providera pod własnymi nazwami, zapisane dla jego innych danych wejściowych, i pozostają nieodczytane.
To, czym jest wartość, decyduje o tym, co trafia do szablonu.
- Literał — ciąg znaków, liczba, wartość logiczna lub ich lista — zostaje zapisany w szablonie, przekonwertowany tak, jak CloudFormation konwertuje tę samą wartość przekazaną dla
Typeparametru przy wdrażaniu stosu:Numberstaje się ciągiem znaków zwracanym przezRefdo niego, więc7dociera jako"7"; typCommaDelimitedListlubList<…>staje się listą ciągów znaków i przyjmuje listę albo ciąg rozdzielany przecinkami, którego elementy są przycinane; każdy inny typ przyjmuje jeden ciąg znaków. Literał jest sprawdzany względem własnychAllowedValues,AllowedPattern,MinLength,MaxLength,MinValueiMaxValueparametru, a literał przez nie odrzucony zatrzymuje kompilację z podaniem parametru i ograniczenia, więc wypełnienie parametru nie usuwa żadnego sprawdzenia zadeklarowanego w szablonie. Wzorzec zapisany w składni wyrażeń regularnych, której kompilacja nie potrafi odczytać, pozostaje do sprawdzenia przez CloudFormation przy wdrażaniu stosu. - Wartość, która w całości jest jedną funkcją wewnętrzną CloudFormation, trafia do miejsca odwołania jako ta funkcja, do obliczenia przez CloudFormation przy wdrażaniu stosu: mapowanie w formie długiej, takie jak
{"Fn::GetAtt": [Queue, Arn]}, lub ciąg znaków będący dokładnie jedną formą krótką —!GetAtt Queue.Arn,!Ref Bucket,!Sub …i inne formy zdefiniowane przez CloudFormation. W ten sposób opublikowane odwołanie innego komponentu trafia do parametru: encje Recipes CloudFormation z katalogu publikują takie odwołanie jako tekst w formie krótkiej, avaluesMappingodczytujące je z kontekstu wstrzykiwania przekazuje je dalej. Wstawiane odwołanie jest odczytywane tak samo w cudzysłowie i bez niego. W cudzysłowie —"{{ .context.inject.env.BUCKET_NAME }}"— mapowanie przekazuje ciąg znaków!GetAtt Queue.Arn; bez cudzysłowu własny YAML mapowania odczytuje!GetAtt Queue.Arnjako tag, a tag zostaje zachowany wraz ze swoim argumentem, a nie odrzucony. W obu przypadkach do parametru trafia funkcja wewnętrzna. Wartość, która jedynie zaczyna się od wykrzyknika lub nie nazywa żadnej formy krótkiej CloudFormation, pozostaje tekstem. - Odwołanie dynamiczne —
{{resolve:ssm:…}},{{resolve:ssm-secure:…}}lub{{resolve:secretsmanager:…}}— trafia do miejsca odwołania w zapisanej postaci, do rozwiązania przez CloudFormation przy wdrażaniu stosu, więc nazywana przez nie wartość nigdy nie znajduje się w szablonie. - Wartość publikowana przez inny komponent z innego stosu trafia do szablonu jako odwołanie między stosami, to samo
Fn::ImportValuelubFn::GetStackOutput, które otrzymuje fragment (zob. Łączenie między stosami), w każdym miejscu, w którym szablon odwoływał się do parametru.
Dla parametru, którego typ CloudFormation odczytuje z Parameter Store — AWS::SSM::Parameter::Value<…> — nie istnieje literał odtwarzający to, co zrobiłby z nim CloudFormation, więc powiązany z nim literał zatrzymuje kompilację; należy powiązać odwołanie {{resolve:ssm:…}} lub funkcję wewnętrzną albo pozostawić parametr niepowiązany. Kompilację zatrzymuje także lista powiązana z parametrem, który szablon nazywa jako zmienną Fn::Sub, ponieważ zmienna podstawia jeden ciąg znaków. Zatrzymuje ją również klucz, który valuesMapping ustawia na null, z podaniem parametru, ponieważ parametr przyjmuje wartość, a null nie jest żadną wartością; aby pozostawić parametr dla wartości przekazanej przy wdrażaniu stosu lub dla jego Default, należy pominąć jego klucz w mapowaniu.
Reguła, która odczytuje parametr po nazwie, pozostawia go niepowiązanym. Fn::ValueOf w Rules szablonu nazywa zadeklarowany parametr po jego identyfikatorze logicznym, a nie przez Ref, a wypełnienie parametru usuwa jego deklarację, więc powiązanie parametru odczytywanego w ten sposób przez regułę zatrzymuje kompilację z podaniem reguły i parametru.
Literał, który może zawierać sekret, jest odrzucany; funkcja wewnętrzna jest zapisywana bez zmian. Wartość zapisaną w szablonie może odczytać każdy, kto może odczytać szablon stosu:
- Parametr, który szablon deklaruje jako
NoEcho, przyjmuje odwołanie dynamiczne lub funkcję wewnętrzną, a powiązany z nim literał zatrzymuje kompilację. - Gdy
valuesMappingodczytuje wartość, którą autor zadeklarował jako wrażliwą, żadnego z jego wyników nie da się powiązać z wartością, z której pochodzi, więc każdy wiązany przez nie literał zatrzymuje kompilację. Wiązane przez nie odwołanie dynamiczne i funkcja wewnętrzna są zapisywane bez zmian — łącznie z tekstem wewnątrz funkcji wewnętrznej. Sekret, który mapowanie wstawia na przykład do tekstuFn::Sub, trafia więc do szablonu jako ten tekst: tylko odwołanie dynamiczne utrzymuje sam sekret poza szablonem. Gdy taka kompilacja przebiega dalej, wypisuje też jedno ostrzeżenie na każdy zadeklarowany liść, zarówno dla mapowania encji Recipe, jak i dla mapowania encji FeatureRecipe encji Feature dołączonej do komponentu, z podaniem liścia i encji, do której należy mapowanie — zob. A declared-sensitive value reaches the target through a values mapping (Wartość zadeklarowana jako wrażliwa trafia do celu przez mapowanie wartości). - Odwołanie dynamiczne zatrzymuje kompilację, gdy jego parametr jest przywoływany we właściwości
UserDatazasobu, w metadanychAWS::CloudFormation::Initlub w sekcjiOutputs: CloudFormation nie rozwiązuje odwołań dynamicznych w danych użytkownika EC2 ani w tych metadanych, a sekcjęOutputspokazuje każdemu, kto odczytuje stos.
Każda taka odmowa wymienia parametry i nie przytacza żadnej wartości.
Pomijanie zasobów w szablonie pobranym ze źródła
Zasoby szablonu pobranego ze źródła należą do niego samego: wartości docierają do niego wyłącznie przez parametry, które deklaruje, więc szablonu pobranego z repozytorium git, który deklaruje zasób, którego encja Release nie może utworzyć — bucket, który operator już zapewnia, klucz zarządzany przez platformę gdzie indziej — nie da się zmienić żadną wartością. Do tego służą wpisy omits: encji Recipe lub FeatureRecipe. Ten dostawca uwzględnia je w szablonie pobranym ze źródła i nigdzie indziej: fragmenty tworzone przez wpis artifacts: są renderowane bez nich.
spec: capability: cloudformation implements: core/store:1.0.0 source: kind: git-repository url: https://git.example.com/platform/templates.git ref: v3.2.0 module_subdir: store omits: # The template bundles an access-log bucket; this Release logs elsewhere. - kind: AWS::S3::Bucket name: StoreLogsWpis wskazuje jeden zasób przez jego Type i jego identyfikator logiczny. Pole kind wpisu to Type zasobu, na przykład AWS::S3::Bucket, a jego name to identyfikator logiczny zasobu, czyli jego klucz w Resources; oba są porównywane dokładnie tak, jak zostały zapisane, i oba muszą się zgadzać, więc wpis z poprawnym Type i niepoprawnym identyfikatorem logicznym niczego nie pomija. Szablon nie ma przestrzeni nazw, więc wpis zawierający namespace zatrzymuje kompilację podczas renderowania komponentu, wskazując ten wpis; każdy wpis jest sprawdzany, zanim cokolwiek zostanie pominięte.
Dopasowywany jest każdy szablon źródła. Źródło jednoplikowe ma jeden szablon. Źródło katalogowe — źródło pobrane z repozytorium git zawsze nim jest — ma każdy plik kończący się na .yaml, .yml, .json lub .template, a wpis pomija każdy wskazany zasób w każdym z nich; plik dołączony obok szablonów nigdy nie jest odczytywany. Dostawca podaje, ile zasobów każdy wpis pominął łącznie we wszystkich szablonach, a wpis, który niczego nie pominął, zatrzymuje kompilację; zob. An omits entry left out nothing the source rendered (Wpis omits nie pominął niczego, co wyrenderowało źródło).
Pominięty zasób znika, zanim cokolwiek innego odczyta szablon. Nie otrzymuje oznaczenia pochodzenia, nie jest liczony wśród nazw, które zawiera stos — więc inny komponent może dostarczyć zasób o tym samym identyfikatorze logicznym bez konfliktu między nimi — i nigdy nie trafia do złożonego stosu. Cała reszta szablonu jest zapisywana dokładnie tak, jak gdyby szablon został napisany bez tego zasobu, a szablon, którego wszystkie zasoby zostały pominięte, zachowuje pustą sekcję Resources.
Pominięty zasób nie może pozostać wskazywany przez to, co zostało, ponieważ CloudFormation odrzuca szablon wskazujący zasób, którego nie deklaruje. Po usunięciu zasobów każde odwołanie, które pozostałe szablony nadal robią do któregoś z nich, zatrzymuje kompilację, a komunikat podaje szablon, zasób, sposób, w jaki odwołanie go wskazuje, oraz miejsce odwołania jako ścieżkę od korzenia szablonu — na przykład /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName. Odwołaniem jest to, co dokumentacja szablonów CloudFormation definiuje jako wskazanie zasobu przez jego identyfikator logiczny, odczytywane w treści każdego zasobu — łącznie z jego właściwościami, metadanymi i politykami — oraz w każdym wyjściu:
Refz identyfikatorem logicznym jako argumentem;Fn::GetAttjako lista, której pierwszym elementem jest identyfikator logiczny, lub jako jeden ciąg —!GetAtt StoreLogs.Arn— którego tekst przed pierwszą kropką nim jest;DependsOnzasobu jako jeden identyfikator logiczny lub ich lista;- każda zmienna
Fn::Sub, w postaci ciągu i w postaci listy:${StoreLogs}i${StoreLogs.Arn}oba wskazująStoreLogs.
Niektóre wartości tylko wyglądają jak odwołania i nie są jako takie odczytywane. ${!StoreLogs} to tekst dosłowny, a zmienna nazwana w mapie postaci listy jest wartością tej mapy. Condition zasobu i pierwszy argument Fn::If wskazują warunek, Fn::FindInMap wskazuje mapowanie, Fn::ImportValue eksport innego stosu, a Fn::GetAZs region. Sekcje Conditions, Mappings, Parameters i Rules nie mogą wskazywać zasobu, a własna sekcja najwyższego poziomu Metadata szablonu to informacja, którą CloudFormation przechowuje, a nie odczytuje, więc żadna z nich nie jest sprawdzana. Ref lub Fn::GetAtt, którego identyfikator logiczny sam jest zapisany jako funkcja wewnętrzna, jest poprawny tylko przy transformacji AWS::LanguageExtensions, która rozwiązuje go podczas wdrażania stosu (zob. Sekcje najwyższego poziomu w złożonym stosie), więc nie wskazuje zasobu, który sprawdzenie mogłoby odczytać, i zostaje pozostawiony bez zmian; tak samo odwołanie do zasobu, którego źródło nigdy nie zadeklarowało.
Sprawdzenie odczytuje własne szablony deklarującej encji Recipe lub FeatureRecipe, łącznie. Składają się one w jeden stos, więc odwołanie do identyfikatora logicznego, który nadal deklaruje inny z tych szablonów, nie zatrzymuje kompilacji. Nic innego nie jest odczytywane: odwołanie do pominiętego zasobu zatrzymuje kompilację nawet wtedy, gdy inny komponent deklaruje zasób o tym identyfikatorze logicznym, a odwołania z czegokolwiek innego, co składa się w stos — innego komponentu, dołączonej encji Feature lub własnych wpisów artifacts: encji Recipe — to sprawdzenie nie widzi, więc CloudFormation odrzuca stos podczas wdrażania. Aby zachować odwołanie, należy zachować zasób. Wartość przypisana parametrowi zastępuje tylko odwołanie do tego parametru, więc odwołanie do zasobu należy do samego szablonu i nie da się go zmienić wartością: należy pominąć również zasób, który je zawiera, lub usunąć wpis. Wyjście nie jest zasobem i żaden wpis go nie wskazuje, więc zasobu wskazywanego w Outputs szablonu nie można z niego pominąć: jego pominięcie zatrzymuje kompilację.
Adnotacje celu chmurowego
Trzy adnotacje granicy informują providera, gdzie wdrażany jest stos, dzięki czemu może on poprawnie połączyć odwołania między stosami:
aggrega.ai/aws-account— konto AWS, na którym wdrażany jest stos.aggrega.ai/aws-region— region AWS, w którym wdrażany jest stos.aggrega.ai/aws-assume-role-arn— ARN roli IAM, którą przyjmuje odczyt stosu między kontami, aby uzyskać dostęp do wartości eksportowanych przez stos równorzędny.
Te adnotacje są dla kompilatora nieprzejrzyste — przekazuje on ich wartości do providera bez ich interpretowania (zob. well-known-annotations.md). Definiuje się je na granicy producenta — stosu, do którego należy eksportowana wartość. Odczyt między kontami przyjmuje rolę na koncie producenta, więc konto, region i rola opisujące odczyt pochodzą z adnotacji granicy producenta, a nie konsumenta.
Odwołania wewnątrz stosu
Gdy krawędź uses łączy dwa komponenty, które trafiają do tej samej granicy — tego samego stosu — konsumowana wartość jest wiązana jako Fn::GetAtt względem identyfikatora logicznego zasobu producenta w obrębie jednego szablonu. Wartość provides producenta trafia do wyrenderowanego wejścia konsumenta jako natywne odwołanie wewnątrz stosu; nie jest potrzebny żaden eksport ani import. Fragment konsumenta może zapisać taką wartość bez cudzysłowu — Value: {{ .context.inject.env.DB_HOST }} — albo w cudzysłowie — Value: "{{ .context.inject.env.DB_HOST }}": w obu przypadkach szablon odczytuje !GetAtt Db.Endpoint.Address jako funkcję wewnętrzną, ponieważ łańcuch będący dokładnie jedną formą skróconą trafia do stosu jako ta funkcja wewnętrzna we fragmencie tak samo jak w valuesMapping. Przykład aws-rds-and-ecs-service pokazuje to na definicji zadania Amazon ECS, która odczytuje adres instancji RDS w jednym stosie.
Powiązania między stosami
Gdy krawędź uses przechodzi z jednej granicy do innej — dwa komponenty trafiają do różnych stosów — odwołanie nie może być zwykłą wartością, ponieważ wytwarzana wartość nie istnieje, dopóki stos producenta nie zostanie wdrożony. Provider wiąże je jako odwołanie międzystosowe CloudFormation. Stos producenta publikuje wartość jako Output stosu z Export pod deterministyczną nazwą eksportu (wyprowadzoną z wydania, granicy, komponentu i dostarczanego klucza). Stos konsumenta odczytuje ją za pomocą jednej z dwóch funkcji wewnętrznych, wybieranej przez porównanie zadeklarowanego rozmieszczenia obu granic:
Fn::ImportValue— przypadek tego samego konta i tego samego regionu. CloudFormation rozwiązuje import względem pasującej nazwy eksportu w obrębie konta i regionu.Fn::GetStackOutput— rzeczywisty odczyt między kontami lub między regionami. Konsument odczytuje wyjście stosu producenta bezpośrednio, przyjmując rolęaws-assume-role-arngranicy producenta na koncie i w regionie producenta.
Semantyka wykrywania. Provider kieruje do Fn::GetStackOutput tylko wtedy, gdy oba końce deklarują rozmieszczenie (konto/region) i te rozmieszczenia się różnią. W każdym innym przypadku — gdy żaden nie deklaruje, deklaruje tylko jeden lub oba deklarują to samo rozmieszczenie — używa Fn::ImportValue. Jest to zachowawcza reguła: odczyt międzystosowy w obrębie tego samego konta pozostaje zwykłym importem, a funkcja wewnętrzna bezpośredniego odczytu jest zarezerwowana dla rzeczywistego przejścia między kontami lub regionami.
Stos producenta zawsze publikuje Export, nawet gdy dany konsument odczytuje go między kontami przez Fn::GetStackOutput. Nieużywany eksport jest bezczynny, a publikowanie go bezwarunkowo sprawia, że szablon producenta pozostaje niezależny od tego, jak każdy konsument odczytuje wartość.
Kilku konsumentów jednej wartości odczytuje jeden eksport. Gdy więcej niż jeden komponent odczytuje tę samą dostarczaną wartość przez granicę — dwóch konsumentów w jednym stosie lub konsumenci w kilku stosach — stos producenta publikuje Export tej wartości raz, a każdy konsument odczytuje tę jedną nazwę: każde Fn::ImportValue importuje ten sam eksport, a konsument umieszczony na innym koncie lub w innym regionie odczytuje to samo wyjście przez Fn::GetStackOutput. Konsument, który odczytuje również wartość niewykorzystywaną przez żadnego innego konsumenta, dodaje tylko eksport tej wartości.
Przykład aws-rds-and-ecs-service buduje przypadek tego samego konta: stos instancji RDS eksportuje każdy wpis, który konsumuje krawędź serwera, a stos serwera odczytuje każdy z nich za pomocą Fn::ImportValue.
Uwaga o wersji.
Fn::GetStackOutputjest natywną funkcją wewnętrzną CloudFormation. Odwołanie między kontami wyrenderowane za jej pomocą wymaga narzędzi CloudFormation rozpoznających tę funkcję. Ścieżka tego samego konta używaFn::ImportValue, które jest dostępne powszechnie.
Wartość odczytana z połączenia zamiast wstrzykniętej
Encja Recipe konsumenta może odczytywać wartości producenta bezpośrednio z połączenia, przez .context.uses.<alias>.provides, zamiast otrzymywać je przez blok inject połączenia. Na granicy stosu taki odczyt jest wiązany tak samo jak wartość wstrzyknięta:
- Wartość będąca funkcją wewnętrzną CloudFormation — znacznik w formie skróconej, taki jak
!GetAtt Db.Endpoint.Address, albo mapowanieReflubFn::w formie pełnej — wskazuje coś, co deklaruje tylko stos producenta, więc konsument otrzymuje to samo odwołanie między stosami, co w przypadku wartości wstrzykniętej: stos producenta publikujeExportdla tego klucza, a konsument odczytuje go za pomocąFn::ImportValuealboFn::GetStackOutput, gdy obie granice deklarują różne rozmieszczenia. - Wartość będąca zwykłym tekstem — port, protokół, nazwa bazy danych — znaczy to samo w każdym stosie, więc konsument otrzymuje samą wartość i nie jest dla niej publikowany żaden eksport. Trafia ona w postaci, w jakiej odczytuje ją CloudFormation: wartość zapisana w całości jest renderowana tak, jak bez granicy, a wartość o kształcie liczby zapisana w cudzysłowie trafia jako liczba.
O tym, czy wartość jest funkcją wewnętrzną, decyduje ten dostawca, odczytując wartość tak, jak odczytuje własny blok provides producenta. Kompilator przekazuje wartość tak, jak zapisała ją encja Recipe producenta, i jej nie interpretuje.
Szablon może taką wartość jedynie skopiować. Może zapisać wartość w całości, wewnątrz dłuższego łańcucha albo przekazać ją przez funkcję, która pozostawia ją bez zmian, taką jak quote. Porównanie, rozgałęzienie, długość lub funkcja zmieniająca wartość — eq, if, len, upper — zostałyby rozstrzygnięte względem czegoś innego niż wartość, ponieważ na takim połączeniu szablon otrzymuje zastępnik, który dostawca podmienia po złożeniu obu stosów. Zamiast tego kompilacja zostaje zatrzymana z podaniem szablonu i każdej odczytanej przez niego wartości, wraz z połączeniem, z którego ją odczytał, i komponentem na każdym jego końcu; należy rozgałęziać na podstawie własnej wartości komponentu konsumującego. To samo dotyczy injectMapping dołączonej encji FeatureRecipe oraz encji FeatureRecipe o zakresie granicy, która odczytuje połączenia granicy. Wartość zapisana wewnątrz dłuższego łańcucha napotyka też własne ograniczenie dostawcy: odwołanie między stosami może występować tylko jako cała wartość, więc funkcja wewnętrzna zapisana wewnątrz dłuższego łańcucha zatrzymuje kompilację, tak jak w przypadku wartości wstrzykniętej.
Jak budowana jest nazwa eksportu
Cztery części są łączone podwójnym łącznikiem, a każda część jest zapisywana za pomocą liter, cyfr i łączników, z których składa się nazwa eksportu. Litera lub cyfra jest przenoszona bez zmian, podobnie jak łącznik wewnątrz części — payments-db pozostaje payments-db. Każdy inny znak jest zapisywany jako krótka sekwencja ucieczki zaczynająca się od -z: ukośnik jako -zs, podkreślenie jako -zu, kropka jako -zd. Część bez żadnej wartości jest zapisywana jako -ze. Nazwa stosu jest budowana w ten sam sposób z wydania i granicy.
Zatem eksport publikujący host z komponentu db, w granicy, której katalog wyjściowy pod dist/ to stack-a/cloudformation, z wydania orders, ma postać:
aggrega--orders--stack-a-zscloudformation--db--hostOdczytanie jej z powrotem jest jednoznaczne i to jest sedno, a nie drobna wygoda: ponieważ część nigdy nie zawiera dwóch łączników z rzędu i nigdy nie kończy się łącznikiem, podwójne łączniki są zawsze połączeniami. Dwa różne zestawy części dają więc zawsze dwie różne nazwy. payments-db i payments_db trafiają do dwóch odrębnych eksportów, zamiast zbiegać się w jednym, a łącznika na krawędzi jednej części nie da się odczytać jako należącego do sąsiedniej.
Względem czego nazwa eksportu jest unikalna i gdzie to się kończy
W obrębie jednej kompilacji nazwa eksportu identyfikuje dokładnie jedno wydanie, granicę, komponent i dostarczany klucz — żadne dwa z nich nie zbiegają się w jednej nazwie, więc kompilacja nie może zgubić jednej eksportowanej wartości za inną.
CloudFormation wymaga ponadto, aby nazwa eksportu była unikalna wśród wszystkiego, co już wdrożono na koncie i w regionie, w których trafia stos. Jest to właściwość wdrożenia, a nie kompilacji, i leży poza zasięgiem jakiegokolwiek wyprowadzenia w czasie kompilacji: kompilator nie uwierzytelnia się w AWS, nie odpytuje go i nie może odczytać wyniku innej kompilacji, więc nic obliczonego z wyprzedzeniem nie może zaobserwować, co jest tam już wdrożone.
Rozróżnienie przez tę granicę przenosi tożsamość wydania, od której zaczyna się każda nazwa eksportu i stosu. Dwa wdrożenia współdzielące konto i region utrzymują swoje eksporty oddzielnie dzięki wydaniu pod różnymi nazwami — to dźwignia, którą ma się w ręku, i powód, dla którego tożsamość wydania stoi na początku nazwy, a nie na jej końcu.
Wpis Outputs może deklarować własną nazwę eksportu
Blok Outputs: w encji Recipe to ręcznie napisany kod CloudFormation, a wpis w nim może zawierać własne Export: z Name:. Ta nazwa trafia do złożonego stosu dokładnie w takiej postaci, w jakiej ją zapisano — provider jej nie przepisuje, nie dodaje do niej prefiksu i nie wymaga, aby wyglądała jak nazwa wyprowadzona.
Zazwyczaj nie ma o tym nic więcej do powiedzenia. Ręcznie zapisana nazwa eksportu, która nie pokrywa się z żadną nazwą wyprowadzaną przez providera, jest publikowana obok nazw wyprowadzonych i nigdy nie jest komentowana. Ręczne zapisywanie jest obsługiwane; nieobsługiwany jest tylko jeden zbieg okoliczności.
Kompilacja zostaje zatrzymana, gdy ręcznie zapisana nazwa eksportu jest równa nazwie, którą provider wyprowadza dla połączenia między granicami w tej samej kompilacji. Obie deklaracje trafiłyby do złożonego szablonu, przez co jedna nazwa eksportu byłaby zadeklarowana dwukrotnie w jednym stosie — a nazwa eksportu musi być unikatowa, więc obie nie mogą istnieć jednocześnie. Komunikat o zatrzymaniu podaje wyprowadzoną nazwę eksportu i cztery części, z których ją zbudowano, dzięki czemu widać, które połączenie ją wytworzyło, a także wskazuje wyjście stosu, pod którym znajduje się ręczna deklaracja, oznaczone jako nazwa składana przez providera, a nie zapisana przez encję Recipe. Nazwa eksportu to fraza, której należy szukać w swoich encjach Recipes. Ręcznie zapisany wpis zawiera ją dokładnie w takiej postaci jak komunikat — ta tożsamość sprawia, że obie nazwy kolidują — więc jest to jedyny ciąg znaków, który występuje zarówno w komunikacie, jak i we własnych plikach. Zatrzymanie usuwa zmiana nazwy eksportu deklarowanej przez ten wpis, a także usunięcie bloku Export: tego wpisu i pozostawienie publikacji eksportu mechanizmowi połączeń między stosami.
Sprawdzenie działa w zakresie kompilacji, a jego zakresem jest jeden stos. Porównuje nazwy eksportów deklarowane przez złożony stos z nazwami, które provider wyprowadza dla połączeń między granicami publikujących do tego samego stosu — jest to porównanie, które kompilacja może wykonać na podstawie tego, co złożyła. Dwa stosy nie są porównywane ze sobą. Natomiast to, na co ręcznie zapisana nazwa trafi wśród eksportów już wdrożonych na danym koncie i w danym regionie, jest właściwością wdrożenia, która leży poza zasięgiem jakiegokolwiek wyprowadzania w czasie kompilacji, z powodu opisanego w części Wobec czego nazwa eksportu jest unikatowa i gdzie to się kończy: kompilator nie uwierzytelnia się w AWS, nie odpytuje go i nie może odczytać wyniku innej kompilacji. Nazwa eksportu zapisana jako funkcja wewnętrzna, a nie jako zwykły ciąg znaków, leży po drugiej stronie tej samej granicy — jest rozwiązywana w czasie wdrożenia, a nic tutaj nie wylicza funkcji wewnętrznych, więc kompilacja nie ma żadnej nazwy do porównania.
Kompilacja zostaje zatrzymana także wtedy, gdy wyjście, na którym publikuje połączenie między granicami, zawiera już Export, którego to połączenie nie zapisało. To wyjście provider składa dla udostępnianego klucza odczytywanego przez konsumenta, więc encja Recipe, której blok Outputs: zapisuje wpis pod tym samym kluczem z własnym Export:, umieszcza swój eksport dokładnie tam, gdzie trafia eksport połączenia. O ile nazwa tego eksportu nie jest dokładnie tą, którą wyprowadza provider — wtedy jest to własny eksport połączenia i każdy konsument go importuje — oba nie mogą tam istnieć jednocześnie: zapisanie eksportu połączenia nadpisałoby ręczny eksport, a zachowanie ręcznego eksportu sprawiłoby, że każdy konsument importowałby nazwę, której połączenie nie opublikowało. Komunikat o zatrzymaniu podaje wyprowadzoną nazwę eksportu i cztery części, z których ją zbudowano, oraz informuje, co znaleziono na tym wyjściu: nazwę eksportu deklarowaną przez wpis, nazwę zapisaną jako funkcja wewnętrzna, blok Export: bez żadnej nazwy albo Export: zapisany jako zwykła wartość zamiast bloku. Zatrzymanie usuwa usunięcie bloku Export: tego wpisu — mechanizm połączeń między stosami publikuje wtedy eksport importowany przez każdego konsumenta.
Kolejność wdrażania
Wartość syncWave: granicy encji Release określa kolejność provisioningu stosu, w który ta granica jest składana. Każdy komponent w granicy dziedziczy falę granicy, a gdy kilka granic wskazuje ten sam katalog wyjściowy — więc ich fragmenty są składane w jeden szablon — stos zawiera więcej niż jedną falę, a provider wyraża kolejność między nimi jako DependsOn.
Każdy zasób wskazuje każdy zasób bezpośrednio poprzedzającej fali, która zawiera jakiekolwiek zasoby, i żadnej wcześniejszej fali. Resztę łańcucha tworzy CloudFormation: zasób w fali 2 zależy od fali 1, która zależy od fali 0, więc cała sekwencja jest uporządkowana, a własna lista każdego zasobu ma rozmiar jednej fali, a nie całego stosu. 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 stosu. Najniższa fala nie wskazuje niczego, ponieważ nic jej nie poprzedza.
Czym jest ta kolejność: kolejnością tworzenia, a w odwrotnym kierunku — kolejnością usuwania. CloudFormation operuje na zasobach równolegle, na ile to możliwe, a DependsOn nadpisuje tę równoległość, aby operować na wskazanych zasobach w określonej kolejności. Atrybut obowiązuje w obu kierunkach, więc fala, która tworzy zasób wcześniej, także usuwa go później — poprawna sekwencja demontażu wynika z samej kolejności i nie wymaga niczego więcej.
Nie jest to kolejność gotowości. Szablon stosu nie wyraża pojęcia gotowości zasobu do działania, więc nic tu nie czeka, aż zasób będzie gotowy — jedynie na zakończenie jego tworzenia przez CloudFormation. To istotna różnica w stosunku do tej samej fali w compose, gdzie na usługę deklarującą healthcheck czeka się, aż zgłosi stan zdrowy: compose ma prymityw gotowości, od którego można uzależnić dalsze kroki, a szablon stosu go nie ma. Ten cel oferuje kolejność tworzenia, a jasne stwierdzenie tego jest bardziej przydatne niż zastrzeżenie dołączone do obietnicy, której nie może spełnić.
Napisany przez autora DependsOn jest rozszerzany, nigdy zastępowany. Fragment deklarujący własne ograniczenie kolejności zachowuje je: wpisy, które zapisał, pozostają pierwsze, w kolejności, w jakiej je zapisał, a po nich następują wpisy fali. Oba wymagania obowiązują i żadne nie przesłania drugiego. Odczytywany jest zarówno pojedynczy identyfikator logiczny, jak i lista, a scalona wartość jest emitowana jako lista, czyli jedyna zapisowa forma, która sprawdza się niezależnie od liczby wpisów powstałych ze scalenia.
Stos, którego wszystkie zasoby mają jedną falę, nic na tym nie zyskuje. Podobnie encja Release, która w ogóle nie deklaruje syncWave: każdy element ma domyślną wartość pola 0, złożony szablon zawiera jedną falę, a wynik jest dokładnie taki, jaki byłby, gdyby provider nie wyrażał żadnej kolejności fal.
Kolejności między dwoma stosami nie da się wyrazić i nie jest ona przybliżana. DependsOn wskazuje zasób w tym samym szablonie, a komponenty składane w inny stos znajdują się poza nim. Fala porządkuje więc każdy zasób w stosie, w który jest składana, i nic poza nim. Kolejność dwóch stosów to sprawa operatora, tak samo jak odwołanie między stosami jest rozwiązywane w czasie wdrożenia, a nie w czasie budowania.
Kolejność, której fale nie wyrażają, pozostaje sprawą samego CloudFormation, a odwołania między zasobami już w dużej mierze ją określają: Fn::GetAtt względem zasobu-producenta mówi CloudFormation, aby najpierw utworzył ten zasób. Fragment, który potrzebuje ograniczenia niewynikającego ani z odwołań, ani z fal, sam zapisuje DependsOn — i właśnie ten przypadek zachowuje opisane wyżej scalanie.
Determinizm
Przy tych samych danych wejściowych dostawca generuje w kolejnych uruchomieniach identyczny bajt po bajcie szablon stosu: identyfikatory logiczne, klucze wyjść, nazwy eksportów i kolejność zasobów są w pełni deterministyczne, dzięki czemu różnice w szablonie stosu CloudFormation są czytelne podczas przeglądu GitOps.