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

ArtifactLibrary

ArtifactLibrary adalah entitas katalog yang menyimpan bundel artefak yang dapat digunakan ulang — kumpulan bernama berisi berkas keluaran tambahan yang saling terkait. Recipes dan FeatureRecipes yang menghasilkan sumber daya pendukung yang sama — sebuah CRD beserta RBAC dan ConfigMap-nya, sebuah NetworkPolicy yang dipasangkan dengan HPA — mendeklarasikan kumpulan tersebut satu kali dalam sebuah pustaka dan merujuknya saat konsumsi melalui entri artifacts: yang nilainya berupa direktif $import:. Entitas pustaka ini berada di Tier 3: bersifat opsional bagi katalog yang memerlukan penggunaan ulang artefak lintas Recipe. Katalog yang setiap Recipes-nya membawa berkas tambahannya sendiri dirilis tanpa ArtifactLibrary apa pun.

Peran ArtifactLibrary

Arsitek platform menyusun ArtifactLibraries untuk memusatkan manifest tambahan yang berulang di seluruh Recipes dan FeatureRecipes dalam katalog. Sebuah library bukanlah instruksi build yang dapat di-deploy; library adalah namespace definisi. Penulis Recipe dan FeatureRecipe mereferensikan sebuah bundel melalui direktif $import:, yang ditulis sekali dan digunakan di mana pun impor tersebut di-resolve.

Yang membedakan jenis library ini dari tiga jenis lainnya adalah granularitas sebuah entri. Entri SchemaLibrary adalah satu skema, entri MappingLibrary adalah satu fragmen templat, dan entri WorkloadLibrary adalah satu dokumen Workload — masing-masing satu badan yang digunakan di satu lokasi. Entri ArtifactLibrary adalah sekumpulan file, karena sumber daya yang dikelompokkannya hanya berguna jika bersama-sama: mengimpor CRD tanpa RBAC-nya menghasilkan kumpulan manifest yang tidak berfungsi. Itulah sebabnya bundel menjadi unit penggunaan ulang dan satu lokasi penggunaan diperluas menjadi beberapa keluaran.

Amplop entitas

Entitas ArtifactLibrary membawa amplop katalog standar. apiVersion: aggrega.ai/v1beta1 dan kind: ArtifactLibrary 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.artifacts, sebuah map wajib yang harus mendeklarasikan setidaknya satu bundel.

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: ArtifactLibrary
metadata:
name: PlatformArtifacts
version: 1.0.0
spec:
artifacts:
OperatorSupport:
crd.yaml: |
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: widgets.platform.example.com
spec:
group: platform.example.com
scope: Namespaced
rbac.yaml: |
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: "{{ .context.instance_id }}-operator"
rules:
- apiGroups: ["platform.example.com"]
resources: ["widgets"]
verbs: ["get", "list", "watch"]

Menulis bundel artefak

spec.artifacts memiliki kedalaman dua tingkat, dan setiap tingkat memiliki tugas tersendiri. Kunci luar adalah nama bundel — pengidentifikasi yang dirujuk oleh konsumen. Kunci dalam adalah nama file, dan setiap nilai dalam adalah isi templat Go yang dikeluarkan ke file tersebut. Sebuah bundel harus mendeklarasikan setidaknya satu file.

spec:
artifacts:
NetworkBaseline:
deny-all.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-deny-all"
spec:
podSelector: {}
policyTypes: ["Ingress"]
allow-dns.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-allow-dns"

Isi file adalah fragmen templat Go yang ditulis sebagai string YAML. Karena sebuah manifest terdiri atas beberapa baris, isi file menggunakan skalar gaya literal YAML (|) agar baris baru dan indentasi tetap utuh saat bolak-balik. Nilai entri bundel harus berupa pemetaan dari nama file ke isi berupa string; menulis string polos di tempat bundel seharusnya berada, atau sebuah urutan, akan ditolak — tingkat yang diimpor oleh konsumen adalah bundel, bukan satu file.

Isi tersebut tidak tembus pandang bagi amplop entitas. Kompiler menyimpan setiap string apa adanya saat ArtifactLibrary dimuat dan tidak mengurai templat di sana; pengurai templat berjalan pada saat konsumsi, ketika sebuah Recipe atau FeatureRecipe mengimpor bundel tersebut. Menyimpan isi apa adanya menjaga ketepatan penulisan untuk pengeluaran ulang, dan ini berarti kesalahan templat muncul di tempat bundel dikonsumsi dan konteks pilarnya diketahui, bukan di pustaka.

Urutan file dalam sebuah bundel adalah urutan yang ditulis oleh penulis, yang dipertahankan selama pemuatan dan konsumsi, sehingga himpunan yang dikeluarkan tetap stabil di seluruh build.

Seluruh kosakata komposisi templat Go tersedia di dalam isi file: {{ define "name" }}...{{ end }} mendeklarasikan blok yang dapat digunakan ulang, {{ template "name" . }} memanggilnya, dan pipeline serta fungsi mengikuti paket Go standar text/template. Konteks pilar yang dapat dibaca oleh isi file — .values, .infra, .locals, .context, .features, serta .workload dan .source jika Recipe yang mengonsumsinya mendeklarasikannya — adalah konteks yang dibaca oleh entri artifacts: milik Recipe yang mengonsumsi itu sendiri, yang didokumentasikan di halaman Recipe pada bidang artifacts:. Isi yang membaca .workload padahal Recipe yang mengonsumsinya tidak mendeklarasikan workload:, atau .source padahal tidak mendeklarasikan source:, akan berhenti dengan diagnostik yang menyebutkan referensi yang tidak dapat dipenuhinya — setiap pilar diperiksa secara terpisah, sehingga mendeklarasikan salah satunya tidak mengizinkan pembacaan yang lain.

Mode penulisan tunggal

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

Alasannya adalah keseragaman permukaan konsumsi. Recipes dan FeatureRecipes sepenuhnya berbasis templat Go, dan kontennya sendiri dievaluasi melalui mesin templat Go yang sama yang meresolusi bundel yang diimpor. Permukaan penulisan paralel akan memaksa penulis berpindah model evaluasi di dalam rendering satu Recipe — satu model untuk konten Recipe itu sendiri, model lain untuk setiap bundel 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 bundel pustaka dengan variasi substantifnya sendiri — alih-alih beralih ke bahasa penulisan kedua di dalam pustaka.

Konvensi penamaan

Nama pustaka dan nama bundel mengikuti PascalCase. JSON Schema amplop entitas menegakkan konvensi ini pada dua posisi melalui batasan pola:

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

ArtifactLibrary dengan nama bundel yang bukan PascalCase gagal dalam validasi amplop saat workspace dimuat. Penegakan ini memikul beban penting: nama bundel muncul dalam fragmen referensi #/artifacts/<name>, sehingga nama yang bukan PascalCase akan merambat ke setiap konsumen yang mengimpor bundel tersebut.

Keseragaman penamaan menjaga fragmen #/artifacts/<name> tetap mudah dibaca: #/artifacts/OperatorSupport dapat dipahami sekilas.

Nama file di dalam bundel bebas bentuk, selama masing-masing menamai sebuah file. Nama file tersebut tidak harus PascalCase dan tidak dibatasi oleh pola skema apa pun, karena nama file itu menamai file yang pada akhirnya dibawa oleh keluaran build — crd.yaml, deny-all.yaml, values-override.json semuanya valid. Yang diwajibkan dari sebuah nama file adalah bahwa ia merupakan nama file relatif biasa, yang ditulis apa adanya; build menolak nama yang tidak menamai file miliknya sendiri, sebagaimana dijelaskan di Merujuk entri pustaka. Kedua tingkat ini dibatasi secara berbeda karena melayani pembaca yang berbeda: nama bundel adalah pengenal yang dirujuk oleh entitas lain, sedangkan nama file adalah nama yang dilihat konsumen di dalam direktori tempat bundel diimpor.

Mereferensikan entri pustaka

Penulis Recipe dan FeatureRecipe mereferensikan sebuah bundel di dalam entri artifacts: yang nilainya berupa map $import:, berdasarkan identitas nama polos bundel tersebut:

# Inside a Recipe's spec:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"

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

Bundel memiliki nama-nama filenya, dan kunci yang mengonsumsi memiliki direktori tempat file-file itu ditempatkan. Satu entri artifacts: yang mengimpor sebuah bundel diekspansi menjadi satu output per file dalam bundel itu, masing-masing bersarang di bawah kunci konsumsi sebagai <key>/<filename>. Kunci di lokasi konsumsi — operator-support di atas — menamai keseluruhan konsumsi, bukan satu file tertentu; contoh tersebut menghasilkan operator-support/crd.yaml dan operator-support/rbac.yaml. Jadi nama bundel dipilih agar mudah dibaca pada referensi, nama file dipilih untuk pembaca direktori output, dan keduanya tidak harus saling sesuai. Kunci konsumsi itu sendiri dibatasi pada satu nama file — huruf atau digit di awal, lalu huruf, digit, titik, tanda hubung, dan garis bawah, dengan kunci di luar alfabet tersebut gagal dalam validasi envelope — sehingga kunci itu menamai tepat satu segmen direktori, dan segala sesuatu di bawah segmen itu berasal dari bundel. Itulah yang memungkinkan nama file bundel tetap bebas sementara kuncinya tetap ketat: nama file unik dalam bundelnya, kunci unik dalam dokumennya, dan kunci adalah segmen pertama dari setiap path yang dihasilkan entri, sehingga tidak ada dua entri artifacts: yang menamai satu output yang sama. Bebas berarti bebas di dalam segmen itu: nama file dapat membawa tata letak bersarangnya sendiri — crds/widget.yaml ditempatkan di <key>/crds/widget.yaml — tetapi harus berupa nama file relatif biasa di bawah kunci, ditulis secara polos, dan nama file yang tidak demikian menghentikan build alih-alih menempatkan file di suatu tempat yang tidak pernah dinamai oleh Recipe yang mengonsumsi. Hal ini menolak nama yang naik di atas kunci atau menamai lokasi absolut; . atau ./, serta nama yang kembali runtuh ke kunci seperti x/.., yang menamai direktori milik kunci itu sendiri alih-alih file di dalamnya; dan nama dengan / di akhir atau ganda, atau dengan bagian . atau .. — x/, a//b, ./a, a/../b — yang merupakan ejaan kedua dari file yang dapat dibawa oleh nama lain, sehingga a//b di samping a/b akan menempatkan dua file pada satu path. Diagnostiknya menyebutkan file bundel dan kunci tempat file itu diimpor. Dua output yang memang membawa nama file yang sama menghentikan build saat node di-render, yang terjadi ketika dua jenis input yang berbeda menyumbangkan satu nama file. Lihat Recipe untuk cara artifacts: disusun bersama jenis input lain dari Recipe dan untuk dua mode penulisan non-pustaka, serta vocabulary/cross-document-ref untuk perbedaan $ref: / $import: yang lebih luas.

Komposisi lintas pustaka

Isi file bundel adalah konten terminal. Tidak seperti entri MappingLibrary atau WorkloadLibrary, file bundel tidak dapat berupa pengalihan $import: pada akar bidang: satu slot file tidak memiliki ruang untuk beberapa file yang akan dibawa oleh bundel lain, sehingga kompiler menolak bentuk tersebut alih-alih menyelesaikannya menjadi sesuatu yang tidak ditulis oleh penulis. Isi yang token pertamanya adalah $import: menghentikan build dengan diagnostik yang menyebutkan bundel dan file tersebut.

Komposisi justru terjadi di situs konsumsi, tempat ruang untuknya tersedia. Recipe yang memerlukan dua bundel mendeklarasikan dua entri artifacts:, dan masing-masing diekspansi secara independen:

# Inside a Recipe's spec — compose bundles where the outputs land:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"
network-baseline:
$import: "PlatformArtifacts#/artifacts/NetworkBaseline"

Nama pustaka yang tidak dikenal, dan nama bundel yang tidak ada dalam pustaka yang berhasil diresolusi, dilaporkan sebagai diagnostik yang berbeda, sehingga penulis dapat membedakan dependensi yang hilang dari nama bundel yang salah eja.

Penempatan tier

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

Jenis library ini melengkapi sebuah himpunan di tingkat katalog — SchemaLibrary menyimpan definisi skema yang dapat digunakan ulang, MappingLibrary menyimpan fragmen mapping yang dapat digunakan ulang, WorkloadLibrary menyimpan konten workload yang dapat digunakan ulang, dan ArtifactLibrary menyimpan bundel artefak yang dapat digunakan ulang. Masing-masing bersifat opsional secara independen; katalog menyertakan yang dibutuhkannya dan tidak menyertakan yang lain.

Apa yang bukan ArtifactLibrary

Beberapa kesalahpahaman umum yang perlu diluruskan sejak awal:

  • Bukan pengganti artifacts: inline. Sebagian besar Recipes membawa berkas pendukung yang cukup spesifik sehingga sebaiknya ditulis inline, tempat penulis membacanya bersama bagian lain dari Recipe. ArtifactLibrary membantu ketika kumpulan berkas yang SAMA menyertai banyak Recipes; untuk konten yang hanya dipakai sekali, penulisan inline adalah pilihan yang tepat.

  • Bukan cara untuk mengganti nama berkas di dalam bundel. Nama berkas adalah milik bundel. Konsumen memilih direktori tempat berkas-berkas itu ditempatkan — itulah fungsi kunci konsumsi — tetapi tidak memilih nama salah satu berkas tersebut: konsumen yang memerlukan nama berkas yang berbeda menggunakan bundel yang mendeklarasikan nama itu atau menulis berkas tersebut secara inline.

  • Bukan tempat untuk konten workload, mapping, atau skema. Dokumen Workload ditempatkan di WorkloadLibrary, dokumen values milik Recipe ditempatkan di MappingLibrary, dan definisi skema ditempatkan di SchemaLibrary. Jenis-jenis library dibedakan menurut jenis konten, bukan menurut pola penggunaan ulang.

  • Bukan mekanisme untuk sumber daya lintas sektoral. Sumber daya pendukung yang berlaku untuk banyak komponen terlepas dari Recipe mana yang merealisasikannya — misalnya sidecar cadangan yang dipasang pada setiap datastore — ditempatkan pada pembuatan sumber daya FeatureRecipe, yang dipasang berdasarkan Feature, bukan berdasarkan Recipe. Lihat entities/featurerecipe.md. ArtifactLibrary memisahkan berkas-berkas yang masing-masing dihasilkan oleh beberapa Recipes atas namanya sendiri.

  • Bukan entitas yang dapat di-deploy secara mandiri. Bundel adalah konten artefak, dan konten artefak tidak pernah dapat dirujuk secara tersendiri — konten itu ada sebagai masukan yang dikonsumsi oleh Recipe atau FeatureRecipe. Memublikasikan ArtifactLibrary membuat bundelnya dapat diimpor; hal itu tidak membuat bundel tersebut dapat di-deploy.