Stack CloudFormation dengan lampiran
Sebuah basis data terkelola dan aplikasi yang membacanya, ditulis sekali sebagai intensi pengembang dan dirakit menjadi templat stack AWS CloudFormation. Dua lampiran membawa sumber dayanya sendiri — sebuah alarm pada basis data dan sebuah parameter pengaturan bersama pada boundary — sehingga contoh ini menunjukkan di mana sumber daya sebuah lampiran ditempatkan dalam stack yang dirakit dan bagaimana sumber daya tersebut dinamai berdampingan dengan sumber daya milik komponen.
Intensi pengembang yang sama dibangun dengan tiga cara: sebagai satu stack, sebagai dua stack dengan sebuah referensi yang melintas di antara keduanya, dan — secara sengaja — sebagai build yang terhenti.
Blok output di halaman ini disalin dari eksekusi nyata, sesuai dengan Membaca output di halaman-halaman ini.
Berkas
aggregate.yaml— maksud pengembang: sebuah basis datapayments-dbbertipecore/datastore/mariadbdan sebuahreporting-appbertipeexample/compute/db-readeryang menyatakan bahwa ia menggunakan basis data tersebut. Tidak ada hal tentang AWS di sini. Blokfeatures:milik basis data membawastorage-headroom, yang melampirkanexample/storage-alarm.release-one-stack.yaml— kedua komponen berada dalam satu batas, sehingga keduanya dirakit menjadi satu stack. Melampirkancore/shared-configdi seluruh batas.release-two-stacks.yaml— maksud yang sama dipisah ke dua batas, sehingga referensi aplikasi ke basis data melintasi tepi stack.release-negative-name-collision.yamldenganaggregate-name-collision.yaml— diharapkan gagal. Melampirkan alarm dua kali ke satu komponen.manifest.yaml— mengikat setiap tipe komponen dan setiap Feature yang dilampirkan ke Recipe yang mengimplementasikannya pada target ini..aggrega-config.yaml— menyebut registri hub tempat entitas katalog di-resolve.
Setiap rilis mengikat slot root_password milik basis data pada entrinya untuk payments-db, dengan core/generated-secret. RDS memiliki kata sandi administrator pada target ini, dan Recipe basis data yang dipilih Manifest membawa direktif yang menyatakan hal itu; hal ini menjadikan pengikatan tersebut keputusan operator, yang ditulis di Release, dan Aggregate tidak menyebut apa pun tentangnya.
Setiap rilis juga melampirkan core/backup ke payments-db, dengan infra.retention_days: 14, dan Manifest mengikatnya ke cloudformation/backup-native. RDS menyimpan cadangan otomatis instans selama 7 hari jika tidak ada yang menyatakan lain; lampiran ini menyimpan masing-masing selama 14 hari. FeatureRecipe tidak merender apa pun: cadangan adalah pengaturan instans, sehingga Recipe basis data membaca lampiran dan menulis "BackupRetentionPeriod": 14 ke dalam Properties milik instans itu sendiri.
Semua entitas yang digunakan contoh ini berada di katalog yang dipublikasikan. Tidak ada yang disalin ke samping berkas rilis, sehingga contoh ini melakukan resolusi terhadap katalog sebagaimana adanya, bukan terhadap snapshot privatnya.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example cloudformation-rds-stackKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd cloudformation-rds-stackBuild
Contoh ini menyertakan tiga release, jadi sebutkan release yang Anda inginkan. Satu release dibangun per eksekusi. Build pertama setiap release memerlukan lockfile-nya, yang ditulis oleh pull:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlBuild mencetak keluaran berikut, dengan <workspace> mewakili folder contoh ini:
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distStack yang telah dirakit ditempatkan di
dist/one-stack/cloudformation/cloudformation-stack.json. Setiap component dan
setiap attachment yang di-render ke direktori tersebut berkontribusi pada satu templat itu —
provider menghasilkan satu stack JSON murni, bukan satu file per kontributor.
Dengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder workspace belum berisi folder `cloudformation-rds-stack`, panggil alat `scaffold` sekali dengan `example` diatur ke `cloudformation-rds-stack` dan tanpa `dir`: alat ini menulis contoh ke folder `cloudformation-rds-stack` baru. Lalu panggil alat `build` dengan `workspace_root` diatur ke `cloudformation-rds-stack`, `release` diatur ke `release-one-stack.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis build; file tersebut berada di bawah `cloudformation-rds-stack/dist/`.Apa yang dihasilkan, dan siapa yang menyumbangkannya
Build satu stack merakit empat sumber daya dari empat penyumbang yang berbeda:
| Sumber daya | Disumbangkan oleh |
|---|---|
PaymentsDb | Recipe milik komponen basis data itu sendiri |
PaymentsDbStorageHeadroom | lampiran storage-headroom pada komponen tersebut |
AppSharedConfig | lampiran shared-settings pada batas |
ReportingApp | Recipe milik komponen aplikasi itu sendiri |
Lampiran backup pada payments-db tidak ada di tabel karena tidak menyumbangkan sumber daya sendiri: apa yang diaturnya ditempatkan di dalam PaymentsDb.
Setiap sumber daya membawa blok provenans yang menyebutkan penyumbang asalnya, sehingga kedua bagian tetap dapat dibedakan di dalam stack yang disumbang oleh keduanya:
"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" },Kedua entri versi adalah satu-satunya baris dalam blok ini yang berubah antar-build,
itulah sebabnya keduanya dihilangkan; penghilangan ketiga hanyalah Properties milik alarm,
yang dicetak tersendiri di bawah. Semua yang ditampilkan adalah apa yang ditulis oleh build Anda sendiri.
Alarm tersebut adalah sumber daya milik lampiran, bukan milik basis data. Melepaskan
storage-headroom dari Aggregate menghapus tepat sumber daya itu beserta satu
output yang dipublikasikannya, dan membiarkan PaymentsDb tetap sama byte demi byte seperti sebelumnya.
Nama sumber daya sebuah lampiran membawa cakupan yang membawa lampiran tersebut
Sebuah Feature ditulis sekali dan dilampirkan berkali-kali, sehingga nama yang diturunkan oleh FeatureRecipe
harus berbeda untuk setiap lampiran. FeatureRecipe ini menggabungkan komponen host
dan nama lampiran: host payments-db, yang dibawa di bawah storage-headroom,
menghasilkan PaymentsDbStorageHeadroom.
Menggabungkan host saja sudah cukup untuk menjaga alarm agar tidak bertabrakan dengan sumber daya yang dipantaunya, tetapi tidak cukup untuk mencegah Feature yang sama, yang dilampirkan dua kali pada satu komponen, bertabrakan dengan dirinya sendiri — dan itulah yang dibahas oleh release yang gagal di bawah.
Properti alarm itu sendiri merujuk host dengan nama turunan milik host:
"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 pada sumber daya basis data diselesaikan menjadi pengenal instans tersebut saat
stack di-deploy. Kedua bagian menurunkan PaymentsDb dari nama komponen yang sama,
itulah yang membuat keduanya sepakat — tidak ada yang dicari di sini.
Siapa memutuskan apa, pada satu lampiran
Lampiran membagi inputnya dengan cara yang sama seperti komponen. Seberapa besar headroom yang
dibutuhkan aplikasi adalah intensi developer, ditulis pada lampiran di
aggregate.yaml — ini adalah properti aplikasi. Ke mana alarm memberi notifikasi,
dan berapa lama penurunan harus berlangsung sebelum alarm terpicu, adalah penentuan ukuran oleh operator, yang disediakan
dari Release:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Sebuah Release menyediakan infra untuk lampiran yang dideklarasikan oleh Aggregate, dan tidak pernah
values. Release dua stack mengatur keduanya; release satu stack tidak mengatur keduanya, dan
perbedaannya dapat dibaca pada output. Jika diatur:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Jika tidak diatur, field tersebut tidak ada, bukan kosong — alarm dihasilkan tanpa aksi notifikasi sama sekali, dan EvaluationPeriods jatuh ke nilai 2 yang dibawa Recipe, bukan ke apa pun yang dideklarasikan Feature. Release yang tidak menyediakan keduanya tetap mendapatkan alarm yang berfungsi, dan menyediakan salah satunya menambahkan tepat satu field.
Output sebuah lampiran dinamai menurut host-nya, bukan menurut dirinya sendiri
Kedua bagian stack dinamai dengan aturan yang berbeda, dan bagian inilah yang mengejutkan banyak orang.
ID logis sumber daya berasal dari Recipe milik lampiran itu sendiri — nama di atas.
Output dinamai menurut komponen yang memublikasikan dan entrinya sekaligus, dan untuk
lampiran, komponen yang memublikasikan adalah host-nya. Alarm memublikasikan satu
entri, alarm-id, dan entri itu muncul sebagai:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },Kedua bagian dapat dibaca setelah Anda mengetahui aturannya: ID logis hanya menerima huruf
dan angka, sehingga provider mengeja apa yang ditolak alfabet tersebut alih-alih
membuangnya — Xzh adalah tanda hubung yang Anda tulis, dan XX adalah tempat nama komponen
berakhir dan nama entri dimulai. payments-db yang memublikasikan alarm-id, dan
tidak ada yang lain, yang menghasilkan nama itu. Nama dalam stack
yang dirakit menjabarkan
skema tersebut secara lengkap.
Itu adalah nama output yang sama yang akan dihasilkan seandainya basis data itu sendiri
memublikasikan alarm-id. Jadi, nama entri yang juga dipublikasikan oleh host akan bertemu dengan
milik lampiran pada satu nama output — itulah sebabnya nama entri yang terbaca sebagai milik
lampiran itu sendiri menjaganya tetap terpisah dari milik host.
Lampiran selebar batas dirender sekali untuk batas tersebut
core/shared-config dilampirkan di Release, pada batas alih-alih pada sebuah
komponen, dan dirender sekali untuk batas tersebut — bukan sekali per komponen di
dalamnya. Build satu stack memuat dua komponen dan tepat satu 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" },Lakukan build release dua stack dan intinya menjadi lebih jelas: setiap batas mendapatkan miliknya sendiri,
yang membawa pengaturan terselesaikan milik batas itu sendiri. Properties dari masing-masing pada
kedua template yang ditulis build tersebut:
"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" },Lampiran ini dilampirkan di Release karena apa yang dibawanya adalah pengaturan milik operator sendiri,
bukan sesuatu yang dideklarasikan Aggregate. Lampiran batas
mengatur infra: dan tidak pernah values: — Aggregate tetap menjadi tempat nilai developer
ditulis.
Memisahkan intent yang sama ke dua stack
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlTidak ada yang berubah di aggregate.yaml. Aplikasi tetap mendeklarasikan bahwa ia menggunakan
database; operator memutuskan di Release bahwa keduanya diprovisikan
secara terpisah, dan akibatnya referensi di antara keduanya melintasi batas stack.
Dalam build satu stack, aplikasi menerima endpoint sebagai referensi di dalam satu template:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },Dalam build dua stack, stack produsen menerbitkan nilai tersebut sebagai export:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },dan stack konsumen membacanya kembali dengan nama yang sama:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Hanya host yang membawa Export, karena itulah entri yang benar-benar dikonsumsi oleh sebuah edge;
entri lain yang diterbitkan database muncul sebagai output biasa.
Alarm dengan cakupan komponen mengikuti host-nya ke stack produsen, dan setiap batas
mempertahankan attachment-nya sendiri yang berlaku untuk seluruh batas.
Tidak satu pun intrinsik dievaluasi pada waktu build. Endpoint belum ada hingga stack di-deploy, sehingga compiler meneruskan referensi tersebut dan CloudFormation yang me-resolve-nya — itulah sebabnya aplikasi tidak pernah menyebutkan alamat.
Untuk cara nama export dibangun, dan kapan konsumen membaca melalui
Fn::ImportValue alih-alih pembacaan lintas akun secara langsung, lihat
Pengkabelan lintas stack.
Build yang berhenti
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml melampirkan alarm dua kali ke satu komponen,
dengan dua nama lampiran. Nama sumber daya setiap lampiran menyusun nama lampirannya
sendiri, sehingga kedua alarm itu adalah dua sumber daya yang berbeda dan tidak bertabrakan
di sana. Output keduanya bertabrakan: masing-masing menerbitkan alarm-id, sebuah output dinamai menurut
komponen host dan entri, dan host-nya adalah komponen yang sama untuk keduanya.
[… 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")Ada empat hal yang dapat dibaca dari situ, dan masing-masing disengaja.
- Kedua ujung disebutkan namanya. Setiap entri menyebutkan komponen dan nama lampiran yang dibawanya, sehingga keduanya dapat dicari dalam file yang Anda tulis. Tidak ada hal dalam sebuah tabrakan yang menjadikan nama salah satu kontributor sebagai nama yang dimaksud, sehingga keduanya dilaporkan, bukan hanya yang pertama.
- Ruang kunci disebutkan namanya.
output-logical-idsmemberi tahu Anda ruang nama mana dari dua ruang nama stack yang tercapai, dan — karena ruang nama sumber daya tidak ada dalam penghentian ini — bahwa nama-nama sumber daya tidak bermasalah. - Tidak ada yang dihasilkan. Build berhenti alih-alih menulis stack yang salah satu dari kedua alarmnya diam-diam tidak memiliki output.
- Membedakan nama sumber daya tidak memperbaiki masalah ini. Nama output dibangun dari komponen host dan entri, sehingga entri-lah yang harus berbeda — entah satu lampiran alih-alih dua, atau sebuah Feature yang nama entri terbitannya terbaca sebagai milik lampiran itu sendiri.
Input identik, output identik
Membangun dua kali dari input yang tidak berubah menghasilkan templat yang identik byte demi byte. Compiler tidak me-resolve data langsung apa pun — compiler tidak pernah memanggil AWS, tidak pernah mencari pengenal akun, dan tidak pernah menjalankan CloudFormation — sehingga build ulang tidak memiliki apa pun untuk ditemukan yang dapat mengubah byte tersebut. Itulah sifat yang diandalkan oleh peninjauan berbasis diff.
dist/ dan file *.lock dihasilkan secara otomatis dan tidak di-commit; keduanya
dihasilkan ulang dari file yang di-commit.