Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

CloudFormation Provider

Provider cloudformation kết xuất các Aggrega Recipes thành các template stack AWS CloudFormation. Mọi component kết xuất vào cùng một thư mục đầu ra dưới provider này đều được lắp ráp thành một stack, được xuất ra dưới dạng một template JSON thuần duy nhất sử dụng các intrinsic dạng dài. Do đó, trong trường hợp thông thường, một boundary trở thành một stack — và hai boundary có directory: phân giải về cùng một đường dẫn sẽ cùng được lắp ráp thành một stack, dùng chung các tên của template đó. Giống như mọi provider của Aggrega, nó hoạt động ngoại tuyến và khép kín — một lần build Aggrega là một quá trình biên dịch trước (ahead-of-time), vì vậy provider không bao giờ gọi AWS, không bao giờ phân giải các định danh do tài khoản sinh ra, và không bao giờ chạy CloudFormation. Các giá trị chỉ có khi chạy được giữ nguyên dưới dạng các tham chiếu intrinsic của CloudFormation (Fn::GetAtt, Fn::ImportValue, Fn::GetStackOutput) mà CloudFormation phân giải tại thời điểm triển khai.

Các Recipe dạng fragment được lắp ráp thành một stack

Một Recipe cloudformation soạn một fragment — các tài nguyên CloudFormation do một component duy nhất đóng góp — thay vì cả một template. Khi các component của một boundary được render, provider lắp ráp mọi fragment trong nhóm điều phối thành một template stack: các tài nguyên được hợp nhất dưới một map Resources duy nhất, các giá trị provides của mỗi component xuất hiện thành Outputs của stack, và các mục cấp cao nhất khác của template được xử lý lần lượt trong Các mục cấp cao nhất trong stack đã lắp ráp. Có hai dạng soạn thảo được chấp nhận:

  • Đầu vào dạng fragment (artifacts). Một Recipe soạn trực tiếp các fragment tài nguyên; provider chuẩn hóa chúng thành các intrinsic dạng đầy đủ thuần JSON và hợp nhất chúng vào stack đã lắp ráp.
  • Đầu vào có nguồn. Một Recipe tham chiếu một template CloudFormation có sẵn (YAML hoặc JSON); provider chuẩn hóa nó thành JSON dạng đầy đủ và kiểm tra cấu trúc của nó trước khi lắp ráp, điền các tham số mà template khai báo từ valuesMapping của Recipe — xem Giá trị cho các tham số của một template có nguồn — và bỏ ra mọi tài nguyên mà các mục omits: của Recipe nêu tên — xem Bỏ tài nguyên ra khỏi một template có nguồn.

Template đã lắp ráp là JSON thuần. Các intrinsic được xuất nguyên văn và không bao giờ được đánh giá lúc build — trình biên dịch không thể phân giải một giá trị chỉ tồn tại sau khi stack được triển khai, và việc đánh giá nó sẽ phá vỡ cam kết biên dịch trước (ahead-of-time).

Một Feature gắn vào một component đóng góp vào cùng stack đó

Một Feature gắn vào một component đóng góp các tài nguyên của nó vào stack mà component chủ của nó được lắp ráp vào, theo cùng điều kiện như Recipe riêng của component chủ. Không có template riêng nào bên cạnh: stack đã lắp ráp là toàn bộ những gì provider này xuất ra cho một thư mục đầu ra, nên các tài nguyên của một Feature được gắn hoặc nằm trong stack đó, hoặc hoàn toàn không được triển khai. Tháo Feature ra sẽ xóa đúng các tài nguyên đó và giữ nguyên các tài nguyên riêng của component chủ.

Vì nằm trong stack đã lắp ráp, chúng dùng chung các tên của stack. Các logical ID tài nguyên của một Feature được gắn nằm trong cùng không gian với của component chủ và của mọi Feature khác được gắn cùng nó, nên Tên trong stack đã lắp ráp áp dụng cho chúng y nguyên. Khi hai bên đóng góp trùng một tên, thông báo dừng sẽ nêu component và khóa mà Feature được gắn dưới đó, để bạn có thể tìm thấy cả hai đầu của xung đột trong chính các tệp của mình.

Các output của một Feature được gắn được công bố dưới tên của component chủ, còn các logical ID tài nguyên của nó thì không. Hai nửa của stack được đặt tên theo các quy tắc khác nhau, nên chúng trả lời câu hỏi này khác nhau. Một logical ID tài nguyên được xuất đúng như FeatureRecipe đã soạn, giống như của bất kỳ Recipe nào. Một output được đặt tên theo cả component công bố lẫn mục đó — và với một Feature gắn vào một component, component công bố chính là component chủ: một Feature gắn vào payments-db công bố alarm sẽ có tên paymentsXzhdbXXalarm, đúng tên mà nó sẽ có nếu chính component chủ công bố mục đó. Vì vậy một tên mục mà component chủ cũng công bố sẽ trùng với tên của phần gắn tại một tên output, và quá trình build dừng lại, nêu component và khóa mà Feature được gắn dưới đó cùng với chính component đó. Chọn các tên mục mang nghĩa riêng của Feature — backup-alarm thay vì alarm — giúp chúng tránh trùng với tên của component chủ.

Mỗi tài nguyên mà một Feature đóng góp giữ danh tính được tạo cho phần gắn đó trong thông tin nguồn gốc (provenance) mà build ghi lên nó, thay vì danh tính của component chủ, nhờ đó hai bên vẫn phân biệt được trong một stack mà cả hai cùng đóng góp. Nhãn và chú thích trình bày cách danh tính đó được tạo.

Các phần cấp cao nhất trong stack được lắp ráp

Nhiều component được lắp ráp vào một stack, nên mọi phần cấp cao nhất mà một template CloudFormation chấp nhận đều phải được quá trình lắp ráp xử lý — kể cả Globals và Hooks, hai phần mà một transform do CloudFormation lưu trữ bổ sung vào ngôn ngữ template. Mỗi phần thuộc đúng một trong các nhóm dưới đây, và một khóa cấp cao nhất mà một component viết nhưng hoàn toàn không phải là một phần nào sẽ nhận một cảnh báo nêu tên component và khóa đó, để không có gì bị bỏ đi mà không được thông báo.

Được lắp ráp dưới các tên mà provider phân phạm vi, hoặc đọc đúng như đã viết. Resources và Outputs, được trình bày đầy đủ trong Tên trong stack được lắp ráp. AWSTemplateFormatVersion do provider viết thay vì đọc từ bất kỳ component nào: ngôn ngữ template chỉ chấp nhận một giá trị duy nhất cho nó, nên không có gì để một component quyết định.

Được mang theo đúng dưới các tên bạn đã viết. Parameters, Mappings, Conditions, Metadata và Rules. Mỗi phần này là một map có khóa là các tên bạn đã chọn, nên các mục của mỗi component đến stack được lắp ráp dưới chính các tên đó, không bị viết lại — đó là điều cho phép Condition: của một tài nguyên, một Fn::FindInMap, hoặc một Ref tới một tham số được phân giải theo khai báo đến cùng với nó. Mỗi phần được mang theo riêng, vì mỗi phần được soạn riêng: một rule khẳng định trên một tham số của cùng tài liệu, một condition có thể không tham chiếu tham số nào, và CloudFormation không cho phép tham chiếu tham số bên trong một mapping.

Ở đây một từ chỉ hai chỗ khác nhau, và chỉ chỗ thứ nhất là của bạn. Metadata trong danh sách trên là phần cấp cao nhất của chính template, một map các tên bạn đã chọn. Mỗi tài nguyên riêng lẻ cũng mang một thuộc tính Metadata của riêng nó, và đó là nơi bản build ghi provenance — dưới một khóa dành riêng duy nhất aggrega.ai/, được thêm bên cạnh bất cứ thứ gì bạn đã viết ở đó thay vì thay thế nó. Vì vậy một mục provenance xuất hiện bên trong một tài nguyên không phải do bạn soạn và không phải do phần cấp cao nhất mang theo.

Parameters, Mappings, Conditions và Rules đặt tên các mục của chúng bằng một logical ID. Vì provider mang một tên đúng như bạn đã viết, bảng chữ cái mà một logical ID chấp nhận cũng áp dụng cho các phần này: một tên trong một trong bốn phần chứa bất cứ thứ gì ngoài chữ cái và chữ số sẽ dừng bản build — xem Tên của một phần được mang theo nằm ngoài bảng chữ cái sẽ dừng bản build. Provider không buộc các tên của phần Metadata cấp cao nhất theo bảng chữ cái đó: chúng đặt tên cho thông tin bạn lưu trữ chứ không phải thứ mà template tham chiếu.

Hai component khai báo các tên khác nhau trong một trong các phần này thì cả hai đều được đưa vào. Hai component khai báo cùng một tên với nội dung giống hệt nhau sẽ được hợp nhất thành một mục duy nhất và bản build tiếp tục. Hai component khai báo cùng một tên với nội dung khác nhau sẽ dừng bản build, nêu tên phần, tên mục và cả hai component — vì nếu không, một trong hai nội dung sẽ bị loại bỏ, khiến component đã viết nó có một khai báo mà stack không mang theo. Đó cũng là cách đối chiếu mà tên tài nguyên và tên output tuân theo, và đổi tên một trong hai sẽ giải quyết được.

Được nêu tên thay vì được mang theo. Description là một mô tả duy nhất về toàn bộ template chứ không phải một map các tên bạn đã chọn, nên một quá trình lắp ráp dựa trên nhiều component không có câu trả lời cho nó: hai mô tả là hai câu trả lời cho một câu hỏi và không cái nào là của stack. Hooks chỉ được đọc bởi transform AWS::CodeDeployBlueGreen, mà stack được lắp ráp không bao giờ mang theo (xem bên dưới). Do đó stack được lắp ráp không mang theo cả hai, và mọi component đã soạn một trong hai đều nhận một cảnh báo nêu tên component và phần đó. Một component viết Globals mà không khai báo transform AWS::Serverless-2016-10-31 đọc nó cũng vậy. Cảnh báo này mang tính tham khảo và nằm ngoài luồng: template được xuất ra giống hệt từng byte như khi không có nó, và --no-unsupported-field-warnings tắt nó cùng với các cảnh báo khác thuộc loại đó.

Transform được xây dựng từ transform của mọi component. Một transform là một macro mà CloudFormation chạy trên toàn bộ template trước khi triển khai bất cứ thứ gì, nên Transform của stack được lắp ráp là hợp của các transform mà các component của nó khai báo — của một template có nguồn cũng như của một fragment — theo thứ tự CloudFormation mô tả: một macro do tài khoản của bạn định nghĩa đứng trước các transform do CloudFormation lưu trữ, và AWS::LanguageExtensions đứng trước AWS::Serverless-2016-10-31. Thứ tự riêng của mỗi component được giữ nguyên, và hai transform không có gì sắp thứ tự sẽ chạy theo thứ tự các component khai báo chúng lần đầu, nên cùng các component cho ra cùng một stack. Một transform được viết dưới dạng chuỗi, còn nhiều transform dưới dạng danh sách. Một stack chỉ có một component, khai báo Transform của nó trong một template hoặc fragment, giữ nó đúng như đã viết ở bất cứ đâu bảng dưới đây cho phép mang theo, và một stack mà các component không khai báo transform nào thì không mang theo transform nào. Transform của một component không gây ra cảnh báo: nó được mang theo, hoặc bản build dừng và nêu tên nó.

Vì một transform xử lý toàn bộ template, việc mang theo một transform sẽ thay đổi cách nội dung của mọi component khác được triển khai, trừ khi những gì nó làm chỉ giới hạn trong nội dung được viết cho nó. Vì vậy mỗi transform nhận cách xử lý mà chính tài liệu của CloudFormation về nó hỗ trợ, và một tổ hợp mà stack không thể mang theo sẽ dừng bản build, nêu tên transform và mọi component trong stack:

transformtrong stack được lắp ráp
AWS::Serverless-2016-10-31được mang theo, cùng với Globals của component khai báo nó. Nó dừng bản build khi các Globals đó tác động tới tài nguyên serverless của component khác, và khi nguồn sự kiện của một trong các tài nguyên của nó nêu tên một tài nguyên mà component khác khai báo, vì transform viết lại tài nguyên mà một sự kiện nêu tên.
AWS::LanguageExtensionsđược mang theo một mình, hoặc bên cạnh AWS::Serverless-2016-10-31 từ cùng một component. Nó dừng bản build khi đứng cạnh nội dung serverless của component khác, vì transform serverless đặt tên những gì nó sinh ra theo cách khác sau khi language extensions đã phân giải các giá trị của nó.
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16được mang theo: chúng chỉ xử lý các lịch xoay vòng yêu cầu chúng.
AWS::ServiceCatalogđược mang theo cho một stack chỉ có một component. Khi đứng cạnh bất kỳ component nào khác, nó dừng bản build, vì nó thay thế mẫu tham chiếu của mình ở bất cứ đâu trong template.
AWS::CodeDeployBlueGreendừng bản build, kể cả khi đứng một mình: CloudFormation từ chối Outputs và Fn::ImportValue ở bất cứ đâu trong một template khai báo nó, còn stack được lắp ráp mang theo các output mà các component của nó công bố.
AWS::Includedừng bản build, kể cả khi đứng một mình: nó chèn nội dung lấy từ S3 khi stack được triển khai, thứ mà bản build không thể đọc.
một macro do tài khoản của bạn định nghĩađược mang theo cho một stack chỉ có một component. Khi đứng cạnh bất kỳ component nào khác, nó dừng bản build, vì bản build không biết nó làm gì với phần còn lại của template.

Hai component khai báo cùng một cặp transform theo thứ tự ngược nhau cũng dừng bản build, nêu cả hai thứ tự và cả hai component, vì stack chạy chúng theo một thứ tự duy nhất. Một component cần một transform mà stack không thể mang theo sẽ được đặt trong một boundary riêng.

Tên trong stack đã lắp ráp

Một logical ID của CloudFormation là duy nhất trong một template và chỉ chấp nhận chữ cái và chữ số, và mọi component lắp ráp vào template đó đều dùng chung các tên của nó — kể cả các component từ một boundary thứ hai, khi cả hai cùng phân giải về một thư mục đầu ra. Vì vậy, mỗi tên mà stack dùng để tham chiếu một thứ gì đó phải khác biệt trên mọi component đã đóng góp nó, và tập hợp các bên đóng góp không phải lúc nào cũng là một boundary duy nhất.

Logical ID của tài nguyên đến từ Recipe. Provider xuất chúng đúng như khi được viết và không viết lại cái nào, nên tên bạn đọc thấy trong template đã lắp ráp chính là tên mà Recipe đã viết. Các Recipes CloudFormation của thư viện chuẩn suy ra nó từ chính tên của instance component, đọc các ký tự phân cách trong tên đó như ranh giới từ: instance payments-db đặt tên tài nguyên của nó là PaymentsDb. Do đó, hai instance cùng kiểu mô tả hai tài nguyên thay vì tranh giành một.

Tên output được phân phạm vi theo component đã công bố chúng. Mỗi mục provides xuất hiện dưới dạng một output được đặt tên theo cả component công bố và mục đó — component payments-db công bố host sẽ xuất hiện dưới dạng paymentsXzhdbXXhost — nên hai component công bố cùng một mục sẽ đến hai output riêng biệt, và ý nghĩa của một output không thay đổi khi có component khác gia nhập stack. Một bên tiêu thụ cross-stack trong cùng tài khoản và Region import theo tên export chứ không theo tên này, nên tên export không bị ảnh hưởng; một lần đọc xuyên tài khoản hoặc xuyên Region sẽ nêu tên output này, đúng như provider viết sẵn cho bạn (xem Kết nối cross-stack).

Cách tạo tên output

Một logical ID không chấp nhận ký tự phân cách nào, nên một tên được tạo từ thứ bạn viết phải bằng cách nào đó mang theo các ký tự phân cách của bạn. Bỏ chúng đi sẽ gây mất thông tin: payments-db và payments_db là hai component, và một tên bỏ đi dấu câu sẽ không xác định được cái nào. Vì vậy, provider thay vào đó mã hóa những gì bảng chữ cái từ chối, viết mỗi ký tự bị từ chối bằng các ký tự mà bảng chữ cái chấp nhận.

Lược đồ này dành riêng một ký tự để mở một chuỗi thoát — chữ hoa X — và viết mọi thứ khác đúng như bạn đã gõ, kể cả chữ hoa. Chỉ chữ hoa được dành riêng, nên chữ thường x trong một tên như nginx-proxy được giữ nguyên như bạn đã viết:

những gì bạn viếtnó trở thànhlý do
một chữ cái hoặc chữ số, trừ Xchính nóbảng chữ cái chấp nhận nó
-Xzhbảng chữ cái từ chối dấu gạch nối
_Xzubảng chữ cái từ chối dấu gạch dưới
.Xzdbảng chữ cái từ chối dấu chấm
/Xzsbảng chữ cái từ chối dấu gạch chéo, thứ mà định danh của một component lồng nhau mang theo
XXzx000058được dành riêng để mở chuỗi thoát, nên nó được viết ra theo code point
bất kỳ thứ gì khácXzx và code point của ký tựmột quy tắc bao phủ mọi ký tự còn lại
chỗ hai nửa gặp nhauXXhai ký tự mở liên tiếp, thứ mà không nửa nào có thể chứa

Việc đọc ngược lại là không mơ hồ, và đó là mục đích chứ không phải một chi tiết cho đẹp. Một X chỉ được giữ nguyên khi ký tự theo sau nó là ký tự mà bảng chữ cái chấp nhận, nên một nửa đã mã hóa không bao giờ kết thúc bằng nó và không bao giờ chứa hai ký tự đó liên tiếp — điều này để XX được tự do mang nghĩa chỗ nối, và chỉ chỗ nối.

Vì vậy, ba tên chỉ khác nhau ở vị trí dấu câu vẫn tách biệt:

component payments-db publishing host → paymentsXzhdbXXhost
component payments_db publishing host → paymentsXzudbXXhost
component payments publishing db-host → paymentsXXdbXzhhost

Các tên này dài hơn và khó đọc ngay hơn tên component bạn đã viết, và đó là sự đánh đổi. Một tên xác định đúng một mục có giá trị hơn một tên ngắn hơn mà không xác định được mục nào trong hai — và bạn tham chiếu một output qua tên export chứ không gõ tên này, nên cái giá phải trả chỉ là phải nhìn lại lần thứ hai khi đọc một template đã xuất.

Logical ID của tài nguyên tuân theo một quy tắc khác, vì provider không tạo ra chúng: nó xuất những gì Recipe đã viết. Các Recipes CloudFormation của thư viện chuẩn suy ra một ID bằng cách đọc các ký tự phân cách trong tên instance như ranh giới từ — instance payments-db đặt tên tài nguyên của nó là PaymentsDb — và cách suy ra đó bỏ đi các ký tự phân cách, nên hai tên instance chỉ khác nhau ở dấu câu, hoặc chỉ ở chữ hoa/thường của một chữ cái, vẫn suy ra cùng một tên tài nguyên. Build dừng lại, nêu tên mọi instance đã dẫn đến tên đó cùng với tên mà chúng trùng vào, thay vì xuất một tài nguyên ở chỗ đã khai báo hai component. Tất cả đều được nêu tên chứ không chỉ một số, vì không có gì trong một xung đột khiến cách suy ra của một instance là cách được dự định. Đổi tên tất cả trừ một trong số chúng sẽ giải quyết được.

Một logical ID của tài nguyên nằm ngoài bảng chữ cái sẽ dừng build

Tính duy nhất và bảng chữ cái là hai yêu cầu riêng biệt, và một tập tên có thể thỏa mãn yêu cầu thứ nhất mà không đạt yêu cầu thứ hai. Vì provider xuất một logical ID của tài nguyên đúng như Recipe đã viết, ID mà một Recipe viết ra phải là ID mà tự một template CloudFormation có thể chứa: chữ cái và chữ số, và không gì khác.

Đây là chỗ một tên được suy ra và một tên được chuyển thẳng đi theo hai hướng khác nhau. Một tên output được tạo bởi provider, thứ mã hóa component công bố và mục đó, nên một tên output luôn nằm trong bảng chữ cái dù bạn viết nửa nào thế nào. Một logical ID của tài nguyên được chuyển thẳng, nên Recipe viết gì thì template nhận đúng thứ đó.

Điều đó khiến nó cũng trở thành một ràng buộc lên tên component, mỗi khi một Recipe viết tên của một instance component thẳng vào logical ID. Một tên component có thể chứa dấu gạch nối hoặc dấu gạch dưới; một logical ID thì không. Do đó, một component mà bạn nhắm tới provider này thông qua một Recipe như vậy chỉ được đặt tên bằng chữ cái và chữ số — paymentsdb thay vì payments-db — và bất cứ thứ gì khác sẽ dừng build.

Thông báo dừng nêu tên bên đóng góp có Recipe đã viết ID đó, chính ID đó, và từng ký tự trong nó không được phép có mặt, và nó cho biết bạn có thể viết gì thay thế. Có hai cách giải quyết, và cách thứ nhất luôn sẵn có cho bạn:

  • Để Recipe tự viết một logical ID riêng thay vì chuyển thẳng một tên. Các Recipes CloudFormation của thư viện chuẩn đi theo hướng này — chúng đọc các ký tự phân cách trong tên instance như ranh giới từ, nên instance payments-db đặt tên tài nguyên của nó là PaymentsDb và bạn giữ được tên component đã chọn. Suy ra một ID theo cách đó đổi việc dừng build này lấy quy tắc xung đột ở trên: hai tên instance chỉ khác nhau ở dấu câu sẽ suy ra cùng một tên tài nguyên.
  • Ở chỗ một Recipe có chuyển thẳng một tên, hãy đổi tên bất cứ thứ gì nó chuyển sang chỉ gồm chữ cái và chữ số. Với Recipe riêng của một component, đó là tên component. Một Feature gắn vào một component đặt tên các tài nguyên của nó từ FeatureRecipe riêng của nó, nên đổi tên component chủ không ảnh hưởng đến chúng — ID mà Recipe đó viết mới là thứ phải thay đổi.

Provider từ chối; nó không âm thầm sửa chữa. Viết lại ID thay cho bạn có vẻ là việc hữu ích, nhưng không phải vậy. Một logical ID là cách CloudFormation nhận diện một tài nguyên qua các lần cập nhật, nên thay đổi nó không phải là đổi tên — nó trỏ đến một tài nguyên khác. Một ID do provider thay thế sẽ trỏ đến nơi khác với tài nguyên đã được triển khai dưới ID bạn đã viết, và sự thay thế đó là điều bạn chưa bao giờ yêu cầu và sẽ phải tự phát hiện từ template đã xuất. Một build dừng lại sẽ nêu rõ vấn đề khi nó vẫn còn trong tầm tay bạn để sửa.

Tên phần được mang theo nằm ngoài bảng chữ cái sẽ dừng bản dựng

ID logic của tài nguyên không phải là những tên duy nhất mà provider mang theo đúng như bạn đã viết. Parameters, Mappings, Conditions và Rules cũng đặt tên cho các mục của chúng bằng một ID logic, và mỗi phần trong bốn phần này đến stack đã lắp ráp dưới tên mà tác giả của nó đã chọn. Vì vậy yêu cầu vẫn là một, trên bốn bề mặt nữa: tên phải là tên mà một template CloudFormation có thể tự chứa — chỉ chữ cái và chữ số, không gì khác — và bất kỳ thứ gì khác sẽ dừng bản dựng.

Có một hệ quả vượt ra ngoài phần mang tên đó, và đó là lý do việc này dừng bản dựng thay vì chỉ cảnh báo. Những tên này là thứ mà Condition: của một tài nguyên, một Fn::FindInMap, hoặc một Ref tới một tham số được phân giải theo. Do đó, một tên mà bảng chữ cái không chấp nhận sẽ đưa tham chiếu trỏ tới nó ra khỏi template có thể triển khai cùng với chính khai báo đó, nên chỉ một tên được viết ra cũng khiến cả hai đồng thời ngoài tầm với — và nếu không có việc dừng này, điều đó chỉ được phát hiện lúc triển khai, bởi người đang triển khai chứ không phải người đã viết tên.

Thông báo dừng nêu tên bên đóng góp có Recipe đã viết tên, phần mà tên được viết trong đó, chính tên đó, và từng ký tự trong tên không được phép có mặt. Phần là thuật ngữ để tìm kiếm trong các Recipes của bạn: những tên này được mang theo dưới đúng phần mà bạn đã viết chúng, nên đó là từ duy nhất xuất hiện cả trong thông báo lẫn trong các tệp của chính bạn. Đổi tên mục chỉ bằng chữ cái và chữ số sẽ khắc phục, và đó là toàn bộ cách khắc phục — một ID logic của tài nguyên cho phép lựa chọn để Recipe tự suy ra một ID thay vì truyền thẳng một tên, còn ở đây không có gì để suy ra, vì tên trong phần chính là thứ bạn đã viết.

Chỉ các tên riêng của một phần mới phải tuân theo bảng chữ cái, không bao giờ là các khóa bên trong một mục. Các khóa cấp hai của một mapping do bạn tự do chọn — us-east-1 dưới một map RegionCidr là trường hợp thông thường, và nó đến template được xuất ra mà không bị thay đổi. Các khóa bên trong phần thân của một tham số, một điều kiện hoặc một rule đặt tên cho các thuộc tính, các khẳng định và các hàm nội tại chứ không phải bất cứ thứ gì stack tham chiếu tới: Assertions của một rule, và một Fn::Contains được viết bên trong nó, là những khóa thuộc loại đó. Không khóa nào trong số đó là ID logic, và không khóa nào bị kiểm tra.

Hai tên mục bạn viết khác nhau sẽ luôn khác nhau

Có ba loại tên mục đủ gần nhau để gặp nhau tại một tên output duy nhất, và không loại nào là hiếm gặp. Vì hai nửa được mã hóa chứ không bị gộp, và gặp nhau tại một chuỗi mà không nửa nào có thể chứa, cả ba đều đến được các tên riêng của chúng:

  • Các mục chỉ khác nhau về dấu câu. Một component công bố cả db-host và db_host sẽ đến dbXzhhost và dbXzuhost.
  • Các mục chỉ khác nhau về chữ hoa chữ thường. host và Host đến host và Host, vì một chữ cái được mang theo đúng kiểu chữ bạn đã viết.
  • Các mục gặp nhau qua chỗ nối. Component payments-db công bố host đến paymentsXzhdbXXhost; component payments công bố db-host đến paymentsXXdbXzhhost.

Hai mục vẫn gặp nhau khi chúng thực sự đặt tên cho cùng một thứ. Tên output được dựng từ component công bố và mục, nên bất cứ thứ gì có chung cả hai sẽ đến một tên duy nhất dù được mã hóa thế nào. Trường hợp bạn dễ gặp nhất là một Feature được gắn hai lần vào một component: một lần gắn công bố dưới host của nó, nên hai lần gắn của một Feature trên một component đều công bố alarm-id từ payments-db, và không có gì trong cặp đó để phân biệt. Bản dựng dừng lại thay vì xuất ra một output trong khi hai output đã được viết, nêu tên component và khóa gắn mà mỗi bên mang theo, để cả hai đầu đều có thể tìm kiếm trong các tệp của chính bạn. Hãy gắn Feature một lần, hoặc dùng một Feature có các tên mục được công bố mang tính riêng của lần gắn đó.

Điều này đúng dù hai mục có mang cùng giá trị hay không. Hai mục có cùng giá trị vẫn mô tả hai output mà tác giả đã yêu cầu, nên gộp chúng thành một sẽ khiến một trong hai output đã được viết ra vắng mặt khỏi stack.

Tên mà một Recipe tạo ra trong template không thuộc phạm vi này

Cách mã hóa ở trên là của provider, và nó áp dụng cho các tên output mà provider dựng. Bạn không dùng được nó bên trong một template của Recipe, và do đó một tên mà template của bạn tạo ra không mang bất kỳ đảm bảo nào của nó. Nói rõ điều này là quan trọng vì mối nguy không thể thấy được từ bên trong template: phép gộp có sẵn ở đó đọc đối số của nó thành các từ và bỏ mọi thứ giữa chúng, nên nối hai giá trị trước khi gộp sẽ làm mất chỗ nối cùng với dấu câu.

Một FeatureRecipe đặt tên tài nguyên từ một instance và một khóa gắn, nối bằng một dấu cách rồi gộp, là dạng cần chú ý — app với cache và app-cache không kèm gì đều gộp thành AppCache, và hai tên va chạm trước khi bất kỳ tính chất nào của phép gộp được áp dụng. Có hai cách giữ cho một tên như vậy khác biệt, và cả hai đều là việc của bạn chứ không phải của provider:

  • Giữ các phần được ghép chỉ gồm chữ cái và chữ số, để không gì bị bỏ và không gì cần phân biệt.
  • Đừng nối hai giá trị mà mỗi giá trị có thể chứa dấu phân tách của giá trị kia. Khi một tên phải mang hai phần, hãy để một phần là một literal cố định mà phần kia không thể chứa.

Khi một tên được ghép thực sự va chạm, nó va chạm dưới dạng ID logic của tài nguyên chứ không phải tên output, nên thông báo dừng bạn gặp là thông báo về tên tài nguyên ở trên.

Một khóa được viết hai lần trong một mapping sẽ dừng bản dựng

Một fragment CloudFormation được đọc như một mapping, và một mapping giữ một giá trị cho mỗi khóa, nên một khóa được viết hai lần sẽ giữ phần thân nào đến sau cùng và loại bỏ phần kia. Khi mapping là một khối Resources hoặc Outputs, phần thân bị loại bỏ là một tài nguyên hoặc một output đã được viết và đơn giản là sẽ không có trong stack.

Thay vào đó, bản dựng dừng lại, nêu tên khóa bị lặp và cả hai dòng nơi nó được viết. Đây là quy định cho toàn bộ fragment chứ không phải quy định về các tên của stack: nó áp dụng cho mọi mapping trong fragment, kể cả Properties của một tài nguyên. Cách phổ biến nhất để gặp nó là một Recipe suy ra ID logic từ một giá trị được viết, trong đó hai giá trị chỉ khác nhau về dấu câu — app-cache và app_cache đều suy ra AppCache, nên fragment viết AppCache hai lần.

Một tên khóa lặp lại ở các vị trí khác nhau trong tài liệu là bình thường và không bị động đến: Type xuất hiện một lần mỗi tài nguyên, và Value một lần mỗi output, bất kể fragment mang bao nhiêu tài nguyên và output. Chỉ sự lặp lại bên trong một mapping mới làm mất một phần thân.

Một component duy nhất có thể chiếm một tên hai lần. Một Recipe đóng góp nhiều fragment — nhiều mục artifacts:, hoặc một thư mục nguồn chứa nhiều template — và tất cả đều được lắp ráp vào cùng một stack, nên các fragment của chính một component dùng chung các tên của stack với nhau đúng như chúng dùng chung giữa các component. Hai fragment trao cho một tên hai phần thân khác nhau sẽ dừng bản dựng, và thông báo dừng nêu không gian khóa chứa tên đó — ID logic của tài nguyên hoặc tên output — cùng với component và chính tên đó. Cả hai không gian đều có thể gặp theo cách này: hai fragment có thể viết cùng một ID logic của tài nguyên cho các tài nguyên khác nhau, và một component đến các tên output của nó qua hai đường, một khối Outputs: tường minh và các mục provides: của nó, nên một mục từ mỗi đường mang cùng một tên cũng gặp nhau ở đó.

Việc khai báo lại một tên tự nó không phải là xung đột. Một tên được viết nhiều lần với nội dung giống hệt nhau đều tham chiếu đến một thứ, nên các lần khai báo lại được gộp thành một mục duy nhất và bản dựng tiếp tục — một sự lặp lại thông thường không gây tổn thất gì. Điều dừng bản dựng là trường hợp làm mất nội dung: một trong hai phần thân sẽ phải bị loại bỏ, và tài nguyên hoặc output mà Recipe đã khai báo khi đó sẽ thiếu khỏi stack. Đổi tên một trong hai sẽ khắc phục.

Kiểm tra cấu trúc đầu vào

Một template CloudFormation được lấy từ nguồn sẽ được kiểm tra cấu trúc trước khi render: provider phân tích template và chuẩn hóa các intrinsic của nó, dừng bản build với một thông báo rõ ràng chỉ ra nút vi phạm khi template bị sai định dạng. Bước phân tích kiểm tra hình dạng, không kiểm tra ngữ nghĩa — nó không liên hệ với AWS, không phân giải các tham chiếu và không đánh giá các intrinsic.

Một template phân tích được không vì thế mà được mang theo toàn bộ. Bước phân tích cho biết tài liệu có đúng định dạng; những gì đến được stack đã lắp ráp được quyết định riêng và theo từng phần, như mô tả trong Các phần cấp cao nhất trong stack đã lắp ráp — một template lấy từ nguồn đi qua cùng quy trình kiểm kê như một fragment.

Bước phân tích cũng không hỏi liệu các tham chiếu của template có phân giải được hay không. Việc một Ref có chỉ đến một parameter, hay một Fn::FindInMap có chỉ đến một map hay không, là câu hỏi về stack đã lắp ráp chứ không phải về bất kỳ tài liệu đầu vào riêng lẻ nào, và CloudFormation sẽ trả lời câu hỏi đó lúc triển khai. Bản build nêu rõ những gì nó không mang theo thay vì phán xét những gì kết quả tham chiếu đến. Những tham chiếu mà nó có phán xét là những tham chiếu do chính bản build làm cho treo: tham chiếu đến một parameter mà phép gán của một template lấy từ nguồn đã điền giá trị, được trình bày ở phần tiếp theo, và tham chiếu đến một tài nguyên mà một mục omits: đã loại khỏi template, được trình bày ở phần sau đó.

Giá trị cho các tham số của một template có nguồn

Một template có nguồn nhận giá trị theo cách chính CloudFormation cung cấp giá trị cho một template: thông qua các Parameters mà nó khai báo. valuesMapping của bất cứ thứ gì cung cấp nguồn cho nó — Recipe của một component, hoặc FeatureRecipe của một Feature được gắn — ghi một khóa cho mỗi tham số mà nó điền, và provider gắn từng khóa vào mọi template của nguồn — mọi Ref tới tham số trong Resources, Outputs, Conditions, Rules và Globals của SAM trở thành giá trị đó, mọi Fn::Sub gọi tên tham số như một biến sẽ nhận giá trị qua bảng biến của nó, và tham số được loại khỏi Parameters của mọi template khai báo nó. Một tham số không có khóa nào gọi tên được giữ nguyên như template đã viết, chờ một giá trị được truyền khi stack triển khai hoặc dùng Default của nó.

Nguồn là đơn vị khai báo một tham số. Các template của một nguồn thư mục được ghép thành một stack, nên một template có thể tham chiếu tới một tham số mà một template khác của cùng nguồn khai báo. Việc điền tham số cũng điền nó ở đó: một template chỉ tham chiếu tới tham số sẽ nhận giá trị như được chuyển đổi theo template đầu tiên của nguồn khai báo nó, và không có gì trong nguồn còn tham chiếu tới một tham số mà phần khai báo đã bị việc gắn giá trị loại bỏ.

Không gì khác trong stack có thể tham chiếu tới một tham số đã được điền. Nội dung bên ngoài nguồn — fragment hoặc template có nguồn của một component khác trong cùng stack — gọi tên một tham số mà việc gắn giá trị của nguồn đã điền, thông qua Ref, một biến Fn::Sub hoặc Fn::ValueOf của một rule, sẽ gọi tên một thứ mà stack đã ghép không còn khai báo, điều CloudFormation từ chối khi stack triển khai. Vì vậy bản build dừng lại, nêu tên từng component, template của nó và tham số, cùng component có valuesMapping đã điền tham số đó — của một Recipe, hoặc của FeatureRecipe của một Feature được gắn; một Feature gắn vào một component được gọi theo tên component đó, còn một Feature gắn vào một boundary được gọi theo định danh mà các tài nguyên của nó mang dưới dạng aggrega.ai/component-id, được tạo từ đường dẫn của boundary và tên của phần gắn (bfr--stack--aux cho phần gắn aux trên boundary stack). Fragment của component mà một Feature được gắn vào, hoặc của một component trong boundary mà Feature được gắn vào, nếu tham chiếu tới một tham số mà việc gắn giá trị của phần gắn đã điền, cũng làm dừng bản build. Một tên mà stack vẫn khai báo thì không bị ảnh hưởng: khi một component khác tự khai báo một tham số có tên đó, hoặc một tài nguyên mang tên đó làm logical ID, các tham chiếu tới nó phân giải về khai báo đó và được giữ nguyên. Để truyền giá trị đi tiếp, hãy để component điền giá trị công bố nó, khai báo tham số trong template tham chiếu tới nó, hoặc xóa khóa khỏi 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 }}"

Chỉ valuesMapping mới điền tham số. Các khóa nó ghi là những tên tham số bạn dự định cho template, nên mỗi khóa phải gọi tên một tham số mà một template nào đó của nguồn khai báo: một khóa không gọi tên tham số nào sẽ làm dừng bản build, nêu tên khóa và các tham số mà từng template thực sự khai báo — chính lỗi CloudFormation sẽ báo cho một tham số không xác định, nhưng được báo khi bạn vẫn còn có thể sửa. Một Recipe hoặc FeatureRecipe không khai báo valuesMapping thì không điền gì: các giá trị riêng của component hoặc của phần gắn đến provider dưới tên riêng của chúng, vốn được viết cho các đầu vào khác của nó, và không được đọc.

Bản chất của một giá trị quyết định những gì đến được template.

  • Một literal — một chuỗi, một số, một boolean, hoặc một danh sách của chúng — được ghi vào template, được chuyển đổi theo cách CloudFormation chuyển đổi cùng giá trị đó khi được truyền cho Type của tham số lúc stack triển khai: một Number trở thành chuỗi mà một Ref tới nó trả về, nên 7 đến dưới dạng "7"; một kiểu CommaDelimitedList hoặc List<…> trở thành một danh sách chuỗi, nhận một danh sách hoặc một chuỗi phân tách bằng dấu phẩy với các phần tử được cắt khoảng trắng; mọi kiểu khác nhận một chuỗi. Một literal được kiểm tra theo AllowedValues, AllowedPattern, MinLength, MaxLength, MinValue và MaxValue của chính tham số, và một literal bị chúng từ chối sẽ làm dừng bản build, nêu tên tham số và ràng buộc, nên việc điền một tham số không loại bỏ kiểm tra nào mà template đã khai báo. Một pattern được viết theo cú pháp biểu thức chính quy mà bản build không đọc được sẽ được để lại cho CloudFormation kiểm tra khi stack triển khai.
  • Một giá trị hoàn toàn là một intrinsic của CloudFormation đến vị trí tham chiếu dưới dạng intrinsic đó, để CloudFormation đánh giá khi stack triển khai: một mapping dạng đầy đủ như {"Fn::GetAtt": [Queue, Arn]}, hoặc một chuỗi đúng bằng một dạng rút gọn — !GetAtt Queue.Arn, !Ref Bucket, !Sub … và các dạng khác mà CloudFormation định nghĩa. Đó là cách tham chiếu được công bố của một component khác đến được một tham số: các Recipes CloudFormation của catalog công bố tham chiếu như vậy dưới dạng văn bản rút gọn, và một valuesMapping đọc nó từ ngữ cảnh injection sẽ truyền nó đi tiếp. Một tham chiếu được chèn được đọc như nhau dù có dấu nháy hay không. Có dấu nháy — "{{ .context.inject.env.BUCKET_NAME }}" — mapping truyền đi chuỗi !GetAtt Queue.Arn; không có dấu nháy, chính YAML của mapping đọc !GetAtt Queue.Arn như một tag, và tag được giữ lại cùng đối số của nó thay vì bị bỏ đi. Cả hai cách đều đến tham số dưới dạng intrinsic. Một giá trị chỉ bắt đầu bằng dấu chấm than, hoặc không gọi tên dạng rút gọn nào của CloudFormation, vẫn là văn bản.
  • Một tham chiếu động — {{resolve:ssm:…}}, {{resolve:ssm-secure:…}} hoặc {{resolve:secretsmanager:…}} — đến vị trí tham chiếu đúng như đã viết, để CloudFormation phân giải khi stack triển khai, nên giá trị mà nó gọi tên không bao giờ nằm trong template.
  • Một giá trị mà một component khác công bố từ một stack khác đến template dưới dạng một tham chiếu liên stack, cũng là Fn::ImportValue hoặc Fn::GetStackOutput mà một fragment nhận được (xem Kết nối liên stack), tại mọi vị trí template đã tham chiếu tới tham số.

Một tham số có kiểu mà CloudFormation đọc từ Parameter Store — AWS::SSM::Parameter::Value<…> — không có literal nào tái tạo được những gì CloudFormation sẽ làm với nó, nên một literal gắn vào tham số như vậy sẽ làm dừng bản build; hãy gắn một tham chiếu {{resolve:ssm:…}} hoặc một intrinsic, hoặc để nó không được gắn. Một danh sách gắn vào một tham số mà template gọi tên như một biến Fn::Sub cũng làm dừng bản build, vì một biến chỉ thay thế một chuỗi. Một khóa mà valuesMapping đặt thành null cũng làm dừng bản build, nêu tên tham số, vì một tham số nhận một giá trị còn null không phải giá trị nào; để dành một tham số cho một giá trị được truyền khi stack triển khai hoặc cho Default của nó, hãy bỏ khóa của nó khỏi mapping.

Một rule đọc tham số theo tên sẽ giữ tham số đó không được gắn. Fn::ValueOf trong Rules của một template gọi tên một tham số đã khai báo theo logical ID của nó thay vì thông qua Ref, và việc điền tham số sẽ loại bỏ khai báo của nó, nên việc gắn giá trị cho một tham số mà một rule đọc theo cách đó sẽ làm dừng bản build, nêu tên rule và tham số.

Một literal có thể chứa bí mật bị từ chối; một intrinsic được ghi đúng như đã cho. Một giá trị được ghi vào template có thể được đọc bởi bất kỳ ai đọc được template của stack:

  • Một tham số mà template khai báo NoEcho nhận một tham chiếu động hoặc một intrinsic, và một literal gắn vào nó sẽ làm dừng bản build.
  • Khi valuesMapping đọc một giá trị mà tác giả đã khai báo là nhạy cảm, không phần nào trong đầu ra của nó có thể được truy ngược về giá trị gốc, nên mọi literal mà nó gắn đều làm dừng bản build. Một tham chiếu động và một intrinsic mà nó gắn được ghi đúng như đã cho — kể cả văn bản bên trong một intrinsic. Chẳng hạn, một bí mật mà mapping chèn vào văn bản của một Fn::Sub vì vậy sẽ đến template dưới dạng văn bản đó: chỉ một tham chiếu động mới giữ được chính bí mật đó ra khỏi template. Khi một bản build như vậy tiếp tục, nó cũng in một cảnh báo cho mỗi leaf đã khai báo, cho mapping của một Recipe cũng như cho mapping của FeatureRecipe của một Feature gắn vào một component, nêu tên leaf và thực thể sở hữu mapping — xem A declared-sensitive value reaches the target through a values mapping (Một giá trị được khai báo là nhạy cảm đến đích thông qua một values mapping).
  • Một tham chiếu động sẽ dừng quá trình build khi tham số của nó được tham chiếu trong thuộc tính UserData của một tài nguyên, trong metadata AWS::CloudFormation::Init, hoặc trong Outputs: CloudFormation không phân giải tham chiếu động trong user data của EC2 hay trong metadata đó, và hiển thị Outputs cho bất kỳ ai đọc stack.

Mọi lần từ chối như vậy đều nêu tên các tham số và không trích dẫn giá trị nào.

Loại bỏ tài nguyên khỏi một template có nguồn

Các tài nguyên của một template có nguồn là của riêng nó: giá trị chỉ đến được template qua các tham số mà nó khai báo, nên một template được lấy từ một kho git mà khai báo một tài nguyên mà Release không được tạo — một bucket mà người vận hành đã cung cấp, một khóa mà nền tảng quản lý ở nơi khác — thì không thể thay đổi bằng một giá trị. Đó là mục đích của các mục omits: của một Recipe hoặc một FeatureRecipe. Provider này áp dụng chúng trên một template có nguồn và không trên gì khác: các fragment mà một mục artifacts: tạo ra được render mà không có chúng.

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: StoreLogs

Một mục chỉ định một tài nguyên bằng Type và logical ID của nó. kind của mục là Type của tài nguyên, chẳng hạn AWS::S3::Bucket, và name của nó là logical ID của tài nguyên, tức khóa của nó dưới Resources; cả hai được so sánh đúng như được viết, và cả hai đều phải khớp, nên một mục có Type đúng nhưng logical ID sai sẽ không loại bỏ gì. Một template không có namespace, nên một mục mang namespace sẽ dừng bản build khi component được render, kèm tên của mục; mọi mục đều được kiểm tra trước khi bất cứ thứ gì bị loại bỏ.

Mọi template của nguồn đều được so khớp. Một nguồn một tệp có một template. Một nguồn thư mục — nguồn lấy từ một kho git luôn là loại này — có mọi tệp kết thúc bằng .yaml, .yml, .json hoặc .template, và một mục loại bỏ mọi tài nguyên mà nó chỉ định trong bất kỳ tệp nào trong số đó; một tệp đi kèm các template thì không bao giờ được đọc. Provider báo cáo số tài nguyên mà mỗi mục đã loại bỏ trên tất cả các tệp đó, và một mục không loại bỏ được tài nguyên nào sẽ dừng bản build; xem An omits entry left out nothing the source rendered (Một mục omits không loại bỏ được gì mà nguồn đã render).

Một tài nguyên bị loại bỏ sẽ biến mất trước khi bất cứ thứ gì khác đọc template. Nó không được gắn thông tin nguồn gốc, không được tính vào các tên mà stack mang — nên một component khác có thể đóng góp một tài nguyên với cùng logical ID mà hai bên không gặp nhau — và nó không bao giờ đến được stack đã lắp ráp. Mọi thứ khác trong template được ghi ra đúng như khi template được viết mà không có tài nguyên đó, và một template mà mọi tài nguyên đều bị loại bỏ vẫn giữ một phần Resources rỗng.

Một tài nguyên bị loại bỏ không được còn bị phần còn lại chỉ đến, vì CloudFormation từ chối một template chỉ đến một tài nguyên mà nó không khai báo. Khi các tài nguyên đã bị xóa, mọi tham chiếu mà các template còn lại vẫn tạo đến một trong số chúng sẽ dừng bản build, và thông báo nêu template, tài nguyên, cách tham chiếu chỉ đến nó, và vị trí của tham chiếu dưới dạng đường dẫn từ gốc của template — ví dụ /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName. Một tham chiếu là những gì tài liệu tham chiếu template của CloudFormation định nghĩa là chỉ đến một tài nguyên bằng logical ID của nó, được đọc trong phần thân của mọi tài nguyên — bao gồm thuộc tính, metadata và các policy của nó — và trong mọi output:

  • Ref, với logical ID làm đối số;
  • Fn::GetAtt, dưới dạng một danh sách có phần tử đầu tiên là logical ID, hoặc dưới dạng một chuỗi — !GetAtt StoreLogs.Arn — có phần văn bản trước dấu chấm đầu tiên là logical ID;
  • DependsOn của một tài nguyên, dưới dạng một logical ID hoặc một danh sách logical ID;
  • mỗi biến của Fn::Sub, ở dạng chuỗi và ở dạng danh sách: ${StoreLogs} và ${StoreLogs.Arn} đều chỉ đến StoreLogs.

Một số giá trị chỉ trông giống tham chiếu và không được đọc như tham chiếu. ${!StoreLogs} là văn bản nguyên văn, và một biến mà map của dạng danh sách đặt tên là giá trị của map đó. Condition của một tài nguyên và đối số đầu tiên của Fn::If chỉ đến một condition, Fn::FindInMap chỉ đến một mapping, Fn::ImportValue chỉ đến một export của stack khác, và Fn::GetAZs chỉ đến một region. Các phần Conditions, Mappings, Parameters và Rules không thể chỉ đến một tài nguyên, và phần Metadata cấp cao nhất của chính template là thông tin mà CloudFormation lưu trữ chứ không đọc, nên không phần nào trong số đó được kiểm tra. Một Ref hoặc một Fn::GetAtt có logical ID tự nó được viết dưới dạng một hàm nội tại chỉ hợp lệ dưới transform AWS::LanguageExtensions, vốn phân giải nó khi stack được triển khai (xem Các phần cấp cao nhất trong stack đã lắp ráp), nên nó không chỉ đến tài nguyên nào mà bước kiểm tra có thể đọc và được giữ nguyên; một tham chiếu đến tài nguyên mà nguồn chưa bao giờ khai báo cũng vậy.

Bước kiểm tra đọc các template riêng của Recipe hoặc FeatureRecipe khai báo, cùng lúc. Chúng được lắp ráp thành một stack, nên một tham chiếu đến một logical ID mà một template khác trong số đó vẫn khai báo sẽ không bị dừng. Không có gì khác được đọc: một tham chiếu đến một tài nguyên bị loại bỏ sẽ dừng bản build ngay cả khi một component khác khai báo một tài nguyên có logical ID đó, và một tham chiếu được tạo bởi bất cứ thứ gì khác được lắp ráp vào stack — một component khác, một Feature được gắn kèm, hoặc các mục artifacts: riêng của Recipe — không nằm trong phạm vi bước kiểm tra này, nên CloudFormation sẽ từ chối stack khi nó được triển khai. Để giữ một tham chiếu, hãy giữ tài nguyên. Một giá trị gắn với một tham số chỉ thay thế tham chiếu đến tham số đó, nên một tham chiếu đến một tài nguyên là của riêng template và không thể thay đổi bằng một giá trị: hãy loại bỏ cả tài nguyên tạo ra tham chiếu đó, hoặc xóa mục. Một output không phải là tài nguyên và không mục nào chỉ đến nó, nên một tài nguyên mà Outputs của template chỉ đến không thể bị loại bỏ khỏi template: loại bỏ nó sẽ dừng bản build.

Chú thích đích đám mây

Ba chú thích boundary cho provider biết một stack được triển khai ở đâu, để nó có thể nối các tham chiếu liên stack một cách chính xác:

  • aggrega.ai/aws-account — tài khoản AWS mà stack được triển khai vào.
  • aggrega.ai/aws-region — vùng AWS mà stack được triển khai vào.
  • aggrega.ai/aws-assume-role-arn — ARN của vai trò IAM mà một lần đọc stack liên tài khoản đảm nhận để truy cập các giá trị được export của một stack ngang hàng.

Các chú thích này không trong suốt đối với trình biên dịch — nó chuyển các giá trị của chúng đến provider mà không diễn giải chúng (xem well-known-annotations.md). Chúng được viết trên boundary producer — stack sở hữu giá trị được export. Một lần đọc liên tài khoản đảm nhận vai trò trong tài khoản của producer, nên tài khoản, vùng và vai trò mô tả lần đọc đó đều đến từ các chú thích của boundary producer, không phải của consumer.

Tham chiếu trong cùng stack

Khi một cạnh uses kết nối hai component nằm trong cùng một boundary — cùng một stack — giá trị được tiêu thụ sẽ được nối dưới dạng một Fn::GetAtt trỏ đến logical ID của tài nguyên producer bên trong một template duy nhất. Giá trị provides của producer đi vào đầu vào đã render của consumer dưới dạng một tham chiếu gốc trong cùng stack; không cần export hay import. Fragment của consumer có thể viết một giá trị như vậy trần — Value: {{ .context.inject.env.DB_HOST }} — hoặc trong dấu ngoặc kép — Value: "{{ .context.inject.env.DB_HOST }}": dù theo cách nào, template cũng đọc !GetAtt Db.Endpoint.Address là intrinsic, vì một chuỗi đúng bằng một dạng rút gọn sẽ đến stack dưới dạng intrinsic đó trong fragment cũng như trong một valuesMapping. Ví dụ aws-rds-and-ecs-service minh họa điều này với một task definition của Amazon ECS đọc địa chỉ của một RDS instance trong cùng một stack.

Kết nối giữa các stack

Khi một cạnh uses đi từ một boundary sang một boundary khác — hai component được lắp ráp vào các stack khác nhau — tham chiếu không thể là một giá trị thuần, vì giá trị được tạo ra chưa tồn tại cho đến khi stack của bên cung cấp được triển khai. Provider kết nối nó dưới dạng một tham chiếu cross-stack của CloudFormation. Stack của bên cung cấp công bố giá trị dưới dạng một Output của stack với một Export dưới một tên export tất định (được suy ra từ release, boundary, component và khóa được cung cấp). Stack của bên tiêu thụ đọc nó bằng một trong hai intrinsic, được chọn bằng cách so sánh vị trí đặt đã khai báo của hai boundary:

  • Fn::ImportValue — trường hợp cùng tài khoản, cùng region. CloudFormation phân giải lệnh import dựa trên tên export khớp trong tài khoản và region đó.
  • Fn::GetStackOutput — một lần đọc thực sự xuyên tài khoản hoặc xuyên region. Bên tiêu thụ đọc trực tiếp output của stack bên cung cấp, bằng cách assume aws-assume-role-arn của boundary bên cung cấp vào tài khoản và region của bên cung cấp.

Ngữ nghĩa phát hiện. Provider chỉ chuyển sang Fn::GetStackOutput khi cả hai đầu mút đều khai báo vị trí đặt (tài khoản/region) và các vị trí đó khác nhau. Trong mọi trường hợp khác — không bên nào khai báo, chỉ một bên khai báo, hoặc cả hai khai báo cùng một vị trí — nó dùng Fn::ImportValue. Đây là một quy tắc thận trọng: một lần đọc cross-stack cùng tài khoản vẫn là một lệnh import thuần, và intrinsic đọc trực tiếp được dành cho một bước nhảy thực sự xuyên tài khoản hoặc xuyên region.

Stack của bên cung cấp luôn công bố Export, ngay cả khi một bên tiêu thụ cụ thể đọc nó xuyên tài khoản thông qua Fn::GetStackOutput. Một export không được dùng thì không có tác dụng gì, và việc công bố nó vô điều kiện giữ cho template của bên cung cấp độc lập với cách mỗi bên tiêu thụ chọn để đọc giá trị.

Nhiều bên tiêu thụ của một giá trị đọc cùng một export. Khi có nhiều hơn một component đọc cùng một giá trị được cung cấp qua một boundary — hai bên tiêu thụ trong một stack, hoặc các bên tiêu thụ trong nhiều stack — stack của bên cung cấp công bố Export của giá trị đó một lần, và mọi bên tiêu thụ đều đọc cùng một tên: mỗi Fn::ImportValue import cùng một export, và một bên tiêu thụ đặt ở tài khoản hoặc region khác đọc cùng output đó thông qua Fn::GetStackOutput. Một bên tiêu thụ còn đọc thêm một giá trị mà không bên tiêu thụ nào khác đọc thì chỉ thêm riêng export của giá trị đó.

Ví dụ aws-rds-and-ecs-service dựng trường hợp cùng tài khoản: stack của một RDS instance export từng mục mà cạnh của một server tiêu thụ, và stack của server đọc lại từng mục bằng Fn::ImportValue.

Lưu ý về phiên bản. Fn::GetStackOutput là một intrinsic gốc của CloudFormation. Một tham chiếu xuyên tài khoản được render bằng nó cần công cụ CloudFormation nhận biết được intrinsic này. Đường dẫn cùng tài khoản dùng Fn::ImportValue, vốn khả dụng ở mọi nơi.

Giá trị được đọc từ kết nối thay vì được inject

Recipe của consumer có thể đọc các giá trị của producer trực tiếp từ kết nối, thông qua .context.uses.<alias>.provides, thay vì nhận chúng qua khối inject của kết nối. Khi vượt qua ranh giới stack, một lần đọc như vậy được nối theo cùng cách với một giá trị được inject:

  • Giá trị là một intrinsic của CloudFormation — một thẻ dạng rút gọn như !GetAtt Db.Endpoint.Address, hoặc một ánh xạ Ref hay Fn:: dạng đầy đủ — chỉ đến thứ mà chỉ stack của producer khai báo, nên consumer nhận cùng tham chiếu xuyên stack như một giá trị được inject: stack producer phát hành một Export cho khóa đó, và consumer đọc nó bằng Fn::ImportValue, hoặc bằng Fn::GetStackOutput khi hai boundary khai báo vị trí đặt khác nhau.
  • Giá trị là văn bản thuần — một cổng, một giao thức, một tên cơ sở dữ liệu — có cùng ý nghĩa ở cả hai stack, nên consumer nhận chính giá trị đó và không có export nào được phát hành cho nó. Giá trị đến ở dạng mà CloudFormation đọc nó: một giá trị được viết nguyên vẹn được render như khi không có ranh giới, và một giá trị có dạng số được viết trong dấu ngoặc kép đến dưới dạng một số.

Việc một giá trị có phải là intrinsic hay không do provider này quyết định, bằng cách đọc giá trị theo cách nó đọc khối provides của chính producer. Trình biên dịch chuyển giao giá trị đúng như Recipe của producer đã viết và không diễn giải nó.

Template chỉ có thể sao chép một giá trị như vậy. Nó có thể viết giá trị nguyên vẹn, hoặc bên trong một chuỗi dài hơn, hoặc truyền qua một hàm giữ nguyên giá trị, chẳng hạn quote. Một phép so sánh, một nhánh, một độ dài hoặc một hàm làm thay đổi giá trị — eq, if, len, upper — sẽ được quyết định dựa trên một thứ khác chứ không phải giá trị, vì trên một kết nối như vậy template được trao một giá trị thay thế mà provider sẽ thay thế khi cả hai stack đã được lắp ráp. Thay vào đó, bản build dừng lại, nêu tên template và từng giá trị nó đã đọc, cùng kết nối mà nó đọc giá trị đó và component ở mỗi đầu; hãy rẽ nhánh dựa trên một giá trị của chính component tiêu thụ. Điều tương tự áp dụng cho injectMapping của một FeatureRecipe được gắn và cho một FeatureRecipe phạm vi boundary đọc các kết nối của boundary. Một giá trị được viết bên trong một chuỗi dài hơn còn gặp giới hạn riêng của provider: một tham chiếu xuyên stack chỉ có thể đứng như một giá trị nguyên vẹn, nên một intrinsic được viết bên trong một chuỗi dài hơn sẽ dừng bản build, giống như với một giá trị được inject.

Cách tạo một tên export

Bốn phần được nối với nhau bằng một dấu gạch nối kép, và mỗi phần được viết bằng các chữ cái, chữ số và dấu gạch nối tạo nên một tên export. Chữ cái hoặc chữ số được giữ nguyên như đã viết, và dấu gạch nối bên trong một phần cũng vậy — payments-db vẫn là payments-db. Mọi ký tự khác được viết thành một chuỗi thoát ngắn bắt đầu bằng -z: dấu gạch chéo thành -zs, dấu gạch dưới thành -zu, dấu chấm thành -zd. Một phần hoàn toàn không có giá trị được viết là -ze. Tên stack được tạo theo cùng cách từ release và boundary.

Vì vậy, export công bố host từ component db, trong boundary có thư mục output bên dưới dist/ là stack-a/cloudformation, của release orders, là:

aggrega--orders--stack-a-zscloudformation--db--host

Việc đọc ngược lại không có gì mơ hồ, và đó là mục đích chứ không chỉ là một điểm tiện lợi: vì một phần không bao giờ chứa hai dấu gạch nối liên tiếp và không bao giờ kết thúc bằng dấu gạch nối, các dấu gạch nối kép luôn là chỗ nối. Do đó, hai tập hợp phần khác nhau luôn tạo ra hai tên khác nhau. payments-db và payments_db dẫn đến hai export riêng biệt thay vì trùng vào một, và một dấu gạch nối ở rìa của một phần không thể bị hiểu là thuộc về phần bên cạnh.

Tên export là duy nhất so với những gì, và điều đó dừng ở đâu

Trong một lần build, một tên export xác định đúng một release, boundary, component và khóa được cung cấp — không có hai tổ hợp nào trùng vào một tên duy nhất, nên một lần build không thể làm mất một giá trị được export sau một giá trị khác.

Ngoài ra, CloudFormation yêu cầu tên export phải là duy nhất trên mọi thứ đã được triển khai trong tài khoản và region mà stack được đặt vào. Đó là một thuộc tính của việc triển khai chứ không phải của lần build, và nó nằm ngoài tầm với của bất kỳ phép suy ra nào tại thời điểm build: trình biên dịch không xác thực với AWS, không truy vấn AWS, và không thể đọc output của một lần build khác, nên không có gì được tính toán trước có thể quan sát những gì đã được triển khai ở đó.

Thứ mang sự phân biệt vượt qua ranh giới đó là định danh release đứng đầu mọi tên export và tên stack. Hai lần triển khai dùng chung một tài khoản và region giữ các export của chúng tách biệt bằng cách được release dưới các tên khác nhau — đó là đòn bẩy bạn nắm giữ, và là lý do định danh release đứng đầu tên thay vì đứng cuối.

Một mục Outputs có thể khai báo tên export của riêng nó

Khối Outputs: của một Recipe là CloudFormation do người viết soạn, và một mục trong đó có thể mang Export: riêng với một Name:. Tên đó đến stack đã lắp ráp đúng như đã viết — provider không viết lại nó, không thêm tiền tố cho nó, và không yêu cầu nó trông giống một tên được suy ra.

Thông thường không có gì thêm để nói về nó. Một tên export do người viết soạn không trùng với tên nào mà provider suy ra sẽ được publish cùng với các tên được suy ra và không bao giờ bị nhắc đến. Việc tự soạn được hỗ trợ; chỉ một sự trùng hợp là không.

Bản build dừng lại khi một tên export do người viết soạn trùng với một tên mà provider suy ra cho một liên kết xuyên ranh giới trong cùng bản build. Cả hai khai báo đều sẽ đến template đã lắp ráp, khiến một tên export bị khai báo hai lần trong một stack — mà tên export phải là duy nhất, nên cả hai không thể cùng tồn tại. Thông báo dừng đưa ra tên export được suy ra và bốn phần dùng để tạo nó, để bạn thấy liên kết nào đã tạo ra nó, và nó nêu output của stack mà khai báo do người viết soạn nằm dưới, được đánh dấu là một tên do provider lắp ráp chứ không phải tên do một Recipe viết. Tên export chính là từ khóa để tìm trong các Recipes của bạn. Mục do người viết soạn ghi nó y hệt như thông báo dừng — chính sự đồng nhất đó khiến hai cái thành xung đột — nên đó là chuỗi duy nhất xuất hiện cả trong thông báo lẫn trong các tệp của chính bạn. Đổi tên export mà mục đó khai báo sẽ gỡ bỏ việc dừng, và việc xóa khối Export: của mục đó để cơ chế nối xuyên stack tự publish export cũng vậy.

Phép kiểm tra này thuộc phạm vi bản build, và phạm vi của nó là một stack. Nó so sánh các tên export mà một stack đã lắp ráp khai báo với các tên mà provider suy ra cho các liên kết xuyên ranh giới publish vào chính stack đó — phép so sánh mà bản build có thể thực hiện từ những gì nó đã lắp ráp. Hai stack không được so sánh với nhau. Và việc một tên do người viết soạn gặp phải gì trong số các export đã được triển khai vào một tài khoản và region là một thuộc tính của việc triển khai, nằm ngoài tầm với của bất kỳ phép suy ra nào tại thời điểm build, vì lý do đã nêu trong What an export name is unique against, and where that stops: trình biên dịch không xác thực với AWS, không truy vấn nó, và không thể đọc output của một bản build khác. Một tên export được viết dưới dạng intrinsic thay vì một chuỗi thuần cũng nằm ở phía bên kia của cùng ranh giới đó — nó được phân giải lúc triển khai, và không có gì ở đây đánh giá một intrinsic, nên không có tên nào để bản build so sánh.

Bản build cũng dừng lại khi output mà một liên kết xuyên ranh giới publish lên đã mang sẵn một Export mà liên kết đó không viết. Output đó là output mà provider lắp ráp cho khóa được cung cấp mà một consumer đọc, nên một Recipe có khối Outputs: viết một mục dưới cùng khóa đó, với một Export: của riêng nó, sẽ đặt export của nó đúng vào chỗ của export của liên kết. Trừ khi tên của export đó đúng là tên mà provider suy ra — khi đó nó chính là export của liên kết và mọi consumer đều import nó — hai cái không thể cùng tồn tại ở đó: viết export của liên kết sẽ ghi đè lên export của bạn, còn giữ export của bạn sẽ khiến mọi consumer import một tên mà liên kết không publish. Thông báo dừng đưa ra tên export được suy ra và bốn phần dùng để tạo nó, và cho biết nó đã tìm thấy gì ở output đó: tên export mà mục khai báo, một tên được viết dưới dạng intrinsic, một khối Export: không đặt tên gì, hoặc một Export: được viết dưới dạng giá trị thuần thay vì một khối. Xóa khối Export: của mục đó sẽ gỡ bỏ việc dừng, và khi đó cơ chế nối xuyên stack sẽ publish export mà mọi consumer import.

Thứ tự triển khai

Giá trị syncWave: của một ranh giới Release sắp xếp thứ tự cấp phát của stack mà ranh giới đó được lắp ráp vào. Mọi component trong ranh giới kế thừa wave của ranh giới, và khi nhiều ranh giới phân giải về cùng một thư mục đầu ra — nên các fragment của chúng được lắp ráp thành một template duy nhất — stack chứa nhiều hơn một wave và provider biểu diễn thứ tự giữa chúng bằng DependsOn.

Mỗi tài nguyên nêu tên mọi tài nguyên của wave liền trước có chứa tài nguyên, và không nêu wave nào sớm hơn thế. CloudFormation nối chuỗi phần còn lại: một tài nguyên trong wave 2 phụ thuộc vào wave 1, wave này lại phụ thuộc vào wave 0, nên toàn bộ chuỗi được sắp thứ tự trong khi danh sách riêng của mỗi tài nguyên chỉ có kích thước của một wave thay vì của cả stack. Các wave không cần liên tiếp, và giá trị âm là bình thường — -1 là lựa chọn phổ biến cho một bucket hay một role mà phần còn lại của stack đọc. Wave thấp nhất không nêu tên gì, vì không có gì đứng trước nó.

Thứ tự này là gì: thứ tự tạo, và theo chiều ngược lại, thứ tự xóa. CloudFormation thao tác trên các tài nguyên song song trong phạm vi có thể, và DependsOn ghi đè sự song song đó để thao tác trên các tài nguyên được nêu tên theo một thứ tự đã định. Thuộc tính này chi phối cả hai chiều, nên một wave tạo tài nguyên sớm hơn cũng xóa nó muộn hơn — trình tự gỡ bỏ đúng đắn đi kèm với thứ tự mà không cần thêm gì khác.

Đây không phải thứ tự theo trạng thái sẵn sàng. Một stack template không biểu diễn khái niệm tài nguyên có thể phục vụ, nên không có gì ở đây chờ một tài nguyên trở nên sẵn sàng — chỉ chờ CloudFormation tạo xong nó. Đó là khác biệt thực sự so với cùng wave đó trên compose, nơi một service khai báo healthcheck được chờ cho đến khi báo cáo khỏe mạnh: compose có một primitive về trạng thái sẵn sàng để làm điều kiện, còn stack template thì không có. Thứ tự tạo là điều target này cung cấp, và nói rõ điều đó hữu ích hơn một lời cảnh báo gắn vào một lời hứa mà nó không thể thực hiện.

Một DependsOn do tác giả viết được mở rộng, không bao giờ bị thay thế. Một fragment khai báo ràng buộc thứ tự riêng sẽ giữ nguyên nó: các mục nó đã viết đứng đầu, theo thứ tự nó đã viết, và các mục của wave theo sau. Cả hai yêu cầu đều được giữ và không cái nào che khuất cái kia. Cả một logical ID đơn lẻ lẫn một danh sách đều được đọc, và giá trị đã hợp nhất được xuất ra dưới dạng danh sách, là cách viết duy nhất phù hợp với bất kỳ số lượng mục nào mà phép hợp nhất tạo ra.

Một stack mà mọi tài nguyên đều mang cùng một wave không nhận được gì từ cơ chế này. Một Release không khai báo syncWave nào cũng vậy: mọi thành phần đóng góp mang giá trị mặc định 0 của trường, template đã lắp ráp chỉ chứa một wave, và đầu ra giống hệt như khi provider không biểu diễn thứ tự wave nào.

Thứ tự giữa hai stack không thể biểu diễn, và không được mô phỏng gần đúng. DependsOn nêu tên một tài nguyên trong cùng template, còn các component được lắp ráp vào một stack khác nằm ngoài template đó. Vì vậy một wave sắp thứ tự mọi tài nguyên trong stack mà nó được lắp ráp vào và không gì ngoài đó. Sắp trình tự hai stack là việc của người vận hành, cũng như một tham chiếu cross-stack là sự phân giải lúc triển khai chứ không phải lúc build.

Thứ tự mà các wave không biểu diễn vẫn là việc của chính CloudFormation, và các tham chiếu giữa tài nguyên đã mang phần lớn thứ tự đó: một Fn::GetAtt trỏ tới một tài nguyên producer báo cho CloudFormation tạo tài nguyên đó trước. Một fragment cần một ràng buộc mà cả tham chiếu lẫn wave đều không ngụ ý sẽ tự viết DependsOn, đó chính là trường hợp mà phép hợp nhất ở trên giữ nguyên.

Tính tất định

Với cùng các đầu vào, provider xuất ra một stack template giống hệt nhau đến từng byte qua các lần chạy: logical ID, khóa output, tên export và thứ tự tài nguyên đều mang tính tất định, nhờ đó một stack template CloudFormation cho ra diff gọn gàng khi review theo GitOps.