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

레이블을 구성하는 정책: 환경별 지원 등급과 이를 읽는 판정

거버넌스 플러그인은 이 워크스페이스가 배포하는 모든 컴포넌트에 소유자, 해당 환경이 받는 지원 등급, 백업 일정, 짧은 태그를 레이블로 붙이므로, 개발자가 이를 직접 입력할 필요가 없습니다. 레이블은 빌드 중에 네 개의 거버넌스 연결이 도출합니다.

  • 세 개는 label-transform 역할에 있으며 빌드 노드의 레이블을 구성합니다. Release의 환경을 읽는 Rego 정책과, CLI에 컴파일되어 들어간 두 태깅 플러그인 label-injector, selector-tagger입니다.
  • 하나는 ir-verdict 역할에 있으며, 빌드 그래프에 대한 Rego 정책으로 지원 등급이 없는 노드가 남은 프로덕션 빌드를 중단합니다.

한 Aggregate의 두 Releases는 환경이 staging과 production으로 다르며, 각 노드는 서로 다른 레이블을 갖게 됩니다. 세 번째 빌드는 정책이 범주 하나를 덜 다루는 이 워크스페이스의 복사본에서 check.sh가 실행하는 것으로, 중단되며 빠뜨린 노드를 명시합니다.

구성되는 내용

인스턴스카탈로그 Component여기서의 역할
dbcore/datastore/mariadb쇼핑몰의 데이터베이스
cachecore/datastore/redis그 세션 캐시
webcore/devtool/adminerdb에 연결된 데이터베이스 관리 UI

세 개 모두 Docker Compose로 컴파일되어 dist/compose/docker-compose.yaml에 출력됩니다. Aggregate와 두 Releases 모두 자체 레이블을 지정하지 않습니다. 아래의 모든 레이블은 연결이 작성한 것입니다.

네 개의 연결

이들은 이 워크스페이스의 .aggrega-config.yaml에서 plugins.governance 아래에 연결되므로, 여기서 실행하는 모든 빌드에 적용됩니다.

플러그인역할작성하는 것
1governance/rego:0.9.0, policies/support-tier.rego 사용label-transform모든 노드에 ops.example.com/environment, 설정에 범주가 나열된 모든 노드에 ops.example.com/support-tier
2governance/label-injector:0.9.0label-transform모든 노드에 ops.example.com/owner, datastore 범주의 모든 노드에 backup.example.com/schedule
3governance/selector-tagger:0.9.0label-transformtag, policies/tags.yaml의 맵에서 가져옴
4governance/rego:0.9.0, policies/production-support.rego 사용ir-verdict없음: 빌드를 중단하거나 완료되게 함

0.9.0은 표준 라이브러리 카탈로그에 있는 세 Plugin 엔티티의 버전입니다. 플러그인 자체는 CLI에 컴파일되어 들어가 있으며, 빌드는 그곳에서 이를 제공합니다. aggrega build --release release-production.yaml --auto-pull --detail은 세 개 각각에 대해 둘 다 나열합니다.

[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry]
in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0
in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance
in-binary Plugin governance/rego ← governance/rego:0.9.0
in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance
in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0
in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance
[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]

한 역할의 연결은 나열된 순서대로 실행되며, 각 연결은 앞선 연결이 작성한 레이블을 읽습니다. 레이블 인젝터는 Rego 정책이 작성한 두 레이블을 받고, 셀렉터 태거는 그 레이블과 레이블 인젝터가 작성한 레이블을 받습니다. 판정은 세 개 모두가 실행된 뒤, 이들이 남긴 그래프에 대해 실행됩니다.

label-transform 정책이 읽는 것

label-transform의 정책은 **input.graph.nodes**의 노드를 읽으며, 노드는 노드 ID를 키로 하고 각각 다음을 가집니다.

  • component — 노드가 인스턴스화하는 Component, 예: core/datastore/mariadb
  • resolved_version — 그 Component가 확인된 버전
  • labels — 정책이 실행될 때 노드가 가진 레이블. Component 자체의 레이블과 앞선 변환이 작성한 레이블입니다.
  • values — 노드의 인스턴스가 Aggregate에서 선언하는 값으로, 선언이 없으면 존재하지 않습니다. 여기서는 db만 database: appdb 값 하나를 선언합니다.

Release는 **input.compilation_context**에서 읽습니다. release_name과 environment입니다. 이 덕분에 하나의 정책이 환경마다 다르게 결정할 수 있습니다.

반면 ir-verdict의 정책은 빌드 그래프 전체를 읽으며, 그 노드는 한 단계 더 깊은 **input.graph.spec.nodes**에 있습니다. 한 역할에서 다른 역할로 옮긴 규칙은 복사하지 말고 수정해야 합니다. 경로가 틀리면 아무것도 읽지 못하고 결코 실행되지 않습니다. ir-verdict 페이로드에는 compilation_context가 없으므로 판정은 Release에서 환경을 읽을 수 없습니다. 그래서 여기의 첫 번째 정책은 모든 노드에 ops.example.com/environment도 작성하며, 판정은 그 레이블에서 환경을 읽습니다.

페이로드에 대한 설명을 읽는 대신 직접 보려면, 잠금 파일이 생기도록 한 번 빌드한 다음 다음을 실행합니다.

Terminal window
aggrega build --release release-production.yaml --dry-run --policy-input payloads

이 명령은 각 연결이 받는 페이로드를 payloads/에 씁니다. 한 역할의 여러 연결이 서로 다른 페이로드를 받는 경우에는 연결마다 파일 하나(label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json)를, 다른 각 역할에는 파일 하나를 쓰며, 그 밖에는 아무것도 쓰지 않습니다.

Rego 정책

policies/support-tier.rego는 레이블마다 결정 하나를 labels 아래에 모으며, 노드, 레이블 키, 값을 지정합니다.

env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if {
some id, _ in input.graph.nodes
}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/category"] in data.supported_categories
}

그 설정은 정책의 data 문서이며, 조직의 어휘를 담고 있습니다.

settings:
# The categories whose components get a support tier.
supported_categories: [datastore, devtool]
# The tier each environment gives them.
support_tiers:
production: on-call
staging: office-hours

각 내장 플러그인이 작성하는 것

**label-injector**는 규칙 목록을 적용합니다. 레이블에 규칙의 match 아래 모든 쌍을 포함하는 노드는 그 set 아래의 모든 쌍을 받으며, 쌍은 추가되거나 노드가 이미 가진 레이블의 값을 대체합니다. 쌍이 없는 match는 모든 노드와 일치합니다. 규칙은 여기서처럼 rules 설정에서 읽거나, 설정에 규칙이 없으면 sources 아래에서 규칙이 있는 첫 번째 파일에서 읽습니다. 여기서 두 규칙은 모든 노드에 ops.example.com/owner: shop-team을, datastore 범주의 두 노드인 db와 cache에 backup.example.com/schedule: nightly를 부여합니다. web은 devtool 범주에 속하며 백업 일정을 받지 않습니다.

**selector-tagger**는 항상 tag 키 아래에 레이블 하나를 작성합니다. 그 값은 sources 아래 파일에서 읽는, Component 이름에서 태그로의 맵에서 나옵니다. Component가 맵에 없는 노드는 default 설정을 따르며, default가 없으면 tag 없이 남습니다. policies/tags.yaml은 데이터베이스와 캐시를 매핑합니다.

core/datastore/mariadb: orders
core/datastore/redis: sessions

그리고 연결의 default가 untagged이므로 web에는 untagged 태그가 붙습니다.

둘 다 노드의 레이블과 그 Component만으로 결정합니다. 둘 다 환경을 읽지 않으므로, 두 Releases에서 같은 레이블을 작성합니다.

둘 다 label-transform만 지원합니다. ir-verdict에 연결하면 어느 쪽이든 실행 전에 거부되며, 거기에 연결된 selector-tagger는 다음과 같이 빌드를 중단합니다.

[E0085]
ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandbox

예제 생성하기

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

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

Terminal window
aggrega scaffold --example policy-label-transform

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

Terminal window
cd policy-label-transform

빌드

Terminal window
aggrega build --release release-staging.yaml --auto-pull
aggrega build --release release-production.yaml --auto-pull

표준 라이브러리 카탈로그가 여기 있는 모든 Component, Recipe, Feature와 세 Plugin 엔티티를 제공합니다. 이들은 .aggrega-config.yaml이 지정하는 기본 레지스트리인 hub.aggrega.ai에서 해석됩니다. --catalog로 카탈로그 체크아웃(얻는 방법)을 지정하면 레지스트리에서 아무것도 가져오지 않으므로 빌드는 오프라인으로 실행됩니다. --auto-pull은 빌드 중에 각 Release의 잠금 파일을 채우며, 잠금 파일과 렌더링된 출력은 생성되는 것이고 함께 배포되지 않습니다.

AI 어시스턴트 사용

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

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. Workspace 폴더에 아직 `policy-label-transform` 폴더가 없으면 `example`을 `policy-label-transform`로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `policy-label-transform` 폴더에 예제가 작성됩니다. 그런 다음 각 Release마다 `release-staging.yaml`, `release-production.yaml` 순서로 `build` 도구를 한 번씩 호출하되, 매번 `workspace_root`를 `policy-label-transform`로, `release`를 해당 파일로, `auto_pull`을 true로, `write`를 true로 설정하십시오. 각 빌드가 작성한 파일을 알려 주십시오. 파일은 `policy-label-transform/dist/` 아래에 있습니다.

각 노드가 최종적으로 갖는 레이블

--ir-graph는 빌드 그래프를 빌드 요약보다 먼저 표준 출력에 출력하며, 그래프에는 변환이 남긴 그대로의 각 노드 레이블이 들어 있습니다. aggrega build --release release-production.yaml --auto-pull --ir-graph를 실행한 뒤 web은 다음과 같습니다.

"web": {
"labels": {
"component.aggrega.ai/type": "server",
"component.aggrega.ai/category": "devtool",
"component.aggrega.ai/upstream-licensing": "osi-approved",
"ops.example.com/environment": "production",
"ops.example.com/support-tier": "on-call",
"ops.example.com/owner": "shop-team",
"tag": "untagged"
},
[… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]
}

처음 세 레이블은 Component 자체의 것이고, 마지막 네 개는 세 변환이 작성한 것입니다. check.sh는 각 빌드의 그래프를 읽고 연결이 작성한 레이블을 나열합니다.

labels the attachments wrote, release-staging.yaml:
db ops.example.com/environment: staging
ops.example.com/support-tier: office-hours
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: orders
cache ops.example.com/environment: staging
ops.example.com/support-tier: office-hours
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: sessions
web ops.example.com/environment: staging
ops.example.com/support-tier: office-hours
ops.example.com/owner: shop-team
tag: untagged
labels the attachments wrote, release-production.yaml:
db ops.example.com/environment: production
ops.example.com/support-tier: on-call
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: orders
cache ops.example.com/environment: production
ops.example.com/support-tier: on-call
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: sessions
web ops.example.com/environment: production
ops.example.com/support-tier: on-call
ops.example.com/owner: shop-team
tag: untagged

Releases 사이에서 바뀌는 것은 Rego 정책의 두 레이블뿐입니다.

빌드가 잠금 파일을 채운 뒤에는 aggrega inspect release-production.yaml --ir-graph가 빌드하지 않고도 같은 그래프를 Release의 읽기 쉬운 보기보다 먼저 출력합니다. 변환이 잠금 파일에서 자신의 파일을 읽기 때문입니다. 잠금 파일이 없으면 출력되는 그래프에는 그 파일들이 결정하는 레이블이 하나도 없습니다. ops.example.com/environment도 ops.example.com/support-tier도 없고, 모든 노드에 tag: untagged가 붙습니다.

변환은 레이블만 바꿀 뿐 다른 것은 바꾸지 않음

label-transform의 결정은 노드 하나, 레이블 키 하나와 그 값을 지정하거나, 레이블 하나를 삭제하도록 요청합니다. 노드를 추가하거나, 노드의 Component나 버전을 바꾸거나, 그 값을 건드리는 결정은 없으므로 변환은 그중 어느 것도 표현할 수 없습니다. 빌드에 없는 노드를 지정한 결정은 무시되지 않습니다. 빌드는 E0069로 중단되며 그 노드와 설정하지 못한 레이블을 명시합니다.

release-production.yaml을 이 연결들과 함께, 그리고 연결 없이 빌드한 두 빌드가 이를 보여 줍니다. 두 빌드 그래프는 위에 나열한 레이블만 다르고 그 밖에는 다르지 않습니다. 렌더링된 출력은 전혀 다르지 않습니다. 여기의 Compose Recipes는 이 레이블을 하나도 렌더링하지 않으므로, dist/compose/docker-compose.yaml은 연결이 있든 없든 바이트 단위로 같은 파일이며, check.sh는 실행할 때마다 두 트리를 비교합니다. 레이블은 빌드 그래프에 있으며, 판정은 그곳에서 레이블을 읽습니다.

판정과 그것이 중단하는 빌드

policies/production-support.rego는 변환 뒤에 ir-verdict에 연결되며, 변환이 작성한 레이블을 읽습니다.

deny contains msg if {
some id, node in input.graph.spec.nodes
node.labels["ops.example.com/environment"] == "production"
not node.labels["ops.example.com/support-tier"]
msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])
}

두 Releases 모두 빌드됩니다. staging에서는 판정이 아무것도 요구하지 않고, production에서는 모든 노드가 등급을 가집니다. 정책의 적용 범위를 좁히면 판정이 빠진 노드를 잡아냅니다. .aggrega-config.yaml에서 supported_categories를 [datastore]로 작성하면 web은 지원 등급을 받지 못하고, aggrega build --release release-production.yaml --auto-pull이 중단됩니다.

[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label
caused by: policy violation

빌드는 1로 종료하며 dist/를 쓰지 않습니다. 좁힌 정책에서도 release-staging.yaml은 여전히 빌드됩니다. 그 노드에는 staging 레이블이 붙고, 판정은 이들에게 아무것도 요구하지 않습니다. check.sh는 이 빌드를 워크스페이스의 복사본에서 실행하므로, 이를 보기 위해 여기서 아무것도 수정할 필요가 없습니다.

판정은 수락하거나 거부할 뿐 다른 일은 하지 않습니다. 빌드를 통과시키려고 빠진 레이블을 추가할 수는 없습니다. 프로덕션 노드가 어떤 레이블을 가져야 하는지는 조직의 규칙이며 그 정책에 작성됩니다. 컴파일러는 레이블을 문자열로 그래프에 전달할 뿐 그 의미를 해석하지 않습니다.

lockfile에 기록되는 내용

잠금 파일은 두 종류의 연결을 서로 다르게 기록합니다. 프로덕션 빌드 후 release-production.lock은 각 변환 연결을 mutators: 아래에 담고(플러그인, 역할, 설정, 각 파일의 내용과 다이제스트), 각 변환 플러그인을 plugins: 아래에 고정합니다.

plugins:
- uri: governance/label-injector
[… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice]
referenced_from:
- governance/label-injector:0.9.0
- uri: governance/rego
[… omitted: the artifact digest, recorded twice]
referenced_from:
- governance/rego:0.9.0
- uri: governance/selector-tagger
[… omitted: the artifact digest, recorded twice]
referenced_from:
- governance/selector-tagger:0.9.0

판정 연결은 verdict_inputs: 아래에만, 그 파일의 sha256으로 나타납니다.

verdict_inputs:
- plugin: governance/rego:0.9.0
role: ir-verdict
sources:
- digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8
path: production-support.rego

판정 연결은 고정되지 않습니다. 판정만 연결하면(세 변환을 .aggrega-config.yaml에서 제거하면) 잠금 파일은 mutators: []와 plugins: []를 담고, 판정의 파일은 verdict_inputs: 아래에 있습니다. 변환은 파이프라인의 나머지가 기반으로 삼는 빌드를 바꾸므로 잠금 파일은 그 변경을 만든 플러그인을 보관합니다. 판정은 빌드가 완료되는지 여부만 결정합니다.

모든 빌드 검사하기

이 자체 점검은 사용하는 공유 빌드 헬퍼가 들어 있는 문서 저장소의 체크아웃에서 실행됩니다. aggrega scaffold --example로 작성된 사본에는 그 헬퍼가 없습니다.

Terminal window
./check.sh

check.sh는 build-release 도우미를 통해 빌드 네 개를 실행하고, 각 결과를 이 페이지가 설명하는 결과와 대조합니다.

  • 기준으로서, 거버넌스 연결이 없는 이 워크스페이스의 복사본에서 release-production.yaml을 빌드합니다.
  • 여기의 release-staging.yaml과 release-production.yaml. 각각 모든 노드에 위에 나열한 레이블을 가진 채 완료되어야 하며, 프로덕션 트리는 기준과 바이트 단위로 같아야 합니다.
  • 정책이 datastore 범주만 다루는 복사본에서의 release-production.yaml. E0005와 위의 문장으로 중단되어야 하며, 그 옆에 다른 거부가 있어서는 안 됩니다.

빌드마다 한 줄을 출력한 다음 레이블을 출력하며, 결과가 하나라도 다르면 해당 빌드의 출력을 보여 주고 1로 종료합니다.

RELEASE GOVERNANCE EXIT EXPECTED VERDICT
----------------------------------------------------------------------------------------------------
release-production.yaml none 0 reference OK
release-staging.yaml as attached 0 pass OK: the expected labels
release-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with none
release-production.yaml narrowed 1 halt OK: E0005, the expected sentence
[… omitted: the two label listings shown above]
check: every build ended as expected.

두 복사본은 임시 디렉터리에 만들어지며, 그 .aggrega-config.yaml의 카탈로그 경로는 그곳에서도 확인되도록 절대 경로로 바뀝니다. 이 디렉터리의 파일은 수정되지 않습니다. 여기서 실행하는 두 빌드는 다른 빌드와 마찬가지로 잠금 파일을 채웁니다. ./build-release.sh가 결정하는 바이너리를 사용하므로 AGGREGA_BIN으로 선택할 수 있으며, -- 뒤의 인수는 모든 빌드에 전달됩니다. 빌드가 쓰는 트리를 비교하기 때문에 이 디렉터리에 dist/가 있으면 시작을 거부하며, 실행 후에는 아무것도 남기지 않습니다. 종료 상태가 판정의 전부입니다.

컴파일러가 해석하지 않는 부분

컴파일러는 각 변환에 노드와 Release의 환경을 넘기고, 변환이 결정한 레이블을 적용한 뒤, 그 결과를 판정에 넘깁니다. 컴파일러는 지원 등급이 무엇인지, on-call이 office-hours보다 상위라는 것, devtool에 등급이 필요하다는 것을 알지 못합니다. 그 의미는 정책의 설정과 규칙입니다. 역할, 페이로드, 정책이 레이블을 지정하는 방법은 거버넌스 소켓을, 제품에서 정책이 차지하는 위치는 거버넌스와 컴플라이언스를 참조하십시오.

파일

  • aggregate.yaml — 데이터베이스, 캐시, 그리고 데이터베이스에 연결된 관리 UI입니다. 레이블은 없습니다.
  • manifest.yaml — 각 컴포넌트 유형과 시크릿 Feature를 해당 Docker Compose Recipe에 바인딩합니다. 두 Releases가 공유합니다.
  • release-staging.yaml, release-production.yaml — 두 환경입니다.
  • .aggrega-config.yaml — 기본 레지스트리와 네 개의 거버넌스 연결입니다.
  • policies/support-tier.rego — 레이블 변환 정책입니다.
  • policies/production-support.rego — 판정 정책입니다.
  • policies/tags.yaml — 셀렉터 태거의 컴포넌트-태그 맵입니다.
  • build-release.sh — Release 하나를 빌드하며, 이에 해당하는 aggrega build 명령을 출력합니다.
  • check.sh — 네 번의 빌드를 수행하고 각 결과를 확인합니다.