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

WorkloadLibrary

WorkloadLibrary adalah entitas katalog yang menyimpan fragmen templat Workload yang dapat digunakan ulang. Recipes dan FeatureRecipes yang men-deploy bentuk workload yang sama — server yang mengekspos metrik, batch job, pasangan sidecar — mendeklarasikan bentuk itu sekali dalam sebuah library dan mereferensikannya pada saat konsumsi melalui direktif workload: { $import: ... }. Entitas library ini berada di Tier 3: bersifat opsional untuk katalog yang memerlukan penggunaan ulang workload lintas Recipe. Katalog yang setiap Recipes-nya membawa bentuk workload tersendiri yang berbeda dapat dirilis tanpa WorkloadLibrary apa pun.

Peran WorkloadLibrary

Arsitek platform menyusun WorkloadLibraries untuk memusatkan konten Workload yang berulang di seluruh Recipes dan FeatureRecipes dalam katalog. Sebuah pustaka bukanlah instruksi build yang dapat di-deploy; pustaka adalah namespace definisi. Penulis 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. WorkloadLibraries hanya mengodekan konten Workload — bentuk workload yang disintesis oleh provider menjadi manifest native provider. Dengan menjaga ketiga peran ini tetap terpisah, setiap jenis entitas dapat berkembang dengan ritmenya sendiri; penulis yang tidak memerlukan konten workload bersama tidak akan pernah berurusan dengan entitas pustaka.

Amplop entitas

Entitas WorkloadLibrary membawa amplop katalog standar. apiVersion: aggrega.ai/v1beta1 dan kind: WorkloadLibrary menandai jenis entitas; metadata.name adalah pengenal PascalCase; metadata.version mengikuti semantic versioning yang ketat. Keduanya wajib. metadata.description, metadata.labels, dan metadata.annotations bersifat opsional — label dan anotasi adalah metadata buram yang dideklarasikan penulis, dibawa agar apa pun yang membaca pustaka dapat mencocokkannya, dan kompiler tidak menafsirkan nilainya. Konten pustaka berada di bawah spec.workloads, sebuah map wajib yang harus mendeklarasikan setidaknya satu entri.

Amplop ini tertutup di ketiga tingkat — akar dokumen, metadata, dan spec masing-masing menolak kunci yang tidak dideklarasikan oleh skema.

apiVersion: aggrega.ai/v1beta1
kind: WorkloadLibrary
metadata:
name: BaseWorkloads
version: 1.0.0
spec:
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 }}

Menulis entri Workload

Setiap entri adalah fragmen template Go yang ditulis sebagai string YAML. Keluaran hasil render entri adalah dokumen Workload utuh — dokumen itu membawa apiVersion: aggrega.ai/v1beta1 dan kind: Workload miliknya sendiri — karena field workload: pada sebuah Recipe menerima satu Workload lengkap, bukan fragmen yang disisipkan ke dalam Workload di sekitarnya, dan impor menggantikan seluruh field tersebut. Entri MappingLibrary juga utuh dengan cara yang sama: mengimpornya menggantikan seluruh valuesMapping: milik Recipe.

Isi entri bersifat opak bagi envelope entitas. Compiler menyimpan string tersebut apa adanya saat WorkloadLibrary dimuat dan tidak mem-parse template di sana; parser template berjalan pada saat konsumsi, ketika sebuah Recipe atau FeatureRecipe mengimpor entri tersebut. Menyimpan fragmen apa adanya menjaga ketepatan penulisan untuk emisi ulang, dan itu berarti kesalahan template muncul di tempat entri dikonsumsi dan konteks pilarnya diketahui, bukan di pustaka.

Karena dokumen Workload terdiri atas banyak baris, entri menggunakan skalar gaya literal YAML (|) agar baris baru dan indentasi tetap utuh saat round-trip:

spec:
workloads:
BatchJob: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]

Nilai sebuah entri harus berupa skalar string. Menulis mapping atau sequence di tempat isi entri akan ditolak — isi entri adalah teks template, bukan YAML terstruktur yang ditelusuri compiler.

Seluruh kosakata komposisi template Go tersedia di dalam entri: {{ define "name" }}...{{ end }} mendeklarasikan blok yang dapat digunakan ulang dalam satu pustaka, {{ template "name" . }} memanggilnya, dan pipeline serta fungsi mengikuti paket Go standar text/template. Konteks pilar yang dapat dibaca entri — .values, .infra, .locals, .context, .features — sama dengan konteks yang dibaca template Workload mana pun, dan didokumentasikan di halaman Workload pada bagian evaluasi template.

Provider target harus mendukung sintesis workload. Recipe yang mengimpor entri pustaka tetapi terikat pada provider yang tidak dapat menyintesis Workload akan berhenti secara eksplisit saat render alih-alih menghasilkan bentuk yang terdegradasi; katalog pustaka standar mendeklarasikan workloadSchema pada provider yang mendukungnya, sebagai kontrak yang terdokumentasi.

Mode penulisan tunggal

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

Alasannya adalah keseragaman permukaan konsumsi. Recipes dan FeatureRecipes sepenuhnya menggunakan templat Go, dan kontennya sendiri dievaluasi melalui mesin templat Go yang sama yang meresolusi fragmen yang diimpor. Permukaan penulisan paralel akan memaksa penulis berganti model evaluasi dalam proses rendering satu Recipe — satu model untuk konten Recipe itu sendiri, model lain untuk setiap entri pustaka yang diimpor. Dengan menjaga permukaan tetap seragam, penulis cukup mempelajari satu model evaluasi dan menerapkannya di mana saja.

Penulis yang membutuhkan ekspresivitas di luar kosakata komposisi templat Go melakukan komposisi di tingkat yang lebih tinggi — Components atau Features yang membungkus entri pustaka dengan variasi substantifnya sendiri — alih-alih beralih ke bahasa penulisan kedua di dalam pustaka.

Konvensi penamaan

Nama library dan kunci entri workload mengikuti PascalCase. JSON Schema amplop entitas memberlakukan konvensi ini pada dua posisi melalui batasan pola:

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

WorkloadLibrary dengan kunci non-PascalCase di spec.workloads gagal dalam validasi amplop saat workspace dimuat. Pemberlakuan ini memiliki peran penting: kunci entri workload muncul dalam fragmen referensi #/workloads/<name>, sehingga kunci non-PascalCase akan merambat ke setiap konsumen yang mengimpor entri tersebut.

Keseragaman penamaan menjaga fragmen #/workloads/<name> tetap mudah dibaca: #/workloads/BatchJob dapat dipahami dalam sekilas pandang.

Mereferensikan entri pustaka

Penulis Recipe dan FeatureRecipe mereferensikan entri workload di dalam blok workload: { $import: ... } berdasarkan identitas nama polosnya:

# Inside a Recipe's spec:
spec:
workload:
$import: "BaseWorkloads#/workloads/SimpleServer"

Fragmen #/workloads/<name> memilih entri tersebut dan membedakan referensi workload dari #/mappings/<name> milik MappingLibrary dan #/schemas/<name> milik SchemaLibrary. Referensi tidak membawa host registry; bentuk oci://… yang memuat host ditolak baik oleh skema envelope maupun di lokasi konsumsi, sehingga lokasi fisik registry tidak pernah masuk ke sumber yang ditulis. Penulis dapat menyatakan batas bawah versi minimum opsional sebagai <Library>:<version>#/workloads/<name> — pemisah versinya adalah :, sesuai dengan pemetaan recipe/feature dan pin lockfile, dan penulisan @ sebagai gantinya ditolak dengan diagnostik yang menyebutkan referensi yang telah dikoreksi. Versi yang diresolusi disediakan oleh lockfile per Release, yang mem-pin setiap pustaka yang dikonsumsi berdasarkan nama, versi, dan digest konten; lokasi fisik diikat pada saat resolusi.

Field workload: yang sama menerima dua bentuk lain — string template Go inline, dan $import: dari path file lokal yang relatif terhadap direktori Recipe. Ketiga bentuk tersebut dibedakan berdasarkan bentuk kontennya, dan ketiganya menghasilkan Workload pasca-parse yang sama. Lihat Recipe untuk cara workload: berkomposisi dengan jenis input Recipe lainnya, dan vocabulary/cross-document-ref untuk perbedaan $ref: / $import: yang lebih luas.

Komposisi lintas pustaka

Sebuah entri WorkloadLibrary dapat berupa pengalihan $import: di akar field: token pertama badannya adalah $import: <Library>#/workloads/<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, bukan saat WorkloadLibrary dimuat, dan di-resolve secara rekursif, sehingga entri yang diimpor dapat juga berupa $import: di akar field. Rantai yang berputar kembali ke dirinya sendiri dihentikan dengan diagnostik yang menyebutkan siklusnya. $import: hanya berlaku untuk seluruh entri; ini bukan fungsi template di tengah fragmen. Untuk menyusun teks template di dalam satu entri, gunakan Go template define / template.

# In library A — alias an entry to a shared entry in another library:
spec:
workloads:
StandardServer: |
$import: PlatformWorkloads#/workloads/MetricsServer

Nama library yang tidak dikenal, dan nama entri yang tidak ada dalam library yang berhasil di-resolve, dilaporkan sebagai diagnostik yang berbeda, sehingga penulis dapat membedakan dependensi yang hilang dari entri yang salah eja.

Penempatan tier

WorkloadLibrary berada di Tier 3 dalam model dokumentasi tingkatan entitas — bersifat opsional bagi katalog yang memerlukan penggunaan ulang konten workload lintas Recipe. Katalog yang Recipes-nya membawa konten workload tersendiri yang berbeda dirilis tanpa entitas WorkloadLibrary apa pun; penandaan tingkatan ini menandakan “lanjutan; lewati jika tidak diperlukan” untuk navigasi dokumentasi, bukan kapabilitas. Compiler memperlakukan WorkloadLibrary secara seragam dengan jenis entitas katalog lainnya: validasi envelope yang sama saat pemuatan workspace, pipeline publikasi OCI yang sama saat rilis, dan penyematan lockfile yang sama berdasarkan nama, versi, dan digest konten.

Jenis library ini adalah salah satu dari satu set di tingkat katalog — SchemaLibrary menyimpan definisi skema yang dapat digunakan ulang, MappingLibrary menyimpan fragmen pemetaan yang dapat digunakan ulang, ArtifactLibrary menyimpan bundel artefak yang dapat digunakan ulang, WorkloadLibrary menyimpan konten workload yang dapat digunakan ulang. Masing-masing bersifat opsional secara independen; katalog menyertakan yang diperlukan saja dan tidak menyertakan yang lainnya.

Apa yang bukan WorkloadLibrary

Beberapa kesalahpahaman umum yang perlu diluruskan sejak awal:

  • Bukan pengganti workload: inline. Sebagian besar Recipes membawa konten workload yang cukup spesifik sehingga layak ditulis inline, tempat penulis membacanya bersama bagian lain dari Recipe. Sebuah WorkloadLibrary membantu ketika bentuk workload yang SAMA muncul di banyak Recipes; untuk konten yang hanya dipakai sekali, penulisan inline adalah pilihan yang tepat.

  • Bukan tempat untuk fragmen parsial. Sebuah entri dirender menjadi dokumen Workload yang lengkap. Dokumen values milik sebuah Recipe termasuk dalam MappingLibrary, sekumpulan file pendukung dalam ArtifactLibrary, dan definisi skema dalam SchemaLibrary. Jenis-jenis library dibagi berdasarkan tipe konten, bukan berdasarkan pola penggunaan ulang.

  • Bukan entitas yang dapat di-deploy secara mandiri. Sebuah entri library adalah konten Workload, dan konten Workload tidak pernah dapat dialamatkan secara tersendiri — konten tersebut ada sebagai input yang dikonsumsi oleh sebuah Recipe atau FeatureRecipe. Memublikasikan sebuah WorkloadLibrary membuat entri-entrinya dapat diimpor; hal itu tidak membuatnya dapat di-deploy.

  • Bukan penggunaan ulang parametris di luar mekanisme Go template. Penulis yang memerlukan variasi parametris menggunakan mekanisme {{ define }} + {{ template }} dari Go template di dalam entri library, atau konteks pilar yang disediakan oleh Recipe yang mengonsumsinya. Entitas library itu sendiri tidak menyertakan mesin bantu parametris apa pun.