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

조직 전체 정책: 팀의 규칙, 조직의 규칙, 파이프라인의 규칙

팀의 정책, 그 조직의 정책, 그 파이프라인의 정책이 하나의 빌드에서 함께 실행되며, 각각은 자체 구성 파일에서 연결됩니다. 팀은 자신의 워크스페이스에서 규칙을 연결하고, 조직은 모든 빌드에 규칙 하나를 추가하며, 파이프라인은 하나를 더 추가합니다. 둘 중 어느 쪽도 팀의 파일을 편집하지 않습니다. 빌드는 자신에게 적용되는 모든 파일을 읽고 그 파일들이 담고 있는 모든 연결을 실행합니다.

규칙들은 세 가지 판정 심각도 모두로 보고됩니다. info와 warn은 빌드를 완료시키고 halt는 빌드를 중단시킵니다. 그중 하나인 조직의 규칙은 두 번 연결되며, translation 블록을 통해 매번 다른 심각도로 보고됩니다.

구성되는 내용

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

둘 다 Docker Compose로 컴파일되어 dist/compose/docker-compose.yaml에 기록됩니다. Aggregate 하나, Manifest 하나, Release 하나(release.yaml)이며, 그중 어느 것도 정책을 지정하지 않습니다.

세 개의 파일

주체파일빌드가 읽는 방식연결이 작성되는 위치
팀.aggrega-config.yaml이 디렉터리를 워크스페이스로 표시하므로 여기의 모든 빌드가 이 파일을 읽습니다plugins.governance
조직org/config.yaml전역 구성 파일로서, --config org/config.yaml로 한 번의 빌드에 지정됩니다plugins.governance_append
파이프라인pipeline/.aggrega-config-append-ci.yaml이 디렉터리로 복사되면 파이프라인의 오버레이로서 읽힙니다plugins.governance_append

세 연결 모두 ir-verdict 역할의 Rego 엔진 governance/rego:0.9.0이며, 이 역할은 아무것도 렌더링되기 전에 빌드 그래프를 판정합니다. 0.9.0은 표준 라이브러리 카탈로그에 있는 해당 Plugin 엔터티의 버전입니다. 엔진 자체는 CLI에 컴파일되어 들어가 있으므로(aggrega plugin list는 내장 빌트인 중에 governance/rego를 나열합니다) 여기의 어떤 빌드도 플러그인을 가져오지 않습니다.

조직의 파일은 전역 구성 파일입니다. 머신에는 이 파일이 하나 있으며 모든 빌드에서 읽힙니다. 기본 위치에서 읽거나, AGGREGA_CONFIG 환경 변수가 지정하는 파일을 읽습니다. --config <path>는 대신 한 번의 실행에 대해 파일을 지정하며, 워크스페이스 자체의 파일은 여전히 그 위에 읽힙니다. 조직에서는 이 파일이 모든 개발자의 머신과 모든 파이프라인의 기본 위치에 놓이겠지만, 여기서는 org/에 있으며 이 파일을 읽어야 하는 빌드가 이를 지정합니다. 전역 파일을 명시적으로 지정하기에서 세 가지 방식을 시도하는 순서를 설명합니다.

파이프라인의 파일은 오버레이입니다. 빌드는 .aggrega-config.yaml을 읽는 디렉터리에서 그 옆에 있는 .aggrega-config-append-ci.yaml을 읽습니다. 이 파일은 여기서 pipeline/에 보관되며, 이 디렉터리에서 실행되는 빌드는 이 파일을 읽지 않습니다. 이 파일을 읽는 빌드는 모두 중단되기 때문입니다. 파이프라인의 단계는 이 파일을 복사해 넣는 것입니다.

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .

각 파일은 추가하며, 파이프라인의 오버레이는 추가만 합니다

조직과 파이프라인은 모두 자신의 연결을 plugins.governance_append 아래에 작성합니다. 이는 plugins.governance 목록의 추가용 짝 설정입니다. 짝 설정 아래의 항목은 각 파일 자체의 목록을 읽은 뒤 해석된 목록에 이어 붙여지므로, 팀의 plugins.governance와 조직의 항목이 모두 실행되고 어느 파일도 다른 파일을 지정하지 않습니다. 조직이 plugins.governance 자체가 아니라 짝 설정에 작성하는 이유는, 워크스페이스 파일의 plugins.governance 목록이 전역 파일의 목록을 대체하기 때문입니다. 거기에 작성된 조직의 규칙은 팀의 목록에 의해 버려지며, 빌드는 이에 대해 아무것도 출력하지 않습니다. 목록을 대체하지 않고 확장하기에서 각 목록 설정의 짝 설정을 나열합니다.

파이프라인의 오버레이는 추가만 할 수 있습니다. 목록 설정에 대해 작성한 내용은 다른 파일들이 해석한 내용에 추가됩니다. 아무것도 제거하지 않으며, auto_pull처럼 단일 값을 갖는 설정을 재정의하지도 않습니다. 이 오버레이는 auto_pull: true를 담고 있으며, 이를 읽는 빌드는 해당 키를 무시하고 경고로 그 사실을 알립니다. <workspace>가 빌드가 실행된 디렉터리의 절대 경로를 나타낸다고 할 때, 그 줄은 다음과 같습니다.

warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)

규칙과 각 규칙이 보고되는 심각도

Rego 정책은 각 결정을 결정 키 아래에 모으며, 키가 그 결정이 보고되는 심각도를 정합니다. translation이 없으면 키는 deny, warn, audit이며, 각각 halt, warn, info로 보고됩니다.

심각도빌드가 하는 일
halt중단되고, 1로 종료하며, dist/를 기록하지 않습니다
warn완료되고, 메시지를 출력하며, dist/를 기록합니다
info완료되고, 메시지를 출력하며, dist/를 기록합니다

팀의 규칙 policies/team.rego는 warn 아래에 모으며, 그 연결은 translation을 선언하지 않으므로 warn으로 보고됩니다.

warn contains msg if {
some id, node in input.graph.spec.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v runs with high availability off", [id])
}

조직의 규칙 org/policies/estate.rego는 설정에 나열된 카테고리의 컴포넌트를 거부하고, 각 컴포넌트가 무엇을 실행하는지 기록합니다.

deny contains msg if {
some id, node in input.graph.spec.nodes
category := node.labels["component.aggrega.ai/category"]
category in data.refused_categories
msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])
}
audit contains msg if {
some id, node in input.graph.spec.nodes
msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])
}

refused_categories는 각 연결의 설정이며, 정책은 자신의 연결 설정을 data 문서로 읽습니다.

변환: 하나의 규칙, 두 가지 심각도

연결 설정의 translation 블록은 어떤 결정 키를 읽을지와 각각이 보고되는 심각도를 선언합니다. 이는 기본 매핑을 확장하는 것이 아니라 대체합니다. 지정하지 않은 키는 읽히지 않습니다.

조직의 파일은 자신의 규칙을 권고로 도입합니다. 그 연결은 deny를 warn으로, audit을 info로 보고합니다.

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: warn
- key: audit
severity: info

파이프라인은 같은 파일을 연결하고 같은 규칙이 빌드를 중단시키도록 합니다. 그 변환은 deny만 지정하므로, 그 연결은 audit 기록을 두 번 보고하지 않습니다.

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: halt

따라서 같은 web에 대한 하나의 규칙이 개발자의 빌드에서는 경고가 되고, 파이프라인의 빌드에서는 빌드가 중단되는 이유가 됩니다.

예제 생성하기

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

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

Terminal window
aggrega scaffold --example policy-org-overlay

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

Terminal window
cd policy-org-overlay

빌드

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

팀의 파일만 있는 경우:

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

빌드는 팀의 경고를 출력하고 완료됩니다. 조직의 파일도 함께 있는 경우:

Terminal window
aggrega build --release release.yaml --auto-pull --config org/config.yaml

팀의 경고와 함께 조직의 기록을 info로, 그 규칙을 warn으로 출력하며, 여전히 완료됩니다.

info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

각 판정은 그것을 연결한 파일이 아니라 그것을 보고한 플러그인 rego를 지정하므로, 팀의 경고와 조직의 경고는 똑같이 보입니다. 조직의 메시지처럼 누구의 규칙인지 밝히는 메시지가 둘을 구별하는 방법입니다.

파이프라인의 오버레이를 복사해 넣으면 같은 명령이 중단됩니다.

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .
aggrega build --release release.yaml --auto-pull --config org/config.yaml
[… omitted: the overlay's warning shown above]
[… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them]
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
caused by: policy violation

빌드는 1로 종료하고 dist/를 기록하지 않습니다. 조직의 규칙은 각 연결에서 한 번씩, 두 번 보고됩니다. 조직의 연결에서는 warn으로, 파이프라인의 연결에서는 halt로 보고됩니다. audit 기록은 조직의 연결에서만 한 번 나타납니다. 다시 이 파일 없이 빌드하려면 이 디렉터리에서 .aggrega-config-append-ci.yaml을 제거하십시오.

AI 어시스턴트 사용

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

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

모든 빌드 검사하기

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

Terminal window
./check.sh

check.sh는 build-release 헬퍼를 통해 release.yaml을 다섯 번 빌드하며, 각각 이 워크스페이스의 복사본에서 수행합니다. 팀의 파일만 있는 경우, --config로 지정한 조직의 파일이 있는 경우, 파이프라인의 오버레이를 복사해 넣은 경우, 둘 다 있는 경우, 그리고 연결을 짝 설정 대신 plugins.governance 아래에 작성한 조직 파일의 복사본이 있는 경우입니다. 마지막 경우에는 팀의 목록이 그것을 대체하고 팀의 판정만 출력됩니다. 각 빌드에 대해 종료 상태, dist/가 기록되었는지 여부, 빌드가 출력한 모든 판정(심각도와 메시지로, 빠진 것도 다른 것도 없어야 함)을 확인하고, 오버레이가 읽히는 경우에는 auto_pull을 지정하는 경고도 확인합니다. 빌드마다 한 줄을 출력한 다음 각 빌드가 출력한 판정을 출력하며, 결과가 하나라도 다르면 해당 빌드의 출력을 표시하고 1로 종료합니다.

LAYERS EXIT DIST VERDICT
----------------------------------------------------------------------------------------------------
team 0 yes OK
team + organization 0 yes OK
team + pipeline 1 no OK
all three 1 no OK
team + organization, plugins.governance 0 yes OK
team:
warn db runs with high availability off
team + organization:
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline:
ignored auto_pull
warn db runs with high availability off
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three:
ignored auto_pull
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance:
warn db runs with high availability off
check: every build ended as expected.

복사본은 임시 디렉터리에 만들어지며, 그 .aggrega-config.yaml의 카탈로그 경로는 거기서도 해석되도록 절대 경로로 바뀝니다. 이 디렉터리의 어떤 파일도 편집되거나 기록되지 않습니다. ./build-release.sh가 결정하는 바이너리를 사용하므로 AGGREGA_BIN으로 선택할 수 있으며, -- 뒤의 인수는 모든 빌드에 전달됩니다. 종료 상태가 판정의 전부입니다.

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

컴파일러는 세 파일을 읽고, 그 파일들이 담은 연결을 이어 붙이고, 각 정책에 빌드 그래프와 그 설정을 넘기며, 각 결정이 보고되는 심각도에 따라 동작합니다. 컴파일러는 devtool이 무엇인지, 조직이 왜 그것을 배포하지 않으려 하는지, 고가용성이 팀에 중요하다는 것을 알지 못합니다. 그러한 의미는 정책의 규칙과 설정입니다. 역할, 페이로드, 결정 키에 대해서는 거버넌스 소켓을 참조하십시오.

파일

  • aggregate.yaml — 데이터베이스와 그에 연결된 관리 UI입니다.
  • manifest.yaml — 각 컴포넌트 유형과 시크릿 Feature를 해당 Docker Compose Recipe에 바인딩합니다.
  • release.yaml — 유일한 Release입니다.
  • .aggrega-config.yaml — 팀의 파일로, 기본 레지스트리와 팀의 연결입니다.
  • policies/team.rego — 팀의 규칙입니다.
  • org/config.yaml — 조직의 전역 구성 파일과 그 연결입니다.
  • org/policies/estate.rego — 조직의 규칙입니다.
  • pipeline/.aggrega-config-append-ci.yaml — 파이프라인의 오버레이로, 이 디렉터리로 복사되면 읽힙니다.
  • build-release.sh — Release를 빌드하고, 동등한 aggrega build 명령을 출력합니다.
  • check.sh — 빌드 다섯 개를 실행하고 각 결과를 확인합니다.