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

MappingLibrary

MappingLibrary는 재사용 가능한 Go 템플릿 조각을 담는 카탈로그 엔터티입니다. valuesMapping: 문서 전체(같은 차트를 소스로 하는 여러 Recipes가 각각 그 차트에 넘기는 values)를 공유하는 Recipes와 FeatureRecipes는 이를 라이브러리에 한 번 선언하고, 사용 시점에 valuesMapping: { $import: ... } 지시문으로 참조합니다. 이 라이브러리 엔터티는 Tier 3에 속하며, Recipe 간 매핑 재사용이 필요한 카탈로그가 선택적으로 사용합니다. 반복되는 템플릿 내용이 없는 카탈로그는 MappingLibrary 없이 배포됩니다.

MappingLibrary의 역할

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

“라이브러리”와 “소비자”의 분리는 의도된 것입니다. Recipes는 빌드 지침(source, valuesMapping, artifacts)을 인코딩합니다. FeatureRecipes는 동작 연결을 인코딩합니다. MappingLibraries는 템플릿 조각, 즉 다른 엔티티가 렌더링 시점에 사용하는 Go 템플릿 콘텐츠만 인코딩합니다. 세 역할을 구분해 두면 각 엔티티 종류가 저마다의 주기로 발전할 수 있으며, 공유 템플릿 콘텐츠가 필요 없는 작성자는 라이브러리 엔티티를 접할 일이 없습니다.

엔티티 엔벨로프

MappingLibrary 엔티티는 표준 카탈로그 엔벨로프를 가집니다. apiVersion: aggrega.ai/v1beta1과 kind: MappingLibrary는 엔티티 종류를 나타내고, metadata.name은 PascalCase 식별자이며, metadata.version은 엄격한 시맨틱 버저닝을 따릅니다. 라이브러리의 내용은 spec.mappings 아래에 위치하며, 이는 최소 하나의 항목을 선언해야 하는 필수 맵입니다.

apiVersion: aggrega.ai/v1beta1
kind: MappingLibrary
metadata:
name: BaseMappings
version: 1.0.0
spec:
mappings:
SimpleValues: 'image: {{ .values.image }}'
Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'

항목은 이를 사용하는 Recipe 자체의 템플릿 엔진이 그 Recipe의 렌더링 컨텍스트에 대해 평가합니다. 따라서 항목은 Recipe 자체의 valuesMapping:이 읽는 소문자 기둥(.values, .infra, .context 등)을 읽고, 없는 키에 대해 존재 여부를 고려하는 optional 헬퍼 같은 동일한 함수를 사용합니다. Helm이 차트 values에 쓰는 표기인 .Values는 이 컨텍스트가 정의하는 루트가 아닙니다. 이를 읽는 항목은 해당 참조를 지목하며 빌드를 중단시킵니다.

매핑 항목 작성

각 매핑 항목은 YAML 문자열로 작성된 Go 템플릿 조각입니다. 조각은 엔티티 엔벨로프에 대해 불투명합니다. 컴파일러는 MappingLibrary 로드 시 문자열을 그대로 저장하고, Recipe 또는 FeatureRecipe가 valuesMapping: { $import: ... }를 통해 항목을 가져오는 소비 시점에 이를 파싱합니다. 가져오기는 Recipe의 valuesMapping: 전체를 대체하므로($import: 맵에는 다른 키가 없습니다), 항목은 어떤 문서에 끼워 넣는 조각이 아니라 완전한 values 문서입니다.

짧은 조각은 한 줄에 들어갑니다:

spec:
mappings:
AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'

여러 줄 조각은 YAML의 리터럴 스타일 스칼라(|)를 사용하여 줄바꿈과 들여쓰기가 왕복 과정에서 보존되도록 합니다:

spec:
mappings:
ProbeBlock: |
readinessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}
livenessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}

조각 안에서는 Go 템플릿의 전체 합성 어휘를 사용할 수 있습니다. {{ define "name" }}...{{ end }}는 단일 라이브러리 안에서 재사용 가능한 블록을 선언하고, {{ template "name" . }}는 이를 호출하며, 파이프라인과 함수는 표준 Go text/template 패키지에 따라 지원됩니다.

단일 작성 모드

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

그 이유는 소비 표면의 일관성입니다. Recipes와 FeatureRecipes는 전체가 Go 템플릿이며, 그 자체 내용도 가져온 항목을 해석하는 것과 동일한 Go 템플릿 엔진을 통해 평가되므로, 항목은 Recipe 자체 텍스트와 똑같이 읽히고 작성자는 하나의 평가 모델만 배우면 됩니다. Go 템플릿의 구성 어휘, 즉 라이브러리 안의 {{ define }}과 {{ template }}, 그리고 사용 시점의 $import: 지시문이 라이브러리에 필요한 재사용 가능한 블록과 매개변수화된 호출을 제공합니다.

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

명명 관례

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

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

spec.mappings에 PascalCase가 아닌 키가 있는 MappingLibrary는 워크스페이스 로드 시 엔벨로프 검증에 실패합니다. 이 강제는 중요한 역할을 합니다. 매핑 항목 키는 #/mappings/<name> 참조 프래그먼트에 나타나므로, PascalCase가 아닌 키는 해당 항목을 가져오는 모든 소비자로 전파됩니다.

명명의 일관성은 #/mappings/<name> 프래그먼트의 가독성을 유지합니다. #/mappings/ProbeBlock은 한눈에 읽힙니다.

라이브러리 항목 참조

Recipe 및 FeatureRecipe 작성자는 valuesMapping: { $import: ... } 블록 안에서 매핑 항목을 순수 이름 기반 식별자로 참조합니다:

# Inside a Recipe's valuesMapping block:
spec:
valuesMapping:
$import: "BaseMappings#/mappings/ProbeBlock"

#/mappings/<name> 프래그먼트는 항목을 선택하고, 매핑 참조를 SchemaLibrary의 #/schemas/<name>와 구별합니다. 이 참조는 SchemaLibrary $ref:와 동일한 순수 이름 기반 식별 모델을 사용합니다. 즉 <Library>#/mappings/<name> 형식이며, 레지스트리 호스트를 포함하지 않습니다. 버전은 Release별 lockfile(이름 + 버전 + 콘텐츠 다이제스트)이 제공합니다. 작성자는 선택적으로 최소 버전 하한을 <Library>:<version>#/mappings/<name> 형식으로 지정할 수 있으며(버전 구분자는 :로, recipe/feature 매핑 및 lockfile 고정과 일치합니다), 물리적 위치는 해석 시점에 결정됩니다.

라이브러리 간 구성

MappingLibrary 항목은 필드 루트 $import: 리디렉션일 수 있습니다. 이 경우 항목 본문의 첫 토큰은 $import: <Library>#/mappings/<entry>이며, 이는 항목 전체를 참조된 항목의 내용으로 대체합니다. 즉 제자리 템플릿 처리가 아니라 아이덴티티에 의한 재사용입니다. 리디렉션은 MappingLibrary 로드 시점이 아니라 소비 시점(Recipe 렌더링)에 해석되며, 재귀적으로 해석됩니다. 가져온 항목 자체가 다시 필드 루트 $import:일 수 있습니다. $import:는 항목 전체에만 적용되며, 프래그먼트 중간에 쓰는 템플릿 함수가 아닙니다. 단일 프래그먼트 안에서 템플릿 텍스트를 구성하려면 Go 템플릿의 define / template을 사용합니다.

# In library A — alias an entry to a shared entry in another library:
spec:
mappings:
StandardProbe: |
$import: MonitoringLibrary#/mappings/PrometheusAnnotations

라이브러리는 서로를 자유롭게 참조할 수 있습니다. 자기 자신으로 되돌아오는 체인은 이를 사용하는 Recipe가 렌더링될 때 중단되며, 순환의 각 단계를 지목하는 진단이 함께 출력됩니다.

계층 배치

MappingLibrary는 엔티티 계층 문서화 모델에서 Tier 3에 해당하며, Recipe 간 매핑 재사용이 필요한 카탈로그가 선택적으로 사용합니다. 반복되는 템플릿 내용이 없는 카탈로그는 MappingLibrary 엔티티 없이 배포됩니다. 계층 표시는 기능이 아니라 문서 탐색을 위한 “고급; 필요하지 않으면 건너뛰기”라는 신호입니다. 컴파일러는 MappingLibrary를 다른 카탈로그 엔티티 종류와 동일하게 취급합니다. 워크스페이스 로드 시 같은 엔벨로프 검증을, 릴리스 시 같은 OCI 게시 파이프라인을 거칩니다.

이 라이브러리 종류는 카탈로그 수준에서 SchemaLibrary와 자연스럽게 짝을 이룹니다. SchemaLibrary는 재사용 가능한 스키마 정의를 담고, MappingLibrary는 재사용 가능한 템플릿 조각을 담습니다. 둘 다 필요한 카탈로그는 둘 다 배포하고, 둘 다 필요 없는 카탈로그는 둘 다 배포하지 않습니다.

MappingLibrary가 아닌 것

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

  • 인라인 valuesMapping:의 대체물이 아닙니다. 대부분의 Recipes는 인라인으로 작성하는 편이 나은 단순한 valuesMapping: 내용을 담습니다. 이렇게 하면 Recipe가 자체적으로 완결되고, 작성자는 Recipe의 나머지 부분과 함께 매핑 내용을 읽을 수 있습니다. MappingLibrary는 동일한 조각이 여러 Recipes에 걸쳐 나타날 때 도움이 됩니다. 한 번만 쓰이는 매핑에는 인라인 작성이 올바른 선택입니다.

  • 스키마 내용을 두는 곳이 아닙니다. 스키마 정의(JSON Schema 2020-12)는 SchemaLibrary에 속하고, 템플릿 조각은 여기에 속합니다. 라이브러리 종류는 재사용 패턴이 아니라 내용 유형에 따라 나뉩니다.

  • Go 템플릿의 메커니즘을 넘어서는 매개변수화된 재사용이 아닙니다. 매개변수에 따른 변형이 필요한 작성자는 라이브러리 항목 안에서 Go 템플릿의 {{ define }} + {{ template arg }} 메커니즘을 사용하거나, 자체 변형으로 라이브러리 항목을 감싸는 Components / Features를 구성합니다. 라이브러리 엔터티 자체는 매개변수화 헬퍼 장치를 제공하지 않습니다(SchemaLibrary의 spec.templates 매개변수화 헬퍼에 해당하는 templates 블록이 없습니다). Go 템플릿의 구성 어휘가 같은 사용 사례를 다룹니다.