Stack CloudFormation với các attachment
Một cơ sở dữ liệu được quản lý và ứng dụng đọc nó, được viết một lần dưới dạng ý định của nhà phát triển và được lắp ráp thành các template stack AWS CloudFormation. Hai attachment đem theo các tài nguyên riêng của chúng — một alarm trên cơ sở dữ liệu và một tham số thiết lập dùng chung trên boundary — vì vậy ví dụ này cho thấy tài nguyên của một attachment nằm ở đâu trong stack đã lắp ráp và chúng được đặt tên như thế nào bên cạnh tài nguyên của component.
Cùng một ý định của nhà phát triển được build theo ba cách: thành một stack, thành hai stack với một tham chiếu đi qua giữa chúng, và — một cách có chủ ý — thành một lần build bị dừng.
Các khối output trên trang này được sao chép từ một lần chạy thật, theo Đọc output trên các trang này.
Các tệp
aggregate.yaml— ý định của nhà phát triển: một cơ sở dữ liệupayments-dbthuộc loạicore/datastore/mariadbvà mộtreporting-appthuộc loạiexample/compute/db-readerkhai báo rằng nó sử dụng cơ sở dữ liệu đó. Không có gì về AWS nằm ở đây. Khốifeatures:của cơ sở dữ liệu mangstorage-headroom, gắnexample/storage-alarm.release-one-stack.yaml— cả hai component trong một ranh giới, nên cả hai được lắp ráp thành một stack duy nhất. Gắncore/shared-configtrên toàn ranh giới.release-two-stacks.yaml— cùng ý định đó được chia qua hai ranh giới, nên tham chiếu của ứng dụng tới cơ sở dữ liệu vượt qua một cạnh stack.release-negative-name-collision.yamlcùng vớiaggregate-name-collision.yaml— dự kiến sẽ thất bại. Gắn cảnh báo hai lần vào một component.manifest.yaml— liên kết mỗi loại component và mỗi Feature được gắn với Recipe triển khai nó trên đích này..aggrega-config.yaml— chỉ định registry của hub mà các thực thể catalog được phân giải từ đó.
Mỗi release liên kết slot root_password của cơ sở dữ liệu trên mục của nó cho payments-db, bằng core/generated-secret. RDS sở hữu mật khẩu quản trị viên trên đích này, và Recipe cơ sở dữ liệu mà Manifest chọn mang chỉ thị nói lên điều đó; điều này khiến việc liên kết là một quyết định của người vận hành, được viết trong Release, và Aggregate không nói gì về nó.
Mỗi release cũng gắn core/backup vào payments-db, với infra.retention_days: 14, và Manifest liên kết nó với cloudformation/backup-native. RDS giữ các bản sao lưu tự động của instance trong 7 ngày khi không có gì quy định khác; attachment này giữ mỗi bản trong 14 ngày. FeatureRecipe không render gì cả: bản sao lưu là một thiết lập của instance, nên Recipe cơ sở dữ liệu đọc attachment và ghi "BackupRetentionPeriod": 14 vào chính Properties của instance.
Các thực thể mà ví dụ này sử dụng đều nằm trong catalog đã công bố. Không có gì được sao chép vào bên cạnh các tệp release, nên ví dụ phân giải dựa trên catalog như hiện trạng của nó thay vì dựa trên một bản snapshot riêng của nó.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example cloudformation-rds-stackSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd cloudformation-rds-stackBuild
Ví dụ này đi kèm ba release, vì vậy hãy chỉ định release bạn muốn. Mỗi lần chạy chỉ build một release. Lần build đầu tiên của mỗi release cần lockfile của nó, do lệnh pull ghi ra:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlBản build in ra như sau, với <workspace> đại diện cho thư mục của ví dụ này:
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distStack đã được lắp ráp nằm tại
dist/one-stack/cloudformation/cloudformation-stack.json. Mọi component và
mọi attachment render vào thư mục đó đều đóng góp vào cùng một template đó —
provider xuất ra một stack JSON thuần duy nhất thay vì một tệp cho mỗi bên đóng góp.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ dùng các công cụ của Aggrega, và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `cloudformation-rds-stack`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `cloudformation-rds-stack` và không có `dir`: nó ghi ví dụ vào một thư mục `cloudformation-rds-stack` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `cloudformation-rds-stack`, `release` đặt thành `release-one-stack.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Cho tôi biết bản build đã ghi những tệp nào; chúng nằm dưới `cloudformation-rds-stack/dist/`.Những gì được tạo ra và ai đóng góp
Bản build một stack lắp ráp bốn tài nguyên từ bốn bên đóng góp khác nhau:
| Tài nguyên | Đóng góp bởi |
|---|---|
PaymentsDb | Recipe riêng của component cơ sở dữ liệu |
PaymentsDbStorageHeadroom | attachment storage-headroom trên component đó |
AppSharedConfig | attachment shared-settings trên boundary |
ReportingApp | Recipe riêng của component ứng dụng |
Attachment backup trên payments-db không có trong bảng vì nó không đóng góp tài nguyên riêng nào: những gì nó thiết lập nằm bên trong PaymentsDb.
Mỗi tài nguyên mang một khối nguồn gốc nêu tên bên đóng góp đã tạo ra nó, nhờ đó hai nửa vẫn phân biệt được bên trong một stack mà cả hai cùng đóng góp:
"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" },Hai mục phiên bản là những dòng duy nhất trong khối này thay đổi giữa các
bản build, đó là lý do chúng bị lược bỏ; phần lược bỏ thứ ba chỉ là
Properties của alarm, được in riêng bên dưới. Mọi thứ hiển thị đều là những gì bản build của
bạn ghi ra.
Alarm là tài nguyên của attachment, không phải của cơ sở dữ liệu. Tách
storage-headroom khỏi Aggregate sẽ xóa đúng tài nguyên đó và một
output mà nó công bố, đồng thời giữ nguyên PaymentsDb đến từng byte.
Tên tài nguyên của một attachment mang theo phạm vi chứa attachment đó
Một Feature được viết một lần và gắn nhiều lần, nên tên mà một FeatureRecipe
suy ra phải khác nhau cho mỗi attachment. FeatureRecipe này ghép component chủ
và tên attachment: chủ payments-db, được gắn dưới storage-headroom,
cho ra PaymentsDbStorageHeadroom.
Chỉ ghép component chủ thôi là đủ để alarm không trùng với tài nguyên mà nó giám sát, nhưng không đủ để cùng một Feature gắn hai lần vào một component không xung đột với chính nó — đó chính là nội dung của release thất bại bên dưới.
Các thuộc tính riêng của alarm tham chiếu đến chủ bằng tên suy ra của chủ:
"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 trên tài nguyên cơ sở dữ liệu được phân giải thành định danh của instance đó khi
stack được triển khai. Cả hai nửa đều suy ra PaymentsDb từ cùng một tên component,
đó là điều khiến chúng khớp nhau — không có gì ở đây được tra cứu.
Ai quyết định điều gì, trên một attachment
Attachment chia đầu vào theo cách một component làm. Ứng dụng cần bao nhiêu dung lượng dự phòng là ý định của nhà phát triển, được viết trên attachment trong
aggregate.yaml — đó là một thuộc tính của ứng dụng. Alarm thông báo đến đâu,
và mức sụt giảm phải kéo dài bao lâu trước khi alarm kích hoạt, là định cỡ của người vận hành, được cung cấp
từ Release:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Một Release cung cấp infra cho một attachment mà Aggregate đã khai báo, và không bao giờ cung cấp
values. Release hai stack đặt cả hai; release một stack không đặt cái nào, và
sự khác biệt đọc được trong output. Khi đặt:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Khi không đặt, trường này vắng mặt thay vì rỗng — alarm được tạo ra mà hoàn toàn không có hành động thông báo nào, và EvaluationPeriods lấy giá trị 2 mà Recipe mang thay vì bất cứ giá trị nào Feature đã khai báo. Một Release không cung cấp cái nào vẫn có một alarm hoạt động được, và cung cấp một cái chỉ thêm đúng một trường.
Các output của một attachment được đặt tên theo chủ của nó, không theo chính nó
Hai nửa của stack được đặt tên theo các quy tắc khác nhau, và đây là nửa khiến mọi người bất ngờ.
Logical ID của tài nguyên đến từ Recipe riêng của attachment — tên ở trên.
Một output được đặt tên theo cả component công bố lẫn mục, và với
một attachment thì component công bố là chủ. Alarm công bố một
mục, alarm-id, và nó xuất hiện dưới dạng:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },Hai nửa trở nên dễ đọc khi bạn biết quy tắc: logical ID chỉ chấp nhận chữ cái
và chữ số, nên provider viết ra những gì bảng chữ cái đó từ chối thay vì
bỏ chúng đi — Xzh là dấu gạch nối bạn đã viết, và XX là chỗ tên component
kết thúc và tên mục bắt đầu. payments-db công bố alarm-id, và
không gì khác, mới tạo ra tên đó. Tên trong stack
đã lắp ráp trình bày
đầy đủ lược đồ này.
Đó cũng chính là tên output mà nó sẽ có nếu chính cơ sở dữ liệu
công bố alarm-id. Vì vậy một tên mục mà chủ cũng công bố sẽ trùng với tên của
attachment tại một tên output — đó là lý do các tên mục mang nghĩa riêng của
attachment giúp chúng không trùng với tên của chủ.
Một attachment toàn boundary được render một lần cho boundary
core/shared-config được gắn trong Release, trên boundary thay vì trên một
component, và nó được render một lần cho boundary đó — không phải một lần cho mỗi component trong
đó. Bản build một stack chứa hai component và đúng một 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" },Hãy build release hai stack và điểm này càng rõ hơn: mỗi boundary có cái riêng của mình,
mang các thiết lập đã phân giải của riêng boundary đó. Properties của cái nằm trong
mỗi template trong hai template mà bản build đó ghi ra:
"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" },Nó được gắn trong Release vì những gì nó mang là sự sắp đặt riêng của người vận hành
chứ không phải bất cứ thứ gì Aggregate khai báo. Một attachment boundary
đặt infra: và không bao giờ đặt values: — Aggregate vẫn là nơi các giá trị của nhà phát triển
được viết.
Chia cùng một ý định ra hai stack
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlKhông có gì trong aggregate.yaml thay đổi. Ứng dụng vẫn khai báo rằng nó sử dụng
cơ sở dữ liệu; người vận hành quyết định trong Release rằng hai thành phần được cấp phát
riêng biệt, và do đó tham chiếu giữa chúng đi qua ranh giới giữa các stack.
Trong bản build một stack, ứng dụng nhận endpoint dưới dạng một tham chiếu bên trong template duy nhất:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },Trong bản build hai stack, stack cung cấp công bố giá trị đó dưới dạng một export:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },và stack tiêu thụ đọc lại nó theo đúng tên đó:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Chỉ host mang một Export, vì đó là mục mà một cạnh thực sự
tiêu thụ; các mục được công bố khác của cơ sở dữ liệu xuất hiện dưới dạng output thông thường. Cảnh báo
ở phạm vi component đi theo host của nó vào stack cung cấp, và mỗi ranh giới
giữ attachment trên toàn ranh giới của riêng nó.
Không hàm intrinsic nào được đánh giá lúc build. Endpoint chưa tồn tại cho đến khi stack được triển khai, nên trình biên dịch chuyển tiếp tham chiếu và CloudFormation phân giải nó — đó là lý do ứng dụng không bao giờ nêu tên một địa chỉ.
Để biết tên export được xây dựng thế nào, và khi nào stack tiêu thụ đọc qua
Fn::ImportValue thay vì đọc trực tiếp giữa các tài khoản, xem
Kết nối giữa các stack.
Bản build bị dừng
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml gắn cảnh báo hai lần vào một component,
dưới hai tên attachment. Tên tài nguyên của mỗi attachment được ghép từ chính
tên attachment của nó, nên hai cảnh báo là hai tài nguyên riêng biệt và không xung đột
ở đó. Đầu ra của chúng thì có: mỗi cái đều công bố alarm-id, một đầu ra được đặt tên theo
component chủ và mục, và component chủ là cùng một component cho cả hai.
[… 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")Có bốn điều cần đọc ra từ đó, và mỗi điều đều có chủ ý.
- Cả hai phía đều được nêu tên. Mỗi mục nêu component và tên attachment mà nó đang mang, nên cả hai đều tìm được trong các tệp bạn đã viết. Không có gì trong một xung đột khiến tên của một bên đóng góp là tên được dự định, nên cả hai đều được báo cáo thay vì chỉ bên đầu tiên.
- Không gian khóa được nêu tên.
output-logical-idscho bạn biết không gian tên nào trong hai không gian tên của stack đã bị chạm tới, và — vì không gian tên tài nguyên không có mặt trong lần dừng này — rằng các tên tài nguyên không có vấn đề gì. - Không có gì được xuất ra. Bản build dừng lại thay vì viết ra một stack trong đó một trong hai cảnh báo âm thầm không có đầu ra.
- Đặt tên khác nhau cho các tài nguyên không khắc phục được lỗi này. Tên đầu ra được tạo từ component chủ và mục, nên chính mục mới là thứ phải khác nhau — hoặc một attachment thay vì hai, hoặc một Feature có tên các mục được công bố đọc như của riêng attachment đó.
Đầu vào giống hệt, đầu ra giống hệt
Build hai lần từ các đầu vào không thay đổi sẽ tạo ra các template giống hệt nhau đến từng byte. Trình biên dịch không phân giải dữ liệu trực tiếp nào — nó không bao giờ gọi AWS, không bao giờ tra cứu mã định danh tài khoản, và không bao giờ chạy CloudFormation — nên một lần build lại không có gì để phát hiện mà có thể làm thay đổi các byte. Đó là tính chất mà việc review dựa trên diff dựa vào.
dist/ và các tệp *.lock được sinh ra và không được commit; chúng được sinh lại từ các tệp đã được commit.