거버넌스 소켓
소켓의 한 역할이 아니라 소켓 전체를 다룹니다. 네 가지 역할(빌드를 판정하는 두 역할과 빌드를 형성하는 두 역할), 컴파일러에 포함된 두 정책 엔진, 그리고 운영자가 플러그인을 연결하는 방법을 설명합니다.
운영자는 빌드를 검사하고 발견한 내용에 따라 조치하도록 Wasm 거버넌스 플러그인을 연결합니다. 컴파일러 호스트는 내용에 중립적이고 주관이 없는 상태를 유지합니다. 호스트는 빌드 페이로드를 게스트로 전달하고 게스트가 반환한 결과에 따라 조치할 뿐, 정책 자체를 해석하지 않습니다. 정책 언어, 그 엔진, 규칙 등 도메인 정책에 관한 모든 지능은 게스트 안에 있습니다.
이는 모든 소켓이 따르는 것과 동일한 사전(ahead-of-time) 순수성 계약입니다. 게스트는 전달받은 페이로드를 평가하고, 호스트가 그대로 소비하는 결과를 반환합니다 (샌드박스 계약 참조). 호스트는 게스트가 사용하는 정책 언어에 대해 아무것도 알지 못하며, 자체 정책 엔진 코드를 전혀 포함하지 않습니다.
거버넌스 플러그인은 정확히 하나의 역할에 연결되며, 어떤 페이로드가 도착하는지와 연결이 그 페이로드로 무엇을 할 수 있는지는 플러그인이 아니라 역할이 정합니다. 두 역할은 판정(verdict) 역할입니다. 연결은 빌드를 판정하고, 호스트는 반환된 판정마다 세 가지 조치 중 정확히 하나를 수행합니다. 나머지 두 역할은 변환(transform) 역할입니다. 연결은 빌드의 레이블 또는 어노테이션에 대한 변경을 보고하고, 호스트는 그 변경을 적용합니다. 둘 이상의 역할을 수행하는 플러그인은 역할마다 한 번씩 연결되며, 플러그인 자체는 역할을 선언하지 않습니다. 역할은 연결이 지닙니다.
이 페이지는 거버넌스 소켓을 종합적으로 다룹니다. 네 가지 역할과 각 역할이 전달하는
페이로드, 호스트가 조치하는 판정 심각도, 운영자가 제공하는 엔진에 구애받지 않는
입력 채널, 컴파일러에 포함된 두 정책 엔진(하나는 Rego를, 하나는 CEL을 평가)
각각에 맞는 정책 작성 방법, 게스트가 외부 정책 엔진을 감싸는 방법, 함께 제공되는
참조 게스트, 그리고 운영자가 워크스페이스에 플러그인을 연결하는 방법을 설명합니다. 파이프라인에서 소켓이 차지하는 위치와 타입이 지정된 와이어 형태는
plugin-contract.md를 참조하십시오. 플러그인을 카탈로그 엔터티로
작성하고 게시하는 방법은
Wasm 플러그인 개발자 가이드를 참조하십시오.
멘탈 모델: 호스트는 라우팅하고, 게스트는 결정한다
빌드 시 호스트는 어태치먼트의 역할에 맞는 페이로드를 조립하여 ABI 경계 너머로 전달하고, 게스트가 반환한 것을 다시 읽습니다. verdict 역할에서 그것은 판정(verdict)의 목록이며, 각 판정은 심각도와 사람이 읽을 수 있는 메시지를 담습니다. 호스트는 각 심각도를 빌드 동작에 대응시키며, 메시지의 의미를 읽지 않고, 정책이 무엇을 검사했는지 알지 못하며, 어떤 엔진이 그 결정을 내렸는지도 알지 못합니다. transform 역할에서 그것은 수행할 변경이며, 해당 역할이 관할하는 레이블 또는 어노테이션만을 대상으로 하고 그 밖의 어떤 것도 대상으로 하지 않습니다.
호스트는 정책 내용을 해석하지 않으므로, 정책 표면 전체는 게스트의 것입니다. 규칙을 어떤 언어로 작성하는지, 어떤 엔진이 규칙을 평가하는지, 규칙의 발동이 어떻게 판정이나 변경이 되는지가 모두 게스트에 속합니다. 소켓 계약은 설계상 좁게 정의되어 있습니다. 즉 하나의 역할, 일련의 입력, 하나의 결과이며, 이는 Wasm으로 컴파일되는 어떤 정책 기술이든 이 소켓을 담당할 수 있게 하기 위함입니다.
verdict 역할은 수락하거나 거부할 뿐 그 밖의 일은 하지 않습니다. 호스트는 그 출력을 결정으로만 읽고 결코 변경으로 적용하지 않으므로, 정책이 규정을 준수하지 않는 빌드를 조용히 준수 상태로 바꿔 놓을 수 없습니다. transform 역할은 의도된 예외이며, 이를 예외로 만드는 것은 운영자가 그것을 어태치했다는 사실입니다. 레이블을 다듬도록 플러그인을 어태치하는 것은 레이블을 다듬겠다는 선언입니다. 그러한 어태치먼트가 변경할 수 있는 범위는 자신의 역할 표면으로 한정되며, 그 범위를 벗어나는 것이 있으면 빌드는 명시적으로 중단됩니다.
네 가지 역할
플러그인은 정확히 하나의 역할에 연결되며, 역할은 호스트가 파이프라인의 어느 지점에서 플러그인을 평가하는지, 플러그인이 어떤 페이로드를 받는지, 무엇을 반환할 수 있는지를 정합니다. 두 역할을 수행해야 하는 플러그인은 역할마다 한 번씩, 두 번 연결합니다.
판정 역할: ir-verdict와 render-verdict
ir-verdict— 게스트가 렌더링 전에 중간 표현(IR) 그래프를 대상으로 판단합니다. 페이로드에는 기능에 구애받지 않는 전체 IR 그래프(컴파일러가 보유한 모든 노드, 엣지, 연결)와 함께 분석기가 열거한 라우팅 경로가 담기므로, 정책은 그래프를 다시 순회하지 않고도 토폴로지와 도달 가능성을 판단할 수 있습니다. 이 경로 목록은 시작 노드별로 상한이 있습니다 — 조밀하게 연결되었거나 순환하는 토폴로지에는 열거가 내보내는 것보다 많은 서로 다른 경로가 있을 수 있으며, 상한에 도달하면 해당 시작 노드에서 나머지 경로는 나열되지 않습니다. 따라서 목록에 있는 경로는 실제로 존재하지만, 경로가 없다고 해서 경로가 존재하지 않는다는 증거가 되지는 않습니다. 어떤 것이 도달 불가능한지에 따라 판정이 달라지는 정책은 경로 목록만으로 판단하지 말고, 페이로드에 온전히 담긴 노드와 엣지로부터 이를 확인해야 합니다. 그래프에서 한 가지는 작성된 그대로가 아닙니다. 작성자가 민감하다고 선언한 모든 값은 — 연결의values나infra, 경계 연결의infra, 노드 자체의values나infra, 또는 커넥션 자체의values나infra에 있든 — 보류 마커{"aggrega_withheld": "declared"}로 전달되며, 그 키, 민감도 표시, 그리고 그 옆의 선언되지 않은 모든 값은 작성된 그대로 전달됩니다. 정책은 민감하다고 선언된 자료가 어디로 이동하는지를 판단할 뿐 그 자료를 받지는 않습니다. 거버넌스 정책이 읽는 연결 정보를 참고하십시오.ir-verdict정책은 아티팩트가 생성되기 전, 정적 분석 게이트에서 실행됩니다. 아키텍처와 연결 구성에 관한 정책 — 토폴로지 불변식, 경계 간 인증, 자격 증명 흐름의 형태 — 처럼 무엇이든 렌더링하기 전에 빌드를 중단해야 하는 정책에 사용합니다.render-verdict— 게스트가 렌더링 후에 렌더링된 출력을 대상으로 판단합니다. 페이로드에는 경로순으로 정렬된 생성 아티팩트가 담기므로, 동일한 입력으로 실행하면 전송 데이터가 바이트 단위로 동일합니다. 각 아티팩트에는 출력 경로와 렌더링된 텍스트가 담기며, 생성한 provider가 형식을 선언한 경우에는 렌더링된 형식이, 내용이 정책 실행 전에 파싱되는 형식인 경우에는 내용의 파싱된 구조화 뷰가 추가로 담깁니다.render-verdict정책은 빌드가 생성한 것을 정확히 그대로 보며, 그중 보류되는 것은 없습니다. Recipe가 아티팩트에 렌더링한 값은 렌더링된 그대로 전달되는데, 정책이 판단하는 대상이 아티팩트이기 때문입니다. 구체적인 출력에 관한 정책 — 예를 들어 렌더링된 Docker Compose 서비스나 Kubernetes 객체를 검사하는 규칙 — 에 사용합니다.
변환 역할: annotation-transform과 label-transform
-
annotation-transform— 게스트가 해석 중, 어노테이션 확장 전에 추가할 어노테이션을 보고합니다. 페이로드에는 연결이 어노테이션을 달 수 있는 모든 component가 각각 이미 가진 어노테이션과 함께 담기며, Manifest가 바인딩을 등록한 어노테이션 키도 담깁니다. 등록된 키로 주입된 어노테이션은 이어서 Feature 연결로 확장되며, 이 역할은 이런 방식으로 개발자가 입력하지 않은 기능을 빌드에 추가합니다.어노테이션을 붙일 수 있는 컴포넌트는 경계가
components:아래에 지정하는 모든 컴포넌트와, 경계의aggregates:라우팅 항목이 라우팅해 들이는 모든 컴포넌트입니다. 라우팅 항목은 자신의components:가 그 모두를 지정하든, 일부를 지정하든, 아무것도 지정하지 않든(documents: {}는 아무것도 지정하지 않습니다) 그 모듈의 모든 컴포넌트를, 그 안에 중첩된 모듈의 컴포넌트까지 포함하여 배치하며, 페이로드는 그 각각을 담습니다. 라우팅된 컴포넌트는 빌드 그래프에서 가지는 ID로 지정됩니다. 모듈 이름, 점, 그리고 모듈 안에서의 컴포넌트 이름으로 이루어지며documents.backend와 같고, 중첩된 모듈마다 모듈 이름과 점이 하나씩 더 붙습니다. 이것이 빌드 그래프와 그 진단이 표기하는 방식이므로 결정도 그렇게 지정합니다. 라우팅 항목이 지정하지 않고 배치한 컴포넌트는 페이로드에서 자체 어노테이션을 가지지 않으며, 그 컴포넌트에 주입된 어노테이션은 라우팅 항목 아래에서 그 컴포넌트에 작성된 것으로 적용됩니다. -
label-transform— 게스트가 토폴로지 구성 중, 즉 그래프가 빌드된 후 그래프를 판단하기 전에 적용할 레이블 변경을 보고합니다. 페이로드에는 빌드 노드의 투영 — 각 노드가 인스턴스화하는 Component, 그에 대해 해석된 버전, 현재 가진 레이블, 그리고 해당 인스턴스가 선언하는 값(읽기 전용이며, 그 Component가 민감하다고 선언한 모든 값은 그래프 판정에서와 마찬가지로 보류됨) — 과 함께 Release의 이름과 환경이 담깁니다. 개발자가 직접 입력할 필요가 없어야 하는 파생 메타데이터(컴플라이언스 범위, 소유권, 비용 귀속)와, 개발자가 선언한 구성에 따라 부여되는 capability 레이블에 사용합니다.
역할마다 페이로드가 다른 것은 각 역할이 서로 다른 시점에 작동하고 서로 다른 질문에 답하기 때문입니다. 네 역할 모두 아래에 설명하는 동일한 운영자 제공 입력 채널을 가집니다. 페이로드에 대해 읽는 대신 직접 보려면 aggrega build --release <release> --policy-input <dir>를 사용합니다. 이 명령은 각 역할이 거기에 연결된 플러그인에 넘기는 페이로드를(아무것도 연결되지 않은 역할도 포함하여) 역할마다 하나의 JSON 파일로, 또는 한 역할의 연결들이 서로 다른 페이로드를 받는 경우에는 연결마다 하나의 파일로 기록하며, --dry-run과 함께 쓰면 그 파일들만 기록하고 다른 것은 아무것도 하지 않습니다. annotation-transform, label-transform, ir-verdict에서는 그 파일이 정책이 읽는 input 문서입니다. render-verdict에서는 정책이 읽기 전에 정책 엔진이 페이로드를 재구성하므로(각 아티팩트의 documents는 거기에서 파싱됩니다), 컴파일러에 내장된 엔진의 render-verdict 정책은 빌드를 차단하기 전에 정책 테스트하기에서 보여 주듯이 warn 또는 info로 연결하여 빌드 안에서 테스트합니다. 직접 .wasm을 빌드한 플러그인이라면 aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json으로 그 파일에 대해 실행합니다.
판정과 심각도
아래의 심각도는 판정 역할의 어휘입니다. 변환 역할은 판정이 아니라 변경을 보고하므로 심각도를 갖지 않습니다.
게스트는 판정 목록을 반환합니다. 각 판정은 빌드 동작을 결정하는 심각도를 가집니다.
halt— 빌드를 중지합니다. 호스트는 판정의 메시지를 사유로 표시합니다. 빌드는 아티팩트를 생성하지 않습니다.warn— 판정을 표시합니다. 빌드는 계속 진행됩니다.info— 판정을 기록합니다. 빌드 결과는 바뀌지 않습니다.
이 세 가지가 전부이며, 다른 모든 소켓의 진단이 사용하는 것과 같은 세 가지이므로 심각도는 어디에서 읽든 같은 의미를 가집니다.
그 밖의 값을 가진 판정은 네 번째 경로가 아니라 계약 위반입니다. 빌드는 중지되고, 메시지에는 플러그인, 판정이 가진 값, 계약이 선언하는 세 가지 값이 명시됩니다. 따라서 철자가 틀린 심각도는 아무것도 처리하지 않는 판정으로 넘어가지 않고 빌드 오류로 보고됩니다. 세 가지 값 중에서 보고하는 게스트는 영향을 받지 않습니다.
허용하는 평가는 아무것도 반환하지 않습니다. 게스트는 규칙이 발동할 때만 판정을 내보내므로, 빈 판정 목록은 정책이 빌드를 허용했다는 뜻입니다. 내보낼 “통과” 판정은 없으며, 침묵이 곧 허용입니다.
게스트는 한 번의 평가에서 심각도가 섞인 여러 판정을 반환할 수 있습니다. 호스트는 이를 모두 검토합니다. halt가 하나라도 있으면 빌드가 중지되고(모든 halt 메시지가 표시됨), warn과 info 판정은 빌드를 막지 않고 보고됩니다. 이는 빌드를 중지하는 정책과 권고성 린트 검사를 구분하는 중지 대 권고의 분리를 반영합니다.
with 채널: 소스와 설정
정책 게스트는 보통 자신이 적용하는 구체적인 규칙에 대해 범용적입니다. 엔진은 게스트에 내장되어 있지만, 규칙은 연결마다 제공됩니다. with 채널은 이 연결별 입력을 전달합니다. 이 채널에는 엔진에 구애받지 않는 두 개의 필드가 있습니다.
sources— 게스트가 로드하는 정책 정의 파일입니다. 호스트는 지정된 각 파일을 빌드 시점에 읽어 그 바이트를 불투명하게 게스트에 전달합니다. 호스트는 소스를 파싱하지 않으며, 게스트에 넘기는 경로는 파일의 기본 이름이고 호스트의 절대 경로는 결코 넘기지 않습니다. 바이트가 무엇을 의미하는지는 전적으로 게스트의 몫입니다. 어떤 게스트에게는.rego파일이고, 다른 게스트에게는 다른 정책 형식이며, 정책 세트 전체를 base64로 인코딩한 아카이브를 읽는 게스트에게는 그런 아카이브입니다.settings— 게스트가 자신의 엔진에 매핑하는 구성 맵입니다. 게스트는 조정 가능한 값(레플리카 상한, 필수 레이블 키 등)을 이 맵에서 읽습니다. 기본적으로 호스트는 이 맵에 대해 아무 동작도 하지 않고 그대로 전달합니다. 게스트는 추가로 이 맵에 대한 스키마를 선언할 수 있으며(아래 참조), 이 경우 호스트는 게스트를 실행하기 전에 그 스키마로 맵을 검증합니다.
완전히 내장된 게스트, 즉 규칙이 연결 시점에 제공되지 않고 컴파일되어 들어간 게스트는 with를 완전히 생략합니다. 이 채널은 모든 역할에서 선택 사항입니다.
타입이 지정된 설정
게스트는 자신이 기대하는 settings에 대한 JSON Schema를 선언할 수 있습니다. 선언한 경우, 호스트는 게스트를 실행하기 전에 연결의 settings를 그 스키마로 검증합니다. 스키마를 따르지 않는 설정은 문제가 된 키와 스키마가 기대한 내용을 명시하는 메시지와 함께 빌드를 중단시킵니다. 누락된 필수 키, 잘못된 타입의 값, 알 수 없는 키, 범위를 벗어난 값은 알기 어려운 게스트 실패나, 더 나쁘게는 잘못되었지만 성공한 빌드로 드러나는 대신 사전에 잡힙니다.
타입이 지정된 설정은 선택 사항이며, 호스트가 아니라 게스트가 선언합니다. 설정 스키마를 선언하지 않은 게스트는 자유 형식 동작을 유지합니다. 호스트는 그 settings를 검사 없이 전달합니다. 호스트는 게스트가 선언한 스키마에 대해 일반적인 JSON Schema 검증을 실행할 뿐, 설정이 무엇을 의미하는지는 해석하지 않습니다. 이로써 검사가 엔진에 중립적으로 유지됩니다. 각 게스트는 자신이 읽는 설정의 형태를 기술하고, 호스트는 정확히 그 형태만을 적용하며 그 이상은 하지 않습니다.
설정을 선언하지 않은 연결은 JSON null로 검증됩니다. 이 덕분에 게스트는 설정을 필수로 만들 수 있습니다. 객체만 허용하는 스키마는 설정을 제공하지 않는 연결을 거부하고, 빌드는 중단됩니다. 그 결과는 반대 방향으로도 작용하며, 의도적으로 고려해 작성해야 하는 것은 바로 이쪽입니다. 설정이 실제로 선택 사항인 게스트는 객체뿐 아니라 null도 허용하는 스키마를 선언해야 하며, 그렇지 않으면 설정 없이는 전혀 연결할 수 없습니다. 컴파일러에 내장된 두 정책 엔진이 "type": ["object", "null"]을 선언하는 것도 정확히 이 때문입니다. with: 블록 없이 연결하면 기본값으로 실행됩니다. "type": "object"만 선언한 게스트는 의도했든 아니든 설정을 필수로 만든 것입니다.
ABI는 Aggrega 고유의 것입니다
소켓 계약은 어떤 정책 엔진의 ABI가 아니라 Aggrega 고유의 ABI입니다. 그렇기 때문에 Wasm으로 컴파일된 어떤 정책 기술이든
그대로 끼워 넣는 게스트로 사용할 수 있습니다. 게스트는 바깥쪽으로 Aggrega 인터페이스, 즉 describe()와 게스트가 맡은 역할이 호출하는 export를 사용하며,
어떤 엔진을 사용하는지는 그 인터페이스 뒤에 있는 구현 세부 사항입니다.
외부 정책 엔진을 감싸는 게스트는 그 엔진의 ABI를 자신의 내부에 흡수합니다. 엔진에 자체 Wasm ABI, 자체 진입점 또는 자체 호스트 콜백 프로토콜이 있으면, 감싸는 게스트가 내부에서 엔진을 인스턴스화하고 구동하며 엔진의 결정을 소켓의 판정 형태로 다시 매핑합니다. 컴파일러 호스트는 표준 거버넌스 판정 인터페이스만 볼 뿐, 어떤 엔진이 관여하는지 전혀 알지 못하며 엔진별 코드도 포함하지 않습니다. 정책을 한 엔진에서 다른 엔진으로 바꾸는 것은 호스트 변경이 아니라 연결 변경입니다.
컴파일러에 내장된 두 가지 정책 엔진
두 가지 정책 엔진이 CLI 바이너리에 컴파일되어 들어 있으며, 운영자는 다른 거버넌스 플러그인을 연결하는 것과 같은 방식으로 둘 중 하나 또는 둘 모두를 연결합니다.
| 좌표 | 정책 언어 | 연결되는 소스 |
|---|---|---|
governance/rego | Rego | .rego 파일 또는 전체 정책 세트를 base64로 인코딩한 아카이브 |
governance/cel | Common Expression Language(CEL) | .cel 표현식 파일 또는 .yaml / .yml 규칙 문서 |
언어 외의 모든 것은 공유됩니다. 두 엔진 모두 네 가지 역할을 모두 수행하고, 같은
필드 이름으로 같은 역할별 페이로드를 읽으며, 같은 translation 설정을 통해 결정을
같은 세 가지 판정 심각도에 매핑하고, 평가할 수 없었던 빌드를 허용하는 대신 명시적으로
실패합니다. 각 엔진은 자신을 포함하여 배포하는 컴파일러 릴리스를 버전으로 가지며, 어느 쪽도 외부
도구 체인이 필요하지 않고 빌드 시점에 아무것도 가져오지 않습니다. 다만 각 언어가 표현할 수 있는 것은
공유되지 않습니다. Rego에서는 몇 개의 헬퍼 규칙으로 되는 규칙이 CEL에서는 설정과 반복이
필요할 수 있습니다. 경로를 순회하는 규칙을 작성하기 전에 표현식이 표현할 수 있는 것을
참조하십시오.
다른 점은 규칙을 작성하는 언어이며, 그것이 선택의 유일한 근거입니다. 이미 Rego 코퍼스를 유지하고 있는 조직이나 다른 곳에서 승인 제어용 Rego를 작성하는 팀은 Rego 엔진을 연결하면 기존 정책이 그대로 실행됩니다. Kubernetes validating-admission 정책처럼 규칙을 문서에 대한 단일 표현식으로 표현하는 팀은 CEL 엔진을 연결합니다. 두 엔진은 역할별로 연결되므로, 워크스페이스는 한 역할에서는 Rego를, 다른 역할에서는 CEL을 실행하거나, 같은 역할에서 두 개의 연결로 둘 다 실행할 수 있습니다.
호스트는 결정이 둘 중 어느 쪽에서 왔는지에 구애받지 않습니다. 호스트는 페이로드를 라우팅하고, 판정이나 변경을 다시 읽어 들여 그에 따라 동작합니다. 정책을 한 언어에서 다른 언어로 전환하는 것은 연결의 변경과 규칙의 재작성이며, 결코 호스트의 변경이 아닙니다.
Rego 정책: 두 가지 길
Rego는 널리 쓰이는 정책 언어이며, 이를 실행하는 길은 두 가지입니다. 컴파일러에 포함되어 제공되는 부담이 적은 엔진과, 완전한 충실도를 갖춘 탈출구입니다.
컴파일러에 포함된 Rego 엔진은 부담이 적은 길입니다. 이 엔진은 Wasm 네이티브 Rego 평가기를 갖추고 있으므로, 운영자는 .rego 파일을 sources에 넣고 플러그인을 연결하기만 하면 됩니다. 외부 툴체인이 필요 없고, 빌드 시점에 가져오는 것도 없습니다. 이 엔진은 네 가지 역할을 모두 수행합니다. 같은 플러그인이 연결된 역할에 따라 빌드 그래프를 판정하거나, 렌더링된 출력을 판정하거나, 레이블을 구성하거나, 어노테이션을 주입합니다. 카탈로그상의 식별자는 pluginType: governance 아래의 이름 rego 그 자체, 즉 좌표 governance/rego이며, 버전은 이를 제공하는 컴파일러 릴리스입니다. 이 엔진용 정책 작성은 다음 절에서 다룹니다.
이 평가기는 참조 구현을 내장하지 않고 Rego를 독립적으로 재구현하며, 모든 Rego 내장 함수를 구현하지는 않습니다. 정책이 평가기가 구현하지 않은 내장 함수를 호출하면 연결은 명시적으로 실패합니다. 즉 허용이 아니라 오류를 반환합니다. 그러면 빌드는 플러그인을 지명하는 오류와 함께 중단됩니다. 이는 의도적으로 halt 판정과 구별되므로, “엔진이 이 정책을 평가할 수 없다”가 “정책이 빌드를 허용한다”로 오인되는 일은 없습니다. 평가할 수 없는 정책은 빌드를 중단시키며, 조용히 통과되는 일은 없습니다.
opa build -t wasm 탈출구는 완전한 충실도를 갖춘 길입니다. 정책에 전체 내장 함수 집합이나 참조 엔진의 정확한 의미 체계가 필요하다면, OPA 자체 툴체인으로 정책을 Wasm 모듈로 컴파일하고 그 모듈을 얇은 어댑터 게스트 뒤에서 실행합니다. 어댑터는 OPA의 Wasm ABI를 전적으로 자기 내부에서 흡수합니다(위의 ABI는 Aggrega 고유의 것입니다 참조). 어댑터는 OPA로 빌드된 모듈을 인스턴스화하고, 입력을 설정하고, 평가를 호출한 뒤, 결정을 판정 형태로 다시 매핑합니다. 호스트는 표준 거버넌스 판정 인터페이스만 봅니다.
참조용 어댑터 게스트가 실제 예제로 제공됩니다. 이 어댑터는 Rego로 작성하고 opa build -t wasm으로 WebAssembly 모듈로 미리 컴파일한 정책을 내장합니다. 이 모듈은 고정되어 저장소에 커밋된 산출물이므로, 평가는 OPA 프로세스 없이 그리고 아무것도 가져오지 않고 전적으로 게스트 안에서 실행됩니다. 빌드할 때마다 어댑터는 내장된 Wasm 인터프리터로 그 고정된 모듈을 자기 내부에서 인스턴스화하고, 모듈 자체의 임포트(선형 메모리와 내장 함수 콜백)를 충족시키며, 페이로드를 OPA input 문서로, 연결의 settings를 OPA data 문서로 읽고, 컴파일된 각 엔트리포인트를 평가한 뒤, 각 엔트리포인트의 deny / warn / audit 엔트리포인트 이름을 각각 판정 심각도 halt, warn, info로 매핑합니다. 고정된 정책이 어댑터가 구현하지 않은 호스트 제공 내장 함수를 필요로 하면 어댑터는 명시적으로 실패합니다. 허용을 반환하지 않고 모듈을 거부하므로, 평가할 수 없는 정책은 조용히 통과하지 않고 빌드를 중단시킵니다. Rego 소스에서 고정된 모듈을 다시 생성하는 것은 OPA CLI로 실행하는 작성 단계이며, 빌드 시점의 의존성이 아닙니다. ../examples/policy-data-class-route/는 자체 모듈을 중심으로 그 어댑터를 빌드하며, 둘 다 다시 생성하는 명령을 제공합니다.
두 길은 같은 호스트 계약을 공유하므로, 정책을 컴파일러에 포함된 엔진에서 전체 엔진으로 옮기는 것은 연결 변경에 불과합니다.
Rego 엔진용 정책 작성하기
엔진은 운영자가 작성한 Rego를 네 가지 역할 중 연결된 역할에서 전적으로 게스트 내부에서 평가합니다. 하나의 엔진을 두 역할에 서로 다른 두 정책 파일로 두 번 연결하면, 같은 빌드의 두 시점을 하나의 엔진으로 다룰 수 있습니다.
연결의 역할에 해당하는 페이로드가 정책의 input 문서가 되고, 연결의 settings 객체가 정책의 data 문서가 됩니다. 따라서 정책은 운영자가 제공한 임계값을 data.max_replicas로 읽습니다. 연결이 sources 아래에 선언한 모든 파일은 정책 모듈이 되며, 그 파일들이 선언한 모든 패키지가 평가됩니다.
정책이 작성된 규칙 구문
Rego는 두 가지 규칙 구문으로 작성되며, 엔진은 모듈 단위로 두 구문을 모두 받아들입니다. 따라서 현재 구문이 생기기 전에 구성된 정책 세트도 오늘 작성된 정책과 같은 연결 안에서 함께 평가됩니다.
현재 구문에서는 규칙 본문이 if로 시작하고, 집합으로 수집하는 규칙은 contains로 이를 나타내며, 모듈은 패키지 선언 아래 별도의 줄에 import rego.v1을 선언하여 어떤 구문으로 작성되었는지 밝힙니다:
package example
import rego.v1
deny contains msg if { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}이전의 대괄호 헤드 구문에서는 규칙이 수집하는 값이 규칙 헤드의 대괄호 안에 있고 본문이 그 바로 뒤에 옵니다. 이 구문의 모듈은 아무것도 선언하지 않습니다. 현재 구문으로 파싱되지 않는다는 점으로 식별되기 때문입니다:
package example
deny[msg] { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}아무것도 선언하지 않으면서 현재 구문으로 파싱되는 모듈은 이름을 밝혀 거부됩니다. 선언이 해석을 확정하며, 선언이 없으면 같은 규칙 텍스트가 정반대의 결정에 이를 수 있습니다. 결코 성립하지 않는 규칙 본문은 현재 구문에서는 결정을 내지 않지만 이전 구문에서는 결정을 하나 냅니다. 그래서 침묵해야 했던 정책이 빌드를 중단시키고, 반대의 경우에는 규칙이 막으려고 작성된 빌드를 통과시킵니다. 엔진은 이런 모듈에 대해 해석을 임의로 고르는 대신 모듈을 거부하고 무엇을 추가해야 하는지 알려 줍니다:
policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.이 거부는 판정이 아니라 플러그인 이름을 밝히는 빌드 오류이므로, 평가할 수 없는 정책과 마찬가지로 빌드를 중단시키며 빌드를 허용한 정책으로 읽히는 일이 없습니다.
예상치 못하게 당황하기 전에 알아 둘 만한 경계 사례가 두 가지 있습니다. 규칙 본문이 전혀 없는 모듈, 즉 데이터만 선언하는 모듈은 현재 구문으로 파싱되므로, 두 해석이 달라질 수 없는 경우인데도 선언을 요구받습니다. 그리고 이전 구문으로 작성된 모듈은 현재 구문으로 파싱되지 않으므로 결코 거부되지 않습니다. 둘을 구별하는 것은 엔진 자체이므로, 의도적으로 작성한 대괄호 헤드 정책이 선언을 빠뜨린 현재 구문 정책으로 오인되는 일은 없습니다.
정책은 결정을 결정 키 아래에 수집합니다
모든 역할은 정책의 결정을 결정 키, 즉 정책이 수집 대상으로 삼는 이름 있는 규칙에서 읽습니다. 어떤 키를 읽는지, 그리고 한 키 아래의 결정이 무엇을 뜻하는지는 역할이 정합니다.
판정 역할에서 결정은 메시지이며, 그 메시지가 수집된 키가 메시지를 보고할 심각도를 정합니다. 기본적으로 키는 관례적인 Rego 수집 이름입니다:
| 수집 키 | 보고 심각도 | 빌드에 미치는 영향 |
|---|---|---|
deny | halt | 빌드를 중단합니다 |
warn | warn | 완료되는 빌드와 함께 표시됩니다 |
audit | info | 기록되며, 빌드 결과는 바뀌지 않습니다 |
두 어휘는 서로 다른 것이므로 구분해야 합니다. deny, warn, audit는 정책의 이름이고, halt, warn, info는 소켓이 보고하는 심각도입니다. 왼쪽 열은 이름을 바꿀 수 있고, 오른쪽 열은 모든 소켓이 공유하는 닫힌 집합입니다.
결정의 이름을 다르게 짓는 정책은 연결의 설정에서 매핑을 선언합니다:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warn선언된 매핑은 기본값을 확장하지 않고 대체합니다. 매핑이 지정한 키만 정확히 읽히므로, 위의 매핑을 선언한 뒤에도 여전히 deny로 수집하는 정책은 아무 판정에도 이르지 못합니다. 규칙이 선언된 순서가 판정이 보고되는 순서입니다. 정책이 선언하지 않은 키는 실패가 아니라 결정이 없는 것이므로, 하나의 정책 파일이 여러 연결에 쓰일 수 있습니다.
세 가지 이외의 심각도와 비어 있게 선언된 매핑은 플러그인이 선언한 설정 스키마에 의해 거부됩니다. 호스트는 디스패치 전에 연결의 설정을 이 스키마로 검증합니다. 같은 키를 두 번 매핑하면 매핑을 읽을 때 거부되며, 이 역시 어떤 정책도 실행되기 전입니다. 어느 경우든 빌드는 결정에 이르기 전에 중단되며, 매핑이 절반만 적용된 상태로 중단되는 일은 없습니다.
그 밖의 설정은 정책 자체의 데이터입니다. 매핑은 객체에서 읽혀 나오고 객체는 변경 없이 정책의 data 문서에 전달되므로, 기본 키용으로 작성된 정책은 매핑을 전혀 구성하지 않았을 때와 정확히 같은 데이터 문서를 봅니다.
변환 역할에서 결정은 메시지가 아니라 적용할 변경이므로, 정할 심각도가 없고 대신 키가 고정됩니다. 레이블 형성 역할에서는 labels, 어노테이션 주입 역할에서는 annotations입니다. translation 설정은 판정이 보고되는 곳에서만 읽히므로, 이를 선언한 변환 연결은 해당 역할이 사용하지 않는 설정을 지니고 있는 것입니다.
결정 키는 연결이 로드하는 모든 패키지에서 읽힙니다. 따라서 정책 세트는 규칙을 여러 패키지에 나누어 둘 수 있으며, 각 패키지는 수집한 것을 기여합니다. 그 이면은 문제가 되기 전에 알아 둘 만합니다. 한 연결 안에서 결정 키는 모든 패키지에서 예약된 규칙 이름이므로, 자체 목적으로 우연히 labels에 수집하는 헬퍼 패키지는 그 항목이 레이블 결정으로 읽힙니다. 이는 조용히 넘어가지 않고 명확하게 실패합니다. 연결은 키 아래 수집된 무언가가 그 형태의 결정이 아니라고 보고합니다. 하지만 이런 메시지는 이름 충돌로 읽는 것이 가장 빠르므로, 키는 결정용으로 남겨 두고 헬퍼 규칙에는 다른 이름을 붙이십시오.
각 역할의 페이로드가 노출하는 것
페이로드는 정책의 input 문서이므로, 정책은 와이어가 부여한 이름으로 페이로드를 읽습니다.
빌드 그래프는 그래프를 전달하는 두 역할에서 서로 다른 경로에 있습니다. 그래프에 대한 판정은 그래프 문서 전체를 받으므로 노드는 input.graph.spec.nodes에 있고, 레이블 형성 역할은 노드의 투영을 받으므로 노드는 input.graph.nodes에 있습니다. 따라서 두 역할 사이에서 옮기는 규칙은 복사하는 것이 아니라 수정해야 합니다. 이를 잊으면 오류가 아니라 절대 발동하지 않는 규칙이 증상으로 나타나는데, 존재하지 않는 경로는 단순히 정의되지 않은 것으로 취급되기 때문입니다.
| 역할 | 정책이 읽는 것 |
|---|---|
ir-verdict | input.graph — 빌드 그래프 문서 전체: 노드는 노드 id를 키로 input.graph.spec.nodes에, 엣지는 input.graph.spec.edges에 있습니다. 작성자가 민감하다고 선언한 값은 {"aggrega_withheld": "declared"}로 읽힙니다. input.precalculated_paths — 열거된 라우팅 경로로, 각 경로는 순서가 있는 nodes 목록과, 경로 어디에든 연결된 Feature 유형인 attached_features를 담습니다(아래 참조). 이 목록은 항상 존재합니다. 컴포넌트 간 경로가 없는 빌드는 빈 목록을 담습니다. |
render-verdict | input.artifacts — 출력된 파일마다 하나의 항목으로, 각각 path, content, format, 그리고 파일의 파싱된 문서인 documents를 가집니다. format은 그 파일을 렌더링한 프로바이더가 파일에 대해 선언한 형식입니다. Terraform 프로바이더는 출력하는 모든 .tf 파일에 hcl을, 모든 .tf.json 파일에 json을 선언하며, 벤더링된 모듈의 파일도 여기에 포함됩니다. 어떤 프로바이더도 형식을 선언하지 않은 경우에는 빈 문자열이며, Recipe가 경계의 공유 출력에 기여하는 파일이 그 예입니다. 그런 파일도 확장자에 따라 파싱되므로 어느 경우든 documents가 존재합니다. 구조적으로 읽을 수 없었던 아티팩트는 parse_error를 담고 문서는 담지 않으므로, 정책은 읽을 수 없는 파일을 검사 없이 통과시키는 대신 그 실패 자체를 근거로 거부할 수 있습니다. |
label-transform | input.graph.nodes — 노드 id를 키로 하는 빌드의 노드로, 각각 component, resolved_version, labels, values를 가집니다. 마지막 항목은 노드의 인스턴스가 Aggregate에서 선언하는 값으로, 템플릿이 그 매개변수에 대해 평가된 상태이며, 아무것도 선언하지 않으면 없습니다. 노드의 Component가 민감하다고 선언한 값은 ir-verdict에서와 마찬가지로 {"aggrega_withheld": "declared"}로 읽히고, 선언되지 않은 형제 값은 작성된 그대로 읽힙니다. 규칙은 레이블을 결정하기 위해 input.graph.nodes[id].values를 읽지만, 값을 변경할 수는 없습니다. input.compilation_context — Release의 release_name과 environment로, 정책이 환경별로 다르게 결정할 수 있게 합니다. |
annotation-transform | input.targets — 연결이 어노테이션을 붙일 수 있는 모든 컴포넌트로, 각각 boundary_path, component_name(라우팅 항목이 배치하는 컴포넌트의 경우 metrics.query처럼 빌드 그래프에서의 ID), 그리고 Release가 컴포넌트 자체에 작성한 annotations를 가지며, 각 값은 작성된 그대로입니다. 즉 문자열, 하위 키의 객체, 또는 컴포넌트가 상속받을 어노테이션을 옵트아웃하는 경우 null입니다. 컴포넌트가 가진 모든 키는 값과 관계없이 존재하므로, 규칙은 누군가 이미 작성한 키를 건드리지 않고 둘 수 있습니다. input.binding_keys — Manifest가 바인딩을 등록한 어노테이션 키입니다. |
Terraform 리소스는 Terraform의 두 형식에서 각각 다른 경로로 읽힙니다. 네이티브 .tf 파일의 documents에서 블록은 그 유형 아래에, 그다음 각 레이블 아래에 중첩되며, 마지막 레이블은 블록 목록을 담습니다. 유형과 레이블이 같은 블록은 소스 순서대로 하나의 목록으로 모이기 때문입니다. 따라서 리소스 속성은 input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr>에서 읽습니다. 이름에 관계없이 RDS 인스턴스라면 input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage입니다. .tf.json 파일은 Recipe가 작성한 그대로 읽히므로, 이름이 블록 자체를 담는 통상적인 객체 형식은 resource.<type>.<name>.<attr>에서 읽히며, 두 형식을 모두 대상으로 하는 정책은 두 경로를 모두 읽습니다. 이는 컴파일러 내부의 두 정책 엔진 모두에 해당합니다. 다른 형식을 위해 작성된 Rego 규칙에서는 지정한 경로가 정의되지 않습니다. 그곳의 값을 검사하는 규칙은 절대 발동하지 않고, not으로 값의 부재를 근거로 거부하는 규칙은 모든 리소스에서 발동합니다. 다른 형식으로 인덱싱하거나 선택하는 CEL 표현식은 정책 파일을 지목하는 평가 오류로 빌드를 중단합니다. 아래 렌더 단계 정책 어댑터에서 설명하는 참조 Rego 렌더 어댑터는 네이티브 .tf 파일을 직접 파싱하고 단일 블록을 객체로 읽으므로, 정책을 이 어댑터와 컴파일러 내부 엔진 사이에서 옮길 때 Terraform 경로는 복사하는 것이 아니라 수정해야 합니다.
모든 역할은 추가로 input.sources — 연결 자체의 파일로, 각각 기본 이름 path와 content를 가짐 — 를 담습니다. 정책은 그 파일 중 하나로서만 실행되므로, 규칙이 이 목록을 읽는 곳에서는 목록에 적어도 그 파일이 들어 있습니다.
input.settings는 연결의 설정 객체로, 정책의 data 문서와 같은 객체이며, 연결이 설정을 선언하면 존재합니다. 연결이 아무것도 선언하지 않으면 규칙이 무엇을 보게 되는지는 역할에 따라 다릅니다. ir-verdict, label-transform, annotation-transform에서는 이 필드가 없으므로 input.settings는 페이로드에 없는 다른 경로와 마찬가지로 정의되지 않으며, render-verdict에서는 빈 객체입니다. 따라서 설정이 구성되었는지에 따라 달라지는 규칙은 객체가 아니라 자신이 읽는 설정을 검사하며, 이렇게 하면 모든 역할에서 똑같이 동작합니다. 구성된 max_nodes는 읽히고, 구성되지 않았으면 input.settings.max_nodes가 정의되지 않은 채로 남아 규칙은 아무것도 보고하지 않습니다:
package example
import rego.v1
deny contains msg if { limit := input.settings.max_nodes count(input.graph.spec.nodes) > limit msg := sprintf("this build declares more than %v nodes", [limit])}CEL 엔진은 선언되지 않은 설정 객체를 다르게 처리하며, 이는 아래 해당 엔진의 섹션에서 설명합니다.
attached_features와 binding_keys는 객체가 아니라 목록이므로, 정책은 in으로 포함 여부를 검사합니다:
package security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some gateway in path.nodes input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"] not "core/data-masking" in path.attached_features msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])}attached_features는 경로상의 모든 노드가 가진 모든 연결의 Feature 유형의 합집합입니다. 해당 노드의 연결(connection) 중 하나에 작성된 연결도, 어느 연결에 작성되었든 포함됩니다. 따라서 이 규칙은 게이트웨이 자체에 있는 core/data-masking 연결로 충족되며, 그 Feature는 바로 그곳에 연결됩니다. 게이트웨이가 선언한 콘텐츠 마스킹 기능을 기준으로 선택하기 때문입니다. 이 연결이 마스킹하는 것은 해당 게이트웨이를 통과하는 채팅 및 완성 텍스트이며, 규칙은 연결이 무엇을 나열하는지가 아니라 연결이 존재하는지를 확인합니다.
경로 전체에 대한 합집합이므로, 이 목록은 Feature가 경로 어딘가에 연결되어 있다는 것만 알려 줄 뿐 어디인지는 알려 주지 않습니다. Feature가 경로의 특정 두 컴포넌트 — 제한된 데이터를 보유한 컴포넌트와 그것이 도달하는 컴포넌트 — 사이에 있는지 알아야 하는 규칙은 경로의 nodes를 순서대로 읽고, 각 노드 자체의 연결을 input.graph.spec.feature_values_mapping[<node>]에서 읽습니다. 같은 질문을 attached_features에 던지면, Feature가 두 번째 컴포넌트 너머에 있는 경로도 통과시킵니다. ../examples/policy-data-class-route/는 Rego 엔진, CEL 엔진, OPA용으로 그렇게 작성되어 있습니다.
노드 객체는 자체 id를 담지 않습니다. id는 input.graph.spec.nodes에서 노드가 놓인 키이며, 그래서 위 규칙은 id 필드를 읽는 대신 path.nodes에서 읽은 id를 메시지에 담습니다.
정책이 맵의 키를 만나는 순서
그래프는 작성자가 쓴 순서를 유지합니다. 노드는 컴포넌트가 선언된 순서로, 각 노드의 레이블은 노드가 담고 있는 순서로 유지됩니다. 그 순서는 게스트로 그대로 전달됩니다. 페이로드는 둘 다 순서가 있는 항목으로 담습니다 (순서를 유지하는 맵 참조). 정책이 그 순서를 만나는지는 페이로드가 아니라 정책을 평가하는 엔진이 객체를 보관하는 방식으로 결정됩니다:
- Rego 엔진은 객체의 키를 정렬하여 보관합니다.
input.graph.spec.nodes, 노드의labels, 또는 다른 어떤 객체 — 정책 자체에 작성된 객체 포함 — 를 순회하는 규칙은 키를 정렬된 순서로 만납니다.web,api,metrics로 선언된 컴포넌트는api,metrics,web순으로 만납니다. - CEL 엔진은 맵에 순서를 정하지 않습니다.
input.graph.spec.nodes나 노드의labels에 대한 컴프리헨션은 동일한 입력의 두 빌드에서 키를 다른 순서로 만날 수 있으며, 한 표현식 안에서 같은 맵을 두 번 순회해도 서로 다를 수 있습니다. 그래서 한 결정 키 아래의 메시지가 정렬됩니다. 키가 놓인 위치에 결정이 의존하지 않는 규칙을 작성하십시오. - 플러그인 키트를 사용해 작성한 게스트는 작성자의 순서를 만납니다. 키트를 통해 디코딩하면 노드와 각 노드의 레이블이 페이로드가 담은 순서대로 키트의 순서 유지 컨테이너에 도착하며, 각 키트가 제공하는 거버넌스 어댑터 골격은 같은 순서로 작성된 JSON 문서를 엔진에 전달합니다. 그 문서를 자체 값 타입으로 변환하는 엔진은 대신 그 타입의 순서를 만나며, 이는 순서를 유지하는 맵에서 설명합니다.
레이블 형성: 정책은 레이블의 이름을 지정하고, 엔진이 그것을 지정합니다
레이블 형성 역할에서 정책은 레이블마다 하나의 결정을 labels 아래에 수집하며, 노드, 레이블 키, 레이블이 가질 값을 지정합니다:
package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}이미 존재하는 키를 설정하면 그 값이 대체됩니다. 결정은 대신 키를 제거하도록 요청할 수도 있습니다:
labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if { some id, node in input.graph.nodes node.labels["draft.example.com/scratch"]}정책은 빌드가 적용하는 편집 명령을 작성하는 대신 레이블의 이름을 지정하며, 그 이유는 알아 둘 만합니다. 명령은 레이블을 경로로 지정하는데, Aggrega 레이블 키에는 경로 구분자인 /가 흔히 포함됩니다. 따라서 직접 작성한 경로는 레이블 하나가 아니라 중첩된 위치를 지정하게 됩니다. 엔진이 결정이 지정한 레이블을 지정하므로 이스케이프는 모든 정책이 아니라 한 번만 작성되며, 정책은 경로가 아닌 레이블에 대한 진술로 읽기 쉽게 유지됩니다.
결정은 레이블만 변경할 수 있습니다. 엔진이 내보내는 모든 명령은 한 노드의 한 레이블을 지정하므로, 정책은 노드의 Component, 해석된 버전, 노드 집합, 또는 문자열이 아닌 레이블 값에 대한 변경을 표현할 방법이 없습니다. 빌드에 없는 노드를 지정하거나 노드에 없는 레이블을 제거하는 결정은 명령을 명시하는 메시지와 함께 빌드에서 거부되며, 조용히 무시되는 일은 없습니다.
../examples/policy-label-transform/는 두 개의 내장 태깅 플러그인 옆에 이러한 정책을 연결하고, 그 플러그인들이 작성하는 레이블을 읽는 그래프에 대한 판정도 연결합니다. 각 플러그인이 무엇을 읽고 쓰는지는 내장 태깅 플러그인에 있습니다.
어노테이션 주입
어노테이션 주입 역할에서 정책은 어노테이션마다 하나의 결정을 annotations 아래에 수집하며, 대상 자체가 가진 좌표로 대상을 지정하고 키와 그 값을 함께 지정합니다:
package tagging
import rego.v1
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly",} if { some target in input.targets not target.annotations["backup.example.com/schedule"]}결정이 작성하는 필드 이름은 대상을 읽을 때 사용한 필드 이름과 같으므로, 이 관례는 페이로드만으로 익힐 수 있습니다. input.binding_keys를 읽으면 정책은 Manifest가 의미를 등록한 키만 주입할 수 있으며, 그러한 키가 Feature 연결로 확장됩니다.
결정의 값은 그 어노테이션에 직접 작성할 수 있는 값, 즉 문자열이나 하위 키의 객체입니다. 하위 키 하나를 라우팅하는 바인딩은 문자열을 받고, 여러 하위 키를 라우팅하는 바인딩은 운영자가 Release에 작성하는 것과 똑같이 각 하위 키를 지정한 객체를 받습니다:
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "feature.aggrega.ai/monitoring", "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { some target in input.targets not target.annotations["feature.aggrega.ai/monitoring"]}빌드는 주입된 값을 Release에 작성된 같은 값을 읽는 것과 똑같이 읽으므로, 같은 방식으로 확장되고 바인딩된 Feature에 대해 같은 방식으로 검사됩니다. 엔진은 객체의 키를 정렬된 상태로 유지하므로 하위 키는 정렬된 순서로 빌드에 도달합니다. 그 밖의 형태의 값 — null, 목록, 숫자, 불리언, 또는 하위 키가 없는 객체 — 은 빌드가 주입을 지목하며 거부합니다. 이 역할은 어노테이션을 추가하는 역할이며, null이나 빈 객체는 작성자가 어노테이션을 제거하려고 작성하는 옵트아웃으로 읽히기 때문입니다. 페이로드에 없는 컴포넌트를 지정하는 결정도 같은 방식으로 좌표와 어노테이션을 지목하며 거부됩니다.
빌드가 주입된 어노테이션을 그 라우팅 방식이나 담고 있는 내용 때문에 거부하는 경우 — 여러 하위 키를 라우팅하는 바인딩에 전달된 문자열, 바인딩된 Feature의 스키마가 허용하지 않는 하위 키 값, 또는 Release 측 어노테이션이 사용할 수 없는 values 기둥을 통해 라우팅된 하위 키 — 거부 메시지는 그것을 주입한 플러그인과 그 플러그인이 연결된 거버넌스 역할을 지목합니다. 따라서 그 값은 아무도 작성하지 않은 Release의 한 줄이 아니라 그것을 결정한 정책까지 추적됩니다.
../examples/policy-annotation-transform/는 이러한 정책을 연결하여 한 바인딩에는 문자열을, 다른 바인딩에는 하위 키의 객체를 주입하고, 그 어노테이션을 직접 작성한 Release와 같은 파일을 빌드합니다.
정책 세트 전체를 하나의 아카이브로 첨부하기
정책 세트는 파일 단위로 첨부하거나, 정책 파일과 데이터 문서를 함께 담은 단일 아카이브로 첨부합니다. 이는 Rego 툴체인이 빌드하는 형태입니다. 첨부된 파일의 내용은 텍스트로 게스트에 전달되는데, 압축 아카이브는 텍스트가 아닌 임의의 바이트이므로 아카이브는 base64로 인코딩하고 이름이 .base64로 끝나도록 지정하여 첨부합니다:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64파일을 정책 텍스트가 아닌 아카이브로 표시하는 것은 이름이며, 이로써 그 선택은 운영자 자신의 명시로 남습니다. 따라서 손상된 아카이브는 파싱되지 않는 정책 파일로 읽히는 대신, 파일과 실패한 단계를 명시하여 손상된 아카이브로 보고됩니다. 아카이브 인코딩은 툴체인이 아카이브를 빌드한 뒤 운영자가 추가하는 단계입니다.
아카이브 안에서 모든 .rego 멤버는 정책 모듈이고, 모든 data.json 또는 data.yaml 멤버는 자신이 위치한 디렉터리 아래에 중첩된 데이터 문서입니다. 예를 들어 {"max": 3}을 담은 limits/data.json은 정책에서 data.limits.max로 읽힙니다. 그 밖의 종류의 멤버는 아카이브 자체의 툴체인을 위해 아카이브에 실려 있을 뿐이며 정책 입력이 아닙니다.
열 수 없는 아카이브는 첨부된 파일을 명시하는 실패입니다. 디코딩되지 않는 인코딩, 압축 해제되지 않는 스트림, 잘린 아카이브, 읽히지 않는 데이터 파일, 정책이 전혀 없는 아카이브가 이에 해당합니다. 이 중 어느 것도 빈 정책 세트를 만들지 않습니다. 빈 정책 세트는 아무 결정에도 도달하지 않으므로, “아카이브를 읽을 수 없었다”는 것이 “정책이 빌드를 허용했다”는 것과 결코 구별할 수 없게 되어서는 안 되기 때문입니다.
CEL 엔진용 정책 작성
이 엔진은 운영자가 작성한 CEL을 연결된 네 가지 역할 중 어느 역할에서든 전적으로 게스트 내부에서 평가합니다. 카탈로그 식별자는 pluginType: governance 아래의 단순 이름 cel, 즉 좌표 governance/cel이며, 버전은 이를 포함해 배포하는 컴파일러 릴리스입니다. 서로 다른 두 정책 파일로 두 역할에 두 번 연결하면 하나의 엔진으로 같은 빌드의 두 시점을 다룰 수 있습니다.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20정책은 하나의 이름 input으로 전체 페이로드에 접근하므로, 정책이 읽는 이름은 와이어가 부여한 이름 그대로입니다. 빌드 그래프는 input.graph, 열거된 라우팅 경로는 input.precalculated_paths, 렌더링된 파일은
input.artifacts, 어노테이션 대상은 input.targets에 있습니다. 이러한 역할별 경로는 위의 각 역할의 페이로드가 노출하는 것에
표로 정리된 것과 같으며, 두 엔진에서 동일합니다. 하나의 와이어를 하나의 루트 이름으로 읽습니다.
연결 자체의 파일은 input.sources에, 설정은 input.settings에 있으므로 운영자가 제공한 임계값은 input.settings.max_nodes로 읽습니다. 따로 익혀야 할 두 번째 문서는 없습니다. 설정도 다른 모든 것처럼 input의 일부입니다. 둘 다 항상 값으로 존재하며, 연결이 아무것도 선언하지 않으면 설정은 모든 역할에서 빈 객체이므로 이를 참조하는 표현식은 부재에 대비할 필요가 없고, 어떤 설정이 구성되었는지는 그 키에 대한 검사로 확인합니다: has(input.settings.max_nodes).
두 가지 작성 형식과 그중 하나를 선택하는 파일 이름
정책은 두 가지 형식 중 하나로 연결되며, 어느 형식인지는 파일 이름이 알려 줍니다:
| 파일 이름의 끝 | 읽는 방식 |
|---|---|
.cel | 하나의 표현식으로, 있는 그대로 평가 |
.yaml 또는 .yml | 규칙 문서 — 규칙의 목록 |
| 그 밖의 모든 것 | 하나의 표현식 |
이름이 규칙의 전부입니다. 형식을 선택하는 설정은 없으며, 형식을 추측하기 위해 파일의 텍스트를 검사하지도 않습니다. 어차피 텍스트로는 답할 수 없습니다. 표현식의 가장 바깥 값도 맵이고 규칙 문서의 것도 맵이어서, 두 형식은 모양으로 구별할 수 없기 때문입니다.
따라서 이 규칙은 양방향으로 적용되며, 두 가지 실수 모두 잘못 읽히지 않고 거부됩니다. policy.cel이라는 이름의 규칙 문서는 YAML 규칙 목록이 표현식이 아니므로 거부되고, policy.yaml이라는 이름의 표현식은 표현식이 규칙 목록이 아니므로 거부됩니다. 각 거부는 해당 파일을 명시합니다. 어느 방향이든 파일 이름을 바꾸면 해결됩니다.
정책 세트는 필요한 만큼 여러 파일로 구성할 수 있으며, 하나의 연결 안에서 두 형식을 자유롭게 섞을 수 있습니다.
.cel이라는 이름의 파일에 담긴 표현식
표현식 언어에는 결정을 모아 둘 규칙 이름이 없으므로, 결정은 표현식이 산출하는 값 그 자체입니다. 즉 결정 키에서 그 키가 모으는 것으로의 맵입니다. 판정 역할에서 키는 그 아래에서 도달한 메시지를 모으고, 빌드를 형성하는 역할에서는 적용할 결정을 모읍니다.
{ "deny": input.graph.spec.nodes .filter(n, input.graph.spec.nodes[n].resolved_version == "latest") .map(n, "component " + n + " tracks the latest version; pin it"), "warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],}파일이 생략한 키는 그 파일에서 어떤 결정에도 도달하지 않은 것이므로, 파일이 모든 키를 명시할 필요는 없습니다. 또한 각 역할은 자신과 관련된 키만 읽으므로, 하나의 정책 세트가 같은 파일로 판정 역할과 빌드를 형성하는 역할을 함께 담당할 수 있습니다. 키에는 모은 것의 목록, 그중 하나, 또는 없음을 뜻하는 null 값을 담습니다.
맵이 아닌 다른 값으로 평가되는 표현식은 거부되며, 작성해야 할 모양을 알려 줍니다. 흔히 예상되는 실수는 단순한 size(input.graph.spec.nodes) <= 5입니다.
이는 불리언이며, false를 중단으로 읽으려면 작성자가 쓰지 않은 메시지를 지어내야 합니다.
.yaml 또는 .yml이라는 이름의 파일에 담긴 규칙 문서
규칙 문서는 규칙의 목록이며, 각 규칙은 도달하는 결정 키, 도달 여부를 결정하는 표현식, 도달했을 때 보고할 내용을 명시합니다:
- key: deny expression: size(input.graph.spec.nodes) > 20 message: this build declares a lot of components- key: warn expression: has(input.settings.max_nodes) message: a component ceiling is configured for this environment규칙이 보고하는 내용은 표현식에서와 똑같이, 도달하는 결정 키를 따릅니다. 텍스트는 판정이 담는 메시지입니다. 매핑은 빌드를 형성하는 역할이 읽는 하나의 결정의 필드입니다:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: gold규칙이 둘 중 무엇을 쓰는지는 규칙만으로 결정되며, 이를 선택하는 설정은 없습니다. 키에 맞지 않는 쪽을 쓰는 규칙은 이름과 함께 거부됩니다.
문제가 되기 전에 알아 둘 만한 YAML 세부 사항이 하나 있습니다. 큰따옴표로 시작하는 표현식은 문서 리더를 위해 따옴표로 감싸야 합니다. "로 시작하는 값은 따옴표로 시작하는 텍스트가 아니라 따옴표로 묶인 스칼라로 읽히기 때문입니다.
- key: annotations expression: '"backup.example.com/schedule" in input.binding_keys' message: boundary_path: main component_name: app annotation_key: backup.example.com/schedule annotation_value: nightly규칙 문서는 어떤 평가보다도 먼저, 그것이 나타내는 표현식으로 읽힙니다. 각 규칙은 표현식이 참이면 보고 내용을, 그렇지 않으면 아무것도 담지 않는 결정 키가 되고, 키를 공유하는 규칙은 합쳐집니다. 따라서 하나의 평가기가 두 형식을 모두 실행하며, 규칙 문서는 모든 역할에서 판정과 빌드 형성 결정 모두에 대해 그것이 나타내는 표현식과 정확히 같은 결정을 내립니다. 여기서 두 가지 결과가 따릅니다. 문서와 그것이 나타내는 직접 작성한 표현식은 같은 평가이므로 같은 결정에 도달합니다. 그리고 아래의 순서 규칙은 문서가 아니라 평가된 형태의 것이므로, 문서의 규칙은 작성된 순서대로 보고되지 않습니다.
어떤 형식이 적합한가 — 두 형식은 서로 대체할 수 없습니다
두 형식은 하나의 평가기로 실행되므로 어느 쪽도 더 빠르거나 더 신뢰할 수 있지 않습니다. 다른 점은 각각이 무엇을 말할 수 있는가이며, 두 형식은 익혀야 할 것이 둘이라는 뜻이므로 취향에 맡기기보다 그 구분을 분명히 밝혀 둘 만합니다. 규칙이 보고하는 내용에 따라 고르십시오.
- 보고 내용이 고정되어 있다면 규칙 문서를 사용합니다. 메시지나 결정을 그에 도달하는 표현식 옆에 한 번만 작성하며, 파일은 검사 조건의 목록처럼 읽힙니다. “이것이 참이면 정확히 이렇게 말하라”에는 이쪽이 더 짧은 형식입니다.
- 보고 내용이 찾아낸 대상을 명시해야 한다면 표현식을 사용합니다. 하나의 표현식이 빌드의
컴포넌트를 걸러 컴포넌트마다 메시지나 결정을 산출하므로, 독자는 개수에 관한 한 문장 대신
위반한 각 컴포넌트에 대해
component payments tracks the latest version; pin it을 받습니다.
두 번째 작업은 규칙 문서가 할 수 없는 일입니다. 규칙 문서의 각 규칙은 미리 작성된 하나의 보고 내용만 담으므로, 어느 컴포넌트가 규칙에 걸렸는지 말할 수 없습니다. 문서 형식을 택했다가 메시지에 위반 대상의 이름을 넣고 싶어지면 결국 규칙을 표현식으로 다시 작성하게 되므로, 이 질문을 기준으로 처음부터 선택하는 것이 좋습니다.
표현식으로 말할 수 있는 것
이 엔진이 평가하는 표현식은 filter, map, exists
컴프리헨션, 문자열과 리스트에 대한 +, size, in, startsWith, string(),
조건 연산자, 그리고 계산된 정수로 인덱싱한 리스트를 사용합니다. 일부 CEL 환경이 추가하는 확장 함수는 제공하지 않습니다. join, split,
substring, indexOf, flatten, cel.bind, lists.range는 각각 선언되지 않은 참조로 거부되며, 컴프리헨션은 변수 하나만 받으므로 exists(i, v, …) 같은 두 변수 형태도 같은 방식으로 거부됩니다. 거부는 파일과 참조를 명시하는 빌드 오류입니다:
policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'경로를 순회하는 규칙은 다음 세 가지 결과의 영향을 받습니다:
- 중간 값에 이름을 붙일 방법이 없습니다. 두 번 사용하는 하위 표현식은
두 번 작성하거나, 항목이 하나인 리스트를 매핑해 바인딩합니다.
[value].map(name, …)[0]은name을value에 바인딩한 채 본문을 한 번 평가합니다. - 리스트의 위치를 순회할 방법이 없습니다. 경로의 컴포넌트를 위치별로 비교하는 규칙은
설정에서 위치를 가져와(
[0, 1, 2, …]같은positions리스트) 각 위치로 경로를 인덱싱합니다. 따라서 리스트보다 긴 경로는 일부만 읽지 말고, 그런 경로에서 중단하는 방식으로 대비해야 합니다. - 결정 키는 메시지를 모으며, 메시지의 리스트를 모으지 않습니다. 경로마다 메시지 리스트를 하나씩 산출하는 표현식은 결정 키 아래에서 거부되며, 오류는 메시지가 아닌 리스트 타입의 값을 모았다고 알려 줍니다. 따라서 규칙은 경로마다 레코드 하나를 산출하고 그로부터 메시지를 만듭니다. 또한 표현식이 두 번 산출한 메시지는 두 번 보고됩니다. 아래에 설명하는 정렬은 키가 모은 것을 정렬할 뿐, 중복을 제거하지 않습니다.
../examples/policy-data-class-route/에는 이 세 가지를 모두 반영해 작성한 CEL 규칙이 Rego 엔진용 동일 규칙과 함께 들어 있습니다.
결정 키와 심각도
결정 키, 심각도로의 기본 매핑, 그리고 이를 다른 이름으로 바꾸는 translation 설정은 Rego 엔진과 같습니다. 위의
정책은 결정을 결정 키 아래에 수집합니다를 참조하십시오. 기본적으로 deny는 halt로, warn은 warn으로, audit는 info로 보고됩니다. 선언된 translation은 이 기본값을 확장하지 않고 대체하며, 그것이 선언하는 순서가 판정이 보고되는 순서입니다.
두 엔진은 이를 위해 같은 설정 스키마를 선언하므로, translation 블록은 어떤 언어로 결정을 표현하든 같은 의미를 가지며, 형식이 잘못된 블록은 어떤 정책도 실행되기 전에 거부됩니다.
빌드를 형성하는 역할에서는 키가 매핑되지 않고 고정됩니다. 레이블을 형성하는 역할에서는 labels, 어노테이션을 주입하는 역할에서는 annotations입니다.
순서: 키 안에서 정렬되며, 결정에 대해서는 전순서
하나의 결정 키 아래의 메시지는 정렬된 순서로 보고됩니다. 이는 표시 방식의 선택이 아니라 계약의 일부이며, 그 이유는 알아 둘 가치가 있습니다. 맵에 대한 컴프리헨션, 즉 컴포넌트별 규칙을 작성하는 가장 자연스러운 방법인 input.graph.spec.nodes에 대한 .filter(...)와 .map(...)는 평가기가 고정하지 않는 순서로 그 맵을 순회합니다. 그대로 두면 동일한 입력이 빌드마다 같은 메시지를 다른 순서로 보고하게 됩니다. 정렬은 이를 제거합니다.
버그로 읽히기 쉽지만 버그가 아닌 두 가지 결과가 따릅니다.
- 규칙 문서의 규칙도 정렬되어 보고됩니다. 작성된 순서로 보고되지 않습니다. 문서는 그것이 나타내는 표현식으로 평가되고, 정렬은 키가 수집한 것에 적용되기 때문입니다.
- 직접 작성한 목록도 정렬됩니다.
["second", "first"]를 가진 키는first를second보다 먼저 보고합니다. 평가된 결과에서는 작성자가 직접 입력한 목록과 컴프리헨션이 만든 목록을 구별할 수 없으므로, 보존할 작성 순서가 없습니다.
키 사이의 순서는 translation이 선언한 순서입니다. 파일 사이의 순서는 파일 이름의 순서입니다. 첨부의 소스는 첨부가 나열한 순서가 아니라 이름순으로 정렬되어 도착하기 때문입니다.
빌드를 형성하는 역할에서는 같은 논리가 결정 자체에 적용되며, 순서는 더 엄격합니다. 결정은 그것이 지정하는 모든 것의 오름차순으로 보고되며, 이는 결정이 표현할 수 있는 것에 대한 전순서입니다. 노드, 그다음 레이블 키, 그다음 레이블의 추가 또는 삭제 여부, 그다음 값 순이며, 주입의 경우 경계, 그다음 컴포넌트, 그다음 어노테이션 키, 그다음 그 값 순입니다. 레이블이나 어노테이션의 변경은 렌더링된 출력에 도달하므로, 임의의 순서는 동일한 입력이 빌드마다 다르게 렌더링된다는 뜻이 됩니다.
레이블 형성
레이블 형성 역할에서 정책은 레이블마다 하나의 결정을 labels 아래에 수집하며, 노드, 레이블 키, 레이블이 가질 값을 지정합니다:
{ "labels": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server") .map(n, { "node": n, "key": "compliance.example.com/tier", "value": input.compilation_context.environment == "production" ? "gold" : "bronze", }),}이미 있는 키를 설정하면 그 값이 대체됩니다. 대신 결정은 op를 remove로 지정하여 키 삭제를 요청할 수 있습니다.
{ "labels": input.graph.nodes .filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels) .map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),}결정 하나에는 목록으로 감쌀 필요가 없으며, labels 키를 지정하지 않는 파일은 어떤 레이블도 결정하지 않습니다.
정책은 빌드가 적용하는 편집 명령을 작성하지 않고 레이블을 지정합니다. 그 이유는 Rego 엔진의
레이블 형성 섹션에 설명되어 있습니다.
Aggrega 레이블 키에는 흔히 /가 포함되며, 직접 작성한 경로는 하나의 레이블 대신 중첩된 위치를 가리키게 됩니다. 엔진이 결정이 지정한 레이블을 찾아 처리합니다.
노드가 갖지 않을 수 있는 레이블을 읽는 것은 빈 값이 아니라 실패입니다. 그래서 두 번째 예제는 키를 읽기 전에 키가 있는지 확인합니다. 이는 없는 키를 읽는 것에 대한 표현식 언어 자체의 규칙이며, 명시적으로 드러납니다. 어떤 노드도 갖지 않은 레이블을 참조하는 정책은 조용히 아무것도 결정하지 않는 대신 평가할 수 없었다고 보고합니다.
결정은 레이블만 변경할 수 있습니다. 빌드에 없는 노드를 지정하거나 노드가 갖지 않은 레이블을 삭제하는 결정은 빌드가 해당 명령을 지정하는 메시지와 함께 거부하며, 결코 조용히 무시되지 않습니다.
노드와 레이블 키당 하나의 결정에 도달하십시오. 같은 노드의 같은 레이블에 대해 서로 다른 두 값을 만들 수 있는 규칙은 명세가 불충분합니다. 두 결정을 모두 내보내지 말고, 조건 연산자나 한 분기만 허용하는 필터로 표현식 안에서 값을 확정하십시오.
../examples/policy-label-transform/는 레이블 형성 역할을 처음부터 끝까지 보여 주며, 그 정책은 Rego 엔진용으로 작성되어 있습니다.
등록된 키 아래에 어노테이션 주입
어노테이션을 주입하는 역할에서 정책은 annotations 아래에 어노테이션당 하나의 결정을 수집하며, 대상 자체가 가진 좌표로 대상을 지정하고 키와 그 값을 함께 지정합니다.
{ "annotations": input.targets .filter(t, "backup.example.com/schedule" in input.binding_keys) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly", }),}결정이 작성하는 필드 이름은 대상을 읽어 들인 필드 이름과 같으므로, 이 관례는 페이로드만 보고도 익힐 수 있습니다. input.binding_keys를 읽으면 정책은 Manifest가 의미를 등록한 키, 즉 Feature 첨부로 확장되는 키만 주입할 수 있습니다. 모든 필드는 필수입니다. 키나 컴포넌트 이름이 빈 어노테이션은 정책이 의도해서 요청하는 것이 아닙니다. 컴포넌트가 속한 경계는 정당하게 빈 문자열로 지정될 수 있으므로, 그 필드는 있어야 하지만 비어 있어도 됩니다.
값은 그 어노테이션에 직접 작성할 수 있는 값, 즉 문자열이나 하위 키의 맵이며, 후자는 여러 하위 키를 한 번에 라우팅하는 바인딩에 전달되는 값입니다 — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. 표현식 언어는 맵에 순서를 정하지 않으므로 엔진은 맵의 하위 키를 정렬된 순서로 작성하고, 값은 표현식이 생성한 그대로 전달합니다. JSON 모델이 담을 수 없는 값 — 바이트, 타임스탬프, 기간 — 은 텍스트로 변환되지 않고 거부됩니다. 그런 다음 빌드는 Release에 작성된 같은 값을 읽는 것과 똑같이 값을 읽고, null, 목록, 숫자, 불리언 또는 빈 맵을 주입을 지목하며 거부합니다. 하나의 컴포넌트와 키에 대해 값이 다른 두 결정은 값의 JSON에 따라 정렬됩니다. 대상의 annotations는 기존의 각 값을 작성된 그대로 — 문자열, 맵, 또는 옵트아웃을 나타내는 null로 — 담으므로, "feature.aggrega.ai/monitoring" in t.annotations를 검사하면 값과 관계없이 키를 찾을 수 있습니다.
페이로드에 없는 컴포넌트를 지정하는 결정은 빌드가 좌표와 어노테이션을 지정하며 거부합니다. 빌드가 주입된 어노테이션을 그 라우팅, 하위 키 값 또는 기둥 때문에 거부하는 경우, 거부 메시지는 그것을 주입한 플러그인과 그 플러그인이 연결된 역할을 지목합니다. 레이블과 마찬가지로 컴포넌트와 어노테이션 키당 하나의 결정에 도달하십시오. 하나의 키에 대해 두 결정을 내보내지 말고 표현식 안에서 값을 확정하십시오.
../examples/policy-annotation-transform/는 어노테이션 주입 역할을 처음부터 끝까지 보여 주며, 그 정책은 두 엔진 모두를 위해 작성되어 있습니다.
정책이나 결정을 읽을 수 없을 때
엔진이 읽을 수 없거나 평가할 수 없거나, 문서화된 형태의 결정이 아닌 것을 만드는 정책은 판정이나 변경을 반환하지 않고 빌드를 실패시킵니다. 이 실패는 파일을 지정하고, 결함이 파일의 한 부분에 속하는 경우 그 안의 위치를 지정하는 빌드 결함으로 보고됩니다. 이는 의도적으로 halt 판정과 구별되며, 그래서 “이 정책을 평가할 수 없었다”가 “이 정책이 빌드를 허용한다”로 오인되는 일이 없습니다.
표현식의 경우, 이는 파싱되지 않는 소스(파서 자체의 행과 열, 그리고 문제 위치 아래의 캐럿과 함께 보고됨)와 결정 키에서 그 키가 수집하는 것으로의 맵이 아닌 것으로 평가되는 소스를 포함합니다.
규칙 문서의 경우, 이는 규칙 목록이 아닌 텍스트, 규칙이 없는 목록, 필드가 누락되었거나 빈 필드를 가진 규칙, 형식이 정의하지 않는 필드, 텍스트도 텍스트 간 매핑도 아닌 보고, 그리고 읽을 수 없는 표현식을 포함합니다. 하나의 규칙에 속하는 결함은 그 규칙의 위치(작성자가 자신의 파일을 세는 방식대로 1부터 셈)와 결정 키를 지정합니다. 표현식이 파싱되지 않는 규칙은 평가 전에 거부되므로, 캐럿은 작성자가 본 적 없는 변환된 텍스트의 위치가 아니라 작성자가 쓴 표현식 안에 놓입니다.
빌드를 형성하는 역할의 결정의 경우, 이는 결정이 와야 할 자리의 메시지, 누락된 좌표, 그리고 이 엔진의 결정 형식이 정의하지 않는 필드를 포함합니다. 마지막 항목은 따로 짚어 둘 만합니다. 철자가 틀린 annotation_valu는 무시되지 않고 거부되므로, 조용히 빈 값을 주입하여 변경 없이 완료되는 빌드를 남기는 대신 실수가 보고됩니다. 이러한 모든 거부는 파일을 지정하고, 마지막에 해당 종류의 결정이 지정해야 하는 것을 명시합니다.
렌더 단계 정책 어댑터
렌더 단계 어댑터는 빌드의 IR 그래프가 아니라 렌더링된 출력을 대상으로 추론합니다. 렌더 페이로드는 내보낸 아티팩트를 담고 있으며, 각 아티팩트에는 출력 경로와 렌더링된 내용이 있고, 해당하는 경우 렌더링된 형식과 파싱된 구조적 뷰도 함께 있습니다. 여기에 더해 첨부의 자체 소스와 설정도, 각각 첨부가 선언하는 경우에 담깁니다. 어댑터는 대상으로 하는 출력 형태에 맞게 그 내용을 읽고, 구조화된 결과에 대해 정책을 평가한 뒤, 결과를 halt / warn / info 판정에 매핑합니다. 페이로드 자체는 어떤 출력 형태도 지정하지 않으므로 하나의 어댑터 패턴이 모든 렌더 대상에 쓰입니다. 새 출력 형태는 호스트 변경이 아니라 새 어댑터입니다.
각 렌더 단계 어댑터는 위에서 말한 의미의 어댑터입니다. 바깥으로는 Aggrega ABI를 사용하고 안으로는 대상별 형식이나 외부 정책 엔진의 계약을 흡수하므로, 컴파일러에는 출력 형식이나 정책 로직이 전혀 들어가지 않습니다. 컴파일러에 내장된 Rego 엔진과 CEL 엔진은 render-verdict 역할을 직접 수행하며, 그 밖에 두 개의 참조 렌더 단계 어댑터가 일반적인 출력 형태마다 하나씩 플러그인 개발 키트의 Rust 예제 가운데 작동 예제로 함께 제공됩니다.
../examples/policy-render-verdict/는 네 가지 대상 — Kubernetes 객체, Docker Compose 파일, Terraform 루트 구성, CloudFormation 템플릿 — 의 출력에 대해 render-verdict에서 하나의 규칙을 연결합니다. 이 규칙은 컴파일러 내부의 각 엔진용으로 한 번씩 작성되었으며, 각 대상에 심어 둔 위반은 빌드를 중단시키고 대조군은 통과하는지 확인합니다.
이 역할이든 다른 역할이든 직접 어댑터를 작성하려면 각 플러그인 개발 키트에 포함된 거버넌스 어댑터 골격에서 시작하십시오. 자체 거버넌스 플러그인 작성하기에서 골격부터 그 플러그인이 거부하는 빌드까지 단계별로 안내합니다.
YAML, JSON, Terraform HCL 출력 — 참조 Rego 렌더 어댑터
참조 Rego 렌더 어댑터는 운영자가 제공한 Rego를 모든 YAML 또는 JSON 렌더 출력과 Terraform의 네이티브 HCL 출력에 대해 실행합니다. 이는 렌더 단계 형태의 작동 예제입니다. 컴파일러 내장 엔진과 같은 Wasm 네이티브 Rego 평가기를 사용하고, 같은 deny / warn / audit 수집 관례를 같은 세 가지 판정 심각도에 매핑하되, 빌드 그래프가 아니라 렌더링된 파일을 대상으로 추론합니다.
이 어댑터는 YAML/JSON 대상 전반에서 출력 형태에 독립적입니다. 어댑터는 각 아티팩트의 내용을 하나 이상의 YAML 또는 JSON 문서로 파싱하고(YAML은 JSON의 상위 집합이므로 CloudFormation 스택 같은 JSON 템플릿도 같은 파서로 파싱됩니다), 파싱된 문서를 원시 내용과 함께 정책에 노출합니다. 정책은 일반적인 Rego로 그러한 대상의 구조화된 렌더 출력을 추론합니다. input.artifacts[_].documents[_]는 파싱된 문서(Docker Compose 파일의 services, CloudFormation 템플릿의 Resources)를, input.artifacts[_].content는 원시 텍스트를 내놓으며, 첨부의 settings 객체는 Rego data 문서가 됩니다. 예를 들어 Docker Compose 출력에 대한 승인된 레지스트리 요구 정책은 이미지에 레지스트리 접두사가 없는 서비스를 모두 거부합니다.
이 어댑터는 Terraform의 네이티브 HCL 렌더 출력도 추론합니다. 네이티브 .tf 파일은 YAML도 JSON도 아니므로, 어댑터는 이를 Terraform-JSON(.tf.json) 파일이 이미 파싱되는 것과 같은 정규 객체로 투영합니다. 정책은 리소스 속성을
input.artifacts[_].documents[_].resource.<type>.<name>.<attr>에서 읽으며(RDS 인스턴스라면 input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage), 컴파일러가 어떤 Terraform 형식을 내보냈든 같은 방식으로 읽습니다. 속성 타입은 보존되며(숫자는 숫자로, 불리언은 불리언으로), 해석되지 않은 Terraform 표현식은 ${ ... } 형태의 문자열로 남습니다. Terraform-JSON 본문(.tf.json, .auto.tfvars.json)은 YAML/JSON 경로를 그대로 거쳐 파싱되며, Terraform 템플릿 파일(.tftpl)은 독립 구성이 아니라 템플릿 텍스트이므로 투영되지 않고 다른 비구조적 내용과 마찬가지로 parse_error를 드러냅니다.
이 목록은 컴파일러가 내보내는 것이 아니라 어댑터의 파서가 받아들이는 것을 말합니다. 둘은 같은 집합이 아니며, 자동 로드되는 변수 파일이 둘이 달라지는 경우입니다. 컴파일러는 어떤 경로에서도 그런 오버레이를 내보내지 않습니다(소싱된 모듈의 입력은 경계의 루트 구성에 있는 해당 컴포넌트의 모듈 블록 인수입니다). 따라서 이 형태는 벤더링된 모듈이 자체적으로 이를 포함하고 소싱 경로가 그것을 출력에 그대로 복사할 때에만 정책의 뷰에 도달합니다. 컴파일러가 이를 생성하리라 기대하고 작성한 정책은 결코 발동하지 않습니다.
아티팩트의 내용이 파싱되지 않으면 어댑터는 이를 조용히 허용하지 않습니다. 원시 내용은 유지하되 해당 아티팩트에 대해 파싱된 문서를 노출하지 않고, 파서의 메시지를 input.artifacts[_].parse_error에 기록하므로, 정책은 잘못된 형식의 아티팩트에 대해 명시적으로 빌드를 중단할 수 있습니다. 컴파일러에 내장된 Rego 엔진과 마찬가지로, 내장 평가기가 구현하지 않은 내장 함수를 호출하는 정책은 요란하게 실패합니다. 즉 플러그인을 지목하는 오류가 발생하며, 결코 조용히 허용되지 않습니다.
Kubernetes 출력 — Kubewarden 렌더 어댑터
Kubewarden 렌더 어댑터는 렌더링된 Kubernetes 매니페스트에 대해 Kubewarden 스타일의 어드미션 정책을 실행합니다. 이 어댑터는 Kubernetes admission-review 계약을 안으로 흡수합니다. Kubewarden 정책은 단일 객체를 감싼 요청을 받아 수락 또는 거부 응답을 반환합니다. 렌더 단계에서 빌드의 출력은 이미 Kubernetes 리소스의 집합이므로, 이 단계는 어드미션 형태의 정책을 실행하기에 자연스러운 위치입니다. 렌더링된 각 객체에 대해 어댑터는 파싱된 객체 자체에서 어드미션 필드를 도출하고, 게스트 내부에서 객체를 admission-review 형태의 요청으로 감싸 정책을 실행한 뒤, 응답을 판정에 매핑합니다. 거부는 하나의 판정이 되고, 수락은 아무것도 내보내지 않습니다. 함께 제공되는 참조 정책은 레이블 요구 규칙으로, 모든 객체가 settings가 지정한 레이블 키를 가져야 합니다. 이는 흔한 Kubewarden 패턴입니다.
렌더 단계 어댑터에 공통인 범위
- 렌더 단계, 어댑터당 하나의 출력 형태. 렌더 단계 어댑터는 IR 그래프가 아니라 렌더링된 아티팩트를 대상으로 추론하며, 자신이 파싱하는 출력 형태를 대상으로 합니다. 참조 Rego 렌더 어댑터는 YAML/JSON과 Terraform 네이티브 HCL을, Kubewarden 어댑터는 Kubernetes 객체를 대상으로 합니다. 그래프 단계 정책이나 제공된 어댑터가 파싱하지 않는 출력 형태에 대한 정책은 별개의 게스트입니다.
- 검증 전용. 렌더 단계 어댑터는 수락하거나 거부할 뿐이며, 변경된 객체를 반환하지 않습니다. 변경 정책이 내놓은 변경된 객체는 무시되며, 컴파일러는 정책 판정을 근거로 렌더링된 출력을 다시 쓰지 않습니다. 정책은 결정할 뿐 편집하지 않습니다.
정책 연결하기
운영자는 워크스페이스 구성(.aggrega-config.yaml)의 plugins.governance 목록을 통해 거버넌스 플러그인을 연결합니다. 각 항목은 플러그인, 그 플러그인이 연결되는 role, 그리고 선택적으로 규칙과 조정값을 공급하는 with 채널을 지정합니다.
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3uri는 플러그인으로 해석됩니다. 호스트는 빌드 시점에 각 sources 파일을 읽어 그 바이트를 게스트에 전달하고, settings는 그대로 전달합니다. 거버넌스 플러그인이 연결되지 않은 빌드는 소켓을 no-op으로 실행하므로, 연결은 워크스페이스에 순수하게 추가되는 것입니다.
여러 역할을 수행하는 플러그인 하나는 역할마다 한 번씩 연결되며, 각 연결은 자체 규칙과 자체 설정을 가집니다.
plugins: governance: - uri: governance/rego:<version> role: label-transform with: sources: - ./policies/tagging.rego - uri: governance/rego:<version> role: ir-verdict with: sources: - ./policies/topology.rego settings: translation: - key: blocked severity: halt연결이 지정하는 버전. uri는 Plugin 엔터티를 지정합니다. 즉 <pluginType>/<name> 좌표와 콜론 뒤의 버전이며, 버전은 해석에 관여합니다. CLI에 컴파일된 두 엔진의 경우 엔터티는 두 곳 중 한 곳에서 옵니다. 각 컴파일러 릴리스는 governance/rego와 governance/cel의 Plugin 엔터티를 자체 버전으로 게시하며, 표준 라이브러리 카탈로그는 각각을 게시한 릴리스의 버전으로 이를 담고 있습니다. 워크스페이스는 자신이 나열하는 카탈로그 디렉터리에서 이를 읽습니다. aggrega 바이너리는 각각의 엔터티를 하나씩, 자체 릴리스의 버전으로만 담고 있습니다. 둘 중 어느 쪽에도 없고 어떤 pull도 콘텐츠 캐시로 가져오지 않은 버전을 지정한 연결은 E0137로 빌드를 중단하며 그 참조를 지목합니다.
따라서 연결은 워크스페이스가 읽는 카탈로그에 있는 버전을 지정합니다. 그 버전은 자체 릴리스가 아닌 다른 aggrega 릴리스에서도 카탈로그로부터 해석되지만, 바이너리에만 있는 버전 — 자체 릴리스의 버전 — 은 그 릴리스에서만 해석되며, 이는 판정 역할과 변환 역할 모두 마찬가지입니다. 변환 역할에서 pull은 해석한 버전을 잠금 파일에 고정하고, 워크스페이스가 읽는 카탈로그에도 바이너리에도 없는 버전은 E0103으로 거부합니다. 버전이 선택하는 것은 플러그인의 내보내기와 런타임 제한을 기록하는 Plugin 엔터티이지 엔진이 아닙니다. 참조가 해석되면 실행되는 엔진은 빌드를 실행하는 바이너리에 컴파일된 엔진인데, 바이너리에 내장된 플러그인이 플러그인 모듈을 가장 먼저 읽는 곳이기 때문입니다. 워크스페이스가 직접 선언하는 거버넌스 플러그인 — 자체 카탈로그 디렉터리에 있는 Plugin 엔터티와 그 옆의 .wasm — 은 그 엔터티가 기록하는 버전으로 지정합니다.
각 역할은 기본 진입 함수를 선택합니다. 그래프를 판정하는 역할에는 verdict_ir, 렌더링된 아티팩트를 판정하는 역할에는 verdict_render, 레이블을 형성하는 역할에는 mutate, 어노테이션을 주입하는 역할에는 transform_annotations가 선택되며, 연결은 function:으로 역할을 다른 export에 지정할 수 있습니다. 호스트는 게스트가 describe() 자기 보고에서 선언하지 않은 export로의 디스패치를 거부하므로, 게스트가 수행하지 않는 역할을 지정한 연결은 아무 일도 하지 않고 넘어가는 대신 게스트가 실행되기 전에 이름과 함께 보고됩니다.
function:은 uri가 지정하는 플러그인의 내보내기를 지정합니다. 판정 역할(ir-verdict 또는 render-verdict)의 연결이 function:은 지정하고 uri:는 지정하지 않으면 어떤 플러그인에도 속하지 않는 함수를 지정하는 것이므로, 구성은 읽히는 시점에 E0224로 거부되며, 파일과 목록 안에서 항목의 위치가 지목됩니다. 그 함수를 내보내는 플러그인의 uri를 추가하십시오.
plugins.governance 목록에는 추가용 짝인 plugins.governance_append가 있습니다. 이 짝의 항목은 각 구성 계층에서 해석된 governance 목록 뒤에 이어 붙여지므로, 워크스페이스나 전역 구성은 기본 목록을 가리는 대신 정책 연결을 조합합니다.
CI 소유 오버레이
직접 작성한 .aggrega-config.yaml 외에, 자동화된 파이프라인은 별도의 오버레이 파일 .aggrega-config-append-ci.yaml을 소유할 수 있습니다. 이 파일은 파이프라인이 개발자가 직접 작성한 기본 구성을 전혀 편집하지 않고도 자신이 제어하는 정책(또는 기타 목록 값 구성)을 연결할 수 있도록 존재하며, 파이프라인은 자신의 오버레이 파일을 통째로 덮어쓸 수 있습니다.
오버레이는 엄격하게 추가만 합니다. 기본 파일과 동일한 구성 스키마에 대해 검증되며, 목록 값 필드마다 그 항목이 해석된 목록 뒤에 이어 붙여집니다. 추가만 할 수 있습니다. 기본 항목을 제거할 수 없고 기본 값을 스칼라로 재정의할 수도 없습니다. 오버레이가 담은 스칼라나 맵 키는 추가적 의미가 없으므로 적용되지 않고 무시됩니다(그리고 해석 경고에 이름이 표시됩니다). 또한 오버레이는 워크스페이스 루트를 고정하지 않습니다. workspace: 블록을 담은 .aggrega-config.yaml만 그렇게 하므로, 오버레이를 디렉터리에 넣으면 워크스페이스가 시작되는 위치를 바꾸지 않고 연결만 추가됩니다.
이를 통해 파이프라인은 조직 전체 정책을 적용할 깔끔한 접점을 얻습니다. 파이프라인이 필수 정책 플러그인을 지정하는 .aggrega-config-append-ci.yaml을 넣으면, 그 연결은 개발자가 작성한 내용을 대체하지 않고 그 위에 병합됩니다.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/는 팀의 연결, 전역 구성 파일의 governance_append로 추가된 조직의 연결, 그리고 이 오버레이로 추가된 파이프라인의 연결을 갖춘 하나의 워크스페이스를 빌드하고, 각 조합이 무엇을 출력하는지와 완료되는지를 확인합니다.
정책이 빌드를 통제하기 전에 테스트하기
역할의 페이로드에 없는 경로를 지정하는 Rego 규칙은 오류가 아닙니다. 경로는 정의되지 않고, 규칙은 결코 성립하지 않으며, 빌드는 정책이 허용한 것처럼 완료됩니다. 따라서 새 정책은 세 단계를 거쳐 halt에 이릅니다. 중단하지 않고 보고하는 심각도로 연결하고, 지정하는 모든 경로를 그 역할이 받는 페이로드와 대조하고, 판정할 빌드에서 무엇을 보고하는지 읽습니다.
아래 명령은 examples/policy-org-overlay/의 사본에서 실행되며, 이 사본의 .aggrega-config.yaml은 팀의 정책 대신 새 정책 하나를 연결합니다. 이 정책은 고가용성을 끈 채로 실행되는 데이터 저장소를 거부하기 위한 것이며, 그 규칙은 레이블 형성 정책에서 복사해 온 것입니다:
package datastores
import rego.v1
deny contains msg if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v is a datastore running with high availability off", [id])}보고하도록 연결합니다. 이 정책은 deny 아래에 수집하며, 이는 기본적으로 빌드를 중단합니다. deny만 warn으로 지정하는 translation은 각 결정을 경고로 보고하고 빌드를 완료시킵니다. info는 대신 이를 기록합니다. 정책 자체는 강제될 때의 모습 그대로 둡니다:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/datastore-ha.rego settings: translation: - key: deny severity: warn페이로드를 작성하고 그 안에서 경로를 찾아봅니다. 빌드가 Release의 잠금 파일을 채우고 나면,
aggrega build --release release.yaml --dry-run --policy-input payloads이 명령은 각 역할이 연결에 전달하는 페이로드를 payloads/에 작성하고 그 외에는 아무것도 작성하지 않으며, 다음과 같이 보고합니다. 여기서 <workspace>는 빌드가 실행된 디렉터리를 나타냅니다:
policy input: 4 file(s) written to <workspace>/payloads[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]네 파일은 annotation-transform.json, ir-verdict.json, label-transform.json, render-verdict.json입니다. 아무것도 연결되지 않은 역할의 파일도 작성되므로, 정책은 어디에 연결되기 전에 그 역할에 대해 확인할 수 있습니다. ir-verdict, label-transform, annotation-transform에서 이 파일은 정책이 읽는 input 문서이므로, 규칙을 신뢰하기 전에 규칙이 지정하는 각 경로를 아무 JSON 도구로나 읽어 낼 수 있습니다:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json# ["db","web"]jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json# {"enabled":false,"read_replicas":0}규칙이 찾는 노드는 그곳에 없습니다. input.graph.nodes는 레이블 형성 역할이 노드를 담는 곳이고, ir-verdict에서 노드는 input.graph.spec.nodes에 있습니다(각 역할의 페이로드가 노출하는 것 참조). 이 파일은 수정된 규칙이 무엇을 결정해야 하는지도 알려 줍니다. db는 데이터 저장소이고, 고가용성이 꺼져 있으며, 보고되어야 합니다.
OPA가 설치되어 있으면 Rego 정책을 같은 파일에 대해 직접 평가할 수 있습니다: opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. 컴파일러 내부의 Rego 엔진은 독립적인 구현이므로, 결정을 내리는 것은 여전히 빌드에서의 평가입니다. 엔진이 구현하지 않은 내장 함수는 평가되는 대신 빌드를 중단합니다.
render-verdict에서 이 파일은 정책의 input이 아닙니다. 파일 안의 각 아티팩트는 path, content, format을 담습니다. 규칙이 읽는 documents는 정책 엔진이 페이로드를 받은 뒤 내용에서 파싱하므로, documents를 대상으로 하는 규칙은 이 파일에서 아무것도 찾지 못합니다. 이 역할의 정책은 엔진이 그것을 파싱하는 곳, 즉 다음 단계에서 보듯이 빌드 안에서 테스트합니다.
빌드하고, 보고 내용을 페이로드의 내용과 비교합니다. 복사한 경로를 그대로 쓰면,
aggrega build --release release.yaml --auto-pull이 명령은 완료되며 아무것도 보고하지 않습니다:
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]페이로드에는 고가용성이 꺼진 데이터 저장소가 있는데, 정책은 그에 대해 아무 말도 하지 않았습니다. 그 침묵이 바로 실수이며, 빌드의 다른 어떤 것도 그것을 가리키지 않습니다. 규칙이 input.graph.spec.nodes를 읽도록 하면 같은 명령이 db를 보고하고 완료됩니다:
policy plugin "rego" warning: db is a datastore running with high availability offPull 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]--dry-run을 추가하면 같은 판정을 보고하고 dist/를 작성하지 않으므로, 워크스페이스의 출력을 건드리지 않고 이 반복을 실행할 수 있습니다.
CEL 엔진용으로 작성한 같은 규칙은 조용히 실패하지 않습니다. 그곳에서는 페이로드에 없는 키를 읽는 것이 평가 오류이므로, 같은 translation으로 연결한 policies/datastore-ha.cel에 복사한 경로를 넣으면,
{ "deny": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore" && input.graph.spec.infra_mapping[n].ha.enabled == false) .map(n, n + " is a datastore running with high availability off"),}이 명령은 warn에서도 빌드를 중단합니다. 종료 코드는 1이며, 마지막 줄은 정책 파일과 키를 지목합니다:
ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodesrender-verdict 정책도 같은 방식으로 테스트합니다. 같은 워크스페이스에서 같은 translation으로 render-verdict에 연결한, 호스트에 포트를 게시하는 Compose 서비스를 거부하는 규칙은
package published
import rego.v1
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services count(service.ports) > 0 msg := sprintf("%v publishes a port on the host", [name])}그렇게 하는 서비스 하나를 보고합니다:
policy plugin "rego" warning: web publishes a port on the host[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]그런 다음 강제합니다. translation을 제거하면 deny가 halt로 돌아가고, db를 보고했던 빌드는 이제 그것 때문에 중단되며, 1로 종료하고 dist/를 작성하지 않습니다:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db is a datastore running with high availability off caused by: policy violation보고용 연결을 모든 곳에서 한꺼번에 제거할 필요는 없습니다. 한 구성 파일은 연결의 translation을 warn으로 유지하고, 파이프라인의 오버레이는 같은 정책을 deny를 halt로 하여 연결할 수 있으며, examples/policy-org-overlay/가 조직의 규칙을 도입하는 방식이 바로 이것입니다. 개발자의 빌드에서는 경고가 되고, 파이프라인의 빌드에서는 중단의 이유가 됩니다.
빌드 출력에 대해 CI에서 정책 실행하기
위의 내용은 모두 빌드 내부에 정책을 연결하는 방법입니다. 두 번째 경로가 있으며, 이 경로는 소켓에서 아무것도 필요로 하지 않습니다. 빌드가 작성한 파일에 대해 파이프라인에서 자체 도구를 실행하면 됩니다.
이것이 가능한 이유는 빌드가 내보내는 결과물에 있습니다. Kubernetes 및 Compose 대상은 YAML을 작성하고,
Terraform 대상은 네이티브 HCL 또는 .tf.json 형식의 JSON을 작성합니다.
이들은 생태계의 구성 도구가 이미 읽는 형식이며,
aggrega build는 래퍼 형식도, 인덱스도, 풀어야 할 것도 없이 디렉터리에 일반 파일을
작성합니다. 따라서 YAML, JSON 또는 HCL을 읽는 도구는 사람이 직접 작성한 구성에 대해
실행되는 것과 같은 방식으로 빌드 출력에 대해 실행되며, Aggrega는 이를 위해 소켓,
플러그인 종류, 구성 키를 추가하지 않습니다.
따라서 기존 규칙 모음은 이식할 필요가 없습니다. 이미 Conftest, Kyverno CLI, kubeconform, Checkov 또는 OPA에 규칙을 유지하고 있다면, 그 규칙은 Aggrega 빌드 출력에 대해 그대로 실행되며, 규칙을 평가하는 도구는 파이프라인에 이미 설치된 바로 그 도구입니다.
바로 사용할 수 있는 두 개의 규칙 스크립트가 각각을 호출하는 파이프라인 단계, 그리고 실제 빌드에서 발생한 두 거부 결과와 함께 examples/policy-in-ci/에 있습니다. 이 스크립트는 yq만 사용하므로 정책 도구 체인을 설치하지 않아도 실행됩니다. 이 스크립트가 보여 주는 형태, 즉 출력 디렉터리를 읽고, 판정하고, 문제가 된 아티팩트를 명시하며 0이 아닌 코드로 종료하는 형태는 이 위치에 놓인 모든 도구가 취하는 형태입니다.
규칙이 속하는 경로
두 경로 모두 일급 경로이며, 워크스페이스는 흔히 둘 다 사용합니다. 결정 기준은 규칙이 무엇을 보아야 하고 언제 동작해야 하는가입니다.
다음과 같은 경우 소켓에 연결합니다:
- 빌드가 아티팩트를 아예 생성해서는 안 되는 경우.
ir-verdict정책은 아무것도 렌더링되기 전인 정적 분석 게이트에서 실행되므로, 그곳에서 중단되면 아무것도 작성되지 않습니다. 검토하거나, 격리하거나, 실수로 적용할 출력 파일이 남지 않습니다. 파이프라인 검사는 필연적으로 파일이 생긴 뒤에 실행됩니다. - 규칙에 빌드만 보유한 사실이 필요한 경우.
ir-verdict역할은 조립된 그래프를 읽습니다. 노드, 에지와 그 소켓, 채운 슬롯을 포함한 모든 연결, 작성자가 민감하다고 선언한 값, 라우팅 경로가 이에 해당합니다. 이 중 어느 것도 렌더링된 출력에 남지 않으므로(Kubernetes manifest는 어느 소켓이 값을 전달했는지, 어느 Feature가 리소스를 기여했는지 기록하지 않습니다), 토폴로지나 출처에 관한 규칙이 있을 곳은 하나뿐이며 그것은 소켓입니다. - 빌드가 어디에서 실행되든 규칙이 유지되어야 하는 경우. 거버넌스 연결은 워크스페이스 구성에 있으므로 파이프라인의 빌드뿐 아니라 개발자의 로컬 빌드에도 똑같이 적용됩니다. 파이프라인 검사는 파이프라인이 실행되는 곳에서만 적용됩니다.
- 규칙이 빌드를 판정하기보다 형성해야 하는 경우. 이는 변환 역할만 할 수 있으며, 운영자가 연결했기 때문에만 가능합니다.
다음과 같은 경우 CI에서 실행합니다:
- 규칙이 이미 존재하는 경우. 팀이 실행하고 검토하는 도구에, 그 도구가 이미 파싱하는 형식에 대한 규칙으로 존재한다면, 이를 소켓 정책 내용으로 다시 표현하는 것은 결국 새로운 적용 범위 없이 일만 늘리는 것입니다.
- 규칙이 대상이 받게 될 형태의 아티팩트에 관한 경우. 즉 모든 변환이 끝난 뒤,
적용되는 형태의 최종 파일 집합입니다. 이는
render-verdict역할의 대상이기도 하므로, 이 점만 놓고 보면 두 경로는 같은 것을 보며 선택은 다른 기준에 달려 있습니다. - 결과가 빌드가 아니라 검토자를 위한 것인 경우. 아티팩트와 결과를 나란히 게시하는 파이프라인은 검토자에게 둘 다 제공하지만, 중단된 빌드는 메시지 하나만 제공합니다.
- 검사가 하나의 빌드를 넘어서는 경우. 이번 빌드의 출력을 이전 빌드, 클러스터의 실시간 상태, 또는 어떤 빌드 페이로드에도 담기지 않은 인벤토리와 비교하는 경우입니다. 어느 판정 역할의 정책이든 연결된 빌드만 보며, 그것이 볼 수 있는 전부입니다.
두 경로는 경쟁하지 않고 함께 구성됩니다. 토폴로지 불변 조건은 ir-verdict에서
빌드를 중단하고, 같은 파이프라인은 이어서 해당 빌드가 작성한 결과물에 대해 기존
아티팩트 규칙을 실행합니다.
상호 참조
plugin-contract.md— 소켓의 파이프라인 내 위치, 소켓이 전달하는 타입이 지정된 와이어 형태, 그리고 모든 플러그인이 실행되는 샌드박스.plugin-developer-guide.md— 플러그인 작성,describe()자기 보고, 그리고 publish → pull → build 수명 주기.../entities/plugin.md— 플러그인을 카탈로그로 가져오는Plugin엔티티.../cli/aggrega-build.md— 소켓을 디스패치하는 빌드 명령.../schema/other/aggrega-config.md—plugins.governance연결 지점을 포함한 워크스페이스 구성 스키마.../examples/policy-in-ci/— 빌드 출력을 대상으로 실행할 수 있는 두 개의 규칙 스크립트와 각 스크립트의 파이프라인 단계.../examples/policy-data-class-route/— 라우트를 대상으로 하는 하나의ir-verdict규칙을 Rego 엔진, CEL 엔진, 그리고 참조 어댑터 게스트 뒤의 OPA용으로 각각 작성하고, 엔진마다 하나의--config파일로 빌드별로 연결하며, 세 가지 모두가 모든 Release에서 같은 결과에 도달하는지 확인하는 스크립트를 포함합니다.