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

빌드 출력에 대한 CI 정책

Aggrega 빌드의 출력 디렉터리를 읽고, 규칙을 위반하면 이를 거부하는 바로 사용할 수 있는 규칙 스크립트 두 개입니다. 이 스크립트는 파이프라인에서 aggrega build 다음에, 해당 파이프라인이 구성에 대해 이미 실행하는 다른 작업과 함께 실행됩니다.

이 디렉터리는 Aggrega 워크스페이스가 아닙니다. Aggregate도, Release도, 카탈로그 엔터티도 작성하지 않습니다. 자신의 저장소에 복사해 쓰는 스크립트 한 쌍과, 각 스크립트를 호출하는 파이프라인 단계로 구성됩니다.

이 스크립트가 속한 경로와, 빌드 내 거버넌스 소켓이 대신 적합한 경우는 거버넌스 소켓 페이지에서 설명합니다.

두 가지 규칙

스크립트거부 대상
require-pinned-image.sh태그가 없거나 태그가 latest인 컨테이너 이미지
deny-inline-credential-material.sh자격 증명 자료를 리터럴로 담고 있는 렌더링된 Secret

각 스크립트는 출력 디렉터리를 유일한 인수로 받아 그 안에 있는 모든 것을 순회합니다. 어느 스크립트도 빌드가 어디서 실행되었는지, 어떤 타깃이었는지, 워크스페이스가 어떻게 구성되어 있는지 알지 못합니다.

Terminal window
./require-pinned-image.sh <output-directory>
./deny-inline-credential-material.sh <output-directory>

두 스크립트 모두 PATH에 yq만 있으면 됩니다. JSON은 YAML의 부분 집합이므로 yq는 YAML 문서를 읽는 것과 같은 표현식으로 JSON 문서를 읽습니다. 따라서 하나의 스크립트로 두 가지 형태의 출력을 모두 다룹니다.

yq 외에 이 디렉터리에는 아무것도 필요하지 않습니다. 카탈로그 체크아웃도, aggrega 바이너리도, 네트워크도 필요 없습니다. ./check.sh는 빌드가 내보내는 형태로 직접 작성한 작은 출력 디렉터리에 대해 두 규칙을 실행하고, 각 종료 코드와 보고서를 해당 디렉터리에 기대되는 것과 비교합니다. 하나라도 일치하지 않으면 1로 종료합니다. 규칙을 실행할 실제 빌드를 만들려면 빌드하는 예제가 필요로 하는 것이 필요합니다.

종료 코드는 두 개가 아니라 세 개

0 no finding — the output satisfies the rule
1 finding — the output breaks it, and every offending artifact is named
2 cannot evaluate — bad usage, yq absent, or an artifact that does not parse

세 번째 코드는 의도적으로 두 번째 코드와 구분됩니다. “아티팩트를 읽을 수 없음”은 “아티팩트가 통과함”과 결코 구별되지 않아서는 안 됩니다. 이는 거버넌스 소켓에서 평가할 수 없는 정책을 허용이 아니라 오류로 보고하는 것과 같은 이유입니다. 0이 아닌 모든 종료를 실패로 처리하는 파이프라인은 두 경우 모두 올바르게 동작하며, 둘을 구분하려는 파이프라인은 구분할 수 있습니다.

아무것도 찾지 못한 실행은 얼마나 검사했는지를 알려 줍니다. 따라서 전혀 일치하는 것이 없었던 규칙이 일치했고 충족된 규칙과 구별되지 않는 일 없이 드러납니다.

OK: every image pinned across 3 container(s) in 43 document(s)
OK: no inline credential material across 43 document(s), 1 of them credential-carrying

규칙 조정하기

각 스크립트는 yq와 판정을 분리하고, 둘이 만나는 지점의 주석에 그렇게 명시합니다. yq 표현식이 각 문서를 탭으로 구분된 행으로 읽고, 셸 함수가 각 행을 판정합니다. 다른 규칙을 표현하려면 이 두 부분을 바꾸고 순회는 그대로 두십시오.

이 분리는 장식이 아닙니다. 비슷해 보이는 두 규칙이 서로 반대되는 이유로 이 분리를 필요로 합니다.

  • 키만으로는 충분하지 않습니다. ConfigMap은 Secret과 똑같이 data: 블록을 가지며, ConfigMap의 data:는 자격 증명 자료가 아닙니다. 따라서 키뿐 아니라 종류(kind)도 자격 증명 규칙의 일부입니다.
  • 재귀 검색은 지나칩니다. CustomResourceDefinition은 자체 스키마를 선언하며, 그 스키마는 image라는 속성을 선언할 수 있습니다. 모든 문서에서 image 키를 검색하는 규칙은 CRD의 스키마를 고정되지 않은 워크로드로 보고할 것입니다. 그래서 require-pinned-image.sh는 여섯 개의 pod-spec 경로를 명시적으로 읽으며, 워크로드 종류를 추가하려면 경로를 추가해야 합니다.

예제 생성하기

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

Terminal window
aggrega scaffold --example policy-in-ci

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

Terminal window
cd policy-in-ci

빌드

이 폴더에는 워크스페이스가 없으므로 여기서 빌드할 것이 없습니다. ./check.sh는 빌드가 출력하는 형태로 직접 작성한 작은 출력 디렉터리에 대해 두 규칙을 모두 실행하고, 각 판정을 확인합니다:

Terminal window
./check.sh

실제 빌드에 규칙을 실행하려면, 다음 섹션에서처럼 해당 빌드의 출력 디렉터리를 전달하십시오.

스크립트를 실행할 빌드 만들기

이 트리에 있는 빌드된 예제라면 무엇이든 사용할 수 있습니다. 아래 명령은 뒤에 기록된 종료 코드를 만들어 낸 명령입니다.

Terminal window
cd ../external-secrets-operator
aggrega build --release release.yaml
Terminal window
cd ../ai-agent-and-model-router
aggrega build --release release.yaml

잠금 파일은 배포되지 않고 생성되므로, 새로 클론한 저장소에는 잠금 파일이 없으며 첫 빌드에는 잠금 파일이 필요합니다. 예제 개요에서 이를 해결하는 두 가지 방법을 설명합니다.

파이프라인 단계

아래 스니펫은 GitHub Actions입니다. 이 형태는 셸 명령을 실행하고 종료 코드를 읽을 수 있는 모든 파이프라인에 그대로 적용됩니다. 각 run: 줄은 이 종료 코드를 만들어 낸 명령입니다.

# every image a rendered workload runs is pinned
jobs:
policy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Compile the Release
run: aggrega build --release release.yaml --auto-pull
working-directory: ai-agent-and-model-router
- name: Images are pinned
run: ./require-pinned-image.sh ../ai-agent-and-model-router/dist
working-directory: policy-in-ci
# no credential material reaches the artifacts as a literal
jobs:
policy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Compile the Release
run: aggrega build --release release.yaml --auto-pull
working-directory: external-secrets-operator
- name: No inline credential material
run: ./deny-inline-credential-material.sh ../external-secrets-operator/dist
working-directory: policy-in-ci

자신의 저장소에는 예제 트리가 아니라 하나의 워크스페이스가 있으므로, 인수는 빌드가 출력을 쓰는 위치이며 일반적으로는 워크스페이스 옆의 dist입니다. 스크립트는 파이프라인 도구를 두는 곳에 둡니다. 바뀌는 것은 이 두 경로뿐입니다.

각 규칙이 보고하는 내용

이 디렉터리에서 형제 예제 세 개의 빌드를 대상으로 실행한 결과입니다. 거부는 문제가 되는 모든 아티팩트를 명시하므로, 파이프라인 로그가 곧 발견 사항 목록이 됩니다.

이미지가 고정됨 — Recipes가 모든 이미지를 고정하는 Release를 대상으로:

Terminal window
$ ./require-pinned-image.sh ../ai-agent-and-model-router/dist
OK: every image pinned across 4 container(s) in 12 document(s)
$ echo $?
0

Recipe가 업스트림 Helm 차트를 소스로 사용하고 차트 자체의 이미지 참조를 재정의하지 않는 Release를 대상으로:

Terminal window
$ ./require-pinned-image.sh ../advanced-platform/dist
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container mariadb runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container preserve-logs-symlinks runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: 2 finding(s) across 3 container(s) in 12 document(s)
$ echo $?
1

인라인 자격 증명 자료 없음 — 유일한 Secret이 값이 포함된 채 렌더링되지 않고 런타임에 운영자가 채우는 Release를 대상으로:

Terminal window
$ ./deny-inline-credential-material.sh ../external-secrets-operator/dist
OK: no inline credential material across 43 document(s), 1 of them credential-carrying
$ echo $?
0

세 개의 자격 증명 슬롯을 값으로 채우는 Release를 대상으로:

Terminal window
$ ./deny-inline-credential-material.sh ../ai-agent-and-model-router/dist
REFUSED: helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml (document 1): Secret/agent-router-model.credential carries inline material under api-key
REFUSED: helm/router--api-zukey--router-secret-router-api-key.yaml (document 1): Secret/router-api-key carries inline material under master-key
REFUSED: helm/router--provider-zukey--router-secret-router-provider-key.yaml (document 1): Secret/router-provider-key carries inline material under provider-key
REFUSED: 3 finding(s) across 12 document(s), 3 of them credential-carrying
$ echo $?
1

마지막 거부는 조직이 선택한 규칙이지, Release의 결함이 아닙니다. 자격 증명 슬롯을 값으로 채우는 것은 지원되는 형태입니다. 작성자가 자료를 제공하면 타깃은 워크로드가 읽을 수 있는 곳에 이를 렌더링하며, 컴파일러는 이에 대해 어떤 의견도 갖지 않습니다. 이와 별개로 컴파일러는 작성자가 민감하다고 선언한 값이 리터럴로 전달 키에 도달하면 경고하며, 자격 증명을 값으로 전달하는 방식은 의도된 것이므로 이 경고는 중단하지 않고 권고만 합니다. 어느 경우든 그 형태를 금지하는 것은 조직이며, 여기서 또는 거버넌스 소켓에서 그렇게 합니다. 두 경로와 그 사이의 선택은 거버넌스 소켓 페이지에서 설명합니다.