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

아무도 작성하지 않은 Features를 연결하는 정책: `annotation-transform`에서 주입되는 어노테이션

거버넌스 정책 하나가 상점의 모든 컴포넌트에 플랫폼의 모니터링과 AWS IAM 역할을 부여합니다. 정책은 어노테이션을 추가하는 방식으로 이를 수행합니다. Manifest는 두 어노테이션 키를 두 Features에 바인딩하며, 바인딩된 키 아래의 어노테이션은 Feature 연결로 확장됩니다. 따라서 정책이 추가하는 어노테이션은 각 컴포넌트에 Prometheus ServiceMonitor와 Kubernetes ServiceAccount를 가져다주며, Aggregate와 Release는 어느 것도 작성하지 않습니다.

정책은 annotation-transform 역할에, CLI에 컴파일된 정책 엔진마다 한 번씩 연결됩니다. 바로 Rego와 CEL입니다. 핵심 증명은 같은 어노테이션을 직접 작성한 대조용 Release입니다. 정책 없이 빌드하면, 이 Release는 정책이 어노테이션을 붙이는 Release와 바이트 단위로 동일한 파일을 렌더링합니다.

구성되는 내용

인스턴스카탈로그 Componentrelease.yaml에서 가지는 것
apiexample/compute/service없음
workerexample/compute/service없음
gatewayexample/compute/service자체 모니터링 어노테이션, 간격 10초

세 가지 모두 Helm을 통해 Kubernetes용으로 dist/shop/helm/에 컴파일됩니다. example/compute/service는 표준 라이브러리 카탈로그에 있는 시연용 Component입니다. 이 Component의 모든 인스턴스는 core/prometheus-exporter 연결을 가져야 하며, 이는 Component가 명시하고 빌드가 검사하는 요구 사항입니다.

두 어노테이션 바인딩

manifest.yaml은 두 어노테이션 키에 의미를 부여합니다.

features:
type:
core/prometheus-exporter: helm/prometheus-exporter:1.0.0
core/aws-irsa: helm/aws-irsa:1.0.0
annotations:
feature.aggrega.ai/monitoring:
feature: core/prometheus-exporter
maps:
infra:
- interval
- port
- path
aws-role:
feature: core/aws-irsa
maps:
infra:
- role_arn

여러 하위 키를 라우팅하는 바인딩은 각 하위 키를 명시하는 객체를 값으로 받으므로, feature.aggrega.ai/monitoring은 {interval: …, port: …, path: …}를 받습니다. 하위 키 하나를 라우팅하는 바인딩은 문자열을 받으므로, aws-role은 역할의 ARN을 받습니다. 어노테이션이 펼쳐져 만들어지는 연결은 그 키의 이름을 따릅니다. core/aws-irsa는 ServiceAccount의 이름을 연결의 이름으로 짓기 때문에, 이 키에는 점이나 슬래시가 없습니다.

정책 연결

.aggrega-config.yaml은 허브를 레지스트리로 지정하고 카탈로그 디렉터리는 지정하지 않으며, 거버넌스 연결도 선언하지 않습니다. 정책은 빌드가 --config로 지정하는 파일로 연결됩니다. Rego 엔진에는 governance-rego.yaml, CEL 엔진에는 governance-cel.yaml입니다. Rego용 파일은 다음과 같습니다.

plugins:
governance:
- uri: governance/rego:0.9.0
role: annotation-transform
with:
sources:
- policies/platform-defaults.rego

--config는 해당 실행의 전역 구성 파일을 지정하며, 머신이 원래 읽을 파일을 대신합니다. 이 워크스페이스의 .aggrega-config.yaml은 여전히 그 위에 겹쳐 적용됩니다.

0.9.0은 허브가 각 엔진의 Plugin 엔티티를 게시하는 버전이므로, 연결은 워크스페이스가 읽는 레지스트리에서, 또는 이를 담고 있는 해당 릴리스의 aggrega 바이너리에서 확인됩니다. 실제로 실행되는 엔진은 연결이 어떤 버전을 지정하든, 빌드를 실행하는 aggrega 바이너리에 컴파일되어 들어간 엔진입니다. 모니터링 어노테이션이 받는 객체에는 하위 키 객체를 주입할 수 있는 엔진이 필요하며, 0.8.7 이전 릴리스의 엔진은 그렇게 하지 못합니다.

annotation-transform 정책이 읽는 것

annotation-transform의 정책은 두 가지를 읽습니다.

  • **input.targets**는 어노테이션을 붙일 수 있는 모든 컴포넌트를 나열합니다. 각 대상에는 boundary_path, component_name, 그리고 Release가 해당 컴포넌트에 작성한 annotations가 있으며, 각 값은 작성된 그대로입니다.
  • **input.binding_keys**는 Manifest가 바인딩하는 어노테이션 키를 나열합니다.

aggrega build --release <release> --dry-run --policy-input <dir>는 각 역할이 받는 페이로드를 <dir>에 쓰고, 그 밖에는 아무것도 쓰지 않습니다. release.yaml 빌드로 잠금 파일이 채워진 뒤에 실행합니다.

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -c '.binding_keys' payloads/annotation-transform.json
# ["feature.aggrega.ai/monitoring","aws-role"]
jq -c '.targets[]' payloads/annotation-transform.json
# {"boundary_path":"shop","component_name":"api","annotations":{}}
# {"boundary_path":"shop","component_name":"worker","annotations":{}}
# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}

대상의 annotations에는 Release가 컴포넌트 자체에 작성한 내용이 들어 있습니다. 경계의 aggrega.ai/namespace는 여기에 포함되지 않습니다.

정책

policies/platform-defaults.rego는 어노테이션마다 결정 하나를 annotations 아래에 모읍니다. 각 결정은 대상을 읽어 들일 때 쓰인 두 필드로 대상을 지정한 다음, 키와 값을 지정합니다.

annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": monitoring,
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
monitoring in input.binding_keys
some t in input.targets
not monitoring in object.keys(t.annotations)
}
annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": role,
"annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),
} if {
role in input.binding_keys
some t in input.targets
not role in object.keys(t.annotations)
}

각 규칙은 input.binding_keys에 있는 키에 대해서만 실행되므로, 정책은 Manifest가 의미를 부여하지 않은 것은 아무것도 추가하지 않습니다. 각 규칙은 이미 해당 키를 가진 대상도 건너뜁니다. 컴포넌트가 이미 가진 키에 대한 결정은 Release가 작성한 값을 대체합니다. 이 검사가 없으면 gateway의 10초 간격이 정책의 30초로 바뀌게 됩니다.

policies/platform-defaults.cel은 같은 두 결정을 하나의 표현식으로 나타내며, 두 목록을 +로 이어 붙입니다. 이 표현식 언어에는 sprintf가 없으므로, 맵 키는 object.keys 대신 in으로 검사하고 역할의 ARN은 +로 이어 붙입니다. 표현식 중 역할에 해당하는 절반은 다음과 같습니다.

+ input.targets
.filter(t, "aws-role" in input.binding_keys
&& !("aws-role" in t.annotations))
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "aws-role",
"annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name,
}),

빌드가 렌더링하는 것

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

dist/shop/helm/ 아래에 파일 12개를 씁니다. 컴포넌트마다 Deployment와 Service, 모니터링 어노테이션이 펼쳐진 ServiceMonitor, 그리고 aws-role 어노테이션이 펼쳐진 ServiceAccount입니다. 정책이 주입한 어노테이션에서 나온 api의 ServiceMonitor spec은 다음과 같습니다.

spec:
selector:
matchLabels:
app.kubernetes.io/name: api
endpoints:
- port: metrics
interval: 30s
path: /metrics

gateway의 것은 그 Release 항목이 작성한 값인 interval: 10s를 가집니다. 주입된 aws-role에서 나온, api가 실행될 때 사용하는 ServiceAccount는 다음과 같습니다.

apiVersion: v1
kind: ServiceAccount
metadata:
name: api-aws-role
namespace: shop
annotations:
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api"
aggrega.ai/boundary-path: shop
aggrega.ai/recipe-uri: "aws-irsa:1.0.0"
[… omitted: the labels, which carry the version of the aggrega binary that built the file]

주입하든 직접 작성하든 같은 파일

release-by-hand.yaml은 정책이 주입하는 어노테이션을 각 컴포넌트에 직접 작성한 release.yaml입니다. 정책을 연결하지 않고 빌드하면,

Terminal window
aggrega build --release release-by-hand.yaml --auto-pull

어느 엔진으로 정책을 연결한 release.yaml과도 바이트 단위로 같은 파일 12개를 씁니다. 이 비교에서 제외되는 것은 없습니다. 어노테이션이 주입되었는지 여부는 렌더링된 어떤 파일에도 기록되지 않습니다. check.sh는 실행할 때마다 트리를 비교합니다.

빌드는 주입된 값을 Release에 작성된 같은 값과 정확히 똑같이 읽으므로, 그 값은 같은 연결로 펼쳐집니다.

주입이 기록되는 곳

빌드 그래프가 이를 기록하며, --ir-graph가 그래프를 출력합니다. 주입된 어노테이션을 받은 모든 컴포넌트는 Release 어노테이션 가운데 플러그인을 명시하는 aggrega.ai/injected-by를 가집니다. aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph를 실행한 뒤 api는 다음과 같습니다.

"release_annotations": {
"aggrega.ai/namespace": "shop",
"aws-role": "arn:aws:iam::123456789012:role/shop-api",
"aggrega.ai/injected-by": "governance/rego"
},

기록은 키 단위가 아니라 컴포넌트 단위입니다. gateway도 그 aws-role 때문에 이를 가집니다. 어노테이션이 펼쳐진 각 연결은 직접 작성한 어노테이션과 마찬가지로 그래프에서 "origin": "annotation"을 가집니다.

Helm 타깃은 aggrega.ai/injected-by 어노테이션을 렌더링하지 않으며, 그렇다고 알려 줍니다. 이 빌드에서는 주입을 받은 각 컴포넌트가 출력에 경고 세 개를 추가합니다. api의 첫 번째 경고는 다음과 같습니다.

warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it

--no-unsupported-field-warnings는 이 종류의 경고를 숨기며, 빌드가 쓰는 내용은 아무것도 바꾸지 않습니다.

이 역할은 어노테이션을 추가할 뿐 다른 일은 하지 않음

결정은 컴포넌트 하나, 어노테이션 키 하나와 그 값을 지정합니다. 결정 안의 어떤 것도 컴포넌트를 추가하거나, 레이블을 바꾸거나, Feature를 직접 연결하지 않습니다. 정책은 Manifest가 바인딩하는 키를 통해서만 Feature에 닿으며, 그것이 어떤 Feature인지는 Manifest가 정합니다.

결정은 어노테이션을 제거할 수도 없습니다. 그 값은 문자열이나 하위 키 객체이며, null은 해당 주입을 명시하며 거부됩니다. null은 작성자가 컴포넌트를 상속받을 어노테이션에서 제외하는 방법이기 때문입니다.

바인딩이 하위 키 세 개를 라우팅하는 곳에 문자열이 오는 경우

governance-monitoring-as-string.yaml은 policies/monitoring-as-string.rego를 연결하며, 이 정책은 모니터링 키 아래에 문자열 "30s"를 주입합니다. 이 바인딩은 하위 키 세 개를 라우팅하는데 문자열은 그중 아무것도 지정하지 않으므로,

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

중단되고, 1로 종료하며, dist/를 쓰지 않습니다. 정책은 api와 worker에 이 문자열을 주입했고, 각각이 거부됩니다. 각 거부 메시지는 값을 주입한 플러그인과 그것이 연결된 역할을 명시하므로, 값은 아무도 작성하지 않은 Release의 한 줄이 아니라 그 값을 결정한 정책으로 추적됩니다:

[… omitted: a warning that the attachment is in the global configuration named with --config]
[OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")
---
[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")

정책이 없을 때

거버넌스 연결 없이 빌드한 release.yaml은

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

중단됩니다. 그 Component는 core/prometheus-exporter 연결을 요구하는데, api나 worker에 그것을 제공하는 것이 없습니다.

[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")
---
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")

gateway가 명시되지 않는 것은 그 Release 항목이 자체 모니터링을 작성하기 때문입니다. 정책을 연결하면 같은 Release가 빌드됩니다. 주입된 어노테이션이 펼쳐진 연결은 직접 작성한 것과 마찬가지로 요구 사항을 충족합니다.

lockfile에 기록되는 내용

annotation-transform 연결은 빌드가 렌더링하는 내용을 바꾸므로, 잠금 파일이 이를 고정합니다. Rego 빌드 후 release.lock은 mutators: 아래에 연결을 담으며, 그 플러그인, 역할, 정책 파일의 내용과 다이제스트를 함께 기록합니다.

mutators:
- plugin: governance/rego
role: annotation-transform
sources:
- content: |
[… omitted: the policy file, as written]
digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b
path: platform-defaults.rego

또한 plugins: 아래에 플러그인을 고정합니다.

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

연결은 허브가 게시하는 버전을 지정하므로, 고정은 워크스페이스가 읽는 레지스트리를 통해, 또는 해당 릴리스의 aggrega 바이너리에서 확인됩니다.

예제 생성하기

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

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

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

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

Terminal window
cd policy-annotation-transform

빌드

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

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

AI 어시스턴트 사용

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

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. Workspace 폴더에 아직 `policy-annotation-transform` 폴더가 없으면 `example`을 `policy-annotation-transform`로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `policy-annotation-transform` 폴더에 예제가 작성됩니다. 그런 다음 `aggrega build`를 실행하고 그 `--config` 플래그를 받는 `cli-build` 도구를 `workspace_root`를 `policy-annotation-transform`로, `release`를 `release.yaml`로, `auto_pull`을 true로, `config`를 `governance-rego.yaml`로 설정하여 호출하고, 이어서 같은 방식으로 `config`를 `governance-cel.yaml`로 설정하여 다시 호출하십시오. 마지막으로 `workspace_root`를 `policy-annotation-transform`로, `release`를 `release-by-hand.yaml`로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 각 빌드가 작성한 파일을 알려 주십시오. 파일은 `policy-annotation-transform/dist/` 아래에 있습니다.

모든 빌드 검사하기

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

Terminal window
./check.sh

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

  • 정책 없는 release-by-hand.yaml이 기준입니다. 어노테이션이 펼쳐진 파일 여섯 개를 렌더링해야 합니다.
  • 정책 없는 release.yaml은 api와 worker에 대해 E0162로 중단되어야 하며, 다른 컴포넌트에 대해서는 그러면 안 됩니다.
  • 정책이 있는 release.yaml은 엔진마다 한 번씩 빌드됩니다. 각 빌드는 기준의 파일을 바이트 단위로 똑같이 쓰고, 잠금 파일에 플러그인을 고정하며, 세 컴포넌트 모두를 그 플러그인이 주입한 것으로 기록해야 합니다.
  • 심어 둔 문자열이 있는 release.yaml은 위의 거부로 중단되어야 합니다.

빌드마다 한 줄을 출력한 다음 두 바인딩이 렌더링한 파일을 출력하며, 결과가 하나라도 다르면 해당 빌드의 출력을 보여 주고 1로 종료합니다.

POLICY RELEASE EXIT EXPECTED VERDICT
----------------------------------------------------------------------------------------------------
none release-by-hand.yaml 0 reference OK: the six attachments' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml:
shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml
shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml
shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml
shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml
shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml
shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.

각 빌드는 임시 디렉터리에 만든 이 워크스페이스의 자체 복사본에서 실행되며, 그 .aggrega-config.yaml의 카탈로그 경로는 그곳에서도 확인되도록 절대 경로로 바뀝니다. 이 디렉터리에는 아무것도 쓰지 않습니다. build-release 도우미가 결정하는 바이너리를 사용하므로 AGGREGA_BIN으로 선택할 수 있으며, -- 뒤의 인수는 모든 빌드에 전달됩니다. 종료 상태가 판정의 전부입니다.

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

컴파일러는 컴포넌트와 바인딩된 키를 정책에 넘깁니다. 정책이 결정한 어노테이션을 추가하고, 다른 어노테이션과 마찬가지로 Manifest의 바인딩을 통해 이를 펼칩니다. 컴파일러는 어떤 서비스가 모니터링되어야 하는지, 스크레이프 간격이 무엇인지, 컴포넌트가 어떤 IAM 역할로 실행되어야 하는지 알지 못합니다. 그 의미는 정책과 Manifest에 속합니다. 역할, 페이로드, 결정 키는 거버넌스 소켓을 참조하십시오. 정책 없는 어노테이션 펼치기는 annotation-driven-monitoring을 참조하십시오.

파일

  • aggregate.yaml — 세 서비스이며, 어노테이션은 없습니다.
  • manifest.yaml — 컴포넌트 유형과 두 Features를 각각의 Helm Recipes에, 두 어노테이션 키를 두 Features에 바인딩합니다.
  • release.yaml — 정책이 어노테이션을 붙이는 Release이며, gateway만 어노테이션을 작성합니다.
  • release-by-hand.yaml — 대조군으로, 모든 어노테이션을 직접 작성했습니다.
  • .aggrega-config.yaml — 기본 레지스트리이며, 거버넌스 연결은 없습니다.
  • governance-rego.yaml, governance-cel.yaml — 각 엔진을 통해 annotation-transform에 연결되는 정책이며, 각각 --config로 지정합니다.
  • governance-monitoring-as-string.yaml — 심어 둔 실수이며, --config로 지정합니다.
  • policies/platform-defaults.rego, policies/platform-defaults.cel — 엔진마다 하나씩 있는 정책입니다.
  • policies/monitoring-as-string.rego — 심어 둔 실수입니다.
  • build-release.sh — Release 하나를 빌드하며, 이에 해당하는 aggrega build 명령을 출력합니다.
  • check.sh — 빌드 다섯 개를 실행하고 각 결과를 확인합니다.