WorkloadLibrary
WorkloadLibrary는 재사용 가능한 Workload 템플릿 조각을 담는 카탈로그 엔터티입니다. 동일한 워크로드 형태(메트릭을 노출하는 서버, 배치 작업, 사이드카 쌍 등)를 배포하는 Recipes와 FeatureRecipes는 그 형태를 라이브러리에 한 번 선언하고, 사용 시점에 workload: { $import: ... } 지시문으로 참조합니다. 이 라이브러리 엔터티는 Tier 3이며, Recipe 간 워크로드 재사용이 필요한 카탈로그가 선택적으로 사용합니다. 각 Recipe가 저마다 고유한 워크로드 형태를 갖는 카탈로그는 WorkloadLibrary 없이 배포됩니다.
WorkloadLibrary의 역할
플랫폼 아키텍트는 카탈로그의 Recipes와 FeatureRecipes 전반에서 반복되는 Workload 콘텐츠를 한곳에 모으기 위해 WorkloadLibraries를 작성합니다. 라이브러리는 배포 가능한 빌드 지침이 아니라 정의의 네임스페이스입니다. Recipe 및 FeatureRecipe 작성자는 $import: 지시문으로 라이브러리 항목을 참조하며, 이 지시문은 한 번 작성되고 import가 해석되는 모든 곳에서 사용됩니다.
“라이브러리”와 “소비자”를 나눈 것은 의도된 설계입니다. Recipes는 빌드 지침(source, valuesMapping, artifacts)을 담습니다. FeatureRecipes는 동작 부착을 담습니다. WorkloadLibraries는 Workload 콘텐츠, 즉 provider가 provider 고유의 매니페스트로 합성하는 워크로드 형태만을 담습니다. 세 역할을 구분해 두면 각 엔티티 종류가 저마다의 속도로 발전할 수 있으며, 공유 워크로드 콘텐츠가 필요 없는 작성자는 라이브러리 엔티티를 접할 일이 없습니다.
엔티티 엔벨로프
WorkloadLibrary 엔티티는 표준 카탈로그 엔벨로프를 가집니다. apiVersion: aggrega.ai/v1beta1와 kind: WorkloadLibrary는 엔티티 종류를 나타내고, metadata.name은 PascalCase 식별자이며, metadata.version은 엄격한 시맨틱 버저닝을 따릅니다. 둘 다 필수입니다. metadata.description, metadata.labels, metadata.annotations는 선택 사항입니다. 레이블과 어노테이션은 작성자가 선언하는 불투명한 메타데이터로, 라이브러리를 읽는 쪽이 일치 여부를 판단하는 데 쓸 수 있도록 함께 전달되며, 컴파일러는 그 값을 해석하지 않습니다. 라이브러리의 내용은 spec.workloads 아래에 위치하며, 이는 최소 하나의 항목을 선언해야 하는 필수 맵입니다.
엔벨로프는 세 수준 모두에서 닫혀 있습니다. 문서 루트, metadata, spec은 각각 스키마가 선언하지 않은 키를 거부합니다.
apiVersion: aggrega.ai/v1beta1kind: WorkloadLibrarymetadata: name: BaseWorkloads version: 1.0.0spec: workloads: SimpleServer: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }}Workload 항목 작성
각 항목은 YAML 문자열로 작성된 Go 템플릿 조각입니다. 항목의 렌더링 출력은 완전한 Workload 문서이며, 자체 apiVersion: aggrega.ai/v1beta1과 kind: Workload를 가집니다. Recipe의 workload: 필드는 주변 문서에 이어 붙이는 조각이 아니라 하나의 완전한 Workload를 받고, 가져오기는 필드 전체를 대체하기 때문입니다. MappingLibrary 항목도 같은 방식으로 완전합니다. 그 항목을 가져오면 Recipe의 valuesMapping: 전체가 대체됩니다.
본문은 엔티티 엔벨로프에 대해 불투명합니다. 컴파일러는 WorkloadLibrary 로드 시점에 문자열을 그대로 저장하며, 그 시점에는 템플릿을 파싱하지 않습니다. 템플릿 파서는 Recipe 또는 FeatureRecipe가 항목을 가져오는 소비 시점에 실행됩니다. 조각을 그대로 저장하면 재출력 시 작성 충실도가 보존되며, 템플릿 오류가 라이브러리가 아니라 항목이 소비되고 그 필라 컨텍스트가 알려진 곳에서 드러납니다.
Workload 문서는 여러 줄이므로, 항목은 줄바꿈과 들여쓰기가 왕복 변환에서도 유지되도록 YAML의 리터럴 스타일 스칼라(|)를 사용합니다.
spec: workloads: BatchJob: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: task containers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"]항목의 값은 문자열 스칼라여야 합니다. 본문 자리에 매핑이나 시퀀스를 작성하면 거부됩니다. 항목 본문은 컴파일러가 순회하는 구조화된 YAML이 아니라 템플릿 텍스트입니다.
항목 안에서는 Go 템플릿의 전체 조합 어휘를 사용할 수 있습니다. {{ define "name" }}...{{ end }}는 단일 라이브러리 안에서 재사용 가능한 블록을 선언하고, {{ template "name" . }}는 이를 호출하며, 파이프라인과 함수는 표준 Go text/template 패키지를 따릅니다. 항목이 읽을 수 있는 필라 컨텍스트(.values, .infra, .locals, .context, .features)는 모든 Workload 템플릿이 읽는 컨텍스트와 같으며, Workload 페이지의 템플릿 평가 항목에 문서화되어 있습니다.
대상 프로바이더는 워크로드 합성을 지원해야 합니다. 라이브러리 항목을 가져오지만 Workload를 합성할 수 없는 프로바이더에 바인딩된 Recipe는 저하된 형태를 출력하지 않고 렌더링 시점에 명시적으로 중단됩니다. 표준 라이브러리 카탈로그는 문서화된 계약으로서, 이를 지원하는 프로바이더에 workloadSchema를 선언합니다.
단일 작성 모드
WorkloadLibrary는 Go 템플릿이라는 하나의 작성 모드만 제공합니다. spec은 라이브러리 수준에서 병행 작성 표면도, 표현력을 위한 탈출구도 받아들이지 않습니다.
그 이유는 소비 표면의 일관성입니다. Recipes와 FeatureRecipes는 전체가 Go 템플릿이며, 이들 자체의 내용은 가져온 프래그먼트를 해석하는 것과 동일한 Go 템플릿 엔진을 통해 평가됩니다. 병행 작성 표면이 있다면 작성자는 하나의 Recipe를 렌더링하는 도중에 평가 모델을 전환해야 합니다. Recipe 자체의 내용에는 한 모델을, 가져온 라이브러리 항목에는 다른 모델을 써야 하는 것입니다. 표면을 일관되게 유지하면 작성자는 하나의 평가 모델만 익혀 모든 곳에 적용할 수 있습니다.
Go 템플릿의 조합 어휘를 넘어서는 표현력이 필요한 작성자는 라이브러리 안에서 두 번째 작성 언어로 확장하는 대신, 더 높은 수준에서 조합합니다. 즉, 라이브러리 항목을 자체의 실질적인 변형으로 감싸는 Components나 Features를 사용합니다.
명명 관례
라이브러리 이름과 워크로드 항목 키는 PascalCase를 따릅니다. 엔티티 엔벌로프의 JSON Schema는 패턴 제약을 통해 두 위치에서 이 관례를 강제합니다.
metadata.name은^[A-Z][A-Za-z0-9]*$와 일치해야 합니다.spec.workloads맵 키는propertyNames를 통해 같은 패턴과 일치해야 합니다.
spec.workloads에 PascalCase가 아닌 키가 있는 WorkloadLibrary는 워크스페이스 로드 시 엔벌로프 검증에 실패합니다. 이 강제는 중요한 역할을 합니다. 워크로드 항목 키는 #/workloads/<name> 참조 프래그먼트에 나타나므로, PascalCase가 아닌 키는 해당 항목을 가져오는 모든 소비자에게 전파됩니다.
명명의 일관성은 #/workloads/<name> 프래그먼트를 읽기 쉽게 유지합니다. #/workloads/BatchJob은 한눈에 읽힙니다.
라이브러리 항목 참조
Recipe 및 FeatureRecipe 작성자는 workload: { $import: ... } 블록 안에서 워크로드 항목을 bare-name 식별자로 참조합니다:
# Inside a Recipe's spec:spec: workload: $import: "BaseWorkloads#/workloads/SimpleServer"#/workloads/<name> 프래그먼트는 항목을 선택하며, 워크로드 참조를 MappingLibrary의 #/mappings/<name> 및 SchemaLibrary의 #/schemas/<name>와 구별합니다. 참조에는 레지스트리 호스트가 포함되지 않습니다. 호스트를 포함하는 oci://… 형식은 엔벌로프 스키마와 소비 지점 양쪽에서 거부되므로, 물리적 레지스트리 위치가 작성된 소스에 들어가는 일은 없습니다. 작성자는 선택적으로 최소 버전 하한을 <Library>:<version>#/workloads/<name> 형식으로 지정할 수 있습니다. 버전 구분자는 recipe/feature 매핑 및 lockfile 고정과 동일하게 :이며, 대신 @를 쓰면 수정된 참조를 제시하는 진단과 함께 거부됩니다. 해석된 버전은 Release별 lockfile이 제공하며, lockfile은 소비되는 각 라이브러리를 이름, 버전, 콘텐츠 다이제스트로 고정합니다. 물리적 위치는 해석 시점에 바인딩됩니다.
같은 workload: 필드는 다른 두 가지 형식도 받습니다. 하나는 인라인 Go 템플릿 문자열이고, 다른 하나는 Recipe 디렉터리 기준 상대 경로의 로컬 파일에 대한 $import:입니다. 세 형식은 내용의 형태로 구별되며, 세 가지 모두 파싱 후 동일한 Workload를 생성합니다. workload:가 Recipe의 다른 입력 종류와 어떻게 구성되는지는 Recipe를, 더 넓은 $ref: / $import: 구분은 vocabulary/cross-document-ref를 참조하십시오.
라이브러리 간 구성
WorkloadLibrary 항목은 필드 루트 $import: 리디렉션일 수 있습니다. 이 경우 본문의 첫 토큰은 $import: <Library>#/workloads/<entry>이며, 항목 전체를 참조된 항목의 내용으로 대체합니다. 이는 제자리 템플릿 처리가 아니라 식별자에 의한 재사용입니다. 리디렉션은 WorkloadLibrary 로드 시점이 아니라 사용 시점에 해석되며, 재귀적으로 해석되므로 가져온 항목 자체가 필드 루트 $import:일 수도 있습니다. 자기 자신으로 되돌아오는 체인은 해당 순환을 명시하는 진단과 함께 중단됩니다. $import:는 항목 전체에만 적용되며, 프래그먼트 중간에 쓰는 템플릿 함수가 아닙니다. 단일 항목 안에서 템플릿 텍스트를 구성하려면 Go 템플릿의 define / template을 사용합니다.
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServer알 수 없는 라이브러리 이름과, 해석되는 라이브러리에 없는 항목 이름은 서로 다른 진단으로 보고되므로, 작성자는 누락된 의존성과 철자가 틀린 항목을 구별할 수 있습니다.
계층 배치
WorkloadLibrary는 엔터티 계층 문서화 모델에서 Tier 3에 해당하며, Recipe 간에 워크로드를 재사용해야 하는 카탈로그가 선택적으로 사용합니다. Recipes가 각자 고유한 워크로드 내용을 담는 카탈로그는 WorkloadLibrary 엔터티 없이 배포됩니다. 계층 표시는 기능이 아니라 문서 탐색을 위해 “고급; 필요하지 않으면 건너뛰십시오”라는 신호를 줍니다. 컴파일러는 WorkloadLibrary를 다른 카탈로그 엔터티 종류와 동일하게 취급합니다. 워크스페이스 로드 시 같은 엔벨로프 검증을, 릴리스 시 같은 OCI 게시 파이프라인을, 그리고 이름, 버전, 내용 다이제스트에 의한 같은 lockfile 고정을 적용합니다.
이 라이브러리 종류는 카탈로그 수준의 한 세트 중 하나입니다. SchemaLibrary는 재사용 가능한 스키마 정의를, MappingLibrary는 재사용 가능한 매핑 조각을, ArtifactLibrary는 재사용 가능한 아티팩트 번들을, WorkloadLibrary는 재사용 가능한 워크로드 내용을 담습니다. 각각은 독립적으로 선택하여 사용하며, 카탈로그는 필요한 것만 포함하고 나머지는 포함하지 않습니다.
WorkloadLibrary가 아닌 것
미리 짚어 둘 만한 흔한 오해가 몇 가지 있습니다:
-
인라인
workload:의 대체물이 아닙니다. 대부분의 Recipes는 인라인에 두는 것이 적합할 만큼 구체적인 워크로드 콘텐츠를 담으며, 작성자는 이를 Recipe의 나머지 부분과 함께 읽습니다. WorkloadLibrary는 동일한 워크로드 형태가 여러 Recipes에 걸쳐 나타날 때 도움이 됩니다. 일회성 콘텐츠에는 인라인 작성이 올바른 선택입니다. -
부분 조각을 두는 곳이 아닙니다. 항목은 완전한 Workload 문서로 렌더링됩니다. Recipe의 values 문서는 MappingLibrary에, 보조 파일 묶음은 ArtifactLibrary에, 스키마 정의는 SchemaLibrary에 속합니다. 라이브러리 종류는 재사용 패턴이 아니라 콘텐츠 유형에 따라 나뉩니다.
-
독립적으로 배포할 수 있는 엔티티가 아닙니다. 라이브러리 항목은 Workload 콘텐츠이며, Workload 콘텐츠는 그 자체로는 결코 참조할 수 없습니다. 이는 Recipe 또는 FeatureRecipe가 소비하는 입력으로 존재합니다. WorkloadLibrary를 게시하면 그 항목을 가져올 수 있게 되지만, 배포할 수 있게 되지는 않습니다.
-
Go 템플릿의 메커니즘을 넘어서는 매개변수화된 재사용이 아닙니다. 매개변수화된 변형이 필요한 작성자는 라이브러리 항목 안에서 Go 템플릿의
{{ define }}+{{ template }}메커니즘을 사용하거나, 이를 소비하는 Recipe가 제공하는 필러 컨텍스트를 사용합니다. 라이브러리 엔티티 자체는 매개변수화 헬퍼 기능을 제공하지 않습니다.