Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

MappingLibrary

MappingLibrary adalah entitas katalog yang menyimpan fragmen templat Go yang dapat digunakan ulang. Recipes dan FeatureRecipes yang berbagi seluruh dokumen valuesMapping: — nilai yang diserahkan masing-masing dari beberapa Recipes yang bersumber dari chart yang sama kepada chart itu — mendeklarasikannya sekali dalam sebuah pustaka dan merujuknya pada saat konsumsi melalui direktif valuesMapping: { $import: ... }. Entitas pustaka ini berada di Tier 3: bersifat opsional bagi katalog yang memerlukan penggunaan ulang pemetaan lintas Recipe. Katalog tanpa konten templat yang berulang dirilis tanpa MappingLibrary apa pun.

Peran MappingLibrary

Arsitek platform menyusun MappingLibraries untuk memusatkan fragmen templat Go yang berulang di seluruh Recipes dan FeatureRecipes dalam katalog. Sebuah pustaka bukanlah instruksi build yang dapat di-deploy; pustaka adalah namespace definisi. Penyusun Recipe dan FeatureRecipe mereferensikan entri pustaka melalui direktif $import:, yang ditulis sekali dan digunakan di mana pun impor tersebut berhasil di-resolve.

Pemisahan antara “pustaka” dan “konsumen” disengaja. Recipes mengodekan instruksi build (source, valuesMapping, artifacts). FeatureRecipes mengodekan lampiran perilaku. MappingLibraries hanya mengodekan fragmen templat — konten templat Go yang digunakan oleh entitas lain pada saat render. Dengan menjaga ketiga peran tetap terpisah, setiap jenis entitas dapat berkembang dengan ritmenya sendiri; penyusun yang tidak memerlukan konten templat bersama tidak pernah berurusan dengan entitas pustaka.

Amplop entitas

Entitas MappingLibrary membawa envelope katalog standar. apiVersion: aggrega.ai/v1beta1 dan kind: MappingLibrary menandai jenis entitas; metadata.name adalah pengenal PascalCase; metadata.version mengikuti semantic versioning yang ketat. Konten pustaka berada di bawah spec.mappings, sebuah map wajib yang harus mendeklarasikan setidaknya satu entri.

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 }}'

Sebuah entri dievaluasi oleh mesin templat milik Recipe yang mengonsumsinya, terhadap konteks render Recipe tersebut, sehingga entri membaca pilar huruf kecil yang dibaca valuesMapping: milik Recipe itu sendiri — .values, .infra, .context, dan lainnya — serta menggunakan fungsi yang sama, seperti helper optional yang peka terhadap keberadaan untuk kunci yang tidak ada. .Values, ejaan Helm untuk nilai chart, bukan root yang didefinisikan konteks tersebut: entri yang membacanya menghentikan build, dengan menyebut referensinya.

Menulis entri pemetaan

Setiap entri pemetaan adalah fragmen templat Go yang ditulis sebagai string YAML. Fragmen tersebut bersifat buram bagi amplop entitas — kompiler menyimpan string tersebut apa adanya saat MappingLibrary dimuat dan menguraikannya pada waktu konsumsi ketika sebuah Recipe atau FeatureRecipe mengimpor entri tersebut melalui valuesMapping: { $import: ... }. Impor menggantikan seluruh valuesMapping: milik Recipe — map $import: tidak membawa kunci lain — sehingga sebuah entri adalah dokumen nilai yang lengkap, bukan potongan yang disisipkan ke dalamnya.

Fragmen pendek muat dalam satu baris:

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

Fragmen multibaris menggunakan skalar gaya literal YAML (|) agar baris baru dan indentasi tetap utuh saat bolak-balik:

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

Seluruh kosakata komposisi templat Go tersedia di dalam fragmen: {{ define "name" }}...{{ end }} mendeklarasikan blok yang dapat digunakan ulang di dalam satu pustaka; {{ template "name" . }} memanggilnya; pipeline dan fungsi didukung sesuai paket Go standar text/template.

Mode penulisan tunggal

MappingLibrary hadir dengan satu mode penulisan: templat Go. spec tidak menerima permukaan penulisan paralel dan tidak ada jalan keluar ekspresivitas di tingkat pustaka.

Alasannya adalah keseragaman permukaan konsumsi. Recipes dan FeatureRecipes sepenuhnya berbasis templat Go, dan konten mereka sendiri dievaluasi melalui mesin templat Go yang sama yang meresolusi entri yang diimpor, sehingga sebuah entri terbaca persis seperti teks milik Recipe itu sendiri dan penulis mempelajari satu model evaluasi. Kosakata komposisi templat Go — {{ define }} dan {{ template }} di dalam pustaka, serta direktif $import: pada saat konsumsi — menyediakan blok yang dapat digunakan ulang dan pemanggilan berparameter yang dibutuhkan sebuah pustaka.

Penulis yang membutuhkan ekspresivitas melampaui apa yang ditawarkan kosakata komposisi templat Go melakukan komposisi di tingkat yang lebih tinggi — Components atau Features yang membungkus entri pustaka dengan variasi substantif mereka sendiri — alih-alih beralih ke bahasa penulisan paralel di dalam MappingLibrary itu sendiri.

Konvensi penamaan

Nama pustaka dan kunci entri pemetaan mengikuti PascalCase. JSON Schema dari amplop entitas menegakkan konvensi ini pada dua posisi melalui batasan pola:

  • metadata.name cocok dengan ^[A-Z][A-Za-z0-9]*$.
  • Kunci map spec.mappings cocok dengan pola yang sama melalui propertyNames.

Sebuah MappingLibrary dengan kunci non-PascalCase di spec.mappings gagal dalam validasi amplop saat workspace dimuat. Penegakan ini bersifat penting: kunci entri pemetaan muncul dalam fragmen referensi #/mappings/<name>; kunci non-PascalCase akan merambat ke setiap konsumen yang mengimpor entri tersebut.

Keseragaman penamaan ini menjaga fragmen #/mappings/<name> tetap mudah dibaca: #/mappings/ProbeBlock dapat dipahami sekilas.

Mereferensikan entri pustaka

Penulis Recipe dan FeatureRecipe mereferensikan sebuah entri pemetaan di dalam blok valuesMapping: { $import: ... } melalui identitas nama polosnya:

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

Fragmen #/mappings/<name> memilih entri tersebut dan membedakan referensi pemetaan dari #/schemas/<name> milik SchemaLibrary. Referensi ini menggunakan model identitas nama polos yang sama dengan $ref: pada SchemaLibrary — <Library>#/mappings/<name>, tanpa membawa host registri. Versi disediakan oleh lockfile per Release (nama + versi + digest konten); seorang penulis dapat menyatakan batas versi minimum opsional sebagai <Library>:<version>#/mappings/<name> (pemisah versi adalah :, sesuai dengan pemetaan recipe/feature dan pin lockfile), dan lokasi fisik diikat pada saat resolusi.

Komposisi lintas pustaka

Sebuah entri MappingLibrary dapat berupa pengalihan $import: pada akar bidang: token pertama dari isinya adalah $import: <Library>#/mappings/<entry>, yang menggantikan seluruh entri dengan konten entri yang dirujuk — penggunaan ulang berdasarkan identitas, bukan templating di tempat. Pengalihan ini di-resolve pada saat konsumsi (rendering Recipe), bukan saat MappingLibrary dimuat, dan secara rekursif — entri yang diimpor dapat juga berupa $import: pada akar bidang. $import: hanya berlaku untuk seluruh entri; ini bukan fungsi templat di tengah fragmen. Untuk menyusun teks templat di dalam satu fragmen, gunakan Go template define / template.

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

Pustaka dapat saling merujuk dengan bebas. Rantai yang kembali ke dirinya sendiri berhenti ketika Recipe yang mengonsumsinya di-render, dengan diagnostik yang menyebut setiap langkah siklus.

Penempatan tier

MappingLibrary berada di Tier 3 dalam model dokumentasi tingkatan entitas — bersifat opsional bagi katalog yang memerlukan penggunaan ulang mapping lintas Recipe. Katalog tanpa konten templat yang berulang dirilis tanpa entitas MappingLibrary apa pun; penandaan tingkatan menandakan “lanjutan; lewati jika tidak diperlukan” untuk navigasi dokumentasi, bukan kapabilitas. Compiler memperlakukan MappingLibrary secara seragam dengan jenis entitas katalog lainnya: validasi envelope yang sama saat pemuatan workspace, pipeline publikasi OCI yang sama saat waktu rilis.

Jenis library ini secara alami berpasangan dengan SchemaLibrary di tingkat katalog — SchemaLibrary menyimpan definisi skema yang dapat digunakan ulang; MappingLibrary menyimpan fragmen templat yang dapat digunakan ulang. Katalog yang memerlukan keduanya menyertakan keduanya; katalog yang tidak memerlukan keduanya tidak menyertakan keduanya.

Hal-hal yang bukan MappingLibrary

Beberapa kesalahpahaman umum yang perlu diluruskan sejak awal:

  • Bukan pengganti valuesMapping: inline. Sebagian besar Recipes memuat konten valuesMapping: sederhana yang lebih baik ditulis secara inline — Recipe tetap mandiri dan penulis membaca konten pemetaan bersama sisa Recipe tersebut. MappingLibrary berguna ketika fragmen yang SAMA muncul di banyak Recipes; untuk pemetaan sekali pakai, penulisan inline adalah pilihan yang tepat.

  • Bukan tempat untuk konten skema. Definisi skema (JSON Schema 2020-12) ditempatkan di SchemaLibrary; fragmen templat ditempatkan di sini. Jenis-jenis pustaka dipisahkan berdasarkan jenis konten, bukan berdasarkan pola penggunaan ulang.

  • Bukan penggunaan ulang parametrik di luar mekanisme Go template. Penulis yang membutuhkan variasi parametrik menggunakan mekanisme {{ define }} + {{ template arg }} dari Go template di dalam entri pustaka, atau menyusun Components / Features yang membungkus entri pustaka dengan variasinya sendiri. Entitas pustaka itu sendiri tidak menyediakan mesin pembantu parametrik (tidak ada blok templates yang setara dengan pembantu parametrik spec.templates milik SchemaLibrary); kosakata komposisi Go template mencakup kasus penggunaan yang sama.