Workload
Peran arsitektural jenis Workload — mengapa jenis ini ada, bagaimana ia berkomposisi dengan dua jenis input Recipe lainnya (sourced dan artifacts), serta seluruh permukaan skemanya — dijelaskan di ../../architecture/16-recipe-input-composition.md. Halaman ini membahas permukaan penulisan Workload: bagaimana penulis Recipe menulis konten Workload, apa yang dievaluasi kompiler dan kapan, bagaimana field Workload berinteraksi dengan featuresSchema milik Component, dan pilar mana saja yang dapat dibaca oleh templat di dalam Workload.
Lokasi penulisan
Konten Workload ditulis secara inline atau dari file, di dalam sebuah Recipe atau FeatureRecipe (lihat FeatureRecipe). Sebuah Recipe mendeklarasikan paling banyak satu workload:; sebuah FeatureRecipe juga mendeklarasikan paling banyak satu miliknya sendiri:
# Inline (block scalar)spec: workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload # ...atau
# File-loaded via $import: (path relative to the Recipe directory)spec: workload: $import: ./workload/workload.yamlKedua bentuk menghasilkan objek Workload pascaparsing yang sama; pilihannya hanyalah soal ergonomi penulisan. Bentuk ketiga mengimpor Workload yang dipakai bersama oleh beberapa Recipes dari entri WorkloadLibrary, berdasarkan identitas nama polosnya: $import: <Library>#/workloads/<entry>. Sesuai kosakata impor file yang terpadu, $import: menerima satu sumber — lihat ../vocabulary/cross-document-ref.md untuk perbedaan $ref: / $import: yang lebih luas.
YAML Workload tidak ditulis sebagai entitas katalog yang berdiri sendiri. Tidak ada direktori catalog/workload/; tata bahasa Workload hanya ada sebagai konten yang dikonsumsi oleh sebuah Recipe atau FeatureRecipe — ditulis secara inline, dalam file di sebelahnya, atau dalam entri WorkloadLibrary. Deklarasi apiVersion dan kind di dalam YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) mengidentifikasi konten tertanam tersebut untuk validasi skema; deklarasi tersebut tidak membuat Workload dapat dialamatkan secara independen.
Evaluasi templat
Konten Workload diproses sebagai templat Go terhadap konteks pilar lengkap sebelum di-parse. Ketika penulis Recipe menulis templat seperti berikut…
replicas: {{ optional .infra `replicas` 1 }}…compiler mengevaluasi templat tersebut selama sub-pass Workload pada proses rendering, me-resolve .infra.replicas terhadap payload infra milik node, lalu mem-parse YAML yang dihasilkan sebagai dokumen Workload. locals milik Recipe di-resolve sebelum Workload dievaluasi, sehingga templat Workload membacanya, dalam keadaan sudah di-resolve, di bawah .locals.
Akses pilar di dalam templat Workload:
.values— payload kognitif yang ditulis developer dan dideklarasikan dalam Aggregate..infra— ukuran fisik yang ditulis Ops dan dideklarasikan dalam Release..parameters— sudah diinterpolasi saat resolusi; terlihat melalui.values/.infradi mana pun Developer atau Ops merujuk.parameters.<name>dalam penulisan mereka..locals— state privat Recipe yang di-resolve dalam preamble locals dan dipublikasikan saat resolusi sumber; tersedia di setiap titik evaluasi templat Workload..context.instance_id— ID instans node yang telah diratakan; prefiks nama resource yang dihasilkan oleh provider yang menamai resource hasil sintesis berdasarkan identitas..context.rendered_name— nama yang diberikan untuk resource hasil sintesis oleh provider yang menurunkan namanya sendiri, seperti nama release helm; hanya ada jika provider melaporkannya. Lihat ../templates/rendered-resource-names.md..context.inject— pipa injeksi pasca-intersepsi, yang sudah ditulis ulang olehinjectMappingFeatureRecipe mana pun selama pemetaan injeksi..context.uses— edge topologi yang diperkaya dan keluar dari node ini, masing-masing membawaprovidestarget yang telah di-resolve,labels, dan anotasi bertingkat, serta, di bawah.context.uses.<alias>.features.<slot>, attachment yang dibawa koneksi tersebut..features— attachment milik node itu sendiri, masing-masing membawatype,values,infra, danprovidesyang telah di-resolve. Attachment yang dinamai sesuai slot yang dideklarasikan Component dalamfeaturesSchemamengisi slot tersebut (lihat di bawah). Attachment yang dibawa oleh sebuah koneksi tidak termasuk di dalamnya; attachment tersebut dibaca di bawah koneksinya, dan Workload mengirimkannya dengan menyebut nama koneksi tersebut (lihat Mengirimkan kredensial yang dibawa koneksi).
Lihat ../vocabulary/data-pillars.md untuk kontrak akses pilar lengkap dan ../templates/expansion-matrix.md untuk posisi evaluasi Workload dalam urutan evaluasi templat.
Esensi semantik field
Skema Workload lengkap terdapat di ../../architecture/16-recipe-input-composition.md pada bagian “The Workload Kind.” Konvensi penulisan di bawah ini mencakup keputusan tingkat field yang dibuat oleh penulis Recipe.
form
form mendeklarasikan bentuk controller abstrak dari workload — jenis siklus hidup runtime yang dimilikinya, terlepas dari platform target apa pun. Nilainya berupa satu string, salah satu dari stateless, stateful, daemon, scheduled, task, reference, dan bernilai default stateless jika dihilangkan:
stateless— replika yang dapat saling dipertukarkan dan diskalakan secara horizontal tanpa identitas per replika (layanan berjalan lama yang umum).stateful— replika dengan identitas per replika yang stabil dan penyimpanan per replika. VolumepersistentTemplatemerupakan pendamping bentuk ini.daemon— satu instans per host yang memenuhi syarat.scheduled— eksekusi berulang yang dipicu oleh waktu.task— satu eksekusi hingga selesai.reference— tanpa kontainer sendiri: komponen mewakili endpoint eksternal, yang diberikan sebagaiendpoint(host atau URL, diteruskan apa adanya) danportopsional. Provider helm mengeluarkannya sebagai Service bertipeExternalName; provider compose tidak mengeluarkan apa pun untuknya.
Form itu sendiri tidak membawa jenis sumber daya native platform. Setiap provider target yang menyintesis Workload memetakan form ke bentuk native-nya sendiri:
form | Kubernetes (helm) | Compose |
|---|---|---|
stateless | Deployment | service (tanpa persistent volume) |
stateful | StatefulSet | service + named volume |
daemon | DaemonSet | menghentikan build |
scheduled | CronJob | menghentikan build |
task | Job | menghentikan build |
Provider terraform dan cloudformation merender Recipes bersumber dan Recipes yang hanya berisi artefak, dan tidak menyintesis Workload: Recipe yang mendeklarasikan workload: dan terikat ke salah satunya akan menghentikan build, dengan menyebutkan jenis input yang didukung provider tersebut.
Jika provider target tidak memiliki pemetaan yang bersih untuk suatu form, build dihentikan secara eksplisit alih-alih menurunkan workload ke bentuk yang salah merepresentasikan maksudnya — memilih form yang tidak dapat diekspresikan oleh batas target merupakan error saat build, bukan penurunan diam-diam. Provider compose berhenti pada daemon, scheduled, dan task. Provider helm menghasilkan CronJob untuk scheduled (lihat schedule di bawah) dan hanya berhenti jika jadwalnya tidak ada atau tidak valid.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: statefulcontainers: db: { image: "postgres:16", ports: { db: 5432 } }volumes: data: persistentTemplate: size: "20Gi"services: headless: type: Headless ports: db: 5432schedule
schedule adalah jadwal cron untuk workload form: scheduled — field pendamping yang memberi form berulang tersebut pengulangannya. Nilainya berupa satu string dalam satu format kanonis:
- ekspresi crontab standar 5 field — menit, jam, hari dalam bulan, bulan, hari dalam minggu (misalnya
0 0 * * *untuk setiap hari pada tengah malam,*/15 * * * *untuk setiap lima belas menit), atau - salah satu makro
@hourly,@daily,@weekly,@monthly,@yearly.
schedule wajib jika form: scheduled dan hanya bermakna dalam kondisi itu. Workload form: scheduled tanpa jadwal, jadwal yang bukan ekspresi 5 field maupun makro yang dikenali (ekspresi 6 field dengan awalan detik, token @ yang tidak dikenali, atau field dengan karakter ilegal), atau schedule yang ditetapkan pada form lain mana pun menyebabkan build berhenti dengan pesan yang menyebutkan perbaikannya. Provider helm meneruskan nilai tersebut apa adanya ke spec.schedule pada CronJob yang dihasilkan.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # daily at 02:00containers: report: image: "reporter:1.0" command: ["/report"]suspend
suspend menahan jadwal berulang dari workload form: scheduled. Nilainya boolean dan default-nya false. Dengan suspend: true, resource terjadwal tetap dirender dengan schedule-nya di tempat, tetapi tidak ada eksekusi yang dimulai dari jadwal tersebut sampai jadwal dilanjutkan, dan eksekusi tetap dapat dimulai secara manual dari resource tersebut. Itulah bentuk untuk tugas yang hanya boleh berjalan ketika seseorang memintanya.
Provider helm mengeluarkan field ini sebagai spec.suspend: true milik CronJob. Di Kubernetes, kubectl create job <name> --from=cronjob/<cronjob> memulai eksekusi dari CronJob yang ditahan, dan jadwal dilanjutkan begitu spec.suspend kembali bernilai false. suspend: false dirender persis seperti suspend yang dihilangkan, sehingga field ini tidak mengubah output apa pun sampai diatur. Provider compose tidak memiliki bentuk terjadwal dan menghentikan build pada setiap workload form: scheduled, baik ditahan maupun tidak.
suspend: true pada form lain mana pun merupakan penghentian saat build yang menyebutkan perbaikannya: tidak ada form lain yang membawa jadwal untuk ditahannya.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # documents when it would run; nothing starts it while suspendedsuspend: truecontainers: report: image: "reporter:1.0" command: ["/report"]replicas
Satu bilangan bulat untuk jumlah replika workload. Bernilai default 1 jika dihilangkan. Gunakan ekspresi template untuk menentukan replika dari ukuran yang dideklarasikan Ops:
replicas: {{ optional .infra `replicas` 1 }}containers vs initContainers
containers adalah map berurutan dengan kunci nama container. Container 0 (kunci map pertama) berpengaruh pada urutan pod-spec dalam output Kubernetes dan pada semantik container default. initContainers adalah daftar berurutan entri init-container, masing-masing membawa name, image, serta bentuk penulisan variable/secret/volume-mount yang sama dengan container utama.
name bersifat opsional pada entri initContainers. Entri yang menghilangkannya diberi nama init-<index>, dengan index berupa posisi entri dalam daftar, dihitung dari 0. Karena nama tersebut mengidentifikasi container dalam output yang dirender dan dalam diagnostik apa pun yang menyebutnya, entri yang layak dirujuk layak diberi nama secara eksplisit.
Pelestarian urutan penulisan adalah kontrak penopang dalam model Workload — compiler menghasilkan containers, volumes, services, ports container, variables container, dan attachments container masing-masing dalam urutan yang dideklarasikan penulis Recipe, pada setiap build. Penulis Recipe dapat mengandalkan bentuk berurutan ini: jika apa yang terjadi saat runtime bergantung pada urutan (startup sidecar, perangkaian $(VAR) dalam variabel lingkungan, volumeMounts yang merujuk volume yang dideklarasikan sebelumnya), urutan penulisan ADALAH urutan runtime dalam setiap koleksi tersebut. Lingkungan sebuah container menggabungkan dua di antaranya, dan di antara keduanya provider yang menyintesis menulis entri pembacaan attachment (attachments yang dikirim as: env) terlebih dahulu dan variables biasa sesudahnya, masing-masing jenis dalam urutan penulisan — sehingga pada target Kubernetes sebuah variabel dapat merujuk, sebagai $(NAME), variabel pembacaan attachment mana pun dari container-nya dan variabel mana pun yang dideklarasikan sebelumnya (lihat urutan lingkungan provider helm). Container yang memberikan satu nama baik sebagai entri variables maupun sebagai entri attachments yang dikirim as: env menghentikan build, karena urutan itu saja yang akan menentukan nilai mana dari keduanya yang dilihat proses (lihat A container gives one environment variable two values (Sebuah container memberikan dua nilai untuk satu variabel lingkungan)).
Penulisan field container mengikuti konvensi berikut:
imagebiasanya berupa ekspresi template yang merujuk.values.image(image yang dipilih Developer) dengan override.infra.*opsional untuk awalan registry khusus lingkungan.variablesadalah map string → string biasa untuk variabel lingkungan. Map ini memadukan dua sumber data berbeda melalui ekspresi template Go: literal pilar developer (entri yang ekspresi template-nya membaca.values/.infra/.locals— payload yang berasal dari pilar Component) dan data pipe lintas component (entri yang ekspresi template-nya membaca.context.inject.env.<KEY>— payload yang berasal dariprovides:component lain dan dirutekan melalui pipe topologi). Kedua sumber mengalir ke mapvariablesyang sama; penulis memilih salah satu per entri berdasarkan apakah nilainya lokal bagi component atau diturunkan lintas component. Pola umum:LOG_LEVEL: "{{ .values.log_level }}"adalah pilar developer (lokal bagi component);DB_HOST: "{{ .context.inject.env.DB_HOST }}"adalah pipe lintas component (nilainya berasal dariprovides.hostcomponent target yang dirutekan melalui deklarasiuses[].inject.env.DB_HOSTmilik pemanggil). Kedua bentuk dikompilasi menjadi satu daftarenv:Kubernetes pada Deployment yang dirender; semantik dua sumber hanya berlaku saat penulisan.attachmentsmerujuk slot yang dideklarasikan dalamfeaturesSchemamilik Component, atau, dengan menyebut sebuah koneksi, slot yang dideklarasikan socket koneksi tersebut (lihat bagian integrasi di bawah).portsadalah map port bernama (web: 8080,admin: 9901); nama port sesuai dengan nama port lingkup container dan dirujuk olehservices.<service>.ports.<portname>. Port yang membawa transport selain default target ditulis dalam bentuk yang diperluas — lihat Protokol transport port di bawah.volumeMountsmerujuk berdasarkan nama volume yang dideklarasikan di bagianvolumes:milik Workload.resourcesmendeklarasikanrequestsdanlimitscontainer — kuantitascpudanmemory, serta secara opsional kunci extended-resource untuk GPU dan perangkat lain (lihat Workload GPU dan perangkat di bawah).healthmenggunakan bentuk intent (http: /path,tcp: <port>,exec: [cmd, ...]) — lihat bagian Health Probes di bawah.
volumes
Setiap volume memiliki tepat satu tipe: ephemeral, configmap, secret, persistent, atau persistentTemplate. Tipe-tipe ini saling eksklusif di dalam satu deklarasi volume; setiap tipe membawa field wajibnya sendiri:
volumes: app-config: configmap: source: "{{ .locals.app_cm }}" data: persistent: size: "10Gi" class: "gp3" cache: ephemeral: sizeLimit: "1Gi"persistentTemplate menghasilkan PVC per replika untuk translasi berbentuk StatefulSet; dalam translasi compose, tipe ini turun menjadi satu named volume bersama, dengan peringatan yang dilaporkan bersama build. File yang dihasilkan itu sendiri tidak memuat catatan tentang penurunan tersebut — isinya sama byte demi byte dengan isinya tanpa peringatan.
Translasi per provider. Setiap provider menerjemahkan kelima varian volume ke bentuk native-nya:
| Varian | Helm / helm-chart (K8s) | Compose | Catatan kehilangan |
|---|---|---|---|
ephemeral | emptyDir: { sizeLimit } | entri tmpfs: tingkat service yang menyebut path mount (di memori) | tmpfs Compose didukung RAM; emptyDir helm secara default didukung disk pada node — perbedaan semantik pada media penyimpanan yang mendasarinya. sizeLimit tidak mencapai bagian mana pun dari output compose: entri yang dihasilkan hanyalah path mount. sizeLimit yang ditulis memunculkan peringatan unsupported-field yang menyebutnya, dilaporkan bersama build alih-alih ditulis ke dalam file yang dihasilkan. |
configmap | Referensi volume ConfigMap (memakai sumber daya ConfigMap yang dihasilkan oleh artifacts: milik Recipe atau oleh sebuah Feature) | Referensi configs: tingkat service yang menyebut configmap, di-mount pada path volume mount; entri configs: tingkat atas yang sesuai berasal dari artifacts: milik Recipe | Kedua target mereferensikan configmap berdasarkan nama dan tidak ada yang membaca isinya, sehingga bentuk penulisannya simetris. Yang hilang pada compose adalah semantik update-on-rollout ConfigMap K8s: config compose tetap pada isi yang dihasilkan build. Referensi yang tidak diselesaikan oleh entri tingkat atas mana pun menghentikan build alih-alih menghasilkan mount yang akan menggantung saat runtime. |
secret | Referensi volume Secret (memakai Secret yang disebut oleh attachment kredensial — Secret yang dihasilkan FeatureRecipe-nya, atau yang sudah ada) | env_file: untuk secret berbentuk env, atau file secret yang di-bind-mount untuk secret berbentuk path | Compose tidak memiliki semantik Secret Kubernetes kelas satu. Secret berbentuk path dengan sengaja tidak mengambil rute configs: milik varian configmap: entri config inline akan menulis nilai secret ke dalam file compose yang dihasilkan sebagai plaintext, dan compiler tidak pernah menyelesaikan secret menjadi plaintext. Sumber bind adalah path yang dibuat dapat dijangkau oleh operator pada host compose, di luar siklus hidup CRD vault-fetch mana pun. |
persistent | Sumber daya PVC + volume.persistentVolumeClaim | Named volume | Named volume Compose adalah abstraksi datar di sisi host; PVC helm mendukung deklarasi storage class, access mode, dan kapasitas yang diabaikan compose. |
persistentTemplate | StatefulSet.volumeClaimTemplates (PVC per replika; pendamping form: stateful) | Named volume (diturunkan — satu volume bersama untuk semua replika, dengan peringatan yang dilaporkan) | Compose tidak dapat menyatakan template per replika. Ketika persistentTemplate diterjemahkan ke compose, satu named volume dihasilkan dan berkurangnya fidelitas dilaporkan sebagai peringatan bersama build alih-alih ditulis ke dalam file yang dihasilkan. Workloads yang bergantung pada isolasi volume per replika sebaiknya tidak menargetkan boundary yang hanya compose. |
Bentuk controller dipilih oleh form workload, bukan oleh volume-nya. StatefulSet dihasilkan ketika form: stateful; volume persistentTemplate adalah pendamping form tersebut — volume ini mendeklarasikan penyimpanan per replika pada workload yang sudah memiliki identitas per replika yang disediakan StatefulSet. Mendeklarasikan volume persistentTemplate pada form lain (atau pada default stateless) adalah error saat build yang menyebut perbaikannya: declare form: stateful. Kebalikannya diizinkan — workload form: stateful tidak harus mendeklarasikan volume persistentTemplate. Penulis yang menginginkan semantik StatefulSet menetapkan form: stateful secara langsung.
Workload form: stateful pada provider helm memerlukan Service pengatur headless: deklarasikan tepat satu service dengan type: Headless di Workload yang sama. Provider menghubungkan serviceName milik StatefulSet ke Service headless tersebut (Service itu menyediakan identitas jaringan per pod yang stabil yang dibutuhkan StatefulSet). Build berhenti jika tidak ada service headless yang dideklarasikan — StatefulSet tidak memiliki Service pengatur untuk disebut — atau jika lebih dari satu dideklarasikan, sehingga Service pengatur menjadi ambigu. Workload StatefulSet tetap dapat mendeklarasikan service non-headless tambahan (misalnya service ClusterIP untuk akses klien) di samping satu service pengatur headless tersebut.
Kuantitas sumber daya
Nilai-nilai Workload berikut adalah kuantitas — jumlah yang ditulis dalam notasi yang digunakan Kubernetes untuk sumber daya: nilai resources.requests dan resources.limits sebuah container (atau init container) untuk cpu, untuk memory, dan untuk setiap kunci extended-resource, serta ephemeral.sizeLimit, persistent.size, dan persistentTemplate.size sebuah volume. Skema Workload mengetik masing-masing sebagai string dan tidak membatasi bentuknya. Provider yang menyintesis Workload untuk sebuah target memeriksa setiap kuantitas yang dihasilkannya, dan memeriksa Workload sebagaimana dievaluasi oleh template Recipe, sehingga nilai yang datang melalui infra, parameter Release, atau input template lain dinilai berdasarkan string hasil render-nya.
Sebuah kuantitas adalah, tanpa apa pun sebelum atau sesudahnya:
- tanda opsional,
+atau-; - angka dengan setidaknya satu digit —
2,0.5,.5atau1.; - paling banyak satu dari eksponen —
eatauE, tanda opsional, lalu digit, seperti pada1e3atau5E-2— atau sufiks satuan: sufiks desimaln,u,m,k,M,G,T,PatauE(10⁻⁹ hingga 10¹⁸, dengan kelipatan seribu), atau sufiks binerKi,Mi,Gi,Ti,PiatauEi(1024 hingga 1024⁶).
500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n dan 4u adalah kuantitas; lots, 1.5 cores, 1 gigabyte, 10 GB dan 1e1.5 bukan — eksponen adalah bilangan bulat. E tunggal setelah angka adalah sufiks desimal untuk 10¹⁸ (12E); jika diikuti digit, ia membuka eksponen (1E3).
Ini adalah bentuk yang diterima parser kuantitas milik Kubernetes sendiri, dengan satu perbedaan yang disengaja: string yang angkanya tidak memiliki digit — m, Ki, +, ., e5 — ditolak, sedangkan Kubernetes membacanya sebagai nol. String seperti itulah yang ditinggalkan template ketika nilai yang diinterpolasinya kosong: "{{ .infra.cpu }}m" dengan cpu kosong menghasilkan m. Menolaknya mengubah input kosong menjadi penghentian yang menyebut field-nya, alih-alih menjadi request berukuran nol yang tidak dilaporkan apa pun.
Apa yang dilakukan setiap target terhadap kuantitas:
- helm menghasilkan setiap kuantitas apa adanya, setelah memeriksa masing-masing terhadap bentuk di atas. Nilai di luar bentuk itu menghentikan build dengan error yang menyebut node, path field di Workload —
containers.main.resources.requests.cpu,initContainers[0].resources.limits.memory,volumes.data.persistent.size— dan nilainya. Lihat Helm Provider → mode Workload (disintesis). - compose mengonversi
cpudanmemoryke satuannya sendiri dari nilai yang telah di-parse:cpusmenjadi jumlah core desimal (500m→0.5) danmemorymenjadi jumlah byte yang persis (1.5Gi→1610612736). Nilai yang bukan kuantitas menghentikan build, demikian pula kuantitas yang tidak dapat direpresentasikan compose secara persis — jumlah negatif, jumlah memori yang bukan bilangan bulat byte (1500m), atau jumlah cpu yang lebih halus dari sembilan angka desimal sebuah core — dan error-nya menyebutkan mana dari keduanya yang ditemui. Jumlahnvidia.com/gpudibaca dengan cara yang sama dan menjadi jumlah perangkat, sehingga jumlah yang bukan bilangan bulat perangkat juga menghentikan build. compose tidak menghasilkan extended resource lain maupun ukuran volume, sehingga tidak memeriksa keduanya: kunci extended-resource lainnya danephemeral.sizeLimitdibuang dengan peringatan, dan ukuran persistent tidak membentuk apa pun dalam output-nya. Lihat Compose Provider → Sumber daya container.
Pemeriksaan ini hanya menilai bentuk. Apakah sebuah cluster dapat menjadwalkan jumlah tersebut, atau apakah jumlah tersebut sesuai dengan perangkatnya, berada di luar cakupannya.
services
Map berurutan berisi eksposur layanan. Setiap layanan mendeklarasikan tipenya (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — seberapa jauh port-portnya menjangkau — dan map port bernama. Nama port harus cocok dengan nama port kontainer yang dideklarasikan di bagian lain Workload:
services: http: type: ClusterIP ports: web: 8080 # must exist in containers.<name>.portsBeberapa layanan pada satu Workload lazim digunakan untuk mengekspos lalu lintas internal dan eksternal secara terpisah (ClusterIP internal untuk konsumen di dalam kluster, LoadBalancer untuk lalu lintas eksternal, ClusterIP untuk scraping Prometheus).
Seberapa jauh port suatu layanan menjangkau. type menyatakannya, dan setiap target merendernya dengan istilahnya sendiri:
type | Jangkauan | helm | compose |
|---|---|---|---|
ClusterIP | rekan-rekan workload, pada jaringan target itu sendiri | sebuah Service bertipe ClusterIP | tidak memublikasikan apa pun; rekan menjangkau port pada jaringan compose |
Headless | sama, tanpa alamat kluster | sebuah Service bertipe ClusterIP dengan clusterIP: None | tidak memublikasikan apa pun |
NodePort | di luar jaringan target itu sendiri | sebuah Service bertipe NodePort | setiap port dipublikasikan pada setiap antarmuka host, sebagai <service port>:<container port> |
LoadBalancer | di luar jaringan target itu sendiri | sebuah Service bertipe LoadBalancer | sama seperti NodePort |
Loopback | hanya alamat loopback host itu sendiri | menghentikan build, dengan menyebut layanannya | setiap port dipublikasikan pada alamat loopback IPv4, sebagai 127.0.0.1:<service port>:<container port> |
Nomor port layanan dan port kontainer yang disebutnya adalah dua angka, seperti port dan targetPort pada Service Kubernetes: helm menulis nomor entri sebagai port Service dan menargetkan port kontainer berdasarkan namanya, sedangkan compose memublikasikan nomor entri pada host ke nomor port kontainer. Jika kedua angka sama, compose menulis angka tersebut di kedua sisi.
Loopback ditujukan untuk port yang dijangkau oleh sesuatu di mesin yang sama — browser atau agen yang berjalan di host — dan tidak boleh dijangkau oleh yang lain. Pada compose, binding hanya pada alamat loopback IPv4: alamat loopback IPv6 ::1 tidak di-bind, jadi alamatkan port sebagai 127.0.0.1 alih-alih melalui nama yang mungkin teresolusi ke ::1. Transport yang dideklarasikan dituliskan pada entri seperti pada port terpublikasi mana pun, seperti dalam 127.0.0.1:5514:5514/udp.
Jika dua entri menyebut port yang sama, jangkauan yang lebih luas yang berlaku: port yang dipublikasikan oleh entri NodePort atau LoadBalancer dipublikasikan pada setiap antarmuka meskipun entri Loopback juga menyebutnya, terlepas dari mana yang dideklarasikan lebih dulu.
Pada helm, entri Loopback menghentikan build alih-alih dirender sebagai sesuatu yang bukan dirinya. Service Kubernetes tidak memiliki tipe yang melakukan binding ke alamat loopback host — alamat node mana yang didengarkan oleh Service NodePort merupakan pengaturan seluruh kluster, bukan satu Service — sehingga Service ClusterIP akan menghilangkan jangkauan yang diminta entri, dan Service NodePort akan memublikasikan port pada setiap alamat node yang diizinkan kluster. Penghentian tersebut menyebut node dan layanannya; lihat A service type the helm provider cannot render (Tipe layanan yang tidak dapat dirender oleh provider helm).
Konvensi nama tersintesis. Ketika provider helm menyintesis layanan-layanan suatu Workload, metadata.name setiap Service diturunkan secara deterministik dari nama yang dibawa controller milik workload itu sendiri dan kunci authoring layanan. Untuk Workload sebuah komponen, nama tersebut adalah nama rilis node: <release name>-<service-key>. Nama rilis adalah identitas komponen yang ditulis dalam alfabet yang diterima nama Kubernetes — nama yang sama yang digunakan chart untuk merender, dapat dibaca dalam templat Recipe sebagai {{ .context.rendered_name }} — sehingga nama ini sama dengan instance_id di mana pun identitas tidak mengandung garis bawah maupun huruf kapital. Workload yang mendeklarasikan services.http pada node api-server menghasilkan Service bernama api-server-http; Workload yang sama pada node billing menghasilkan billing-http, dan pada node my_api menghasilkan my-zuapi-http. Nama file keluaran mencerminkan konvensi yang sama: <release name>-<service-key>-service.yaml. Recipe yang memublikasikan alamat Service semacam itu membangunnya dari {{ .context.rendered_name }}, tidak pernah dari {{ .context.instance_id }}, yang tidak menamai Service apa pun di mana pun keduanya berbeda — lihat ../templates/rendered-resource-names.md.
Workload yang disintesis oleh FeatureRecipe dari lampiran Feature dinamai menurut identitas gabungan lampiran itu sendiri, bukan menurut nama rilis: nilai yang dibawa resource-nya dalam label aggrega.ai/component-id, yang tersusun dari komponen host dan kunci yang ditulis di bawah features:, di belakang cfr-- pembuka. Nama rilis yang diturunkan di sana akan menjadi milik host, dan akan menamai resource lampiran menurut resource milik host sendiri. Jadi FeatureRecipe yang Workload-nya mendeklarasikan services.scrape, untuk lampiran stats pada node front-door, menghasilkan Deployment cfr--front-door--stats dan Service cfr--front-door--stats-scrape. Segmen pertama itu tidak pernah sama dengan instance_id, dan tidak ada kunci dalam konteks templat FeatureRecipe yang membawanya: pada templat sebuah lampiran, {{ .context.rendered_name }} dan {{ .context.instance_id }} sama-sama menamai host (front-door) dan {{ .attachment_name }} hanyalah kuncinya (stats), sehingga {{ .context.rendered_name }}-scrape menamai Service scrape milik host sendiri jika host mendeklarasikannya, dan tidak pernah Service milik lampiran — lihat ../templates/rendered-resource-names.md. File keluaran berada di belakang prefiks yang dibawa setiap file yang dikeluarkan lampiran — nama host dan nama lampiran, masing-masing diikuti -- — sehingga Service tersebut ditulis ke front-door--stats--cfr--front-door--stats-scrape-service.yaml.
Konvensi ini memiliki dua konsekuensi praktis. Pertama, tabrakan lintas node mustahil secara konstruksi — prefiks nama membedakan layanan di setiap node dalam boundary, karena dua identitas yang berbeda selalu menghasilkan dua nama rilis yang berbeda, identitas lampiran membawa host maupun kuncinya, dan tidak ada nama komponen yang boleh diawali cfr-- (build berhenti pada nama seperti itu — lihat Component identity cannot be stamped on what it emits (Identitas Component tidak dapat dicapkan pada apa yang dikeluarkannya)), sehingga dua Workload yang masing-masing mendeklarasikan services.http menghasilkan resource K8s Service yang berbeda dengan nama yang tidak tumpang tindih. Satu-satunya sisa adalah identitas lampiran yang terlalu panjang untuk target: identitas itu diperpendek di sekitar digest dari keseluruhannya, dan dua identitas yang diperpendek secara prinsip dapat bertemu — lihat Label provenans yang dikeluarkan pada output hasil render. Kedua, sebuah Workload tidak dapat mendeklarasikan satu kunci layanan dua kali — map services: yang menyebut sebuah kunci dua kali ditolak saat YAML Workload di-parse, dan build berhenti dengan menyebut kunci itu dan barisnya.
Risiko tabrakan yang masih tersisa ada pada batas panjang nama K8s: nama Service Kubernetes dibatasi 63 karakter, dan bentuk tersintesis <release name>-<service-key> dapat melampaui batas tersebut jika kedua segmen panjang. Compiler Aggrega tidak memberlakukan batas ini; build mengeluarkan Service tersebut, dan Kubernetes menolaknya saat diterapkan. Penulis dengan ID instans bersarang dalam (misalnya, data-layer.regional.eu-west.primary) ditambah kunci layanan yang panjang sebaiknya menjaga panjang gabungan di bawah 63 karakter. Hal yang sama berlaku untuk Workload sebuah lampiran: identitas gabungan yang terlalu panjang untuk target diperpendek, tetapi kunci layanan yang ditambahkan padanya tidak, sehingga Service lampiran yang membawa kunci panjang tetap dapat melampaui 63 karakter dan ter-build tanpa penghentian.
Catatan khusus provider (compose). Provider compose menurunkan depends_on secara otomatis dari uses-edge IR. Entri-entri tersebut dikeluarkan tanpa gating — entri membawa semantik service_started terlepas dari apakah target mendeklarasikan healthcheck — sehingga layanan yang seluruh dependensinya berasal dari edge uses mengeluarkan daftar bentuk pendek (depends_on: [<target>]). Gating entri turunan edge pada kesehatan target tidak diimplementasikan. Bentuk panjang dikeluarkan jika suatu entri memang membawa kondisi, yang merupakan cara penantian pada init container diekspresikan; lihat providers/compose.md.
Protokol transport port
Port kontainer ditulis dalam salah satu dari dua bentuk yang setara. Angka saja adalah bentuk singkat dan tidak mendeklarasikan transport, sehingga target menerapkan default-nya sendiri — TCP pada setiap target yang memilikinya:
containers: main: image: "{{ .values.image }}" ports: web: 8080Bentuk diperluas memuat angka dan transport sekaligus, dan bentuk inilah yang diperlukan port ketika port tersebut membawa apa pun selain default itu:
containers: main: image: "{{ .values.image }}" ports: web: 8080 # short form — no transport declared dns: port: 53 protocol: UDP # TCP | UDP | SCTP sigtran: port: 2905 protocol: SCTPKedua bentuk dapat dicampur secara bebas di dalam satu map ports, dan port yang tidak memiliki transport untuk dideklarasikan tetap dalam bentuk singkat.
Transport dideklarasikan sekali, pada port kontainer. Entri services.<service>.ports menyebut sebuah port kontainer dan membawa transport port tersebut, sehingga eksposur layanan tidak dapat bertentangan dengan port yang dibuka kontainer. Tidak ada key protocol pada port layanan, dan menuliskannya akan ditolak.
Mengapa field ini ada. Target deployment memperlakukan transport yang tidak ditentukan sebagai transport streaming. Komponen yang memerlukan port datagram — media realtime, telefoni, resolusi nama, jaringan privat, server game — jika tidak demikian hanya dapat mendeklarasikan angkanya, dan stack akan ter-deploy dengan semua gerbang lolos sementara tidak ada klien yang terhubung, karena trafiknya datagram sedangkan port yang dibuka bukan. Mendeklarasikan transport-lah yang membuat hal itu dapat diekspresikan.
Compiler tidak menafsirkan nilainya. Compiler tidak membaca transport dari nama port dan tidak memeriksa transport yang dideklarasikan terhadap apa yang sebenarnya digunakan proses di balik port: nilai tersebut adalah data yang Anda deklarasikan dan yang dikeluarkan oleh engine target. Port bernama dns tanpa key protocol adalah port TCP, dan port bernama web yang mendeklarasikan protocol: UDP adalah port UDP.
Perilaku per target.
| Target | Port tanpa transport yang dideklarasikan | Transport yang dideklarasikan |
|---|---|---|
| helm | containerPort dan port Service tidak membawa key protocol | dikeluarkan apa adanya sebagai protocol: pada port kontainer dan pada setiap port Service yang menyebutnya |
| compose | dipublikasikan sebagai <host>:<container>, tanpa perubahan | dipublikasikan sebagai <host>:<container>/tcp atau /udp; SCTP tidak memiliki penulisan di compose dan menghentikan build alih-alih memublikasikan port yang akan membawa transport berbeda |
Port kontainer yang tidak dipublikasikan oleh layanan mana pun sama sekali tidak muncul di file compose — itulah perilaku tetap compose untuk port kontainer — sehingga transport yang dideklarasikan pada port seperti itu tidak memiliki tempat untuk dituliskan dan tidak menghentikan build.
Health probe — bentuk maksud
Setiap kontainer mendeklarasikan probe-nya di bawah kunci health: miliknya sendiri (containers.<name>.health), dalam bentuk maksud yang abstrak; Workload tidak memiliki health tingkat atas. Setiap provider menerjemahkan maksud tersebut ke dalam bentuk probe aslinya pada saat sintesis.
health: ready: http: /healthz # intent: HTTP GET probe timeoutSeconds: 5 live: tcp: 8080 # intent: TCP socket check timeoutSeconds: 5 startup: exec: ["check-ready.sh"] # intent: command exec timeoutSeconds: 30 periodSeconds: 10Tiga bentuk maksud (http:, tcp:, exec:) saling eksklusif dalam satu deklarasi probe. Resolusi port untuk http: tanpa port eksplisit mengambil nama port pertama menurut urutan abjad yang dideklarasikan container di bawah containers.<name>.ports — aturan yang sama pada kedua target, sehingga sebuah probe membaca port yang sama target mana pun yang merendernya. Container yang tidak mendeklarasikan port bernama tidak dapat membawa probe HTTP: build berhenti dengan kesalahan penerjemahan yang menyebutkan probe yang bermasalah.
Penerjemahan per provider. Setiap provider menerjemahkan maksud probe yang abstrak ke dalam bentuk aslinya pada saat sintesis:
| Maksud | Helm (K8s) | Compose | Catatan kehilangan |
|---|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" | Compose tidak memiliki bentuk probe HTTP asli; wrapper CMD-SHELL bergantung pada keberadaan curl di dalam image container. |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" | Compose tidak memiliki bentuk probe TCP asli; wrapper CMD-SHELL bergantung pada keberadaan nc di dalam image container. |
exec: [cmd, ...] | exec.command: [cmd, ...] | CMD [cmd, ...] | Pemetaan satu-ke-satu; kedua provider membawa daftar perintah apa adanya. |
Wrapper CMD-SHELL milik Compose mendekati probe HTTP dan TCP melalui predikat yang dapat dievaluasi shell. Yang tidak dimiliki compose adalah bentuk probe asli, bukan field pengaturan waktu: periodSeconds, timeoutSeconds, failureThreshold, dan initialDelaySeconds yang ditulis dibawa ke healthcheck sebagai interval, timeout, retries, dan start_period — bagian “Probes” di providers/compose.md memuat pemetaan per field. Bentuk exec: asli sama sekali tidak memerlukan wrapper dan diterjemahkan satu-ke-satu pada kedua target.
Probe yang dibungkus diterjemahkan secara diam-diam: tidak ada apa pun di docker-compose.yaml yang dihasilkan yang menandainya, dan tidak ada diagnostik yang melaporkan pembungkusan tersebut. Yang dilaporkan build pada jalur ini adalah slot probe yang sama sekali tidak mencapai output — sebuah service compose membawa satu healthcheck, sehingga jika sebuah Workload mendeklarasikan lebih dari satu dari ready:, live:, dan startup:, hanya slot yang diutamakan yang diterjemahkan (live di atas ready di atas startup) dan peringatan unsupported-field menyebutkan slot yang diterjemahkan dan slot yang dibuang.
Catatan khusus Provider (compose). Menulis blok health: pada Workload yang menargetkan compose tidak membuat urutan depends_on bergantung pada kesehatan: entri depends_on milik provider compose yang diturunkan dari edge uses: selalu menggunakan semantik service_started, terlepas dari apakah Workload target mendeklarasikan probe kesehatan. Membuat entri tersebut bergantung pada kesehatan target belum diimplementasikan — bentuk panjang yang akan membawa kondisi semacam itu sebenarnya sudah dihasilkan, untuk penantian init-container, sehingga yang belum ada adalah pilihan untuk membuat sebuah edge bergantung pada kesehatan, bukan bentuk untuk menyatakannya. Lihat providers/compose.md untuk aturan inferensi selengkapnya.
Field pass-through berbentuk K8s — scheduling, serviceAccount, podSecurityContext
Skema Workload menerima tiga field tingkat atas opsional yang terutama ada untuk meneruskan primitif native Kubernetes melalui provider helm sambil mempertahankan bentuk struktural Aggrega. Provider compose menerjemahkan subset yang memiliki padanan di Compose dan mengabaikan sisanya dengan mengeluarkan peringatan. Aggrega memvalidasi bentuk luarnya tetapi tidak mengawasi konten di dalamnya (lihat Cakupan validasi di bawah) — nilai-nilai dalam yang native K8s diteruskan apa adanya ke spesifikasi pod hasil render helm.
scheduling
scheduling mengelompokkan empat primitif penjadwalan native K8s — nodeSelector, affinity, tolerations, topologySpreadConstraints — ke dalam satu blok yang dikunci berdasarkan tujuan. Setiap sub-field berbentuk persis seperti field spesifikasi pod Kubernetes yang bersesuaian:
apiVersion: aggrega.ai/v1beta1kind: Workloadscheduling: nodeSelector: disktype: ssd region: us-east-1 tolerations: - key: dedicated operator: Equal value: gpu-workloads effect: NoSchedule affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: { app: "{{ .context.instance_id }}" } topologyKey: kubernetes.io/hostname topologySpreadConstraints: - maxSkew: 1 topologyKey: topology.kubernetes.io/zone whenUnsatisfiable: ScheduleAnywaycontainers: app: { image: "..." }Terjemahan Provider. Provider helm meneruskan setiap sub-field apa adanya ke dalam spesifikasi pod yang dirender. Provider compose tidak menerjemahkan satu pun dari keempatnya: provider ini menghilangkan seluruh blok scheduling, dan sebuah peringatan menyebutkannya.
serviceAccount
serviceAccount adalah string biasa yang berisi nama ServiceAccount tempat workload berjalan:
apiVersion: aggrega.ai/v1beta1kind: WorkloadserviceAccount: "{{ .context.rendered_name }}-runner"containers: app: { image: "..." }Nama tersebut dibangun dari {{ .context.rendered_name }}, yaitu nama release yang digunakan provider helm untuk menamai resource milik workload itu sendiri, sehingga nama tersebut diterima oleh cluster apa pun nama komponennya. Field ini mereferensikan ServiceAccount yang sudah ada; field ini tidak membuatnya. Resource RBAC pendampingnya (objek ServiceAccount itu sendiri, ditambah Role / RoleBinding / ClusterRole / ClusterRoleBinding) sebaiknya dikirim melalui salah satu dari dua saluran:
- Recipe
artifacts:— bila RBAC tersebut intrinsik bagi Recipe ini (Recipe tahu bahwa ia memerlukan Role tertentu untuk tugas tertentu). - Features dengan Resource Generation — bila RBAC bersifat lintas bagian (sebuah FeatureRecipe Workload-Identity yang melampirkan ServiceAccount terikat IAM ke setiap komponen dengan label tertentu).
Menetapkan serviceAccount: tanpa memastikan ServiceAccount yang dinamai itu ada akan menghasilkan error K8s saat runtime pada waktu apply, bukan error saat build — validasi skema workload tidak memeriksa keberadaan ServiceAccount (tidak ada akses saat kompilasi ke status cluster sesuai invarian kemurnian AOT).
Provider compose mengabaikan serviceAccount: dengan peringatan; Compose tidak memiliki konsep pengikatan identitas yang setara.
podSecurityContext
podSecurityContext berisi primitif keamanan tingkat pod — UID, GID, fsGroup, supplementalGroups — yang berlaku untuk setiap container di dalam pod:
apiVersion: aggrega.ai/v1beta1kind: WorkloadpodSecurityContext: runAsUser: 1000 runAsGroup: 3000 fsGroup: 2000 supplementalGroups: [4000, 5000]containers: app: { image: "..." }Semantik field. Keempat field berupa integer (UID/GID numerik, bukan string); runAsUser dan runAsGroup menetapkan UID/GID efektif proses container; fsGroup menetapkan kepemilikan grup untuk volume yang di-mount ke dalam pod; supplementalGroups menambahkan GID tambahan ke grup proses setiap container.
Terjemahan Provider. Provider helm meneruskan blok ini apa adanya ke dalam spesifikasi pod yang dirender. Provider compose tidak memiliki padanan untuk fsGroup atau supplementalGroups dan menghilangkan masing-masing dengan peringatan; runAsUser/runAsGroup diterjemahkan menjadi bentuk Compose user: 1000:3000 pada setiap service yang dihasilkan Workload, termasuk sidecar dan init container, dan runAsGroup tanpa runAsUser di sampingnya dihilangkan dengan peringatan. Setiap container dan init container juga membawa securityContext miliknya sendiri — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation, serta capabilities.add / capabilities.drop. Provider helm mengeluarkannya pada container; provider compose mengeluarkan readOnlyRootFilesystem sebagai read_only, capabilities.add / capabilities.drop sebagai cap_add / cap_drop, dan runAsUser / runAsGroup sebagai user milik container itu sendiri, yang menggantikan milik pod; provider ini menghilangkan runAsNonRoot, allowPrivilegeEscalation, dan runAsGroup yang ditulis tanpa runAsUser, masing-masing dengan peringatan, dan juga memperingatkan ketika runAsUser milik sebuah container membuat runAsGroup milik pod tertinggal. providers/compose.md memuat pemetaan per field.
Workload GPU dan perangkat
Workload yang memerlukan perangkat keras khusus — GPU, atau perangkat lain yang disediakan vendor — menyatakan dua hal yang saling independen: runtime tingkat pod yang diekspos oleh node yang mendukung perangkat tersebut (runtimeClassName), dan jumlah perangkat per kontainer yang diklaim workload (kunci extended-resource di bawah resources milik sebuah kontainer). Workload GPU yang umum mendeklarasikan keduanya bersama-sama, tetapi masing-masing berdiri sendiri dan salah satunya dapat muncul tanpa yang lain.
Kedua field tersebut menggambarkan komputasi — pod dan kontainer yang berjalan di atas perangkat — sehingga keduanya ditempatkan pada workload yang menjalankan kontainer. Workload yang hanya membawa endpoint eksternal dan tidak mendeklarasikan kontainer sendiri tidak memiliki pod atau kontainer untuk menempelkannya: menetapkan runtimeClassName pada workload yang hanya berisi endpoint seperti itu akan menghentikan build, dengan menyebutkan runtimeClassName dan Recipe yang Workload-nya mendeklarasikannya, dan tanpa kontainer tidak ada tempat untuk menaruh permintaan resource perangkat.
runtimeClassName
runtimeClassName adalah satu string yang menamai RuntimeClass tempat pod berjalan — runtime kontainer yang diekspos oleh node yang mendukung perangkat, misalnya runtime GPU bernama nvidia. Field ini adalah selektor tingkat pod: berlaku untuk setiap kontainer dalam workload. Compiler meneruskan nama tersebut apa adanya sebagai penunjuk deterministik; kluster menyelesaikannya menjadi RuntimeClass yang telah dikonfigurasi administratornya, pada saat penjadwalan. Aggrega tidak memeriksa apakah RuntimeClass yang cocok ada — Aggrega tidak memiliki akses ke status kluster pada waktu kompilasi — sehingga nama tanpa RuntimeClass yang terkonfigurasi muncul sebagai error penjadwalan pada saat apply, bukan error saat build.
Kunci extended-resource
resources.requests dan resources.limits milik sebuah kontainer membawa kuantitas cpu dan memory biasa serta, di sampingnya, kunci extended-resource: kuantitas perangkat dengan cakupan vendor atau domain yang dikunci dengan nama lengkap <domain>/<name> seperti nvidia.com/gpu atau amd.com/gpu. Segmen domain memuat setidaknya satu titik, dan titik itulah yang membedakan kunci extended (nvidia.com/gpu) dari kuantitas cpu dan memory biasa. Setiap nilai adalah kuantitas string ("1", "2") yang diteruskan compiler apa adanya, dan helm provider memeriksa bentuknya sebelum mengeluarkannya (lihat Kuantitas resource); device plugin milik kluster menyelesaikan dan mengalokasikan perangkat pada saat penjadwalan.
Contoh lengkap — workload inferensi GPU
apiVersion: aggrega.ai/v1beta1kind: WorkloadruntimeClassName: nvidiacontainers: inference: image: "{{ .values.image }}" resources: requests: cpu: "2" memory: "8Gi" nvidia.com/gpu: "1" limits: nvidia.com/gpu: "1"Workload ini memilih runtime nvidia untuk pod-nya dan mengklaim satu GPU untuk kontainer inference. Kuantitas GPU muncul di requests maupun limits: perangkat tidak dapat di-oversubscribe, sehingga request dan limit-nya ditetapkan ke nilai yang sama.
Terjemahan provider. Ini adalah konsep native Kubernetes. Helm provider mengeluarkan runtimeClassName pada spesifikasi pod yang dirender dan setiap kunci extended-resource apa adanya di bawah resources.requests / resources.limits milik kontainer, sehingga keduanya mencapai kluster melalui output Kubernetes. Compose provider mencadangkan jumlah nvidia.com/gpu sebagai GPU NVIDIA sebanyak itu pada service milik kontainer (lihat Compose Provider → Resource kontainer); satu host tidak memiliki konsep runtime class dan tidak ada padanan untuk kunci extended-resource lainnya, sehingga workload yang mendeklarasikan runtimeClassName atau kunci lain dirender pada target compose tanpanya.
Berjalan di jaringan node
Secara default, sebuah workload berjalan dalam network namespace miliknya sendiri: kontainernya hanya melihat antarmuka mereka sendiri, dan lalu lintas mencapai mereka melalui translasi alamat milik target. hostNetwork: true meminta susunan yang lain — workload berjalan dalam network namespace milik node itu sendiri, sehingga workload melihat antarmuka node dan port yang dibuka kontainernya dapat dijangkau pada alamat node itu sendiri, tanpa translasi di antaranya.
Itulah yang dibutuhkan oleh satu kelas perangkat lunak. Media realtime, telefoni, jaringan privat virtual, dan lalu lintas serupa membawa alamat peer di dalam payload, sehingga alamat yang ditulis ulang selama transit tiba dengan menggambarkan tempat yang tidak dapat dijangkau peer; berjalan pada alamat node itulah yang menjaga keduanya tetap konsisten.
apiVersion: aggrega.ai/v1beta1kind: WorkloadhostNetwork: truecontainers: media: image: "{{ .values.image }}" ports: rtp: port: 7881 protocol: UDPApa yang dideklarasikannya, dan apa yang tidak
hostNetwork memilih sebuah network namespace, dan hanya itu.
- Ia tidak mendeklarasikan port. Port yang dibuka sebuah workload tetap dideklarasikan di bawah
containers.<name>.ports, persis seperti tanpanya, dan port tersebut tetap bermakna sama. MendeklarasikanhostNetworktidak menambahkan port dan tidak menghapus kebutuhan untuk mendeklarasikannya. - Ia tidak mendeklarasikan jumlah port. Aplikasi yang menginginkan banyak port berurutan — misalnya server media yang menyesuaikan rentang dengan jumlah prosesor mesin — mengonfigurasi rentang itu dalam badan konfigurasinya sendiri, dari nilai yang diberikan operatornya, dengan cara yang sama seperti mengonfigurasi hal lain yang dibacanya saat start-up. Itu adalah pengaturan aplikasi, bukan pengaturan workload, dan kontrak workload bukan tempatnya.
- Tidak ada yang disimpulkan. Kompiler tidak membaca makna apa pun dari nilai tersebut dan tidak menurunkannya dari hal lain: tidak dari nama port, tidak dari tipe atau label sebuah komponen, tidak dari berapa banyak port yang dideklarasikan. Sebuah workload berjalan di jaringan node jika, dan hanya jika, workload tersebut menyatakannya.
Karena menggambarkan komputasi, hostNetwork termasuk pada workload yang menjalankan kontainer. Workload yang hanya membawa endpoint eksternal tidak mendeklarasikan kontainer, sehingga tidak memiliki network namespace untuk dipilih: mendeklarasikan hostNetwork pada workload yang hanya berisi endpoint akan menghentikan build, dengan menyebut hostNetwork dan Recipe yang Workload-nya mendeklarasikannya.
Terjemahan Provider
Provider helm mengeluarkan hostNetwork: true pada pod spec yang dirender, yang merupakan cara Kubernetes menyatakan pilihan yang sama. Deklarasi ini mencapai pod spec dan tidak ada yang lain — Services yang dikeluarkan identik dengan maupun tanpanya.
Provider compose mengeluarkan network_mode: host pada service milik workload itu sendiri. Satu konsekuensi muncul dari cara compose memodelkan jaringan: service dalam mode tersebut tidak terpasang ke jaringan boundary, karena compose memperlakukan pemasangan ke jaringan dan pengadopsian namespace host sebagai alternatif, bukan tambahan. Karena itu, peer-nya menjangkaunya pada alamat host itu sendiri alih-alih melalui nama service — yang memang merupakan makna host networking pada target mana pun — dan setiap service lain pada boundary tidak terpengaruh.
Dua bentuk dapat dikombinasikan dengannya pada target tersebut. Kontainer sidecar mengikuti service utama ke jaringan host tanpa mendeklarasikan apa pun, karena kontainer tersebut mengambil namespace service utama dengan menyebut namanya. Init container tidak demikian: ia menjadi service yang ditunggu oleh service utama, sehingga ia bergabung ke jaringan boundary atas namanya sendiri alih-alih mengadopsi namespace yang akan membuat penantian tersebut melingkar. Karena itu, workload yang mendeklarasikan hostNetwork sekaligus initContainers menjalankan service-nya sendiri di jaringan node sementara init service-nya tetap berada di jaringan boundary — susunan yang lebih sempit daripada satu namespace bersama yang diberikan bentuk pod, dan provider compose menyebutkannya dalam peringatan unsupported-field alih-alih membiarkannya ditemukan saat run time.
Workload yang tidak mendeklarasikan hostNetwork tidak membawa key tersebut dalam output-nya: key itu tidak ada, alih-alih dikeluarkan sebagai false.
Integrasi lampiran dengan featuresSchema milik Component
Blok containers.<name>.attachments milik Workload merujuk ke slot kredensial yang dideklarasikan dalam featuresSchema milik Component — atau, untuk entri yang menyebut sebuah koneksi, slot yang dideklarasikan oleh socket koneksi tersebut (lihat Menyampaikan kredensial yang dibawa sebuah koneksi); blok ini tidak mendeklarasikan slot baru. Lihat ../entities/component.md untuk permukaan penulisan featuresSchema. from menyebut slot; itu bukan nama Secret yang dihasilkan.
Entri containers.<name>.attachments dirender menjadi referensi ke resource Secret — secretKeyRef Kubernetes (untuk as: env) atau volume berbasis secret (untuk as: file) — yang keduanya menunjuk ke Secret berdasarkan nama. Synthesizer menentukan nama dan kunci data tersebut dari provides yang diekspos slot: secretKeyRef.name yang dirender untuk entri adalah .features.<slot>.provides.name milik slot, dan kunci datanya adalah .features.<slot>.provides.key. Penulis Recipe hanya menulis from: <slot> dan as: env; synthesizer membaca provides yang telah ditentukan — synthesizer tidak menurunkan ulang nama tersebut. Ini adalah pembacaan .features.<slot>.provides.<key> yang sama dengan yang digunakan Recipe sumber untuk existingSecret: satu slot kredensial memasok konsumen Recipe sumber dan konsumen Workload hasil sintesis secara identik (simetri sumber/workload).
Empat aturan validasi mengatur integrasi ini:
- Setiap nilai
attachments.<KEY>.fromharus cocok dengan nama slot yang dideklarasikan dalamfeaturesSchemamilik Component — atau, pada entri yang menyebut sebuah koneksi, dalam socket koneksi tersebut. Nama slot yang tidak dikenal adalah galat saat pemuatan. - Mekanisme penyampaian
as:(envataufile) harus tercantum dalam allowlistinject:slot yang dideklarasikan oleh Component. Workload yang mendeklarasikanas: fileterhadap slot yang entrifeaturesSchema-nya menetapkaninject: [env]adalah galat saat pemuatan. - Slot yang ditandai
inject: [](penyampaian blackbox) dalamfeaturesSchemamilik Component sama sekali tidak boleh muncul dalam blokattachments:Workload. Slot tersebut disampaikan oleh mekanisme internal Recipe (misalnya parameterexistingSecretpada chart Helm), bukan melalui eksposur Workload. - Slot yang dirujuk harus dapat direferensikan — pengisinya harus menerbitkan locator
provides(name,key) untuk resource Secret, baik yang diemit oleh realisasinya maupun yang sudah ada. Slot yang diisi oleh kredensial yang disampaikan melalui inject (yang menulis nilai ke pipa inject dan tidak menerbitkan locator) tidak memiliki apa pun untuk ditunjuk; merujuknya dari entriattachments:Workload adalah galat saat pemuatan. Kredensial yang disampaikan melalui inject mencapai kontainer melalui pipa inject slot (entrivariablesyang membaca.context.inject.env.<KEY>), bukan melalui entriattachments:.
Catatan provider. Helm merender referensi secretKeyRef/volume secret yang dijelaskan di atas. Provider compose tidak memiliki primitif env-dari-secret bawaan; entri lampiran as: env pada Workload yang menargetkan compose dirender sebagai entri lingkungan dengan nilai kosong dan peringatan yang menyebut entri tersebut (lihat halaman provider compose), sementara aturan dapat-direferensikan (agnostik terhadap kapabilitas) tetap berlaku.
Contoh:
# In the Component catalog entityspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipe's Workloadworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected at load time: blackbox slotMenyampaikan kredensial yang dibawa sebuah koneksi
Socket sebuah Component dapat mendeklarasikan, dalam usesSchema.<socket>.featuresSchema, slot yang diisi oleh setiap koneksi yang dihubungkan melaluinya — sehingga komponen yang menjangkau beberapa target memegang satu kredensial per koneksi, bukan satu untuk semuanya. Lampiran seperti itu tidak termasuk dalam .features milik komponen itu sendiri; lampiran itu berada di bawah koneksinya, pada .context.uses.<alias>.features.<slot>. Entri Workload menyampaikannya dengan menyebut koneksi di samping slot:
- pada entri
attachmentssebuah kontainer,connection: <alias>di sampingfrom: <slot>; - pada entri
envFromsebuah kontainer,connection: <alias>di sampingsecret: <slot>—connectionhanya diterima di sampingsecret.
Kedua bentuk diterima pada setiap kontainer dan setiap init container. <alias> adalah nama tempat koneksi ditulis dalam blok uses komponen, pada Aggregate atau pada Release — kunci yang digunakan Recipe untuk membaca koneksi di bawah .context.uses — dan <slot> adalah slot yang dideklarasikan oleh socket tempat koneksi tersebut dihubungkan.
Sebelum aturan mana pun di atas membaca Workload, setiap entri yang menyebut koneksi ditulis ulang ke nama yang diambil pada komponen oleh lampiran yang dibawa koneksi tersebut dalam slot itu: alias, titik, dan slot (gpt.credential). Setiap aturan kemudian berjalan pada entri yang ditulis ulang persis seperti pada entri yang menyebut salah satu slot milik Component sendiri: allowlist inject: slot socket mengatur as:, slot socket yang mendeklarasikan inject: [] tidak dapat dirujuk, lampiran yang mengisinya harus dapat direferensikan, dan provider menentukan nama dan kunci data Secret dari provides yang telah ditentukan milik lampiran tersebut — sehingga entri setiap koneksi merujuk ke kredensial milik koneksi itu sendiri. Slot socket yang mendeklarasikan sensitive: true dibaca untuk entri persis seperti deklarasi slot Component. Entri yang ditulis ulang itulah yang diterima provider; kunci connection tidak sampai kepadanya.
Tiga jenis entri ditolak, masing-masing dengan menyebut apa yang dirujuknya:
- entri yang menyebut koneksi yang tidak digunakan komponen — penolakan menyebut koneksi, slot, dan koneksi yang memang digunakan komponen;
- entri yang menyebut slot yang tidak dideklarasikan oleh socket koneksi — penolakan menyebut slot, koneksi, socket, dan slot yang dideklarasikannya;
- entri yang menulis sendiri nama gabungan (
from: gpt.credential). Slot sebuah koneksi disebut dengan menyebut koneksinya, sehingga nama gabungan tidak pernah menjadi cara kedua untuk menjangkaunya.
Koneksi yang tidak membawa lampiran dalam slot tersebut membuat entri tidak memiliki apa pun untuk dirujuk, dan aturan dapat-direferensikan menolaknya. Workload yang dirender oleh FeatureRecipe dibatasi pada slot yang dideklarasikan oleh Feature yang diimplementasikannya, yang tidak menjangkau satu pun koneksi komponen host, sehingga entri di sana yang menyebut koneksi ditolak karena menyebut koneksi yang tidak digunakan komponen.
Contoh:
# In the Component catalog entityspec: usesSchema: models: featuresSchema: credential: sensitive: true inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`# through the `models` socket, each carrying its own `credential`workload: | containers: main: attachments: MODEL_KEY_GPT: from: credential connection: gpt as: env MODEL_KEY_NIM: from: credential connection: nim as: envPada helm, MODEL_KEY_GPT dirender sebagai secretKeyRef yang menyebut Secret yang diterbitkan oleh kredensial koneksi gpt, dan MODEL_KEY_NIM menyebut Secret yang diterbitkan oleh kredensial koneksi nim. Pada compose, entri as: env yang menyebut koneksi diemit dengan nilai kosong dan peringatan dukungan parsial yang sama dengan yang diterima entri yang menyebut salah satu slot milik Component sendiri.
Permukaan validasi
Setiap Workload divalidasi pada saat pemuatan Recipe sebelum rendering apa pun dijalankan. Validasi memiliki dua tahap:
- Validasi skema. Nilai Workload diunifikasi terhadap skema Workload
aggrega.ai/v1beta1yang tertanam. Error memuat jalur field dan batasan yang dilanggar (misalnya,.containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). Validasi skema menegakkan setiap tipe, enum, rentang, dan disjungsi yang dideklarasikan dalam skema — termasukformcontroller dengan himpunan tertutup (salah satu daristateless,stateful,daemon,scheduled,task,reference),typeservice dengan himpunan tertutup (salah satu dariClusterIP,Headless,NodePort,LoadBalancer,Loopback), rentang port bilangan bulat (1..65535), disjungsi bentuk probe (tepat satu darihttp,tcp,exec), dan disjungsi varian volume (tepat satu dariephemeral,configmap,secret,persistent,persistentTemplate). - Validasi referensi silang. Referensi attachment Workload diperiksa terhadap
featuresSchemamilik Component — dan, untuk entri yang menyebut sebuah koneksi, terhadap slot yang dideklarasikan oleh socket koneksi tersebut — (keanggotaan slot, allowlist pengirimanas:, pengecualian blackbox) serta terhadap provides yang telah di-resolve dari setiap slot yang direferensikan (kemampuan untuk direferensikan — pengisinya harus memublikasikanname/key). Ini adalah pemeriksaan lintas entitas yang tidak dapat dilakukan oleh validasi yang hanya berbasis skema.
Kedua tahap menghasilkan bentuk pesan yang sama dengan awalan CATALOG_ERROR; kegagalan menghentikan build sebelum output rendering apa pun dihasilkan. Penulis Recipe mendapatkan umpan balik yang tepat sasaran, yang mengidentifikasi field persis yang gagal dan batasan yang menolaknya.
Field pass-through berbentuk K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, daftar items di dalam volume ConfigMap dan Secret, hook lifecycle httpGet) hanya divalidasi secara struktural — skema Aggrega membatasi keberadaan dan bentuk luarnya, tetapi bentuk dalam dari nilai-nilai yang didefinisikan oleh API K8s ini merupakan tanggung jawab provider (provider helm meneruskannya apa adanya ke spesifikasi pod K8s; provider compose menolak atau menurunkannya sesuai kebutuhan). Workload yang menggunakan nilai affinity yang bentuknya salah akan lolos validasi Aggrega dan error-nya baru muncul saat sintesis provider.
Kuantitas sumber daya juga merupakan string bagi skema dengan cara yang sama: tidak ada tahap yang memeriksa bentuknya. Provider yang melakukan sintesis yang memeriksanya, pada Workload yang telah dievaluasi, dan berhenti pada nilai di luar bentuk kuantitas — lihat Kuantitas sumber daya.
Sumber daya tambahan berada di luar Workload
Workload hanya menggambarkan bentuk workload — kontainer, volume, layanan, replika, penjadwalan, konteks keamanan, akun layanan. Workload tidak memiliki field additionalResources dan tidak memiliki deklarasi ConfigMap / Secret / CRD inline.
Penulis Recipe menghasilkan sumber daya tambahan melalui dua saluran di luar Workload:
artifacts:tingkat Recipe — untuk sumber daya yang intrinsik bagi Recipe ini (ConfigMap tertentu yang dirujuk oleh Workload milik Recipe, pendaftaran CRD sekali pakai yang dibutuhkan Recipe). Field ini adalah map berisi entri bernama; setiap entri ditulis inline atau dimuat melalui$import:per entri. Lihat bagian Artifacts Mechanism di ../../architecture/16-recipe-input-composition.md untuk tiga mode penulisan.- Features dengan Resource Generation — untuk kebutuhan lintas bidang yang dilampirkan melalui selektor Release (Feature ServiceMonitor yang dilampirkan ke setiap komponen yang mengekspos metrik, Feature NetworkPolicy yang dilampirkan ke setiap workload produksi). Lihat ../entities/featurerecipe.md untuk permukaan penulisan FeatureRecipe.
Workload tetap berfokus pada bentuk workload; manifest tambahan yang bersifat lintas bidang maupun yang intrinsik bagi Recipe memiliki tempat penulisannya sendiri.
Pola Workload yang umum
Skema Workload bersifat luas — skema ini mencakup server HTTP satu kontainer, pola sidecar multi-kontainer, rantai init-container, batch job, dan layanan stateful dengan volume persisten. Tiga pola cukup sering berulang sehingga menulis boilerplate dari awal untuk setiap Recipe merupakan pemborosan. Blok di bawah ini adalah templat salin-tempel yang dapat diadaptasi oleh penulis Recipe untuk komponen tertentu.
Pola yang dipakai bersama oleh beberapa Recipes dapat dipublikasikan sekali sebagai entri WorkloadLibrary dan diimpor dengan $import: <Library>#/workloads/<entry>; templat di sini adalah titik awal untuk disesuaikan, atau untuk dipublikasikan dengan cara itu.
Pola 1 — Server dengan eksposur metrik
Aplikasi web tipikal yang melayani lalu lintas aplikasi pada satu port dan mengekspos metrik yang di-scrape Prometheus pada port terpisah. Dua layanan dalam Workload — satu untuk aplikasi, satu untuk metrik — menjaga kebijakan service mesh dan konfigurasi load balancer tetap dapat dipisahkan dengan rapi.
apiVersion: aggrega.ai/v1beta1kind: Workloadreplicas: {{ optional .infra `replicas` 2 }}containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} metrics: {{ optional .values `metrics_port` 9090 }} variables: LOG_LEVEL: "{{ optional .values `log_level` "info" }}" health: ready: http: /healthz timeoutSeconds: 5 live: http: /healthz timeoutSeconds: 5services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }} metrics: type: ClusterIP ports: metrics: {{ optional .values `metrics_port` 9090 }}Layanan metrik biasanya diberi anotasi untuk penemuan Prometheus melalui lampiran Feature pada permukaan Release (misalnya, feature.aggrega.ai/prometheus-scrape: "true"); Workload itu sendiri tetap bersih dari anotasi scrape yang spesifik untuk provider.
Pola 2 — Batch job
Workload yang berjalan hingga selesai alih-alih melayani lalu lintas tanpa batas waktu. Pola ini menetapkan form: task, menghilangkan services: sepenuhnya — batch job tidak mengekspos port — dan mengandalkan bentuk task dari provider target (Kubernetes Job pada provider helm; provider compose tidak memiliki bentuk task dan menghentikan build pada form: task). Provider helm menetapkan restartPolicy pod yang valid untuk Job (Never kecuali kontainer mendeklarasikan OnFailure), karena pod Job tidak dapat menggunakan default Always.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: taskcontainers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"] args: - "--config" - "/etc/config/job.yaml" variables: JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}" volumeMounts: - name: config path: /etc/configvolumes: config: configmap: source: "{{ .context.instance_id }}-config"Volume konfigurasi merujuk ke ConfigMap yang diharapkan dihasilkan oleh Recipe bersama Workload melalui artifacts: (lihat “Sumber daya tambahan berada di luar Workload” di atas) — Workload itu sendiri hanya mendeklarasikan sisi konsumsinya. Identitas menamainya pada provider yang menamai workload sesuai identitas, seperti yang dilakukan compose; pada helm, yang menamai sumber daya workload sesuai nama release, bangun nama ConfigMap — di sini dan di artefak — dari {{ .context.rendered_name }} sebagai gantinya, sehingga nama tersebut diterima oleh klaster apa pun nama komponennya.
Pola 3 — Pasangan sidecar
Pod dua kontainer tempat kontainer utama menangani logika aplikasi dan sidecar menangani kepentingan lintas sektor (terminasi TLS, pengiriman log, proxy service mesh, guardrail AI). Urutan penulisan dalam containers: berpengaruh — provider helm menghasilkan kontainer sesuai urutan deklarasi; kunci pertama (di sini, main) adalah target kontainer default untuk kubectl logs dan perkakas serupa.
apiVersion: aggrega.ai/v1beta1kind: Workloadreplicas: {{ optional .infra `replicas` 2 }}containers: main: image: "{{ .values.app_image }}" ports: app: {{ optional .values `app_port` 8080 }} variables: UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}" sidecar: image: "{{ .values.sidecar_image }}" ports: proxy: {{ optional .values `proxy_port` 9000 }} variables: PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"services: external: type: ClusterIP ports: proxy: {{ optional .values `proxy_port` 9000 }}Service mengekspos port sidecar (bukan port kontainer utama), merutekan lalu lintas eksternal melalui sidecar ke kontainer utama melalui localhost. Kedua kontainer berbagi namespace jaringan pod, sehingga localhost:<port> menjangkau kontainer rekan secara langsung. Untuk sidecar yang memerlukan injeksi kredensial (pola guardrail AI yang kanonis), kredensial biasanya berada pada blok attachments: milik sidecar, bukan milik kontainer utama — menjaga kredensial tetap terbatas pada batas proses sidecar.
Pemilihan pola
Ketiga pola tersebut memetakan ke kepentingan bentuk pengiriman yang berbeda:
- Server dengan metrik — layanan yang berjalan lama dan dijaga tetap hidup oleh klaster; beberapa eksposur Service untuk pemisahan lalu lintas.
- Batch job — eksekusi terbatas; tanpa eksposur Service; mengandalkan ConfigMap yang dihasilkan Recipe atau status eksternal sebagai input.
- Pasangan sidecar — pod multi-kontainer dengan namespace jaringan bersama; Service milik sidecar mengekspos kepentingan lintas sektor tersebut.
Pola keempat — server stateful dengan volume persisten — menetapkan form: stateful dan mendeklarasikan penyimpanan per replika melalui volumes.<name>.persistentTemplate; provider helm menghasilkan StatefulSet untuk bentuk stateful (lihat providers/helm.md). Pola ini identik bentuknya dengan “server dengan metrik” dengan form: stateful, volume persistentTemplate tambahan, dan tepat satu layanan type: Headless untuk mengatur StatefulSet (build berhenti tanpanya); penulis yang membutuhkannya mengadaptasi Pola 1 dengan ketiga deklarasi tersebut.
Rujukan silang
- ../../architecture/16-recipe-input-composition.md — peran arsitektural jenis Workload dan cakupan skema lengkapnya.
- ../entities/recipe.md — cara
workload:dikomposisikan dengan dua jenis input Recipe lainnya. - ../entities/component.md — penulisan
featuresSchemayang dirujuk oleh blokattachments:Workload. - ../entities/featurerecipe.md — sumber daya tambahan tingkat Feature yang berdampingan dengan Workloads.
- ../vocabulary/data-pillars.md — kontrak akses pilar untuk evaluasi templat.
- ../templates/expansion-matrix.md — posisi evaluasi Workload dalam matriks evaluasi templat.