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

Stos CloudFormation z dołączeniami

Zarządzana baza danych i odczytująca ją aplikacja, opisane raz jako intencja programisty i złożone w szablony stosów AWS CloudFormation. Dwa dołączenia wnoszą własne zasoby — alarm na bazie danych i parametr wspólnych ustawień na granicy — dlatego ten przykład pokazuje, gdzie zasoby dołączenia trafiają w złożonym stosie i jak są nazywane obok zasobów komponentu.

Ta sama intencja programisty jest budowana na trzy sposoby: jako jeden stos, jako dwa stosy z odwołaniem przechodzącym między nimi oraz — celowo — jako budowanie, które zostaje zatrzymane.

Bloki wyjścia na tej stronie są skopiowane z rzeczywistego uruchomienia, zgodnie z Odczytywanie wyjścia na tych stronach.

Pliki

  • aggregate.yaml — intencja dewelopera: baza danych payments-db typu core/datastore/mariadb oraz reporting-app typu example/compute/db-reader, który deklaruje, że korzysta z tej bazy danych. Nic dotyczącego AWS się tu nie znajduje. Blok features: bazy danych zawiera storage-headroom, dołączając example/storage-alarm.
  • release-one-stack.yaml — oba komponenty w jednej granicy, więc oba są składane w jeden stos. Dołącza core/shared-config w całej granicy.
  • release-two-stacks.yaml — ta sama intencja podzielona między dwie granice, więc odwołanie aplikacji do bazy danych przekracza krawędź stosu.
  • release-negative-name-collision.yaml wraz z aggregate-name-collision.yaml — oczekiwane niepowodzenie. Dołącza alarm dwukrotnie do jednego komponentu.
  • manifest.yaml — wiąże każdy typ komponentu i każdy dołączony Feature z encją Recipe, która implementuje go na tym celu.
  • .aggrega-config.yaml — wskazuje rejestr hub, z którego rozwiązywane są encje katalogu.

Każde wydanie wiąże slot root_password bazy danych w swoim wpisie dla payments-db, za pomocą core/generated-secret. Na tym celu hasłem administratora zarządza RDS, a encja Recipe bazy danych wybrana przez Manifest zawiera dyrektywę, która to stwierdza; dzięki temu powiązanie jest decyzją operatora, zapisaną w encji Release, a Aggregate nic o nim nie mówi.

Każde wydanie dołącza też core/backup do payments-db, z infra.retention_days: 14, a Manifest wiąże je z cloudformation/backup-native. Jeśli nic nie wskazuje inaczej, RDS przechowuje automatyczne kopie zapasowe instancji przez 7 dni; to dołączenie przechowuje każdą przez 14. Encja FeatureRecipe niczego nie renderuje: kopia zapasowa jest ustawieniem instancji, więc encja Recipe bazy danych odczytuje dołączenie i zapisuje "BackupRetentionPeriod": 14 we własnych Properties instancji.

Wszystkie encje używane w tym przykładzie znajdują się w opublikowanym katalogu. Nic nie jest kopiowane obok plików wydań, więc przykład jest rozwiązywany względem katalogu w jego bieżącym stanie, a nie względem jego prywatnej migawki.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

Terminal window
aggrega scaffold --example cloudformation-rds-stack

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd cloudformation-rds-stack

Kompilacja

Ten przykład zawiera trzy wydania, więc należy wskazać to, które ma zostać zbudowane. W jednym uruchomieniu buduje się jedno wydanie. Pierwsza kompilacja każdego wydania wymaga jego pliku blokady, który zapisuje pull:

Terminal window
aggrega pull --release release-one-stack.yaml
aggrega build --release release-one-stack.yaml

Budowanie wypisuje (<workspace> oznacza folder tego przykładu):

Total build time: 4.1s
Build completed: 1 file written to <workspace>/dist

Złożony stos trafia do dist/one-stack/cloudformation/cloudformation-stack.json. Każdy komponent i każde dołączenie renderujące się do tego katalogu wnosi swój wkład do tego jednego szablonu — dostawca emituje pojedynczy stos w czystym JSON zamiast osobnego pliku dla każdego współtwórcy.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i sam nie twórz żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `cloudformation-rds-stack`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `cloudformation-rds-stack` i bez `dir`: zapisze ono przykład do nowego folderu `cloudformation-rds-stack`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `cloudformation-rds-stack`, `release` ustawionym na `release-one-stack.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisała kompilacja; znajdują się w `cloudformation-rds-stack/dist/`.

Co trafia do wyniku i kto to dostarczył

Kompilacja jednego stosu składa cztery zasoby od czterech różnych dostawców:

ZasóbDostarczony przez
PaymentsDbwłasną encję Recipe komponentu bazy danych
PaymentsDbStorageHeadroomdołączenie storage-headroom na tym komponencie
AppSharedConfigdołączenie shared-settings na granicy
ReportingAppwłasną encję Recipe komponentu aplikacji

Dołączenia backup na payments-db nie ma w tabeli, ponieważ nie wnosi ono własnego zasobu: to, co ustawia, trafia do wnętrza PaymentsDb.

Każdy zasób zawiera blok pochodzenia wskazujący, od kogo pochodzi, dzięki czemu obie części pozostają rozróżnialne w stosie, do którego obie się przyczyniły:

"PaymentsDbStorageHeadroom": {
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/aggregate-name": "aggregate",
"aggrega.ai/boundary-path": "app",
[… omitted: a compiler-version entry, which moves with the build]
"aggrega.ai/component-id": "cfr--payments-db--storage-headroom",
"aggrega.ai/environment": "production",
"aggrega.ai/provider": "cloudformation",
[… omitted: a provider-version entry, which moves with the build]
"aggrega.ai/recipe-uri": "storage-alarm:1.0.0"
}
},
[… omitted: the alarm's Properties, printed in full just below]
"Type": "AWS::CloudWatch::Alarm"
},

Dwa wpisy wersji to jedyne wiersze tego bloku, które zmieniają się między kompilacjami, dlatego je pominięto; trzecie pominięcie to po prostu Properties alarmu, wydrukowane osobno poniżej. Wszystko, co pokazano, zapisuje również własna kompilacja.

Alarm jest zasobem dołączenia, a nie bazy danych. Odłączenie storage-headroom od encji Aggregate usuwa dokładnie ten zasób i jedno publikowane przez niego wyjście, a PaymentsDb pozostawia bajt w bajt bez zmian.

Nazwa zasobu dołączenia zawiera zakres, który niesie dołączenie

Encja Feature jest tworzona raz i dołączana wiele razy, więc nazwa wyprowadzana przez FeatureRecipe musi być unikalna dla każdego dołączenia. Ta składa komponent hosta i nazwę dołączenia: host payments-db, dołączony pod storage-headroom, daje PaymentsDbStorageHeadroom.

Złożenie samego hosta wystarczyłoby, by alarm nie kolidował z obserwowanym zasobem, ale nie wystarczyłoby, by ta sama encja Feature dołączona dwa razy do jednego komponentu nie kolidowała sama ze sobą — i tego dotyczy niżej opisane wydanie, które kończy się błędem.

Własne właściwości alarmu odwołują się do hosta przez jego wyprowadzoną nazwę:

"Properties": {
"AlarmDescription": "Free storage below 21474836480 bytes on payments-db",
"ComparisonOperator": "LessThanThreshold",
"Dimensions": [
{
"Name": "DBInstanceIdentifier",
"Value": {
"Ref": "PaymentsDb"
}
}
],
"EvaluationPeriods": 2,
"MetricName": "FreeStorageSpace",
"Namespace": "AWS/RDS",
"Period": 300,
"Statistic": "Minimum",
"Threshold": 21474836480,
"TreatMissingData": "breaching"
},

Ref na zasobie bazy danych rozwiązuje się do identyfikatora tej instancji podczas wdrażania stosu. Obie części wyprowadzają PaymentsDb z tej samej nazwy komponentu i dlatego są zgodne — niczego tu się nie wyszukuje.

Kto decyduje o czym w jednym dołączeniu

Dołączenie dzieli swoje dane wejściowe tak jak komponent. Ile zapasu potrzebuje aplikacja, to intencja dewelopera, zapisana w dołączeniu w aggregate.yaml — to właściwość aplikacji. Dokąd alarm wysyła powiadomienia i jak długo spadek musi trwać, zanim alarm się uruchomi, to wymiarowanie operatora, dostarczane z encji Release:

payments-db:
features:
storage-headroom:
infra:
evaluation_periods: 3
notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"

Encja Release dostarcza infra dla dołączenia zadeklarowanego w encji Aggregate, nigdy values. Wydanie dwóch stosów ustawia oba pola; wydanie jednego stosu żadnego, a różnicę widać w wyniku. Ustawione:

"Properties": {
"AlarmActions": [
"arn:aws:sns:eu-west-1:123456789012:payments-oncall"
],

Nieustawione pole jest nieobecne, a nie puste — alarm jest emitowany bez jakiejkolwiek akcji powiadomienia, a EvaluationPeriods przyjmuje wartość 2 zapisaną w encji Recipe, a nie cokolwiek zadeklarowanego w encji Feature. Encja Release, która nie dostarcza żadnego z nich, nadal otrzymuje działający alarm, a dostarczenie jednego dodaje dokładnie jedno pole.

Wyjścia dołączenia są nazywane od jego hosta, a nie od niego samego

Dwie części stosu są nazywane według różnych reguł i to ta część zaskakuje ludzi.

Logiczny identyfikator zasobu pochodzi z własnej encji Recipe dołączenia — to nazwa podana wyżej. Wyjście jest nazywane od publikującego komponentu i wpisu łącznie, a w przypadku dołączenia publikującym komponentem jest host. Alarm publikuje jeden wpis, alarm-id, który pojawia się jako:

"paymentsXzhdbXXalarmXzhid": {
"Value": {
"Ref": "PaymentsDbStorageHeadroom"
}
},

Obie części dają się odczytać, gdy zna się regułę: identyfikator logiczny dopuszcza tylko litery i cyfry, więc dostawca zapisuje słownie to, czego ten alfabet nie przyjmuje, zamiast to pomijać — Xzh to wpisany łącznik, a XX to miejsce, gdzie kończy się nazwa komponentu i zaczyna nazwa wpisu. Do tej nazwy prowadzi payments-db publikujący alarm-id i nic innego. Nazwy w złożonym stosie opisują ten schemat w całości.

To ta sama nazwa wyjścia, jaką uzyskałaby baza danych, gdyby sama opublikowała alarm-id. Nazwa wpisu, którą publikuje również host, spotkałaby się więc z wpisem dołączenia w jednej nazwie wyjścia — dlatego nazwy wpisów brzmiące jak własne nazwy dołączenia nie kolidują z nazwami hosta.

Dołączenie obejmujące całą granicę renderuje się raz dla granicy

core/shared-config jest dołączony w encji Release, na granicy, a nie na komponencie, i renderuje się raz dla tej granicy — nie raz na każdy komponent w niej. Kompilacja jednego stosu zawiera dwa komponenty i dokładnie jeden AppSharedConfig:

"AppSharedConfig": {
[… omitted: the provenance Metadata, whose shape is shown above]
"Properties": {
"Description": "Settings shared by every component in the app boundary",
"Name": "/app/shared-config",
"Type": "String",
"Value": "tier=production"
},
"Type": "AWS::SSM::Parameter"
},

Po skompilowaniu wydania dwóch stosów widać to wyraźniej: każda granica dostaje własny, z własnymi rozwiązanymi ustawieniami tej granicy. Properties tego zasobu w każdym z dwóch szablonów zapisywanych przez tę kompilację:

"Properties": {
"Description": "Settings shared by every component in the data boundary",
"Name": "/data/shared-config",
"Type": "String",
"Value": "tier=production-data"
},
"Properties": {
"Description": "Settings shared by every component in the app boundary",
"Name": "/app/shared-config",
"Type": "String",
"Value": "tier=production-app"
},

Jest dołączony w encji Release, ponieważ to, co niesie, jest własnym układem operatora, a nie czymkolwiek, co deklaruje encja Aggregate. Dołączenie na granicy ustawia infra:, a nigdy values: — encja Aggregate pozostaje miejscem, w którym tworzy się wartości dewelopera.

Rozdzielenie tej samej intencji na dwa stosy

Terminal window
aggrega pull --release release-two-stacks.yaml
aggrega build --release release-two-stacks.yaml

W aggregate.yaml nic się nie zmienia. Aplikacja nadal deklaruje, że korzysta z bazy danych; to operator decyduje w encji Release, że obie są provisionowane oddzielnie, a w efekcie referencja między nimi przekracza krawędź stosu.

W kompilacji z jednym stosem aplikacja otrzymuje endpoint jako referencję wewnątrz jedynego szablonu:

"Properties": {
"Name": "/reporting/db-host",
"Tier": "Standard",
"Type": "String",
"Value": {
"Fn::GetAtt": [
"PaymentsDb",
"Endpoint.Address"
]
}
},

W kompilacji z dwoma stosami stos producenta publikuje tę wartość jako eksport:

"paymentsXzhdbXXhost": {
"Value": {
"Fn::GetAtt": [
"PaymentsDb",
"Endpoint.Address"
]
},
"Export": {
"Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"
}
},

a stos konsumenta odczytuje ją pod tą samą nazwą:

"Properties": {
"Name": "/reporting/db-host",
"Tier": "Standard",
"Type": "String",
"Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"}
},

Tylko host ma Export, ponieważ to jest wpis, który krawędź faktycznie konsumuje; pozostałe opublikowane wpisy bazy danych pojawiają się jako zwykłe wyjścia. Alarm w zakresie komponentu podąża za swoim hostem do stosu producenta, a każda granica zachowuje własne dołączenie obejmujące całą granicę.

Żadna z funkcji wewnętrznych nie jest wyliczana w czasie kompilacji. Endpoint nie istnieje, dopóki stos nie zostanie wdrożony, więc kompilator przekazuje referencję dalej, a CloudFormation ją rozwiązuje — dlatego aplikacja nigdy nie podaje adresu.

Informacje o tym, jak budowana jest nazwa eksportu i kiedy konsument odczytuje wartość przez Fn::ImportValue zamiast bezpośredniego odczytu między kontami, zawiera sekcja Połączenia między stosami.

Kompilacja, która się zatrzymuje

Terminal window
aggrega pull --release release-negative-name-collision.yaml
aggrega build --release release-negative-name-collision.yaml

aggregate-name-collision.yaml dołącza alarm dwukrotnie do jednego komponentu, pod dwiema nazwami dołączeń. Nazwa zasobu każdego dołączenia zawiera jego własną nazwę dołączenia, więc oba alarmy są dwoma odrębnymi zasobami i w tym miejscu nie kolidują. Kolidują ich wyjścia: każde publikuje alarm-id, wyjście jest nazywane od komponentu-hosta i wpisu, a hostem obu jest ten sam komponent.

[… omitted: the pull's lines, which report the same collision while writing the lockfile]
[TRANSLATION_ERROR E0038]
dispatch groups whose contributors derive one name more than once in one key space
caused by (2):
[TRANSLATION_ERROR] release-negative-name-collision.yaml
derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation")
---
[TRANSLATION_ERROR] release-negative-name-collision.yaml
derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")

Można z tego odczytać cztery rzeczy i każda z nich jest zamierzona.

  • Nazwane są obie strony. Każdy wpis podaje komponent oraz nazwę dołączenia, które przenosił, więc obie można wyszukać w napisanych plikach. Nic w kolizji nie czyni nazwy jednego z autorów tą zamierzoną, dlatego zgłaszane są obie, a nie tylko pierwsza.
  • Nazwana jest przestrzeń kluczy. output-logical-ids wskazuje, która z dwóch przestrzeni nazw stosu została osiągnięta, oraz — ponieważ przestrzeni nazw zasobów brak w tym zatrzymaniu — że nazwy zasobów były poprawne.
  • Nic nie jest emitowane. Kompilacja zatrzymuje się, zamiast zapisać stos, w którym jeden z dwóch alarmów po cichu nie ma wyjścia.
  • Rozróżnienie nazw zasobów tego nie naprawia. Nazwa wyjścia jest budowana z komponentu-hosta i wpisu, więc to wpis musi się różnić — albo jedno dołączenie zamiast dwóch, albo encja Feature, której nazwy publikowanych wpisów odczytuje się jako własne nazwy tego dołączenia.

Identyczne wejście, identyczne wyjście

Dwukrotne budowanie z niezmienionych danych wejściowych daje szablony identyczne co do bajtu. Kompilator nie rozwiązuje żadnych danych na żywo — nigdy nie wywołuje AWS, nigdy nie wyszukuje identyfikatora konta i nigdy nie uruchamia CloudFormation — więc ponowne budowanie nie może odkryć niczego, co zmieniłoby bajty. Na tej właściwości opiera się przegląd oparty na porównywaniu różnic.

Katalog dist/ i pliki *.lock są generowane i nie są commitowane; można je wygenerować ponownie z plików, które są commitowane.