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

ArtifactLibrary

ArtifactLibrary는 재사용 가능한 아티팩트 번들, 즉 함께 사용되는 보조 출력 파일들에 이름을 붙인 집합을 보관하는 카탈로그 엔터티입니다. 동일한 지원 리소스(RBAC 및 ConfigMap과 함께하는 CRD, HPA와 짝을 이루는 NetworkPolicy 등)를 내보내는 Recipes와 FeatureRecipes는 그 집합을 라이브러리에 한 번 선언하고, 사용 시점에 값이 $import: 지시문인 artifacts: 항목을 통해 참조합니다. 이 라이브러리 엔터티는 Tier 3으로, Recipe 간 아티팩트 재사용이 필요한 카탈로그에서 선택적으로 사용합니다. 각 Recipes가 자체 보조 파일을 지니는 카탈로그는 ArtifactLibrary 없이 배포됩니다.

ArtifactLibrary의 역할

플랫폼 아키텍트는 카탈로그의 Recipes와 FeatureRecipes 전반에서 반복되는 보조 매니페스트를 한곳에 모으기 위해 ArtifactLibraries를 작성합니다. 라이브러리는 배포 가능한 빌드 지침이 아니라 정의 네임스페이스입니다. Recipe 및 FeatureRecipe 작성자는 $import: 지시문으로 번들을 참조하며, 이 지시문은 한 번 작성되고 import가 해석되는 모든 곳에서 사용됩니다.

이 라이브러리 종류를 다른 세 가지와 구별하는 것은 항목의 단위입니다. SchemaLibrary 항목은 하나의 스키마이고, MappingLibrary 항목은 하나의 템플릿 조각이며, WorkloadLibrary 항목은 하나의 Workload 문서입니다. 각각은 단일 위치에서 사용되는 단일 본문입니다. ArtifactLibrary 항목은 파일의 집합인데, 그것이 묶는 리소스는 함께 있을 때만 유용하기 때문입니다. RBAC 없이 CRD만 가져오면 작동하지 않는 매니페스트 집합이 만들어집니다. 이것이 번들이 재사용의 단위이고 단일 사용 위치가 여러 출력으로 확장되는 이유입니다.

엔티티 엔벨로프

ArtifactLibrary 엔티티는 표준 카탈로그 엔벨로프를 가집니다. apiVersion: aggrega.ai/v1beta1와 kind: ArtifactLibrary는 엔티티 종류를 나타내고, metadata.name은 PascalCase 식별자이며, metadata.version은 엄격한 시맨틱 버전 관리를 따릅니다. 둘 다 필수입니다. metadata.description, metadata.labels, metadata.annotations는 선택 사항입니다. labels와 annotations는 라이브러리를 읽는 쪽이 일치 여부를 판단하는 데 쓸 수 있도록 담기는, 작성자가 선언하는 불투명한 메타데이터이며, 컴파일러는 그 값을 해석하지 않습니다. 라이브러리의 내용은 spec.artifacts 아래에 위치하며, 이는 적어도 하나의 번들을 선언해야 하는 필수 맵입니다.

엔벨로프는 세 수준 모두에서 닫혀 있습니다. 문서 루트, metadata, spec은 각각 스키마가 선언하지 않은 키를 거부합니다.

apiVersion: aggrega.ai/v1beta1
kind: ArtifactLibrary
metadata:
name: PlatformArtifacts
version: 1.0.0
spec:
artifacts:
OperatorSupport:
crd.yaml: |
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: widgets.platform.example.com
spec:
group: platform.example.com
scope: Namespaced
rbac.yaml: |
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: "{{ .context.instance_id }}-operator"
rules:
- apiGroups: ["platform.example.com"]
resources: ["widgets"]
verbs: ["get", "list", "watch"]

아티팩트 번들 작성

spec.artifacts는 두 단계 깊이이며, 각 단계는 서로 다른 역할을 합니다. 바깥쪽 키는 번들 이름으로, 소비자가 참조하는 식별자입니다. 안쪽 키는 파일 이름이며, 각 안쪽 값은 해당 파일로 출력되는 Go 템플릿 본문입니다. 번들은 파일을 하나 이상 선언해야 합니다.

spec:
artifacts:
NetworkBaseline:
deny-all.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-deny-all"
spec:
podSelector: {}
policyTypes: ["Ingress"]
allow-dns.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-allow-dns"

파일 본문은 YAML 문자열로 작성된 Go 템플릿 조각입니다. 매니페스트는 여러 줄로 이루어지므로, 파일 본문은 줄바꿈과 들여쓰기가 왕복 과정에서 유지되도록 YAML의 리터럴 스타일 스칼라(|)를 사용합니다. 번들 항목의 값은 파일 이름에서 문자열 본문으로의 매핑이어야 합니다. 번들이 들어갈 자리에 단순 문자열이나 시퀀스를 작성하면 거부됩니다. 소비자가 가져오는 단위는 단일 파일이 아니라 번들이기 때문입니다.

본문은 엔티티 엔벨로프에 대해 불투명합니다. 컴파일러는 ArtifactLibrary 로드 시 각 문자열을 그대로 저장하며 그 시점에 템플릿을 파싱하지 않습니다. 템플릿 파서는 Recipe 또는 FeatureRecipe가 번들을 가져오는 소비 시점에 실행됩니다. 본문을 그대로 저장하면 재출력 시 작성 충실도가 보존되며, 템플릿 오류가 라이브러리가 아니라 번들이 소비되고 그 필러 컨텍스트가 알려진 곳에서 드러나게 됩니다.

번들 내의 파일 순서는 작성자가 작성한 순서이며 로드와 소비 과정 전반에 걸쳐 유지되므로, 출력되는 집합은 빌드 간에 안정적입니다.

파일 본문 안에서는 Go 템플릿의 전체 합성 어휘를 사용할 수 있습니다. {{ define "name" }}...{{ end }}는 재사용 가능한 블록을 선언하고, {{ template "name" . }}는 이를 호출하며, 파이프라인과 함수는 표준 Go text/template 패키지를 따릅니다. 파일 본문이 읽을 수 있는 필러 컨텍스트(.values, .infra, .locals, .context, .features, 그리고 소비하는 Recipe가 선언한 경우 .workload와 .source)는 소비하는 Recipe 자체의 artifacts: 항목이 읽는 컨텍스트와 같으며, Recipe 페이지의 artifacts: 필드 아래에 설명되어 있습니다. 소비하는 Recipe가 workload:를 선언하지 않았는데 .workload를 읽거나, source:를 선언하지 않았는데 .source를 읽는 본문은 충족할 수 없었던 참조를 명시하는 진단과 함께 중단됩니다. 각 필러는 개별적으로 검사되므로, 하나를 선언했다고 해서 다른 하나를 읽을 수 있는 것은 아닙니다.

단일 작성 모드

ArtifactLibrary는 하나의 작성 모드, 즉 Go 템플릿만 제공합니다. spec은 병렬 작성 표면을 받지 않으며, 라이브러리 수준에서 표현력을 위한 탈출구도 받지 않습니다.

그 이유는 소비 표면의 균일성입니다. Recipes와 FeatureRecipes는 전체가 Go 템플릿이며, 이들 자체의 콘텐츠는 가져온 번들을 해석하는 것과 동일한 Go 템플릿 엔진을 통해 평가됩니다. 병렬 작성 표면이 있으면 작성자는 하나의 Recipe를 렌더링하는 동안 평가 모델을 전환해야 합니다. Recipe 자체 콘텐츠에는 한 모델을, 가져온 번들에는 다른 모델을 사용해야 하는 것입니다. 표면을 균일하게 유지하면 작성자는 하나의 평가 모델만 익혀 모든 곳에 적용할 수 있습니다.

Go 템플릿의 구성 어휘를 넘어서는 표현력이 필요한 작성자는 라이브러리 안에서 두 번째 작성 언어로 확장하는 대신, 더 높은 수준에서 구성합니다. 즉 라이브러리 번들을 자체적인 실질적 변형으로 감싸는 Components나 Features를 사용합니다.

명명 관례

라이브러리 이름과 번들 이름은 PascalCase를 따릅니다. 엔티티 엔벨로프의 JSON Schema는 패턴 제약을 통해 두 위치에서 이 관례를 강제합니다.

  • metadata.name은 ^[A-Z][A-Za-z0-9]*$와 일치해야 합니다.
  • spec.artifacts 맵 키는 propertyNames를 통해 같은 패턴과 일치해야 합니다.

번들 이름이 PascalCase가 아닌 ArtifactLibrary는 워크스페이스 로드 시 엔벨로프 검증에 실패합니다. 이 강제는 중요한 역할을 합니다. 번들 이름은 #/artifacts/<name> 참조 프래그먼트에 나타나므로, PascalCase가 아닌 이름은 번들을 가져오는 모든 소비자에게 전파됩니다.

이름의 일관성 덕분에 #/artifacts/<name> 프래그먼트를 읽기 쉽게 유지할 수 있습니다. #/artifacts/OperatorSupport는 한눈에 읽힙니다.

번들 안의 파일 이름은 각각이 파일을 가리키기만 하면 자유 형식입니다. 파일 이름은 PascalCase가 아니며 어떤 스키마 패턴도 이를 제약하지 않습니다. 파일 이름은 빌드 출력이 최종적으로 담게 되는 파일의 이름이기 때문입니다. crd.yaml, deny-all.yaml, values-override.json은 모두 유효합니다. 파일 이름은 평범하게 작성된 일반적인 상대 파일 이름이어야 합니다. Referencing Library Entries에서 설명하듯이, 빌드는 자기 자신의 파일을 가리키지 않는 이름을 거부합니다. 두 수준이 서로 다르게 제약되는 이유는 서로 다른 독자를 위한 것이기 때문입니다. 번들 이름은 다른 엔티티가 인용하는 식별자이고, 파일 이름은 소비자가 번들을 가져온 디렉터리 안에서 보는 이름입니다.

라이브러리 항목 참조

Recipe 및 FeatureRecipe 작성자는 값이 $import: 맵인 artifacts: 항목 안에서 번들의 단순 이름(bare-name) 식별자로 번들을 참조합니다:

# Inside a Recipe's spec:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"

#/artifacts/<name> 프래그먼트는 번들을 선택하며, artifacts 참조를 MappingLibrary의 #/mappings/<name>, SchemaLibrary의 #/schemas/<name>, WorkloadLibrary의 #/workloads/<name>와 구별합니다. 참조에는 레지스트리 호스트가 포함되지 않습니다. 호스트를 포함하는 oci://… 형식은 엔벨로프 스키마와 소비 지점 양쪽에서 거부되므로, 물리적 레지스트리 위치는 작성된 소스에 절대 들어가지 않습니다. 작성자는 선택적으로 최소 버전 하한을 <Library>:<version>#/artifacts/<name> 형식으로 지정할 수 있습니다. 버전 구분자는 다른 라이브러리 종류 및 lockfile 고정과 동일하게 :이며, 대신 @를 쓰면 수정된 참조를 제시하는 진단과 함께 거부됩니다. 확정된 버전은 Release별 lockfile이 제공하며, lockfile은 소비되는 각 라이브러리를 이름, 버전, 콘텐츠 다이제스트로 고정합니다. 물리적 위치는 해석 시점에 바인딩됩니다.

파일 이름은 번들이 소유하고, 파일이 놓이는 디렉터리는 소비하는 키가 소유합니다. 번들을 가져오는 artifacts: 항목 하나는 해당 번들의 파일마다 하나의 출력으로 확장되며, 각 출력은 소비 키 아래 <key>/<filename>으로 중첩됩니다. 소비 지점의 키(위 예의 operator-support)는 개별 파일이 아니라 소비 전체를 가리킵니다. 위 예는 operator-support/crd.yaml과 operator-support/rbac.yaml을 생성합니다. 따라서 번들 이름은 참조에서의 가독성을 위해, 파일 이름은 출력 디렉터리를 읽는 사람을 위해 정해지며, 둘이 서로 일치할 필요는 없습니다. 소비 키 자체는 단일 파일 이름으로 제한됩니다. 첫 글자는 문자 또는 숫자이고, 그 뒤로 문자, 숫자, 점, 하이픈, 밑줄이 올 수 있으며, 이 문자 집합을 벗어난 키는 엔벨로프 검증에 실패합니다. 따라서 키는 정확히 하나의 디렉터리 세그먼트를 가리키고, 그 세그먼트 아래의 모든 것은 번들에서 옵니다. 이 덕분에 키는 엄격하게 유지하면서 번들의 파일 이름은 자유 형식으로 둘 수 있습니다. 파일 이름은 번들 안에서 고유하고, 키는 문서 안에서 고유하며, 키는 항목이 생성하는 모든 경로의 첫 세그먼트이므로, 두 artifacts: 항목이 같은 출력을 가리킬 수 없습니다. 자유 형식이란 그 세그먼트 안에서 자유롭다는 뜻입니다. 파일 이름은 자체적인 중첩 구조를 가질 수 있지만(crds/widget.yaml은 <key>/crds/widget.yaml에 놓입니다), 키 아래의 평범하게 작성된 일반 상대 파일 이름이어야 하며, 그렇지 않은 파일 이름은 소비하는 Recipe가 지정한 적 없는 위치에 파일을 두는 대신 빌드를 중단시킵니다. 이에 따라 다음이 거부됩니다. 키 위로 올라가거나 절대 위치를 가리키는 이름, 키 안의 파일이 아니라 키 자체의 디렉터리를 가리키는 .이나 ./ 및 x/..처럼 키로 다시 수렴하는 이름, 그리고 끝에 붙거나 중복된 / 또는 .이나 .. 부분을 가진 이름(x/, a//b, ./a, a/../b)입니다. 마지막 경우는 다른 이름이 가질 수 있는 파일의 또 다른 표기이므로, a/b 옆에 a//b가 있으면 한 경로에 두 파일이 놓이게 됩니다. 진단은 번들 파일과 그것을 가져온 키를 알려 줍니다. 실제로 같은 파일 이름을 가진 두 출력은 노드가 렌더링될 때 빌드를 중단시키며, 이는 서로 다른 두 입력 종류가 같은 파일 이름을 제공할 때 발생합니다. artifacts:가 Recipe의 다른 입력 종류와 어떻게 조합되는지와 라이브러리를 사용하지 않는 두 가지 작성 모드는 Recipe를, 더 넓은 $ref: / $import: 구분은 vocabulary/cross-document-ref를 참조하십시오.

라이브러리 간 구성

번들 파일 본문은 최종 콘텐츠입니다. MappingLibrary나 WorkloadLibrary 항목과 달리, 번들 파일은 필드 루트 $import: 리디렉션이 될 수 없습니다. 하나의 파일 슬롯에는 다른 번들이 가져올 여러 파일을 담을 공간이 없으므로, 컴파일러는 그 형태를 작성자가 쓰지 않은 무언가로 해석하는 대신 거부합니다. 첫 토큰이 $import:인 본문은 번들과 파일을 명시하는 진단과 함께 중단됩니다.

대신 구성은 그럴 공간이 있는 소비 지점에서 이루어집니다. 두 번들이 필요한 Recipe는 두 개의 artifacts: 항목을 선언하며, 각 항목은 독립적으로 확장됩니다.

# Inside a Recipe's spec — compose bundles where the outputs land:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"
network-baseline:
$import: "PlatformArtifacts#/artifacts/NetworkBaseline"

알 수 없는 라이브러리 이름과, 해석되는 라이브러리에 없는 번들 이름은 서로 다른 진단으로 보고되므로, 작성자는 누락된 의존성과 잘못 입력한 번들 이름을 구별할 수 있습니다.

계층 배치

ArtifactLibrary는 엔터티 계층 문서 모델에서 Tier 3에 해당하며, Recipe 간 아티팩트 재사용이 필요한 카탈로그가 선택적으로 사용합니다. Recipes가 자체 보조 파일을 갖는 카탈로그는 ArtifactLibrary 엔터티 없이 배포됩니다. 계층 표시는 기능이 아니라 문서 탐색을 위해 “고급 항목이므로 필요하지 않으면 건너뛰십시오”라는 뜻을 나타냅니다. 컴파일러는 ArtifactLibrary를 다른 카탈로그 엔터티 종류와 동일하게 취급합니다. 워크스페이스 로드 시 동일한 엔벌로프 검증을 거치고, 릴리스 시 동일한 OCI 게시 파이프라인을 사용하며, 이름, 버전, 콘텐츠 다이제스트로 동일하게 lockfile에 고정됩니다.

이 라이브러리 종류로 카탈로그 수준의 한 세트가 완성됩니다. SchemaLibrary는 재사용 가능한 스키마 정의를, MappingLibrary는 재사용 가능한 매핑 조각을, WorkloadLibrary는 재사용 가능한 워크로드 콘텐츠를, ArtifactLibrary는 재사용 가능한 아티팩트 번들을 담습니다. 각각은 독립적으로 선택하여 사용할 수 있으며, 카탈로그는 필요한 것만 포함하고 나머지는 포함하지 않습니다.

ArtifactLibrary가 아닌 것

미리 짚어 둘 만한 흔한 오해가 몇 가지 있습니다:

  • 인라인 artifacts:의 대체 수단이 아닙니다. 대부분의 Recipes는 인라인에 두는 것이 적합할 만큼 고유한 보조 파일을 포함하며, 작성자는 이 파일을 Recipe의 나머지 부분과 함께 읽습니다. ArtifactLibrary는 동일한 파일 세트가 여러 Recipes에 함께 포함될 때 유용합니다. 일회성 내용에는 인라인 작성이 올바른 선택입니다.

  • 번들 안의 파일 이름을 바꾸는 수단이 아닙니다. 파일 이름은 번들에 속합니다. 소비자는 파일이 배치될 디렉터리를 선택할 수 있지만(소비 키가 하는 일이 바로 이것입니다), 각 파일의 이름은 선택할 수 없습니다. 다른 파일 이름이 필요한 소비자는 그 이름을 선언하는 번들을 사용하거나 파일을 인라인으로 작성합니다.

  • workload, mapping, schema 내용을 위한 곳이 아닙니다. Workload 문서는 WorkloadLibrary에, Recipe의 values 문서는 MappingLibrary에, schema 정의는 SchemaLibrary에 속합니다. 라이브러리 종류는 재사용 패턴이 아니라 내용 유형에 따라 나뉩니다.

  • 횡단 리소스를 위한 메커니즘이 아닙니다. 어떤 Recipe가 구현하는지와 관계없이 여러 컴포넌트에 걸쳐 적용되는 보조 리소스(예: 모든 데이터 저장소에 연결되는 백업 사이드카)는 FeatureRecipe 리소스 생성에 속하며, 이는 Recipe가 아니라 Feature 단위로 연결됩니다. entities/featurerecipe.md를 참조하십시오. ArtifactLibrary는 여러 Recipes가 각자 자신을 위해 출력하는 파일을 공통으로 분리해 냅니다.

  • 독립적으로 배포할 수 있는 엔터티가 아닙니다. 번들은 아티팩트 내용이며, 아티팩트 내용은 그 자체로 주소 지정될 수 없습니다. 이는 Recipe 또는 FeatureRecipe가 소비하는 입력으로서 존재합니다. ArtifactLibrary를 게시하면 그 번들을 가져올 수 있게 되지만, 배포할 수 있게 되지는 않습니다.