Komposisi input Recipe — tiga jenis input, Workload, artefak
Recipe menghasilkan file manifes untuk penyedia targetnya. Bab ini membahas bagaimana Recipes menyusun output-nya dari tiga jenis input yang ortogonal — sourced, synthesized, dan artifacts —, bagaimana setiap jenis input distrukturkan, dan penyedia mana yang menghasilkan output apa. Peran konseptual entitas Recipe (template terjemahan yang ditulis Ops yang memetakan maksud developer ke satu penyedia fisik) dijelaskan di 04-entity-taxonomy.md; permukaan authoring Recipe pada tingkat kata kunci dijelaskan di ../language-reference/entities/recipe.md.
Alasan
Alat rendering native setiap penyedia — Helm, Docker Compose — sudah tahu cara me-render manifes native penyedia. Tugas Recipe adalah mendeklarasikan APA yang harus dinyatakan manifes tersebut: image container mana, port mana, variabel lingkungan mana, volume mana, layanan mana, batas sumber daya mana.
Recipe harus mengekspresikan lebih dari yang dapat dimuat oleh sekumpulan kunci tetap (misalnya image, environment, ports, replicas) yang dipetakan ke sebuah Deployment dan sebuah Service, di antaranya:
resources(request/limit CPU/memori)- Probe liveness, readiness, atau startup
volumeMounts/volumesnodeSelector/affinity/tolerationsserviceAccount/securityContext- Pod multi-container, sidecar
- Sumber daya ConfigMap / Secret / PVC / CRD
- Service non-ClusterIP (LoadBalancer, NodePort, Headless)
Lapisan abstraksi perlu mendeskripsikan bentuk beban kerja secara utuh, bukan sekumpulan kunci tetap. Tiga jenis input yang dijelaskan di bawah adalah abstraksi tersebut: Recipe menyusun output-nya secara aditif dari chart atau modul yang dimuat secara eksternal (source:), spesifikasi Workload abstrak yang disintesis penyedia menjadi manifes native penyedia (workload:), dan manifes native penyedia berbasis template yang langsung dihasilkan Recipe (artifacts:).
Tiga jenis input
Komposisi dengan penambahan
Ada tiga cara untuk menghasilkan file manifes native penyedia dari sebuah Recipe, dan ketiganya tersusun dengan penambahan, bukan saling meniadakan:
source:— artefak yang dimuat secara eksternal (chart Helm, file compose) yang di-render penyedia secara native, denganvaluesMapping:menyediakan nilai overlay.workload:— spesifikasi Workload abstrak (jenis milik platform) yang disintesis penyedia menjadi manifes native penyedia. Field ini menerima block scalar YAML inline atau$import:ke satu file lokal atau entri pustaka; dispatch-nya ditentukan oleh bentuk konten.artifacts:— map berisi manifes native penyedia, inline atau dimuat dengan$import:, yang diproses sebagai template Go terhadap konteks pilar lengkap. Setiap entri dapat ditulis inline (nilai entri adalah block scalar) atau melalui$import:ke satu file atau konten pustaka.
Ketiganya menghasilkan file yang dikeluarkan compiler ke direktori output boundary. Ketiganya dapat berdampingan dalam satu Recipe, dengan tunduk pada aturan validasi di bawah. Semantik penggabungan hanya pada tingkat teratas: setiap jenis input menghasilkan file utuh; file-file dikeluarkan berdampingan; tabrakan nama file output adalah error fatal.
Nama mode deskriptif
Tiga “mode” tersebut adalah kosakata deskriptif untuk dokumentasi dan diagnostik. Penulis Recipe tidak mendeklarasikan mode; mereka menulis kata kunci yang mereka butuhkan. Sebuah Recipe dicirikan oleh input dominannya:
| Kata kunci dominan | Nama mode deskriptif |
|---|---|
source: + valuesMapping: (tanpa workload:, tanpa artefak) | sourced |
workload: (tanpa source:, tanpa artefak) | synthesized |
artifacts: (tanpa source:, tanpa workload:) | artifacts-only (secara informal: “inline”) |
| Kombinasi apa pun dari dua atau lebih | dijelaskan secara eksplisit (misalnya “sourced dengan artifacts”, “synthesized dengan artifacts”) |
Tidak ada kata kunci bernama mode: dan tidak ada enum. Mode adalah properti yang muncul dari input mana yang ada.
Sekilas bentuk Recipe
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: ... version: 1.0.0spec: capability: helm | compose | helm-chart | ... implements: core/...:1.0.0
locals: { ... } provides: { ... }
# ─── Sourced input (optional, paired) ─── source: ... valuesMapping: | # Go template → YAML/JSON overlay values # OR: valuesMapping: $import: ./mappings/api-server.tmpl # local file path # OR: valuesMapping: $import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ─── workload: | # Go template → YAML → parsed Workload # OR (single-source $import for whole-content load from a file or library): workload: $import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ─── artifacts: "filename.yaml": | # Inline Go template → manifest YAML "other.yaml": $import: ./artifacts/other.yaml # per-entry $import: for file or library contentSetiap field di atas diterima oleh skema Recipe, dan compiler mengonsumsi ketiga jenis input — rendering sourced, sintesis Workload, dan emisi artifacts. Yang berbeda adalah dukungan per penyedia — penyedia mana yang me-render jenis input mana — yang dicatat dalam matriks kapabilitas Provider di akhir bab ini.
Aturan validasi saat pemuatan
Skema Recipe dan validasi saat pemuatan memberlakukan aturan komposisi berikut:
valuesMapping:memerlukansource:. Tanpasource:untuk di-overlay, tidak ada yang menerima nilai yang dipetakan. Recipe denganvaluesMapping:tanpasource:adalah error saat pemuatan. (source:tanpavaluesMapping:diizinkan — chart atau modul di-render dengan nilai default-nya sendiri.)workload:menerima satu sumber — inline atau$import:, tidak keduanya. Recipe menentukan Workload sebagai block scalar inline atau sebagai$import:ke satu file. Bentuk$import:bersumber tunggal sesuai kosakata impor file yang terpadu; penggabungan multi-sumber tidak didukung padaworkload:. Dispatch yang salah bentuk adalah error saat pemuatan.workload:memerlukan penyedia yang mampu melakukan sintesis. Dukungan sintesis adalah properti penyedia itu sendiri, bukan properti field yang dideklarasikan. Recipeworkload:yang terikat ke penyedia yang tidak dapat melakukan sintesis ditolak saat node di-render — melalui gerbang kapabilitas penyedia (lihat matriks kapabilitas Provider) — dengan diagnostik yang jelas. Katalog pustaka standar mendeklarasikanworkloadSchemapada penyedia yang mampu melakukan sintesis menurut konvensi, sebagai kontrak terjemahan yang terdokumentasi, tetapi gerbang tersebut bergantung pada kapabilitas yang dilaporkan penyedia itu sendiri, bukan pada keberadaan field tersebut.- Setidaknya satu jenis input harus ada. Recipe tanpa satu pun dari
source:+valuesMapping:,workload:, atauartifacts:tidak menghasilkan output dan merupakan error saat pemuatan. - Entri artefak inline dan
$import:dapat berdampingan. Recipe dapat mendeklarasikan sebagian entriartifacts:secara inline dan sebagian lainnya melalui direktif$import:per entri. Kunci setiap entri menamai output-nya sendiri, sehingga entri dari kedua bentuk tidak pernah bertabrakan satu sama lain (lihat Apa yang menamai setiap file output). - Tabrakan nama file lintas jenis input adalah error saat render. Jika dua jenis input sebuah Recipe — output yang di-render dari sumber, output yang disintesis dari beban kerja, atau output yang dihasilkan dari artefak — menghasilkan file dengan nama yang sama, compiler mengeluarkan error fatal yang mengidentifikasi setiap kontributor. Pemeriksaan ini berjalan setelah terjemahan Workload, sehingga terjadi saat render, bukan saat pemuatan.
Jenis Workload
Kepemilikan dan lokasi
Workload adalah jenis milik platform pada apiVersion: aggrega.ai/v1beta1. Deklarasi JSON Schema 2020-12-nya disematkan dalam biner compiler saat build; penulis katalog tidak mengedit skema Workload, dan juga tidak menulis file YAML Workload mandiri sebagai entitas katalog. Tata bahasa Workload dikonsumsi di dalam field workload: sebuah Recipe atau FeatureRecipe (inline, atau melalui $import: ke satu file atau entri WorkloadLibrary) dan tidak di tempat lain.
Workload adalah jenis platform dan konsep compiler, bukan entitas terpisah dalam Taksonomi entitas. Recipe adalah entitas authoring; Workload adalah bentuk yang diambil oleh input yang disintesis dari Recipe.
Satu Workload per Recipe
Recipe mendeklarasikan paling banyak satu workload:. Workload mewakili satu unit komputasi yang terkait dengan Component yang diimplementasikan Recipe ini. FeatureRecipe juga mendeklarasikan paling banyak satu workload: miliknya sendiri — unit komputasi milik Feature, yang disintesis melalui jenis Workload yang sama — lihat FeatureRecipe. Kasus penggunaan yang memerlukan beban kerja sampingan tambahan diekspresikan melalui:
artifacts:— manifes tambahan di samping beban kerja, dalam Recipe yang sama (inline atau melalui$import:per entri).- Features dengan Pembuatan Sumber Daya — beban kerja sampingan lintas bidang (misalnya sidecar backup yang dilampirkan ke database) yang dideklarasikan sebagai entitas katalog terpisah, tempat FeatureRecipe menyintesis
workload:miliknya sendiri (atau me-render melaluisource:/artifacts:). Lihat 14-extensibility.md untuk Pembuatan Sumber Daya oleh FeatureRecipe.
Hal ini mempertahankan model satu unit komputasi per penulis: Recipe menyintesis beban kerja milik Component; FeatureRecipe menyintesis miliknya sendiri.
Permukaan lengkap
Kumpulan field Workload besar dan terus bertambah. Alih-alih menuliskannya ulang di sini, tempat salinannya akan tertinggal dari kontrak tanpa ada yang melaporkannya, bab ini menunjuk ke dua permukaan yang memuat seluruhnya:
- Referensi skema Workload yang dihasilkan — setiap field, tipenya, nilai default-nya, dan batasannya, dihasilkan dari JSON Schema yang diterbitkan dan dibandingkan dengannya pada setiap build, sehingga tidak dapat mendeskripsikan bentuk yang tidak diterima compiler.
- Halaman authoring Workload — panduan authoring tingkat field: arti setiap field, menjadi apa setiap penyedia me-render-nya, dan kombinasi mana yang ditolak build.
Deklarasi JSON Schema 2020-12 untuk Workload bersifat otoritatif dan dirilis tersemat dalam biner compiler. Provider helm dan compose menyintesis workload: sebuah Recipe, baik inline maupun dimuat dengan $import:; lihat matriks kapabilitas Provider untuk dukungan per penyedia.
Integrasi secret dengan featuresSchema
Blok containers.<name>.attachments milik Workload mereferensikan slot yang dideklarasikan oleh featuresSchema milik Component; blok ini tidak mendeklarasikan slot baru. Lihat ../language-reference/entities/component.md untuk permukaan authoring featuresSchema.
Kontrak validasi:
- Setiap nilai
attachments.<KEY>.fromharus cocok dengan nama slot yang dideklarasikan dalamfeaturesSchemamilik Component — atau, untuk entri yang menyebut koneksi denganconnection: <alias>, dengan slot yang dideklarasikan socket koneksi tersebut diusesSchema.<socket>.featuresSchema. Entri seperti itu ditulis ulang ke nama yang diambil lampiran koneksi pada komponen (<alias>.<slot>) sebelum aturan mana pun di sini dijalankan, sehingga setiap aturan di bawah membacanya seperti membaca entri yang menyebut slot milik Component itu sendiri. - Mekanisme pengiriman
as:(envataufile) harus ada dalam daftar yang diizinkan pada arrayinject:slot tersebut. - Slot yang ditandai
inject: [](blackbox) dalamfeaturesSchemamilik Component tidak boleh muncul dalam blokattachments:Workload — slot tersebut dikirim oleh mekanisme internal Recipe (misalnya melaluiexistingSecretHelm), bukan melalui eksposur Workload.
Contoh:
# In the Componentspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipeworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected — root_password is blackboxProbe kesehatan: maksud, bukan mekanisme
Probe Kubernetes dan healthcheck Docker Compose memiliki bentuk yang berbeda. Satu bentuk maksud abstrak diterjemahkan dengan rapi ke keduanya:
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: 10Providers menerjemahkan setiap intensi ke bentuk native masing-masing:
| Maksud | Helm (K8s) | Compose |
|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" |
exec: [cmd] | exec.command: [cmd] | CMD [cmd] |
Resolusi port untuk http: tanpa port eksplisit mengambil nama port pertama menurut abjad yang dideklarasikan container di bawah containers.<name>.ports, pada kedua target. Container yang tidak mendeklarasikan port bernama tidak dapat membawa probe HTTP, dan build berhenti dengan menyebut probe tersebut.
Compose menurunkan probe HTTP/TCP menjadi perintah shell healthcheck, dan sebuah layanan compose hanya membawa satu healthcheck: jika lebih dari satu probe dideklarasikan, satu yang diterjemahkan dan sebuah peringatan menyebutkan probe yang dibuang.
Jenis volume
Lima jenis volume; tanpa jenis gabungan:
| Jenis | Semantik | K8s (helm) | Compose |
|---|---|---|---|
ephemeral | Tmpfs / emptyDir; hilang bersama pod | emptyDir: { sizeLimit } | mount tmpfs:, tanpa ukuran (peringatan melaporkan sizeLimit yang ditulis) |
configmap | File konfigurasi hanya-baca | Referensi volume ConfigMap | referensi configs: tingkat layanan ke config tingkat teratas yang dideklarasikan artifacts: milik Recipe |
secret | File secret hanya-baca | Referensi volume Secret | file secret hanya-baca yang di-bind-mount |
persistent | PVC tunggal; bertahan saat pod dimulai ulang | Sumber daya PVC + volume.persistentVolumeClaim | volume bernama |
persistentTemplate | PVC per replika; pendamping form: stateful | StatefulSet.volumeClaimTemplates | volume bernama (diturunkan; peringatan dikeluarkan) |
Compose tidak dapat mengekspresikan template per replika. Saat persistentTemplate diterjemahkan ke compose, ia diturunkan menjadi satu volume bernama yang digunakan bersama oleh setiap replika, dan sebuah peringatan melaporkan penurunan tersebut. Volume persistentTemplate memerlukan form: stateful; mendeklarasikannya pada bentuk lain menghentikan build.
Eksposur multi-layanan
Setiap layanan adalah eksposur yang independen. Pola yang umum: layanan HTTP di port 8080 (ClusterIP internal) + layanan metrik di port 9090 (ClusterIP) + endpoint admin di port 9901 (LoadBalancer):
services: http: type: ClusterIP ports: web: 8080 metrics: type: ClusterIP ports: prom: 9090 admin: type: LoadBalancer ports: admin: 9901Masing-masing menjadi objek Service Kubernetes terpisah saat di-render dengan penyedia helm, yang sebaliknya berhenti pada entri Loopback. Di compose, layanan NodePort dan LoadBalancer menerbitkan port-nya di setiap antarmuka host dari layanan compose, layanan Loopback hanya di alamat loopback host, dan layanan ClusterIP serta Headless tidak menerbitkan apa pun.
Nama layanan dalam output K8s diberi awalan instance_id milik komponen agar unik. Nama port harus cocok dengan nama port container yang dideklarasikan di containers.<name>.ports.
Kontrak terjemahan sisi Provider: workloadSchema
Plugin yang me-render sebagai penyedia (pluginType: provider) mendeklarasikan spec.provider.workloadSchema — deklarasi JSON Schema 2020-12 yang mendokumentasikan bagaimana field Workload diterjemahkan ke output native penyedia tersebut. Inilah kontrak terjemahan yang mendokumentasikan dirinya sendiri. Lihat ../language-reference/entities/plugin.md untuk permukaan authoring Plugin, termasuk blok spec.provider.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: helm-renderer version: 1.0.0 pluginType: providerspec: abiVersion: v1beta1 provider: workloadSchema: | # how Workload translates to K8s manifests // Each Workload produces: 1 controller object chosen by workload.form // (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job) // + 1..N Services (one per workload.services entry) // + 1..N PVCs (one per workload.volumes.*.persistent entry) // + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source) // ...Field workloadSchema menyampaikan maksud terjemahan kepada penulis katalog dan tooling IDE. Field ini adalah kontrak terjemahan yang terdokumentasi, yang dideklarasikan menurut konvensi pada penyedia yang melakukan sintesis — tetapi dukungan sintesis ditentukan oleh penyedia itu sendiri, bukan oleh keberadaan field ini. Recipe yang menargetkan, dengan workload:, penyedia yang tidak dapat melakukan sintesis ditolak saat node di-render — melalui gerbang kapabilitas penyedia — dengan error yang jelas, baik penyedia tersebut mendeklarasikan workloadSchema maupun tidak.
Skema Plugin mendeklarasikan spec.provider.workloadSchema — isinya dikompilasi menjadi JSON Schema 2020-12 saat Plugin dimuat — dan konsumsi workload: di sisi Recipe sudah dirilis. Dukungan sintesis ditegakkan saat render oleh gerbang kapabilitas penyedia, berdasarkan kapabilitas yang dilaporkan penyedia yang terikat; workloadSchema adalah kontrak terdokumentasi yang dijaga tetap selaras oleh katalog pustaka standar dengan kapabilitas tersebut, bukan input gerbang itu sendiri. aggrega validate, yang dijalankan atas seluruh katalog, juga menampilkan lebih awal, sebelum build, Recipe workload: yang terikat ke penyedia yang tidak melakukan sintesis, jika katalog memuat entitas Plugin penyedia tersebut.
Sumber daya tambahan berada di luar Workload
Spesifikasi Workload tidak memiliki field additionalResources, tidak ada extras, dan tidak ada deklarasi inline ConfigMap/Secret/CRD. Workload hanya memodelkan bentuk beban kerja: container, volume, layanan, replika, penjadwalan, konteks keamanan, service account — semua yang mendeskripsikan bagaimana satu unit komputasi berjalan.
Sumber daya tambahan memiliki dua tempat yang sah di luar Workload:
- Features + FeatureRecipes — mekanisme untuk kebutuhan lintas bidang. ServiceMonitor yang dilampirkan ke “server apa pun dengan metrik yang diekspos” adalah
core/prometheus-exportersebagai Feature. Sumber daya routing yang menerbitkan server pada sebuah hostname juga merupakan Feature, dan bentuk routing menentukan yang mana:core/public-ingressjika target merekonsiliasi Ingress,core/http-routejika target menjalankan Gateway API — masing-masing diwujudkan oleh FeatureRecipe yang dipilih Manifest per Release. NetworkPolicy yang diberlakukan pada semua beban kerja produksi adalah Feature yang dilampirkan Release produksi di seluruh boundary. Features tersusun secara ortogonal dan dapat digunakan ulang di berbagai Recipes. Lihat 14-extensibility.md untuk Pembuatan Sumber Daya oleh FeatureRecipe. artifacts:tingkat Recipe — untuk sumber daya yang termasuk dalam implementasi Recipe spesifik ini dan tidak layak dibuatkan Feature. Pendaftaran CRD satu kali yang dibutuhkan Recipe. PodDisruptionBudget khusus Recipe yang hanya berlaku saat Recipe ini digunakan. ConfigMap yang direferensikan Workload milik Recipe. Setiap entri bersifat inline atau dimuat dengan$import:; lihat bagian Mekanisme artefak di bawah.
Batas antara Feature dan artefak adalah konvensi sosial. Jika sumber daya tambahan bersifat lintas bidang (berlaku untuk banyak Recipes, atau dilampirkan secara kondisional melalui selector), itu adalah Feature. Jika sumber daya itu intrinsik bagi satu Recipe ini (Recipe tidak dapat menjalankan tugasnya tanpa menghasilkan sumber daya tersebut), itu adalah artefak. Penulis memilih berdasarkan penggunaan ulang dan semantik lampiran; compiler tidak mengawasi pilihan tersebut.
Features dan artefak Recipe bersama-sama mencakup sumber daya tambahan yang dibutuhkan sebuah Recipe.
Mekanisme artefak
Artefak inline dan yang dimuat dari file
Jenis input artifacts menghasilkan file manifes native penyedia berbasis template langsung ke output boundary, di samping output apa pun yang di-render dari sumber atau disintesis dari beban kerja. Penulis mendeklarasikannya melalui dua permukaan:
spec: artifacts: "servicemonitor.yaml": | apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: {{ .context.instance_id }}-monitor spec: endpoints: - port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml": $import: ./artifacts/networkpolicy.yaml "crd-registration.yaml": $import: ./artifacts/crd-registration.yamlPath $import: bersifat relatif terhadap direktori Recipe dan harus tetap berada di dalamnya, karena setiap file yang dibawa publikasi Recipe diambil dari direktori tersebut — setiap file yang disebut impor ikut bersamanya — dan file di luar direktori itu tidak akan ikut. Konvensi yang umum menempatkannya di subdirektori ./artifacts/, meskipun compiler tidak memberlakukannya. Kunci map menamai setiap file yang dihasilkan — bagian berikutnya membahas artinya dalam masing-masing dari tiga bentuk.
Setiap entri (inline atau dimuat dengan $import:) diproses sebagai template Go terhadap konteks template lengkap sebelum dikeluarkan ke direktori output.
Apa yang menamai setiap file output
Map diberi kunci berdasarkan nama entri, dan kunci menamai apa yang dihasilkan entri dalam setiap bentuk authoring. Untuk entri inline, kunci adalah nama file output, digunakan sebagaimana tertulis:
artifacts: "configmap-config.yaml": | ... "pdb.yaml": | ...Menghasilkan configmap-config.yaml dan pdb.yaml. Kunci menetapkan nama file; di mana file itu berakhir adalah keputusan target, dan bagian tentang emisi per penyedia di bawah membahasnya.
Untuk entri $import: file, kunci juga merupakan nama file output. File yang diimpor menyediakan konten; file itu tidak menyediakan nama, sehingga penulis yang menginginkan nama file output tertentu menuliskan nama itu sebagai kunci:
artifacts: "monitor.yaml": $import: ./artifacts/monitor.yaml "netpol.yaml": $import: ./artifacts/subdir/some-other-name.yamlMenghasilkan .../monitor.yaml dan .../netpol.yaml. File yang diimpor entri kedua bernama some-other-name.yaml, dan nama itu tidak sampai ke output — kuncinyalah yang sampai. Dua entri yang mengimpor file berbeda yang kebetulan bernama sama, ./extras/shared.yaml dan ./overrides/shared.yaml, karenanya merupakan dua output yang berbeda, masing-masing dinamai oleh kuncinya sendiri.
Untuk entri $import: pustaka, yang menarik sekumpulan file sebagai satu unit, entri tersebut diperluas menjadi satu output per file dalam bundel, masing-masing bersarang di bawah kunci sebagai <key>/<filename>. Satu kunci menamai banyak file, sehingga kunci saja tidak dapat menamainya: kunci adalah direktori tempat file-file bundel berakhir, bukan nama salah satunya.
Karena setiap bentuk menamai output-nya dari kunci, kunci dibatasi di permukaan authoring pada apa yang dapat menjadi satu nama file: huruf atau angka di awal, lalu huruf, angka, titik, tanda hubung, dan garis bawah. Titik membawa ekstensi yang diharapkan konsumen, yang membuat kunci dapat langsung digunakan sebagai nama file; dan alfabetnya tidak memuat / maupun . di awal, sehingga satu kunci tidak pernah dapat membentuk lebih dari satu segmen path dan tidak pernah dapat menjadi segmen direktori induk. Kunci di luar alfabet gagal dalam validasi envelope saat workspace dimuat, pada aggrega validate, dan dalam diagnostik editor.
Dua output artifacts: yang membawa nama file yang sama menghentikan build saat node di-render, apa pun bentuk yang menghasilkannya. Dua entri dari satu map artifacts: tidak pernah menamai satu output yang sama: kunci bersifat unik dalam satu dokumen dan merupakan satu nama file, sehingga nama output entri file tunggal adalah kuncinya dan output entri bundel semuanya berada di bawah direktori yang dinamai menurut kuncinya. Karena itu, segmen pertama setiap path yang dihasilkan adalah kunci yang menghasilkannya, dan kunci yang berbeda tetap menjadi nama output yang berbeda. Yang dicakup penghentian ini adalah kasus lintas jenis input — satu nama file yang disumbangkan oleh dua di antaranya, template chart dan entri artefak yang sama-sama menghasilkan servicemonitor.yaml — dengan diagnostik yang menyebut setiap asal yang berkontribusi.
Konteks template untuk artefak
Template artefak memiliki akses ke konteks pilar lengkap:
.values,.infra,.context.*,.locals,.provides,.features,.metadata— pilar standar Aggrega yang dijelaskan di 06-data-taxonomy-and-composition.md..workload— spesifikasi Workload yang telah di-parse untuk Recipe ini (jika ada). Memungkinkan artefak mereferensikan nilai Workload tanpa duplikasi, misalnya ServiceMonitor yang mereferensikan.workload.services.metrics.ports.prom..source— konten fieldsource:yang telah di-resolve (jika ada).
Artefak dievaluasi setelah Workload di-parse, sehingga .workload tersedia jika ada. Untuk Recipes tanpa workload:, .workload bernilai nil; template yang mencoba melakukan dereferensi terhadapnya gagal dengan error yang jelas. Untuk Recipes tanpa source:, .source bernilai nil dengan mode kegagalan yang sama.
Invarian kemandirian
Artefak harus mandiri. Artefak hanya dapat mereferensikan input Recipe yang dideklarasikan: konteks pilar, Workload milik Recipe itu sendiri (jika ada), dan nilai source: milik Recipe itu sendiri. Artefak tidak dapat mereferensikan:
- Output Recipes lain dalam boundary yang sama.
- Sumber daya Kubernetes di lingkungan sekitar yang tidak dideklarasikan Recipe.
- Secret, ConfigMap, atau sumber daya lain yang diasumsikan ada secara eksternal (kecuali direferensikan melalui pilar yang dideklarasikan).
Artefak ConfigMap yang direferensikan oleh volumes.*.configmap.source milik Workload harus dihasilkan oleh Recipe INI (melalui artifacts: yang menghasilkan ConfigMap tersebut) atau oleh Feature yang dilampirkan ke node ini. Dependensi lintas Recipe dalam satu boundary tidak didukung.
Invarian ini mempertahankan kemampuan penggunaan ulang Recipe: Recipe dapat dimasukkan ke kombinasi Aggregate + Release mana pun yang memenuhi kontrak pilarnya, tanpa dependensi tersembunyi.
Label provenans
Setelah terjemahan, setiap file yang dihasilkan membawa provenans aggrega.ai/* dalam metadatanya — baik file itu di-render dari sumber, disintesis dari beban kerja, maupun dihasilkan dari template artefak. Setiap permukaan emisi membubuhkannya dari satu kumpulan builder bersama, sehingga file yang sama selalu membawa provenans yang sama, apa pun jenis input yang menghasilkannya. Kumpulan ini terbagi berdasarkan apakah suatu nilai memenuhi charset nilai label Kubernetes: kunci yang aman untuk label adalah label (dapat dikueri); kunci yang tidak aman untuk charset — recipe-uri (memuat :), boundary-path (path bersarang memuat /), dan sync-wave (- di awal wave negatif) — adalah anotasi, yang nilainya tidak dibatasi. Nilai identitas yang tidak diwajibkan build untuk mengikuti aturan label — nama agregat, lingkungan, nama penyedia, versi compiler dan penyedia — adalah label yang ditulis dalam bentuk yang diterima label, dan jika bentuk itu berbeda dari nilainya, nilai apa adanya juga menjadi anotasi di bawah kunci yang sama (Aggregate bernama imported/flow diberi label imported-flow dan anotasi imported/flow). Semua file yang membawa output dari Recipe yang sama berbagi provenans yang sama:
metadata: labels: aggrega.ai/component-id: api # ... plus the recommended app.kubernetes.io/name label annotations: aggrega.ai/recipe-uri: api-server-helm:1.0.0 aggrega.ai/boundary-path: productionPembagian ini seragam di ketiga jenis input. (Penyedia Compose tidak memiliki konsep anotasi dan nilai labelnya tidak dibatasi, sehingga ia menghasilkan seluruh kumpulan sebagai label layanan.) Lihat 11-governance-and-compliance.md untuk pembubuhan provenans saat kompilasi.
Karena penyedia membubuhkan provenans di tempat yang dimuat oleh format output-nya sendiri, penyedia yang formatnya tidak menyediakan tempat seperti itu untuk file tertentu menghasilkan file tersebut tanpa perubahan dan menyatakannya. Compose adalah kasus yang perlu diketahui: tempat provenansnya adalah blok labels: sebuah layanan, sehingga fragmen artefak compose yang hanya menyumbangkan volumes:, configs:, atau models: tingkat teratas tidak membawa provenans, dan build mengeluarkan peringatan “skipped provenance label injection (injeksi label provenans dilewati)” yang menyebut artefak tersebut. Peringatan itu wajar untuk fragmen dengan bentuk tersebut, bukan tanda adanya masalah — layanan yang dihasilkan komponen yang sama membawa kumpulan lengkap, dan tidak ada yang berubah pada byte yang dihasilkan. Yang dicegahnya adalah kemungkinan ketiga: file yang keluar dari build tanpa dibubuhi provenans tanpa disebutkan.
CloudFormation adalah kasus lain yang perlu diketahui, dan bedanya terletak pada di mana provenans ditempatkan, bukan pada apakah provenans ditempatkan. Template CloudFormation tidak memiliki blok metadata tingkat dokumen yang ikut bersama sumber daya, sehingga provenans ditempatkan pada atribut Metadata milik setiap sumber daya, di bawah satu kunci aggrega.ai/provenance yang memuat seluruh kumpulan:
"StoreBucket": { "Type": "AWS::S3::Bucket", "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/component-id": "store", "aggrega.ai/recipe-uri": "store-recipe:1.0.0", "aggrega.ai/boundary-path": "stack" } }}Tiga properti mengikuti dari tempat itu. Atribut Metadata tersedia pada setiap sumber daya apa pun tipenya, sehingga setiap sumber daya yang dibawa stack hasil perakitan dibubuhi provenans — termasuk banyak tipe sumber daya yang sama sekali tidak menerima tag, yang tidak akan memiliki tempat bagi pembubuhan berbasis tag. Pembubuhan ini ditambahkan ke Metadata apa pun yang ditulis penulis, bukan menggantikannya, sehingga entri milik penulis tetap ada di sampingnya. Dan karena dilakukan per sumber daya, bukan per template, stack yang dirakit dari beberapa komponen membawa identitas kontributor masing-masing sumber daya — komponennya, Recipe-nya, dan boundary-nya — yang tidak dapat diekspresikan oleh satu entri untuk seluruh template.
Seluruh kumpulan bergerak bersama di bawah kunci tersebut. Nilai Metadata adalah JSON tanpa batasan, sehingga tidak ada pembagian charset yang perlu dilakukan; dua kunci yang hanya dibaca runtime Kubernetes — nama label standar yang direkomendasikan dan anotasi urutan deployment yang dikonsumsi controller GitOps — tidak disertakan, karena keduanya tidak menamai apa pun dalam sebuah stack. Entri provenans biasa aggrega.ai/sync-wave tetap ada, karena entri itu mencatat wave yang dideklarasikan komponen, bukan memberi instruksi kepada controller.
Bentuk yang tidak memiliki tempat di sini adalah template atau fragmen yang tidak mendeklarasikan sumber daya — yang hanya menyumbangkan Parameters, Mappings, Conditions, atau Rules. Bentuk ini tidak membawa provenans, mencapai stack hasil perakitan dengan kontennya tetap utuh, dan build mengeluarkan peringatan “skipped provenance injection (injeksi provenans dilewati)” yang menyebutnya. Seperti pada compose, peringatan itu wajar untuk kontribusi dengan bentuk tersebut: sumber daya yang disumbangkan komponen yang sama di tempat lain membawa kumpulan lengkap, dan byte yang dihasilkan tetap sama, ada atau tidak ada yang mendengarkan.
Semantik artefak per Provider
Semantik per provider di bawah ini menjelaskan bagaimana setiap provider mengintegrasikan artefak ke dalam output native-nya.
provider helm: artefak adalah dokumen YAML Kubernetes yang ditulis di bawah direktori yang dinamai menurut komponen yang mendeklarasikannya, di dalam direktori output yang memuat manifes yang dirender dari chart dan disintesis dari Workload. Alasannya adalah penamaan: manifes yang dirender atau disintesis diberi nama oleh provider berdasarkan komponen tempatnya berada, sedangkan artefak diberi nama berdasarkan kunci yang ditulis oleh pembuatnya, yang tidak menyatakan apa pun tentang komponen mana itu — sehingga dua komponen yang terikat ke satu Recipe akan menulis satu jalur tanpa ada pembuat yang dapat memisahkannya. Direktori tersebut memakai nama komponen itu sendiri, sehingga file yang dibaca kembali oleh pembuat di output memiliki nama yang mereka tulis, satu tingkat lebih dalam.
Operator yang menginginkan tata letak berbeda dapat memakai template subDirectory: milik boundary, yang memindahkan setiap file yang dikeluarkan kontributor, bukan hanya artefaknya. Lihat ../language-reference/path-template-variables.md.
provider compose: artefak adalah fragmen compose. Kunci tingkat atas (services:, volumes:, configs:, models:) digabungkan ke dalam docker-compose.yaml gabungan per boundary selama langkah komposisi boundary.
provider helm-chart (kasus khusus): artefak tidak ditulis ke direktori output sebagai file mandiri — Helm memiliki pipeline render. Sebagai gantinya, provider helm-chart menempatkan setiap entri artifacts: di dalam chart itu sendiri, dan bentuk penulisan entri menentukan di mana entri itu berakhir. Setiap entri diproses sebagai template Go dengan konteks pilar Aggrega TERLEBIH DAHULU, sebelum penempatan apa pun; dari situ kedua bentuk berbeda jalan. Entri yang dimuat dengan $import: adalah file template pra-Helm: entri tersebut diinjeksikan ke direktori templates/ milik chart SEBELUM render Helm, sehingga Helm merendernya bersama template milik chart sumber. Skalar blok inline adalah file chart lepas: skalar tersebut ditempatkan di root chart di bawah kunci yang ditulis, tanpa prefiks templates/ dan tanpa label provenans yang digabungkan, sehingga template milik chart dapat membacanya melalui .Files.Get / .Files.Glob milik Helm — pola ConfigMap-dari-file. Ini memberi provider helm-chart mekanisme ekstensi yang setara dengan yang disediakan artifacts: untuk provider helm biasa, sambil tetap menghormati model chart Helm.
File yang diinjeksikan berakhir di boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — file-file sebuah bundle bersarang di bawah kunci tersebut — sehingga file itu berada di samping template chart sumber dan Helm mengambilnya selama tahap render berikutnya. Skalar blok inline berakhir di boundaries/<bp>/charts/<nodeID>/<authored-key> — root chart, satu tingkat di atas templates/ — karena file yang dibaca melalui .Files harus berada di tempat chart mencarinya, dan file yang ditempatkan di bawah templates/ justru dirender sebagai manifes. Kedua bentuk diberi nama menurut kunci tempat keduanya ditulis; yang membedakannya adalah direktori tempat provider menempatkannya.
Konvensi delimiter helm-chart. Tahap pra-template Aggrega pada entri artefak helm-chart, baik yang dimuat dengan $import: maupun yang inline, menggunakan delimiter [[ ]] alih-alih {{ }} bawaan, sehingga sintaks {{ ... }} milik Helm di dalam file tetap utuh hingga tahap render Helm. Penulis menulis substitusi sisi Aggrega sebagai [[ .context.instance_id ]], [[ .values.name ]], dan seterusnya; substitusi sisi Helm tetap sebagai {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }}, dan seterusnya. Mencampur kedua pasangan delimiter dalam satu file adalah bentuk penulisan yang didukung.
Provenans dan artefak helm-chart. Provenans digabungkan ke dalam metadata.labels dan metadata.annotations (sesuai pemisahan berdasarkan charset di atas) untuk file yang dimuat dengan $import: yang lolos round-trip YAML dengan token Helm tetap terjaga — file yang hanya memakai konteks Aggrega [[ ]] atau dengan {{ }} Helm hanya pada posisi skalar berkutip. File dengan aksi template Helm struktural ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} pada posisi tempat aksi tersebut menghasilkan struktur YAML alih-alih daun skalar), atau file dengan {{ ... }} tanpa kutip pada posisi nilai, tidak lolos round-trip YAML Aggrega; build mengeluarkan peringatan “skipped provenance label injection” (injeksi label provenans dilewati) yang menyebut nama artefak dan meneruskan file tanpa perubahan. Peringatan ini memang diharapkan untuk setiap file artefak helm-chart yang dimuat dengan $import: yang memakai aksi template Helm struktural atau substitusi nilai Helm tanpa kutip — ini adalah kasus umum dalam penulisan Helm di produksi, bukan kasus pinggiran. Penulis yang memerlukan label provenans pada file seperti itu menginjeksikannya melalui template bernama yang mereka tulis sendiri di _helpers.tpl milik chart (misalnya template bernama aggrega.commonLabels) atau mekanisme setara di sisi Helm, bukan melalui injeksi pra-template Aggrega.
Tabrakan nama file root chart. Artefak yang dimuat dengan $import: yang kunci tulisannya bertabrakan dengan nama file root chart (Chart.yaml, values.yaml, .helmignore, dan sebagainya) tidak terdeteksi oleh pemeriksaan tabrakan nama file Aggrega — artefak berakhir di templates/<authored-key> sementara file root berakhir di root chart, dan prefiks jalur membuat keduanya berbeda dari sudut pandang Aggrega. Penulis menghindari nama kunci tersebut; akibat memakainya adalah Helm melihat kedua file (satu di root chart, satu di dalam templates/) dan dapat merender salinan di sisi templates secara tidak terduga.
provider terraform: artefak adalah file konfigurasi Terraform, dikeluarkan apa adanya ke direktori milik komponen sendiri di bawah pohon modules/ milik boundary. HCL (main.tf) adalah default yang ergonomis dan Terraform JSON (.tf.json) diterima secara setara; keduanya tidak ditranspilasi maupun diformat ulang. Konfigurasi root boundary mendeklarasikan komponen tersebut sebagai blok module yang source-nya menunjuk ke direktori itu, sehingga seluruh boundary tetap menjadi satu graf dependensi; itu adalah direktori yang sama yang ditempati file-file modul yang di-vendor, sehingga Recipe yang mendeklarasikan source: dan artifacts: sekaligus menulis keduanya berdampingan. Provenans dibawa sebagai blok komentar Terraform di awal; ketika sebuah komponen menyumbangkan body JSON, yang tidak memiliki sintaks komentar, setiap body dikeluarkan tanpa perubahan dan provenans dibawa dalam file .tf pendamping yang hanya berisi komentar di sampingnya, sehingga cap tersebut tidak pernah terduplikasi di antara keduanya. Lihat halaman provider terraform.
provider cloudformation: artefak adalah fragmen stack — sumber daya yang disumbangkan satu komponen, bukan template utuh. Provider menormalkan setiap fragmen menjadi fungsi intrinsik bentuk panjang dalam JSON murni dan menggabungkannya ke dalam satu stack yang dirakit untuk direktori output tersebut, tempat sumber daya bergabung ke satu peta Resources dan provides komponen muncul sebagai Outputs stack di bawah nama yang dibatasi pada komponen penerbitnya. Bagian tingkat atas lain dari sebuah fragmen yang bertahan dalam perakitan dijelaskan di Apa yang dibawa dokumen gabungan dari artifacts:. Lihat halaman provider cloudformation.
Cakupan boundary: file untuk output bersama sebuah boundary
Mekanisme artefak memiliki cakupan kedua. Semua yang dijelaskan di atas ditulis ke posisi milik komponen sendiri dalam output boundary-nya; spec.boundary.artifacts milik sebuah Recipe adalah peta yang sama — tiga bentuk yang sama, aturan kunci-ke-nama-file yang sama, konteks template yang sama — tetapi ditulis satu kali untuk boundary secara keseluruhan. Cakupan ini ada untuk file yang dibaca target satu kali bagi semua yang di-deploy sebuah boundary, yang tidak dapat ditampung oleh posisi milik komponen mana pun: dokumentasi Terraform menyatakan bahwa modul yang dimaksudkan untuk dipanggil tidak boleh berisi blok provider, dan modul yang berisi blok tersebut tidak dapat dipanggil dengan depends_on, count, atau for_each, sehingga konfigurasi provider berada di konfigurasi root boundary, bukan di dalam modul sebuah komponen.
Tempat file berakhir. Di direktori yang memuat output rakitan grup dispatch, di samping file-file yang ditulis di sana oleh perakitan milik provider sendiri — untuk terraform, di samping konfigurasi root. Compiler mengevaluasi setiap entri satu kali per komponen yang dirender Recipe, terhadap konteks komponen tersebut, dan menulis file itu sendiri: provider tidak diberi satu pun file ini, dan tidak ada cap yang dibubuhkan ke dalamnya untuk menyatakan dari komponen mana file itu berasal, karena file itu milik setiap kontributor yang mendeklarasikannya.
Bagaimana kontributor bertemu. File yang dideklarasikan setiap kontributor pada satu grup dispatch digabungkan berdasarkan nama. Satu nama yang dideklarasikan dengan byte identik menjadi satu file; satu nama yang dideklarasikan dengan byte berbeda, atau nama yang ditulis sendiri oleh perakitan provider, menghentikan build dengan menyebut file tersebut dan setiap kontributornya — penolakan yang sama yang dialami dua kontributor yang menulis satu jalur output. Jadi konfigurasi provider yang dibutuhkan dua Recipes ditulis oleh keduanya dengan satu nama, dan build memeriksa bahwa keduanya sama.
Siapa yang menerimanya. Apakah file yang ditempatkan di samping output rakitan sebuah boundary bermakna adalah properti target provider, sehingga hal itu merupakan klaim provider sendiri, yang dibaca dari deklarasi provider itu sendiri seperti jenis input-nya. Recipe yang mendeklarasikan blok tersebut untuk provider yang tidak mengklaimnya ditolak sebelum apa pun dirender. Kisi di bawah memuat klaim ini sebagai kolom terakhirnya; di antara provider yang didistribusikan bersama compiler, terraform yang membuatnya.
Yang bukan merupakan artefak
Tiga perbedaan struktural:
Bukan lintas provider dalam satu Recipe. Sebuah Recipe mendeklarasikan tepat satu capability: di bagian atas spec-nya. Semua yang dihasilkan Recipe — output yang dirender dari source, output yang disintesis dari workload, dan keluaran artefak — berada dalam format native provider tersebut. Artefak Recipe helm berisi YAML Kubernetes. Artefak Recipe compose berisi fragmen compose. Sebuah Recipe menargetkan satu provider; setiap output berada dalam format native provider tersebut.
Komposisi multi-provider terjadi pada tingkat Release. Boundary menampung komponen dengan provider campuran; kontributor setiap provider pada jalur terevaluasi sebuah boundary di-dispatch dan dirakit secara independen per (jalur, provider). Sebuah Release dengan komponen yang masing-masing menargetkan helm, helm-chart, dan compose dapat menempatkan ketiganya dalam satu boundary; pengelompokan dispatch mempartisinya per provider, kontributor setiap provider berakhir di output rakitan masing-masing di bawah jalur boundary, dan operator menulis koordinasi lintas provider melalui struktur boundary yang dipilihnya. Koordinasi lintas provider adalah tanggung jawab penulis Release.
Bukan Recipes di dalam Recipes. Artefak tidak memuat atau menyusun Recipes lain. Artefak adalah manifes inline (atau jalur file ke manifes inline), diproses sebagai template dengan pilar Recipe ini, dan dikeluarkan ke output Recipe ini. Penggunaan ulang Recipe terjadi melalui tiga mekanisme: extends: milik Component (Recipe yang ditulis untuk Component dasar melayani setiap Component yang memperluasnya; yang diwariskan adalah metadata dan skema, bukan file output — Recipe sendiri tidak mendeklarasikan extends:); pemetaan URI datar milik Manifest (Component yang sama dapat diresolusikan ke Recipes yang berbeda di berbagai katalog — lihat ../language-reference/entities/manifest.md); serta Features + FeatureRecipes (kepentingan lintas sektoral yang dilampirkan secara ortogonal).
Bukan lapisan perekat lintas Recipe. Artefak tidak dapat mereferensikan nama, sumber daya, atau status yang tidak dideklarasikan sendiri oleh Recipe. Artefak ConfigMap yang direferensikan oleh Workload milik Recipe harus dikeluarkan oleh Recipe ini. Artefak yang mengharapkan Secret yang disediakan secara eksternal harus mendapatkan nama Secret tersebut melalui pilar .features — dari provides yang telah diresolusikan milik attachment yang mengeluarkannya — bukan mengasumsikan Secret itu ada. Ini adalah invarian keswadayaan (di atas) yang dinyatakan dari sudut pandang penulisan artefak: setiap Recipe mengeluarkan file dalam satu format, diterapkan oleh satu alat, ke direktori output satu boundary.
Matriks kapabilitas Provider
Setiap provider mendeklarasikan jenis input yang direndernya; sebuah gate jenis input terpusat menerima kombinasi yang didukung dan menolak sisanya dengan diagnostik yang seragam saat node dirender. Kapabilitas adalah properti provider, bukan Recipe — sebuah provider merender subset dari tiga jenis tersebut. Kolom artifacts: membedakan artefak yang menyertai di samping input utama sourced/synthesized dari Recipe mandiri yang hanya berisi artefak (tanpa source:, tanpa workload:). Dua kolom terakhir adalah klaim provider bahwa ia mematuhi omits: dan bahwa ia menerima file yang disumbangkan sebuah Recipe ke output bersama boundary-nya di bawah boundary.artifacts: (di atas); keduanya bukan jenis input.
Baca setiap kolom secara terpisah. Sebuah baris menyatakan jenis mana yang dirender provider jika diambil satu per satu. Baris itu tidak menyatakan bahwa dua jenis yang dicentang boleh dideklarasikan bersama. Karena jenis-jenis tersebut tersusun secara aditif, setiap jenis yang dideklarasikan di-dispatch dan dikeluarkan secara terpisah, sehingga sebuah pasangan dapat ditolak karena alasan yang tidak dimuat oleh kedua kolom tersebut — paling sering karena kedua jenis menghasilkan file dengan nama output yang sama. Kombinasi mana yang benar-benar diterima setiap provider dijelaskan dalam prosa di Apa yang diterima setiap provider, selengkapnya.
| Provider | source: + valuesMapping: | workload: | artifacts: (di samping) | hanya artefak (mandiri) | omits: | boundary.artifacts: |
|---|---|---|---|---|---|---|
| helm | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| compose | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| helm-chart | ✅ | ❌ | ✅ diproses sebagai template dengan delimiter [[ ]] | ❌ | ❌ | ❌ |
| terraform | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| cloudformation | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
Kisi ini mencakup provider yang didistribusikan bersama compiler. Provider yang disediakan secara terpisah mendeklarasikan jenis input yang diterimanya, apakah ia mematuhi omits:, dan apakah ia menerima boundary.artifacts: dengan cara yang sama, dan compiler membaca deklarasi itu melalui jalur yang sama — provider tersebut tidak tercantum di sini, karena halaman yang diterbitkan tidak dapat mendaftar provider yang belum pernah dilihatnya.
Sel yang ditandai ✅ di-render; ❌ adalah penolakan kapabilitas provider yang dimunculkan oleh gate. Fragmen compose per node digabungkan per jalur perakitan, sehingga boundary yang berbagi directory: berbagi satu file.
Apa yang diterima setiap provider, selengkapnya
helm — setiap kombinasi. source: + valuesMapping:, workload:, artifacts:, dua di antaranya, atau ketiganya. Ini satu-satunya provider yang didistribusikan bersama compiler yang tidak menolak kombinasi apa pun, dan alasannya adalah cara ia menamai output: setiap file yang dikeluarkan dinamai menurut sumber daya di dalamnya, sehingga manifes yang dirender dari sebuah chart dan manifes dari Workload yang disintesis tidak pernah berakhir pada satu nama. Recipe yang mendeklarasikan ketiganya mengeluarkan file chart, file Workload, dan file artefak berdampingan di direktori output boundary.
compose — setiap kombinasi kecuali dua kombinasi yang memuat source: dan workload: bersama-sama. Setiap jenis secara terpisah dapat di-build, dan artifacts: dapat menyertai salah satunya. source: dengan workload: tidak dapat di-build, begitu pula ketiganya bersama-sama; Mengapa compose tidak dapat menggabungkan source dengan workload menjelaskan alasannya, dan itu bukan penolakan kapabilitas.
helm-chart — source: + valuesMapping:, sendiri atau dengan artifacts: di sampingnya. Tidak ada yang lain. Provider ini tidak menyintesis workload:, dan tidak memiliki bentuk yang hanya berisi artefak: Recipe yang satu-satunya jenis input-nya adalah artifacts: akan berhenti. Alasannya adalah tempat provider ini menaruh artefak — di dalam chart milik komponen sendiri — sehingga Recipe tanpa source: tidak menyisakan chart untuk menaruhnya.
terraform — tiga bentuk: source: + valuesMapping: saja, artifacts: saja, atau keduanya bersama. Provider ini tidak menyintesis workload:.
cloudformation — tiga bentuk yang sama dengan terraform, dengan satu pengecualian yang sama. source: + valuesMapping: saja, artifacts: saja, atau keduanya bersama; tanpa workload:.
Seperti apa jenis input yang ditolak
Recipe yang mendeklarasikan jenis input yang tidak dirender oleh provider terikatnya menghentikan build saat node dirender, dan menghentikannya apa pun yang dideklarasikan Recipe di samping jenis tersebut — memasangkan workload: dengan source: yang dapat dirender provider tidak membuat workload tersebut lolos. Penghentian itu menyebut provider, jenis yang tidak dapat direndernya, dan jenis yang direndernya:
[CATALOG_ERROR E0265] instance unit provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesizedPenolakan bentuk yang hanya berisi artefak terbaca dengan cara yang sama dan menyebut bentuk tersebut: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 adalah pengenal yang perlu dicatat ketika penghentian ini perlu dinamai secara tetap — dalam gate continuous integration, issue, atau runbook; tabel setiap kondisi menguraikannya.
Mengapa compose tidak dapat menggabungkan source dengan workload
Provider compose menghasilkan satu fragmen per komponen dan menamai fragmen itu menurut komponennya. Render dari source dan sintesis Workload masing-masing menghasilkan fragmen komponen tersebut dengan satu nama itu, sehingga Recipe yang mendeklarasikan keduanya menghasilkan dua file dengan nama yang sama, dan build berhenti karena tabrakan tersebut:
[CATALOG_ERROR E0211] instance unit rendering node "unit" caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")Nama fragmen berasal dari pengenal milik komponen sendiri dan tidak ada permukaan penulisan untuknya, sehingga tidak ada perubahan pada konten Recipe yang dapat menghindari tabrakan tersebut. Penghentian ini adalah properti pasangan, bukan salah satu jenis — compose merender source, compose menyintesis Workload, dan kisi tersebut benar mencentang keduanya. Untuk memakai kedua bentuk bagi satu komponen di bawah compose, pisahkan keduanya ke dua komponen, atau masukkan konten source ke dalam Workload.
Apa yang dibawa dokumen gabungan dari artifacts:
Dua provider menggabungkan kontributornya ke dalam satu dokumen per jalur perakitan: compose ke dalam satu docker-compose.yaml, cloudformation ke dalam satu template stack. Dokumen gabungan hanya dapat membawa bagian yang dimodelkan oleh perakitnya, sehingga centang artifacts: menyatakan di mana konten sebuah fragmen ditempatkan, bukan bahwa setiap kunci di dalam fragmen tersebut bertahan.
compose membawa services:, volumes:, configs:, dan models: dari fragmen artefak, beserta kunci ekstensinya yang berprefiks x-. Fragmen yang mendeklarasikan apa pun selain itu di tingkat atas menghentikan build dengan menyebut kuncinya — networks:, karena jaringan diturunkan per boundary alih-alih dikumpulkan dari kontributor, dan demikian pula blok secrets: atau name: tingkat atas. Halaman provider compose memberikan aturan penggabungan per kunci dan alternatif untuk routing lintas jaringan.
cloudformation membawa Resources, Outputs, Parameters, Mappings, Conditions, Metadata, dan Rules, serta membangun Transform dari milik setiap kontributor. Transform digabungkan dalam urutan yang didokumentasikan CloudFormation, dengan Globals milik SAM menyertai transform yang membacanya, dan transform yang akan mengubah cara konten kontributor lain di-deploy menghentikan build dengan menyebut namanya. Description tidak dibawa, dan build menyatakannya: build memunculkan peringatan bidang yang tidak didukung yang menyebut bagian dan komponen tersebut, sama seperti untuk kunci tingkat atas lain yang tidak dibawa stack, sehingga tidak ada yang dibuang secara diam-diam. Peringatan ini bersifat saran — template yang dikeluarkan identik byte demi byte dengan yang dihasilkan tanpanya, dan --no-unsupported-field-warnings membungkam kelas tersebut. Outputs dibawa dengan nama yang dibatasi provider pada komponen penyumbangnya, sehingga dua komponen yang menyumbangkan output bernama sama ke satu stack tetap memisahkannya. Bagian tingkat atas dalam stack rakitan menjelaskan setiap bagian satu per satu.
Tiga provider lainnya tidak menggabungkan, sehingga tidak ada kunci artefak yang berisiko dibuang oleh perakit. helm tidak merakit apa pun: manifes setiap komponen mencapai direktori output boundary apa adanya. terraform dan helm-chart menyarangkan — file setiap komponen berakhir di direktori miliknya sendiri, direktori modul Terraform atau subchart, dan dokumen root di boundary mereferensikannya — sehingga entri artefak ditempatkan sebagai file utuh alih-alih dibaca ke dalam dokumen bersama. Tempat entri artefak helm-chart berakhir, dan mengapa pasangan delimiter-nya berbeda, dijelaskan di Semantik artefak per Provider.