공유 스키마 라이브러리와 매핑 라이브러리: MariaDB Component
이 페이지는 Component의 스키마와 Recipe의 매핑 대부분을 여러 엔터티가 공유하는 라이브러리에 두는 한 가지 아이디어를 설명하며, 실행 가능한 워크스페이스가 아닙니다. MariaDB + Adminer — 실행 가능한 이중 대상 예제는 데이터베이스의 스토리지 설정을 스키마 라이브러리로 구성합니다. 다음 명령으로 직접 만든 폴더에 써 보십시오:
aggrega scaffold --example mariadb-adminer그런 다음 이어서 실행할 명령을 출력합니다:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yaml이 페이지의 엔터티는 네임스페이스 my-org에 있는 자체 카탈로그입니다. 각 엔터티의 형태는 프로덕션급 MariaDB Component와 그 Recipe, 그리고 이를 뒷받침하는 두 라이브러리가 취하는 형태입니다.
형태를 담는 스키마 라이브러리
SchemaLibrary는 이름 있는 스키마를 선언하며, 이 스키마는 간결한 형식(필드마다 한 줄로 타입, 제약 조건, 기본값을 적는 형식)으로 작성되고, 빌드는 어떤 값을 검사하기 전에 이를 JSON Schema 2020-12로 컴파일합니다. 발췌:
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: Datastores version: 1.0.0spec: schemas: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" } NodePool: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "Datastores#/schemas/PodResources" } MariaDBPayload: architecture: { type: string, enum: [standalone, replication], default: standalone } image: tag: { type: string, validate: '{{ ne . "latest" }}', validateMessage: "image.tag must name a version: latest moves with every chart release" } primary: { $ref: "Datastores#/schemas/NodePool", required: true } secondary: when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2, max: 8, default: 2 }참조는 라이브러리를 그 metadata.name으로 지정하며(Datastores#/schemas/<entry>), 라이브러리 내부에서도 라이브러리가 저장된 위치로 지정하지 않습니다. 따라서 라이브러리가 워크스페이스의 카탈로그에 있든 레지스트리에 게시되어 있든 같은 참조가 해석됩니다. validate:와 validateMessage:는 필드 자체의 검사를 추가합니다. when:은 객체 전체를 조건부로 만들므로, 보조 풀의 제약 조건은 아키텍처가 replication으로 해석되는 경우에만 적용됩니다. 문서 간 $ref:는 그 옆에 properties, required, description만 둘 수 있으며, 그래서 보조 풀은 NodePool을 참조하지 않고 전부 작성되어 있습니다.
이를 참조하는 Component
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-org/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: schema: values: $ref: Datastores#/schemas/MariaDBPayload infra: cpu_arch: { type: string, enum: [amd64, arm64], default: amd64 } provides: host: { type: string, format: hostname } port: { type: integer, min: 1024, max: 65535 } featuresSchema: root_credentials: required: true inject: [] replication_credentials: required: false inject: [] assertions: replication-needs-credentials: | {{- if eq .values.architecture "replication" -}} {{- if not (hasKey .features "replication_credentials") -}} {{- fail "architecture=replication requires replication_credentials secret to be supplied" -}} {{- end -}} {{- end -}}values 기둥은 $ref: 한 줄입니다. 작고 Component 고유한 infra와 provides는 인라인으로 남습니다. 어설션은 어떤 Recipe가 이를 구현하든, 어떤 스키마 키워드로도 표현되지 않는 Component 계약의 규칙을 담습니다.
변환을 담는 매핑 라이브러리
MappingLibrary는 Recipe가 가져오는 템플릿 조각을 담습니다. 한 항목은 차트의 values를 렌더링하고, define으로 헬퍼를 선언한 뒤 각 노드 풀마다 template으로 이를 호출합니다:
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BitnamiHelpers version: 1.0.0spec: mappings: MariaDBBitnamiCore: | {{- define "BitnamiNodePool" }} resources: requests: cpu: {{ .pool.resources.requests.cpu | quote }} memory: {{ .pool.resources.requests.memory | quote }} {{- end }} {{- with .values -}} fullnameOverride: {{ $.context.rendered_name | quote }} architecture: {{ .architecture }} primary: name: primary {{- template "BitnamiNodePool" (dict "pool" .primary) }} {{- end }}헬퍼는 그것을 사용하는 항목 안에 선언됩니다. Recipe는 항목 하나를 가져오고, 정의는 그것을 담은 항목과 함께 이동하기 때문입니다. 조각은 Aggrega의 렌더러가 평가하므로 Sprig의 함수와, 없을 수도 있는 키에 쓰는 Aggrega의 optional을 사용합니다(sprig-functions.md 참조). Helm의 include는 그중 하나가 아니며, template은 출력을 정확히 그 자리에 씁니다.
이를 가져오는 Recipe
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: capability: helm implements: my-org/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "25.0.8" valuesMapping: $import: BitnamiHelpers#/mappings/MariaDBBitnamiCore provides: host: "{{ .context.rendered_name }}{{ if eq .values.architecture `replication` }}-primary{{ end }}" port: "3306"Recipe는 작습니다. 매핑은 라이브러리에 있고, Recipe는 자신의 것, 즉 렌더링하는 차트와 게시하는 주소만 유지합니다. 매핑이 차트의 fullnameOverride를 .context.rendered_name으로 고정하므로, Recipe는 프라이머리의 Service 이름을 가정하지 않고 계산할 수 있습니다.
라이브러리가 주는 이점
JSON Schema로 작성하면 각 필드의 한 줄 맵은 중첩 블록이 되고, 모든 객체에 type: object, properties:, 그리고 required: 목록이 추가됩니다. when:과 validate:에는 그에 해당하는 JSON Schema 키워드가 없습니다. 간결한 형식은 $jsonschema: 탈출구 없이 이 Component에 필요한 모든 것을 다룹니다. 절약은 공유할수록 커집니다. 라이브러리는 한 번만 작성하고, 이후 각 Component의 values 기둥은 $ref: 한 줄입니다.
참고 문서: 간결한 형식 작성, 문서 간 $ref:, 어설션 블록, SchemaLibrary, MappingLibrary.