콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

attachment가 있는 CloudFormation 스택

관리형 데이터베이스와 이를 읽는 애플리케이션을 개발자 의도로 한 번 작성하고 AWS CloudFormation 스택 템플릿으로 조립합니다. 두 attachment가 자체 리소스를 가져오므로(데이터베이스의 경보와 경계의 공유 설정 매개변수), 이 예제는 조립된 스택에서 attachment의 리소스가 어디에 배치되고 component의 리소스와 함께 어떻게 이름이 지정되는지 보여 줍니다.

같은 개발자 의도를 세 가지 방식으로 빌드합니다. 하나의 스택으로, 둘 사이를 가로지르는 참조가 있는 두 개의 스택으로, 그리고 의도적으로 중단되는 빌드로 빌드합니다.

이 페이지의 출력 블록은 이 페이지의 출력 읽기에 따라 실제 실행에서 복사한 것입니다.

파일

  • aggregate.yaml — 개발자 의도: 타입이 core/datastore/mariadb인 payments-db 데이터베이스와, 타입이 example/compute/db-reader이며 이 데이터베이스를 사용한다고 선언하는 reporting-app입니다. AWS에 관한 내용은 여기에 전혀 없습니다. 데이터베이스의 features: 블록은 storage-headroom을 담고 있으며, example/storage-alarm을 연결합니다.
  • release-one-stack.yaml — 두 컴포넌트가 하나의 경계 안에 있으므로 둘 다 단일 스택으로 조립됩니다. 경계 전체에 core/shared-config를 연결합니다.
  • release-two-stacks.yaml — 같은 의도를 두 경계로 나누므로, 애플리케이션의 데이터베이스 참조가 스택 경계를 넘습니다.
  • release-negative-name-collision.yaml와 aggregate-name-collision.yaml — 실패할 것으로 예상됩니다. 하나의 컴포넌트에 알람을 두 번 연결합니다.
  • manifest.yaml — 각 컴포넌트 타입과 연결된 각 Feature를 이 대상에서 그것을 구현하는 Recipe에 바인딩합니다.
  • .aggrega-config.yaml — 카탈로그 엔터티를 해석해 오는 허브 레지스트리를 지정합니다.

모든 release는 payments-db에 대한 항목에서 데이터베이스의 root_password 슬롯을 core/generated-secret으로 바인딩합니다. 이 대상에서는 RDS가 관리자 비밀번호를 소유하며, Manifest가 선택하는 데이터베이스 Recipe에 그렇다고 명시하는 지시문이 담겨 있습니다. 따라서 이 바인딩은 Release에 작성되는 운영자의 결정이 되며, Aggregate는 이에 대해 아무것도 말하지 않습니다.

모든 release는 또한 infra.retention_days: 14와 함께 core/backup을 payments-db에 연결하고, Manifest는 이를 cloudformation/backup-native에 바인딩합니다. RDS는 달리 지정하지 않으면 인스턴스의 자동 백업을 7일 동안 보관하지만, 이 attachment는 각각을 14일 동안 보관합니다. FeatureRecipe는 아무것도 렌더링하지 않습니다. 백업은 인스턴스의 설정이므로, 데이터베이스 Recipe가 attachment를 읽고 "BackupRetentionPeriod": 14를 인스턴스 자체의 Properties에 기록합니다.

이 예제에서 사용하는 엔터티는 모두 게시된 카탈로그에 있습니다. release 파일 옆에 복사해 둔 것이 없으므로, 예제는 카탈로그의 비공개 스냅샷이 아니라 현재 상태의 카탈로그를 기준으로 해석됩니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

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

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd cloudformation-rds-stack

빌드

이 예제에는 세 개의 release가 포함되어 있으므로 원하는 release를 지정합니다. 한 번 실행할 때마다 하나의 release가 빌드됩니다. 각 release의 첫 빌드에는 lockfile이 필요하며, 이는 pull이 기록합니다:

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

빌드는 다음을 출력하며, <workspace>는 이 예제의 폴더를 나타냅니다.

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

조립된 스택은 dist/one-stack/cloudformation/cloudformation-stack.json에 생성됩니다. 해당 디렉터리로 렌더링되는 모든 component와 모든 attachment는 그 하나의 템플릿에 기여합니다. provider는 기여자마다 파일을 하나씩 만드는 대신 순수 JSON으로 된 단일 스택을 내보냅니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `cloudformation-rds-stack` 폴더가 없으면 `example`을 `cloudformation-rds-stack`으로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `cloudformation-rds-stack` 폴더에 예제가 작성됩니다. 그런 다음 `workspace_root`를 `cloudformation-rds-stack`으로, `release`를 `release-one-stack.yaml`로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `cloudformation-rds-stack/dist/` 아래에 있습니다.

무엇이 생성되고, 누가 기여했는가

one-stack 빌드는 네 개의 서로 다른 기여자로부터 네 개의 리소스를 조립합니다:

리소스기여자
PaymentsDb데이터베이스 컴포넌트 자체의 Recipe
PaymentsDbStorageHeadroom해당 컴포넌트에 붙은 storage-headroom 연결
AppSharedConfig경계에 붙은 shared-settings 연결
ReportingApp애플리케이션 컴포넌트 자체의 Recipe

payments-db의 backup attachment가 표에 없는 이유는 자체 리소스를 제공하지 않기 때문입니다. 그것이 설정하는 내용은 PaymentsDb 안에 들어갑니다.

각 리소스에는 출처가 된 기여자를 명시하는 provenance 블록이 있으므로, 두 기여자가 함께 기여한 스택 안에서도 두 부분을 구별할 수 있습니다:

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

두 버전 항목은 이 블록에서 빌드마다 바뀌는 유일한 줄이므로 생략했습니다. 세 번째 생략은 아래에 따로 출력한 경보의 Properties일 뿐입니다. 표시된 모든 내용은 직접 실행한 빌드가 쓰는 내용과 같습니다.

경보는 데이터베이스의 리소스가 아니라 연결의 리소스입니다. Aggregate에서 storage-headroom을 분리하면 정확히 그 리소스와 그것이 게시하는 하나의 출력만 제거되고, PaymentsDb는 바이트 단위까지 그대로 유지됩니다.

연결의 리소스 이름은 그 연결을 가진 범위를 담습니다

Feature는 한 번 작성되어 여러 번 연결되므로, FeatureRecipe가 도출하는 이름은 연결마다 달라야 합니다. 이 예제는 호스트 컴포넌트와 연결 이름을 조합합니다. storage-headroom 아래에 연결된 호스트 payments-db는 PaymentsDbStorageHeadroom이 됩니다.

호스트만 조합해도 경보가 감시 대상 리소스와 충돌하지 않게 하기에는 충분하지만, 같은 Feature를 한 컴포넌트에 두 번 연결했을 때 자기 자신과 충돌하지 않게 하기에는 충분하지 않습니다. 아래의 실패하는 릴리스가 바로 이 문제를 다룹니다.

경보 자체의 속성은 호스트가 도출한 이름으로 호스트를 참조합니다:

"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는 스택이 배포될 때 해당 인스턴스의 식별자로 해석됩니다. 두 부분이 같은 컴포넌트 이름에서 PaymentsDb를 도출하기 때문에 서로 일치하며, 여기서 조회되는 것은 없습니다.

하나의 연결에서 누가 무엇을 결정하는가

연결은 컴포넌트와 같은 방식으로 입력을 나눕니다. 애플리케이션에 필요한 여유 공간의 크기는 개발자 의도로, aggregate.yaml의 연결에 작성되며 애플리케이션의 속성입니다. 경보를 어디로 알릴지, 그리고 하락이 얼마나 지속되어야 경보가 발생하는지는 운영자 사이징으로, Release에서 제공됩니다:

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

Release는 Aggregate가 선언한 연결에 대해 infra를 제공하며, values는 제공하지 않습니다. two-stack 릴리스는 둘 다 설정하고 one-stack 릴리스는 둘 다 설정하지 않으며, 그 차이는 출력에서 확인할 수 있습니다. 설정한 경우:

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

설정하지 않으면 해당 필드는 비어 있는 것이 아니라 존재하지 않습니다. 경보는 알림 동작 없이 생성되고, EvaluationPeriods는 Feature가 선언한 값이 아니라 Recipe가 가진 2로 정해집니다. 둘 다 제공하지 않는 Release도 동작하는 경보를 얻으며, 하나를 제공하면 정확히 필드 하나가 추가됩니다.

연결의 출력 이름은 연결 자신이 아니라 호스트를 따라 붙습니다

스택의 두 부분은 서로 다른 규칙으로 이름이 붙으며, 이쪽이 사람들을 놀라게 하는 부분입니다.

리소스 논리 ID는 연결 자체의 Recipe에서 나옵니다. 위의 이름이 그것입니다. 출력은 게시하는 컴포넌트와 항목을 함께 사용해 이름이 붙으며, 연결의 경우 게시하는 컴포넌트는 호스트입니다. 경보는 alarm-id라는 항목 하나를 게시하며, 다음과 같이 나타납니다:

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

규칙을 알면 두 부분을 읽을 수 있습니다. 논리 ID는 문자와 숫자만 허용하므로, provider는 그 문자 집합이 거부하는 문자를 버리지 않고 풀어서 씁니다. Xzh는 작성한 하이픈이고, XX는 컴포넌트 이름이 끝나고 항목 이름이 시작되는 지점입니다. payments-db가 alarm-id를 게시하는 경우에만 그 이름에 도달합니다. 조립된 스택의 이름에서 전체 방식을 설명합니다.

이는 데이터베이스 자체가 alarm-id를 게시했을 때 도달하는 출력 이름과 같습니다. 따라서 호스트도 게시하는 항목 이름은 연결의 항목과 하나의 출력 이름에서 만나게 됩니다. 그래서 연결 고유의 것으로 읽히는 항목 이름을 쓰면 호스트의 이름과 겹치지 않습니다.

경계 전체 연결은 경계당 한 번 렌더링됩니다

core/shared-config는 Release에서 컴포넌트가 아니라 경계에 연결되며, 그 안의 컴포넌트마다가 아니라 해당 경계에 대해 한 번 렌더링됩니다. one-stack 빌드에는 컴포넌트 두 개와 정확히 하나의 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"
},

two-stack 릴리스를 빌드하면 요점이 더 분명해집니다. 각 경계는 해당 경계에서 해석된 자체 설정을 담은 고유한 것을 갖습니다. 그 빌드가 쓰는 두 템플릿 각각에 있는 것의 Properties:

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

이것이 Release에서 연결되는 이유는 담고 있는 내용이 Aggregate가 선언하는 무언가가 아니라 운영자 자신의 구성이기 때문입니다. 경계 연결은 infra:를 설정하고 values:는 설정하지 않습니다. 개발자 값은 여전히 Aggregate에서 작성됩니다.

같은 의도를 두 스택으로 나누기

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

aggregate.yaml에서는 아무것도 바뀌지 않습니다. 애플리케이션은 여전히 데이터베이스를 사용한다고 선언합니다. 둘을 따로 프로비저닝한다는 결정은 운영자가 Release에서 내리며, 그 결과 둘 사이의 참조가 스택 경계를 넘게 됩니다.

단일 스택 빌드에서는 애플리케이션이 엔드포인트를 하나의 템플릿 안의 참조로 받습니다.

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

두 스택 빌드에서는 생산자 스택이 그 값을 export로 게시합니다.

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

그리고 소비자 스택이 같은 이름으로 그 값을 다시 읽습니다.

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

Export를 가지는 것은 host뿐입니다. 엣지가 실제로 소비하는 항목이 그것이기 때문입니다. 데이터베이스가 게시하는 나머지 항목은 일반 출력으로 나타납니다. 컴포넌트 범위의 경보는 호스트를 따라 생산자 스택으로 들어가고, 각 경계는 자신의 경계 전체 첨부를 유지합니다.

두 내장 함수 모두 빌드 시점에는 평가되지 않습니다. 엔드포인트는 스택이 배포될 때까지 존재하지 않으므로, 컴파일러는 참조를 그대로 전달하고 CloudFormation이 이를 해석합니다. 애플리케이션이 주소를 직접 지정하지 않는 이유가 이것입니다.

export 이름이 만들어지는 방식과, 소비자가 직접적인 교차 계정 읽기 대신 Fn::ImportValue를 통해 읽는 경우에 대해서는 스택 간 연결을 참조하십시오.

중단되는 빌드

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

aggregate-name-collision.yaml은 하나의 컴포넌트에 두 개의 첨부 이름으로 알람을 두 번 첨부합니다. 각 첨부의 리소스 이름은 자신의 첨부 이름을 포함하여 구성되므로, 두 알람은 서로 다른 두 리소스가 되며 리소스 이름에서는 충돌하지 않습니다. 충돌하는 것은 출력입니다. 각 첨부가 alarm-id를 게시하고, 출력은 호스트 컴포넌트와 항목을 기준으로 이름이 지정되며, 두 첨부의 호스트는 같은 컴포넌트입니다.

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

여기서 읽어 낼 수 있는 점은 네 가지이며, 모두 의도된 것입니다.

  • 양쪽 모두 이름이 표시됩니다. 각 항목은 컴포넌트와 그 항목이 담고 있던 첨부 이름을 함께 제시하므로, 작성한 파일에서 둘 다 검색할 수 있습니다. 충돌에서는 어느 한 기여자의 이름이 의도된 것이라고 볼 근거가 없으므로, 첫 번째 것만이 아니라 둘 다 보고됩니다.
  • 키 공간의 이름이 표시됩니다. output-logical-ids는 스택의 두 이름 공간 중 어느 쪽에서 충돌이 발생했는지 알려 주며, 리소스 이름 공간이 이 중단에 나타나지 않으므로 리소스 이름에는 문제가 없었다는 것도 알려 줍니다.
  • 아무것도 출력되지 않습니다. 두 알람 중 하나가 아무 표시 없이 출력을 갖지 않는 스택을 작성하는 대신 빌드가 중단됩니다.
  • 리소스 이름을 서로 다르게 지정해도 이 문제는 해결되지 않습니다. 출력 이름은 호스트 컴포넌트와 항목으로 만들어지므로, 달라져야 하는 것은 항목입니다. 즉 첨부를 두 개가 아닌 하나로 하거나, 게시하는 항목 이름이 해당 첨부 고유의 것으로 읽히는 Feature를 사용해야 합니다.

동일한 입력, 동일한 출력

변경되지 않은 입력으로 두 번 빌드하면 바이트 단위로 동일한 템플릿이 생성됩니다. 컴파일러는 실시간 데이터를 해석하지 않습니다. AWS를 호출하지 않고, 계정 식별자를 조회하지 않으며, CloudFormation을 실행하지도 않습니다. 따라서 다시 빌드해도 바이트를 바꿀 수 있는 무언가를 새로 발견할 일이 없습니다. diff 기반 리뷰가 의존하는 것이 바로 이 속성입니다.

dist/와 *.lock 파일은 생성되는 것이며 커밋되지 않습니다. 이들은 커밋된 파일로부터 다시 생성됩니다.