Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

CloudFormation-Stack mit Anbindungen

Eine verwaltete Datenbank und die Anwendung, die sie liest, einmal als Entwicklerabsicht verfasst und zu AWS-CloudFormation-Stack-Templates zusammengesetzt. Zwei Anbindungen bringen eigene Ressourcen mit — ein Alarm auf der Datenbank und ein Parameter für gemeinsame Einstellungen auf der Boundary —, daher zeigt dieses Beispiel, wo die Ressourcen einer Anbindung im zusammengesetzten Stack landen und wie sie neben denen der Komponente benannt werden.

Dieselbe Entwicklerabsicht wird auf drei Arten gebaut: als ein Stack, als zwei Stacks mit einer Referenz, die zwischen ihnen verläuft, und — absichtlich — als ein Build, der abbricht.

Die Ausgabeblöcke auf dieser Seite sind aus einem echten Lauf kopiert, gemäß Die Ausgabe auf diesen Seiten lesen.

Dateien

  • aggregate.yaml — Entwicklerabsicht: eine Datenbank payments-db vom Typ core/datastore/mariadb und eine reporting-app vom Typ example/compute/db-reader, die deklariert, dass sie die Datenbank verwendet. Nichts über AWS steht hier. Der Block features: der Datenbank trägt storage-headroom und bindet example/storage-alarm an.
  • release-one-stack.yaml — beide Komponenten in einer Boundary, sodass beide zu einem einzigen Stack zusammengesetzt werden. Bindet core/shared-config an die gesamte Boundary an.
  • release-two-stacks.yaml — dieselbe Absicht, auf zwei Boundaries aufgeteilt, sodass die Referenz der Anwendung auf die Datenbank eine Stack-Grenze überquert.
  • release-negative-name-collision.yaml mit aggregate-name-collision.yaml — soll fehlschlagen. Bindet den Alarm zweimal an eine Komponente an.
  • manifest.yaml — bindet jeden Komponententyp und jedes angebundene Feature an das Recipe, das es auf diesem Ziel implementiert.
  • .aggrega-config.yaml — nennt die Hub-Registry, aus der die Katalogentitäten aufgelöst werden.

Jedes Release bindet den Slot root_password der Datenbank in seinem Eintrag für payments-db mit core/generated-secret. RDS besitzt auf diesem Ziel das Administratorpasswort, und das Datenbank-Recipe, das das Manifest auswählt, trägt die Direktive, die das besagt; damit wird die Bindung zu einer Entscheidung des Operators, im Release geschrieben, und das Aggregate sagt nichts darüber.

Jedes Release bindet außerdem core/backup an payments-db an, mit infra.retention_days: 14, und das Manifest bindet es an cloudformation/backup-native. RDS bewahrt die automatischen Backups der Instanz 7 Tage lang auf, wenn nichts anderes angegeben ist; diese Anbindung bewahrt jedes 14 Tage lang auf. Das FeatureRecipe rendert nichts: Das Backup ist eine Einstellung der Instanz, daher liest das Datenbank-Recipe die Anbindung und schreibt "BackupRetentionPeriod": 14 in die eigenen Properties der Instanz.

Die Entitäten, die dieses Beispiel verwendet, liegen alle im veröffentlichten Katalog. Neben die Release-Dateien wird nichts hineinkopiert, daher wird das Beispiel gegen den Katalog in seinem aktuellen Stand aufgelöst und nicht gegen eine private Momentaufnahme davon.

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd cloudformation-rds-stack

Build

Dieses Beispiel liefert drei Releases mit, nennen Sie also das gewünschte. Pro Lauf wird ein Release gebaut. Der erste Build jedes Release braucht sein Lockfile, das der Pull-Befehl schreibt:

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

Der Build gibt aus, wobei <workspace> für den Ordner dieses Beispiels steht:

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

Der zusammengesetzte Stack landet unter dist/one-stack/cloudformation/cloudformation-stack.json. Jede Komponente und jede Anbindung, die in dieses Verzeichnis rendert, trägt zu dieser einen Vorlage bei — der Provider gibt einen einzigen reinen JSON-Stack aus statt einer Datei pro Beitragendem.

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie nur die Aggrega-Werkzeuge, und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `cloudformation-rds-stack` enthält, rufen Sie das Werkzeug `scaffold` einmal mit `example` auf `cloudformation-rds-stack` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `cloudformation-rds-stack`. Rufen Sie dann das Werkzeug `build` mit `workspace_root` auf `cloudformation-rds-stack`, `release` auf `release-one-stack.yaml`, `auto_pull` auf true und `write` auf true gesetzt auf. Sagen Sie mir, welche Dateien der Build geschrieben hat; sie liegen unter `cloudformation-rds-stack/dist/`.

Was im Stack landet und wer es beigetragen hat

Der Ein-Stack-Build setzt vier Ressourcen von vier verschiedenen Beitragenden zusammen:

RessourceBeigetragen von
PaymentsDbdas eigene Recipe der Datenbankkomponente
PaymentsDbStorageHeadroomdie Anbindung storage-headroom an dieser Komponente
AppSharedConfigdie Anbindung shared-settings an der Boundary
ReportingAppdas eigene Recipe der Anwendungskomponente

Die Anbindung backup an payments-db steht nicht in der Tabelle, weil sie keine eigene Ressource beiträgt: Was sie setzt, landet in PaymentsDb.

Jede Ressource trägt einen Herkunftsblock, der den Beitragenden nennt, von dem sie stammt, sodass die beiden Hälften innerhalb eines Stacks, zu dem beide beigetragen haben, unterscheidbar bleiben:

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

Die beiden Versionseinträge sind die einzigen Zeilen in diesem Block, die sich zwischen Builds ändern, weshalb sie ausgelassen sind; die dritte Auslassung sind lediglich die Properties des Alarms, die unten eigens ausgegeben werden. Alles Gezeigte ist das, was Ihr eigener Build schreibt.

Der Alarm ist die Ressource der Anbindung, nicht die der Datenbank. storage-headroom vom Aggregate zu lösen, entfernt genau diese Ressource und die eine Ausgabe, die sie veröffentlicht, und lässt PaymentsDb Byte für Byte so, wie es war.

Der Ressourcenname einer Anbindung trägt den Geltungsbereich, der die Anbindung trägt

Ein Feature wird einmal verfasst und vielfach angebunden, daher muss der Name, den ein FeatureRecipe ableitet, je Anbindung eindeutig sein. Dieses setzt die Host-Komponente und den Anbindungsnamen zusammen: Host payments-db, getragen unter storage-headroom, ergibt PaymentsDbStorageHeadroom.

Allein den Host einzusetzen, würde genügen, um den Alarm von der Ressource getrennt zu halten, die er überwacht, und nicht genügen, um zu verhindern, dass dasselbe Feature, zweimal an eine Komponente angebunden, mit sich selbst kollidiert — und genau darum geht es im fehlschlagenden Release unten.

Die eigenen Eigenschaften des Alarms adressieren den Host über den abgeleiteten Namen des Hosts:

"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 auf die Datenbankressource löst sich bei der Bereitstellung des Stacks in den Bezeichner dieser Instanz auf. Beide Hälften leiten PaymentsDb aus demselben Komponentennamen ab, und das lässt sie übereinstimmen — hier wird nichts nachgeschlagen.

Wer was entscheidet, an einer einzigen Anbindung

Die Anbindung teilt ihre Eingaben so auf, wie es eine Komponente tut. Wie viel Reserve die Anwendung braucht, ist Entwicklerabsicht, an der Anbindung in aggregate.yaml verfasst — es ist eine Eigenschaft der Anwendung. Wohin der Alarm benachrichtigt und wie lange ein Einbruch anhalten muss, bevor er auslöst, ist Dimensionierung durch den Operator, aus dem Release geliefert:

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

Ein Release liefert infra für eine Anbindung, die das Aggregate deklariert hat, und nie values. Das Zwei-Stack-Release setzt beide; das Ein-Stack-Release setzt keines von beiden, und der Unterschied ist in der Ausgabe ablesbar. Gesetzt:

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

Nicht gesetzt, ist das Feld abwesend statt leer — der Alarm wird ganz ohne Benachrichtigungsaktion emittiert, und EvaluationPeriods fällt auf die 2 zurück, die das Recipe trägt, statt auf irgendetwas, was das Feature deklariert hat. Ein Release, das keines von beiden liefert, erhält dennoch einen funktionierenden Alarm, und eines zu liefern, fügt genau ein Feld hinzu.

Die Ausgaben einer Anbindung werden nach ihrem Host benannt, nicht nach ihr selbst

Die beiden Hälften des Stacks werden nach unterschiedlichen Regeln benannt, und dies ist die Hälfte, die überrascht.

Eine logische Ressourcen-ID stammt aus dem eigenen Recipe der Anbindung — der Name oben. Eine Ausgabe wird nach der veröffentlichenden Komponente und dem Eintrag zusammen benannt, und bei einer Anbindung ist die veröffentlichende Komponente der Host. Der Alarm veröffentlicht einen Eintrag, alarm-id, und er erscheint als:

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

Die beiden Hälften sind lesbar, sobald Sie die Regel kennen: Eine logische ID lässt nur Buchstaben und Ziffern zu, daher schreibt der Provider aus, was dieses Alphabet ablehnt, statt es wegzulassen — Xzh ist der Bindestrich, den Sie geschrieben haben, und XX ist die Stelle, an der der Komponentenname endet und der Eintragsname beginnt. payments-db, das alarm-id veröffentlicht, und nichts anderes erreicht diesen Namen. Namen im zusammengesetzten Stack legt das Schema vollständig dar.

Das ist derselbe Ausgabename, der sich ergeben hätte, wenn die Datenbank selbst alarm-id veröffentlicht hätte. Ein Eintragsname, den auch der Host veröffentlicht, würde also mit dem der Anbindung in einem einzigen Ausgabenamen zusammentreffen — weshalb Eintragsnamen, die sich als die eigenen der Anbindung lesen, sie von denen des Hosts getrennt halten.

Eine Boundary-weite Anbindung wird einmal für die Boundary gerendert

core/shared-config wird im Release angebunden, an der Boundary statt an einer Komponente, und es wird einmal für diese Boundary gerendert — nicht einmal pro Komponente darin. Der Ein-Stack-Build enthält zwei Komponenten und genau ein 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"
},

Bauen Sie das Zwei-Stack-Release, und der Punkt wird deutlicher: Jede Boundary erhält ihr eigenes, das die eigenen aufgelösten Einstellungen dieser Boundary trägt. Die Properties desjenigen in jeder der beiden Vorlagen, die dieser Build schreibt:

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

Es wird im Release angebunden, weil das, was es trägt, die eigene Einrichtung des Operators ist und nichts, was das Aggregate deklariert. Eine Boundary-Anbindung setzt infra: und nie values: — das Aggregate bleibt der Ort, an dem Entwicklerwerte verfasst werden.

Dieselbe Absicht auf zwei Stacks aufteilen

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

In aggregate.yaml ändert sich nichts. Die Anwendung deklariert weiterhin, dass sie die Datenbank verwendet; der Operator entscheidet im Release, dass die beiden getrennt bereitgestellt werden, und die Referenz zwischen ihnen überquert folglich eine Stack-Grenze.

Im Ein-Stack-Build erhält die Anwendung den Endpunkt als Referenz innerhalb der einzigen Vorlage:

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

Im Zwei-Stack-Build veröffentlicht der erzeugende Stack diesen Wert als Export:

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

und der konsumierende Stack liest ihn unter demselben Namen zurück:

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

Nur host trägt einen Export, weil das der Eintrag ist, den eine Kante tatsächlich konsumiert; die anderen veröffentlichten Einträge der Datenbank erscheinen als einfache Ausgaben. Der Alarm mit Komponenten-Geltungsbereich folgt seinem Host in den erzeugenden Stack, und jede Boundary behält ihre eigene Boundary-weite Anbindung.

Keine der beiden intrinsischen Funktionen wird zur Build-Zeit ausgewertet. Der Endpunkt existiert erst, wenn der Stack bereitgestellt wird, daher leitet der Compiler die Referenz durch, und CloudFormation löst sie auf — weshalb die Anwendung nie eine Adresse nennt.

Wie der Exportname gebildet wird und wann der Konsument über Fn::ImportValue statt über einen direkten kontenübergreifenden Lesezugriff liest, siehe Stack-übergreifende Verdrahtung.

Der Build, der abbricht

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

aggregate-name-collision.yaml bindet den Alarm zweimal an eine Komponente an, unter zwei Anbindungsnamen. Der Name der Ressource jeder Anbindung setzt ihren eigenen Anbindungsnamen ein, daher sind die beiden Alarme zwei verschiedene Ressourcen und kollidieren dort nicht. Ihre Ausgaben schon: Jede veröffentlicht alarm-id, eine Ausgabe wird nach der Host-Komponente und dem Eintrag benannt, und der Host ist für beide dieselbe Komponente.

[… 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")

Vier Dinge lassen sich daraus ablesen, und jedes davon ist beabsichtigt.

  • Beide Enden werden genannt. Jeder Eintrag gibt die Komponente und den Anbindungsnamen an, den sie trug, sodass beide in den Dateien, die Sie geschrieben haben, auffindbar sind. Nichts an einer Kollision macht den Namen eines Beitragenden zum beabsichtigten, daher werden beide gemeldet statt nur der erste.
  • Der Schlüsselraum wird genannt. output-logical-ids sagt Ihnen, welcher der beiden Namensräume des Stacks erreicht wurde, und — weil der Namensraum der Ressourcen in diesem Abbruch fehlt — dass die Ressourcennamen in Ordnung waren.
  • Nichts wird emittiert. Der Build hält an, statt einen Stack zu schreiben, in dem einer der beiden Alarme stillschweigend keine Ausgabe hat.
  • Die Ressourcen unterschiedlich zu benennen, behebt diesen Fall nicht. Der Ausgabename wird aus der Host-Komponente und dem Eintrag gebildet, daher ist es der Eintrag, der sich unterscheiden muss — entweder eine Anbindung statt zwei oder ein Feature, dessen veröffentlichte Eintragsnamen sich als die eigenen dieser Anbindung lesen.

Identische Eingabe, identische Ausgabe

Zweimal aus unveränderten Eingaben zu bauen, erzeugt byte-identische Vorlagen. Der Compiler löst keine Live-Daten auf — er ruft nie AWS auf, schlägt nie einen Kontobezeichner nach und führt nie CloudFormation aus —, daher hat ein erneuter Build nichts zu entdecken, was die Bytes verschieben könnte. Das ist die Eigenschaft, auf die sich ein diff-basiertes Review verlässt.

dist/ und die *.lock-Dateien werden erzeugt und nicht committet; sie entstehen neu aus den Dateien, die committet sind.