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

Recipe

Peran konseptual entitas Recipe (templat terjemahan yang ditulis oleh Ops untuk memetakan Developer Intent ke dalam format fisik) dijelaskan di architecture/04-entity-taxonomy.md. Halaman ini membahas permukaan penulisan Recipe — penunjuk (source), pemeta (valuesMapping:), dukungan IaC native, dan contoh-contoh lengkap.

Arsitektur Recipe: pointer dan mapper

Sebuah Recipe menjalankan tepat dua fungsi:

  1. Pointer (source): Memberi tahu compiler secara tepat di mana kode infrastruktur berada.
  2. Mapper (valuesMapping): Menyuntikkan konteks abstrak Aggrega ke dalam variabel spesifik yang diharapkan oleh kode di bawahnya. Field ini adalah satu permukaan Go template dengan tiga mode penulisan — block scalar inline, $import: file, atau $import: library — yang dipilih berdasarkan bentuk kontennya. Lihat Field valuesMapping — tiga mode penulisan di bawah.

Karena sebuah Recipe berpasangan secara ketat 1:1 dengan satu kapabilitas render, kapabilitas tersebut (spec.capability) dideklarasikan secara eksplisit di tingkat root, sehingga compiler Go mengetahui secara tepat plugin rendering Wasm hilir mana yang harus dipanggil.

spec.implements mendeklarasikan tipe component katalog mana yang dapat diimplementasikan oleh Recipe. Compiler menggunakannya untuk memverifikasi pemetaan Manifest (implements dari Recipe yang dipetakan harus cocok dengan tipe yang dipetakan) dan untuk menyarankan kandidat — recipe yang dicantumkan dalam diagnostik tanpa pemetaan dan diberi peringkat pertama dalam pelengkapan editor. Field ini tidak pernah menentukan build: pemetaan Manifest adalah pilihan deployment eksplisit pengguna, yang dipatok dalam lockfile. Recipe yang implements-nya tidak berversi, eksak, atau berupa rentang yang kompatibel secara major tetap hanya menawarkan dirinya untuk suatu tipe; penggunalah yang mematok pilihannya. FeatureRecipe.spec.implements memiliki peran yang identik untuk tipe feature.

A. Skema source berbasis Wasm

Agar bias implementasi tidak masuk ke compiler, blok source bukanlah sekumpulan field infrastruktur yang tetap. Field source mendukung dua format:

  • String universal (cepat & bersih): Paling cocok untuk path lokal, artefak OCI, dan repositori Git. Compiler menyimpulkan metode pengambilan dari prefiks dan sufiks string (./src, https://github.com/example/module.git, oci://...): URL yang diakhiri .git, atau ditulis dengan git:// atau ssh://, adalah repositori Git yang diambil pada branch default-nya, dan URL https:// yang tidak menunjuk repositori maupun chart .tgz atau fragmen .yaml ditolak karena ambigu.
  • Objek terstruktur terbuka: Sebuah dictionary terbuka (additionalProperties: true) yang key-nya didefinisikan oleh provider dan diekspos ke template Recipe sebagai .source.* (misalnya .source.chart). Maksud desainnya adalah bahwa socket WebAssembly setiap provider mendefinisikan dan memvalidasi bentuk source-nya sendiri (misalnya registry/chart/appVersion untuk Helm).

Apa yang diselesaikan inti. Tidak ada provider yang memvalidasi kunci source miliknya sendiri. Source yang diambil diselesaikan oleh identitas bawaan yang kind-nya memilih resolver — helm-oci-chart, helm-https-chart, compose-https-fragment, dan git-repository. Source yang dimaksudkan untuk diambil harus memuat kind dan url; koordinat tambahan mana yang memilih konten bergantung pada kind-nya. Kind chart dan fragment menerima version, dan mematoknya sebagaimana ditulis. git-repository menerima ref — sebuah tag, branch, atau commit — dan secara opsional module_subdir, yang menamai direktori di dalam repositori yang menjadi artefaknya; karena hanya commit yang menamai konten yang tidak dapat diarahkan ulang, referensi diselesaikan pada waktu lock dan lockfile mencatat baik referensi yang ditulis maupun commit hasil penyelesaiannya. module_subdir yang naik ke atas repositori sebagaimana ditulis — backslash dihitung sebagai pemisah — ditolak sebelum apa pun diambil. Repositori diarsipkan dari checkout-nya sendiri: symbolic link yang di-commit di dalamnya diarsipkan sebagai file atau direktori yang ditunjuknya jika itu berada di dalam repositori, dan link yang mengarah ke luar repositori menghentikan pull, dengan menyebut link tersebut menurut tempatnya di repositori. Source terstruktur yang url:-nya menamai path filesystem tidak diambil: source tersebut dibaca dari disk dengan ketentuan yang sama seperti string path biasa, dengan url: relatif yang berpangkal pada direktori yang memuat file entitas yang mendeklarasikannya. Source terstruktur yang tidak mencantumkan kind/url juga tidak diambil, dan jika pengambilan dimaksudkan, build berhenti secara jelas pada penelusuran source waktu lock alih-alih diam-diam menghasilkan kekosongan. Konten selalu dipatok secara ahead-of-time; compiler tidak pernah mengambil state runtime secara langsung.

Apa yang dipatok di samping Recipe. Untuk source yang diambil yang kind, url, chart, module_subdir, version dan ref-nya semuanya ditulis langsung alih-alih menggunakan template, aggrega pin mencatat digest dari apa yang diambilnya dalam entity.lock, sebuah file di direktori Recipe itu sendiri yang Anda commit di sampingnya. Pematokan adalah langkah penulis Recipe, dan tidak memerlukan Release; pull atas Recipe yang lock-nya tidak mencatat pin akan berhenti dan menyebutkannya, kecuali pull diminta menjalankan langkah yang sama. Build membandingkan digest tersebut dengan digest yang dicatat lockfile Release untuk source yang sama, dan berhenti jika keduanya tidak cocok — kecuali untuk source yang ditulis pada ref: git, yang barisnya dicatat pada commit hasil penyelesaian ref tersebut dan tidak dibandingkan. Source yang diambil yang koordinatnya diisi dari template dipatok per Release sebagai gantinya, dalam lockfile setiap Release. Source yang menamai direktori atau file di samping Recipe tidak diambil: aggrega pin mencatat satu digest per file yang disumbangkannya ke apa yang dibawa oleh publikasi Recipe — setiap file di direktori Recipe, untuk source yang ditulis sebagai template — dan setelah lock mencatatnya, build membandingkan source dengannya sebelum provider membacanya, dan berhenti pada file yang ditambahkan, diubah, atau dihapus sejak pin — dengan E0305, atau lebih dulu dengan E0130 jika lockfile Release, yang ditulis sebelum perubahan, mencatat Recipe menurut apa yang dibawanya. Lock yang tidak mencatat pin untuk source seperti itu tidak memberi build apa pun untuk dibandingkan, dan pull atau publikasi yang tidak mematok akan menolaknya. File Recipe itu sendiri tidak pernah ditulisi. aggrega pull menjelaskan file tersebut dan cara menanggapi setiap penghentian.

spec.capability dapat membawa pin versi dalam bentuk yang diterima implements — persis (helm:<version>) atau rentang caret (helm:^<version>) — yang memilih versi plugin provider mana yang me-render Recipe; pin yang tidak dipenuhi versi tersedia mana pun menghentikan build. Tanpa pin (spec.capability: "helm"), versi tersedia tertinggi yang me-render-nya. Versi yang tersedia adalah yang ditampilkan aggrega plugin list: provider yang dibangun ke dalam aggrega membawa versi compiler itu sendiri. Pin bukan bagian dari nama Recipe: Manifest memetakan Recipe yang mendeklarasikan capability: "compose:1.2.3" sebagai compose/<name>:<version>, persis seperti yang tidak di-pin, dan mengubah pin tidak pernah mengganti namanya; nilai pemetaan yang menulis pin ke dalam nama (compose:1.2.3/<name>:<version>) ditolak sebagai referensi recipe yang salah bentuk (E0095) sebelum apa pun dicari.

Model mental: spec.capability menamai format output yang Anda inginkan (misalnya helm, terraform, compose); compiler menyelesaikannya ke plugin Wasm yang me-render format tersebut (misalnya provider/helm). Anda mendeklarasikan formatnya; Aggrega mengikat alatnya.

B. Injeksi konteks: lapisan pemetaan semantik

Untuk mencegah compiler melakukan deep-merge yang berbahaya dan non-deterministik di berbagai lingkungan, sebuah Recipe hanya mengizinkan satu sumber kebenaran tunggal untuk lapisan pemetaannya.

Engineer Ops menulis konten pemetaan untuk menerjemahkan konteks abstrak sebelum plugin rendering Wasm dijalankan. Bahasa pemetaannya adalah Go template (text/template + Sprig); pustaka Sprig sudah terdaftar sebelumnya; action standar define dan template didukung, dan include tidak terdaftar.

Nama fieldCakupan dan fase eksekusiKasus penggunaan terbaik
injectMapping (khusus FeatureRecipe)Intersepsi pra-render. Dievaluasi di memori Go sebelum Recipe dasar. Secara native melakukan deep-merge dictionary keluarannya secara ketat di atas pipe .context.inject milik pemanggil. Sengaja tidak ada dalam skema Recipe dasar — lihat entities/featurerecipe untuk alasan arsitekturalnya.Menulis ulang secara presisi variabel env yang diinjeksikan atau memformat FQDN untuk pemanggil tanpa memerlukan Wasm JSONPatch.
valuesMappingRendering dasar (Go template). Dievaluasi untuk memetakan variabel ke chart/modul infrastruktur source yang mendasarinya. Satu field, tiga mode penulisan (inline, file $import:, pustaka $import:). Lihat subbagian di bawah untuk mekanisme dispatch-nya.Memetakan variabel standar (seperti replika atau tag image) ke dalam chart Helm langsung di YAML Recipe, atau mereferensikan template bersama melalui $import: untuk penggunaan ulang lintas Recipe.

Catatan: injectMapping eksklusif untuk FeatureRecipes dan memisahkan intersepsi variabel dari valuesMapping. valuesMapping milik Recipe dasar mengonsumsi, tanpa mengetahuinya, string .context.inject yang telah ditulis ulang oleh blok injectMapping FeatureRecipe, sehingga keduanya tetap terpisah.

Kunci yang ditulis valuesMapping sebagai null sampai ke provider sebagai null, dan apa yang dilakukannya di sana ditentukan oleh provider, sehingga setiap halaman provider menyatakannya: helm menghapus nilai default chart untuk kunci tersebut, helm-chart menuliskannya ke dalam values umbrella, compose menuliskannya ke dalam file compose, terraform menuliskannya sebagai argumen modul null, dan cloudformation menolaknya.

Field valuesMapping — tiga mode penulisan

valuesMapping: milik sebuah Recipe adalah satu permukaan Go template yang menerima tiga mode dispatch. Compiler melakukan dispatch berdasarkan bentuk konten field tersebut; anotasi $mode: tidak diperlukan.

Mode 1: Go template inline (block scalar YAML). Nilai field adalah string yang ditulis dalam bentuk block scalar YAML |:

spec:
valuesMapping: |
{{- with .values -}}
image:
tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }}
pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }}
architecture: {{ optional . `architecture` "standalone" }}
primary:
replicaCount: {{ optional .primary `replicaCount` 1 }}
{{- end }}

Mode inline adalah bentuk penulisan yang lazim untuk Recipes yang konten pemetaannya berukuran kecil hingga sedang (di bawah ~50 baris). Isi template berada inline bersama bagian lain dari envelope Recipe; konten Recipe bersifat mandiri.

Mode 2: File $import:. Nilai field adalah map yang hanya berisi $import: dengan path file lokal:

spec:
valuesMapping:
$import: ./mappings/api-server.tmpl

Compiler memuat konten file tersebut (sebuah Go template), me-render-nya terhadap konteks template Recipe standar, dan memperlakukan hasilnya sebagai keluaran pemetaan. Resolusi path bersifat relatif terhadap direktori Recipe — path relatif ditambatkan ke direktori yang berisi recipe.yaml yang mendeklarasikannya, bukan ke direktori tempat build dijalankan — dan path harus tetap berada di dalam direktori tersebut, sebagaimana dijelaskan dalam Path konten tetap berada di dalam direktori milik Recipe sendiri. Mode file cocok untuk konten pemetaan berukuran sedang hingga besar (~50+ baris) dan pola review yang menampilkan perubahan pemetaan sebagai diff file tersendiri.

Mode 3: Pustaka $import:. Nilai field adalah map yang hanya berisi $import: dengan referensi identitas nama polos ke sebuah entri MappingLibrary:

spec:
valuesMapping:
$import: DatastoreHelpers#/mappings/MariaDBCore

Compiler me-resolve referensi tersebut terhadap himpunan MappingLibrary yang telah di-resolve (katalog lokal ditambah pustaka apa pun yang di-pin dalam lockfile), memuat konten entri, dan memperlakukannya sebagai keluaran pemetaan; entri yang isinya sendiri berupa $import: di root field di-resolve secara rekursif. Referensi tidak membawa host registry — nama pustaka di-resolve berdasarkan identitas dan versinya berasal dari lockfile per Release, dengan batas bawah versi minimum :<version> yang opsional (<Library>:<version>#/mappings/<entry>). Konten pustaka berbagi konteks template Recipe standar. Mode pustaka cocok untuk penggunaan ulang lintas Recipe — pola pemetaan yang berulang di banyak Recipes (beberapa Recipes datastore yang berbagi logika helper datastore; beberapa Recipes provider Helm yang berbagi pola pod-template). Entitas MappingLibrary menyediakan pemversian, pinning lockfile, dan penampilan di UI hub.

Aturan dispatch. Compiler menelusuri node YAML dan melakukan dispatch berdasarkan bentuk konten:

  1. Jika node adalah string scalar, lakukan dispatch sebagai mode inline (Mode 1).
  2. Jika tidak, node adalah map; periksa kunci $import:.
  3. Jika nilai $import: adalah referensi pustaka nama polos (<Library>#/mappings/<Entry>, opsional dengan batas bawah :<version>), lakukan dispatch sebagai mode pustaka (Mode 3).
  4. Jika tidak (path file lokal), lakukan dispatch sebagai mode file (Mode 2).
  5. Bentuk lain apa pun (map tanpa $import:, map dengan kunci tambahan selain $import:, dan sebagainya) menghasilkan error saat build.

Hanya $import: satu sumber. $import: menerima satu sumber. Penggabungan multi-sumber tidak didukung pada valuesMapping:. Recipe yang perlu menyusun beberapa fragmen pemetaan menggunakan entri MappingLibrary dengan komposisi Go template define / template internal, file lokal dengan direktif Go template template yang memanggil file sejajar, atau komposisi inline untuk konten pendek. Lihat entities/mappinglibrary untuk entitas pustaka, dan vocabulary/cross-document-ref untuk perbedaan $ref: / $import: yang lebih luas.

Provenans. Pesan error dari kegagalan rendering template mengutip provenans yang sesuai per mode: template inline mengutip file:baris Recipe tempat block scalar dimulai; impor file mengutip konten file yang diimpor; impor pustaka mengutip posisi sumber entri MappingLibrary, dengan identitas pustaka tanpa host (<Library>#/mappings/<entry>) sebagai penunjuk kanonis untuk referensi yang stabil — host registry dalam referensi ditolak, sehingga lokasi fisik tidak pernah masuk ke penunjuk.

C. Dukungan IaC native

Tim Ops yang membawa infrastructure-as-code miliknya sendiri menyimpannya di direktori milik Recipe itu sendiri — direktori modul atau templat seperti ./src, yang disebut oleh source: — atau mengambilnya dengan source: terstruktur (modul Terraform dari repositori git-nya, dengan kind: git-repository), atau menuliskannya sebagai isi bertemplat di bawah artifacts:. Lapisan pemetaan (valuesMapping: — inline, impor file, atau impor pustaka) menyediakan konteks abstrak bagi kode tersebut, dan provider mengeluarkan hasilnya dalam format milik target itu sendiri; tidak ada bahasa konfigurasi yang dikonversi menjadi bahasa lain:

  1. Terraform: sebuah modul di-vendor file demi file, dan isi yang ditulis dikeluarkan persis sebagaimana ditulis, baik HCL native (main.tf) maupun Terraform JSON (.tf.json) — CLI terraform membaca keduanya. Konfigurasi root boundary, aggrega.modules.tf, memanggil direktori setiap komponen sebagai blok module, dan output valuesMapping: dari modul bersumber menjadi argumen blok tersebut. Lihat provider terraform.
  2. CloudFormation: templat bersumber, YAML atau JSON, dan fragmen resource yang ditulis Recipe dinormalisasi menjadi JSON bentuk panjang dan digabungkan menjadi satu templat stack per boundary, dengan output valuesMapping: mengisi parameter yang dideklarasikan templat bersumber. Lihat provider cloudformation.

Nilai yang baru ada setelah infrastruktur diterapkan tetap menjadi penunjuk yang di-resolve oleh target — interpolasi Terraform ${ ... }, Ref atau Fn::GetAtt CloudFormation — dan tidak pernah dievaluasi pada waktu build.

Contoh A: Chart Helm jarak jauh (pemetaan inline & kontrak locals)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-chart
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
# The shipped fetch form: { kind, url, version }. 'kind' selects a built-in
# resolver (helm-oci-chart, helm-https-chart, compose-https-fragment).
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
# Default chart version. Override via infra.source_version.
version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals:
primary_compute: mariadb
listen_port: "3306"
volumes_path: "/spec/template/spec/volumes"
root_path: "/-"
# The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm
# pipeline: the suffix it follows the rendered name with. A local cannot read
# .context.rendered_name, so each template writing the full name joins the two.
secret_target_db_password: "mariadb-auth"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
# Every key the Component's provides contract declares is published
user: "{{ .values.user }}"
database: "{{ .values.database }}"
protocol: "mariadb"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"
auth:
# Reads the suffix from the local rather than restating it, so the secret
# name is authored once and every reader follows that one definition
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"

Contoh B: Modul Terraform lokal (pemetaan file)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-s3-tf
version: 1.0.0
spec:
capability: terraform
implements: aws/s3-bucket:1.0.0
source: "./src"
locals:
primary_compute: bucket_instance
resource_path: "/resource/aws_s3_bucket/main"
root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments
valuesMapping: |
bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"
region: "{{ .infra.aws_region }}"

Contoh C: Recipe Component konkret (mengikat infrastruktur) Ops memetakan antarmuka generik ke realitas fisik. (Di sinilah detail jaringan L4 diikat — baik ditulis langsung, atau, seperti port proxy di bawah, diambil dari blok infra yang diisi oleh Release.)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: kong-gateway
version: 1.0.0
spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
# A chart repository root paired with the chart's name.
kind: helm-https-chart
url: https://charts.konghq.com
chart: kong
version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides:
# The chart's proxy Service: it suffixes the name pinned below with "-proxy"
host: "{{ .context.rendered_name }}-proxy"
port: "{{ .infra.proxy_port }}"
protocol: "http"
# The contract's other keys: empty while nothing is wired to the models
# socket, and while metrics are off
endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}'
model: '{{ optional .values "model" "" }}'
metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Disiplin penamaan sumber daya cloud.

Recipes yang menghasilkan nama sumber daya cloud — nama bucket S3, pengenal basis data RDS, nama peran IAM, nama stack CloudFormation, dan bidang lain mana pun yang nilainya menempati namespace global di penyedia cloud — harus menggabungkan {{ .metadata.release_name }} dan/atau {{ .context.instance_id }} ke dalam nama yang dirender untuk menghindari tabrakan ketika Recipe yang sama dijalankan pada beberapa Releases atau instans komponen. bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" dari Contoh B adalah pola kanonisnya.

Disiplin ini berlaku di mana pun satu namespace global membatasi nama. Nama bucket AWS S3 berbagi namespace global di semua akun dalam satu region; dua Releases dari Aggregate yang sama (prod-billing dan staging-billing) tidak dapat sama-sama men-deploy bucket bernama customer-data — deployment kedua gagal saat runtime karena ditolak oleh AWS. Menggabungkan release_name membedakan Release; menggabungkan context.instance_id membedakan per instans komponen; menggabungkan keduanya membedakan per komponen per Release.

Apa yang diperiksa dan tidak diperiksa oleh compiler. Compiler tidak memeriksa keluaran valuesMapping: untuk mencari bidang nama sumber daya cloud tanpa interpolasi ini. Disiplin ini dijaga oleh penulis Recipe (yang tahu bidang mana yang menamai sumber daya unik global untuk penyedia target) dan peninjau (yang menangkap pola sumber daya tanpa nama saat peninjauan PR). Plugin linter dapat menandai Recipes yang keluaran valuesMapping:-nya merujuk bidang nama sumber daya cloud tanpa interpolasi release_name / instance_id; soket linter sudah tersedia dan berjalan melalui aggrega lint (lihat plugins/plugin-contract.md “Placement criterion: the linter socket vs the governance verdict roles”), dan tidak satu pun aturan linter publikasi yang memeriksa hal ini.

Disiplin ini adalah salah satu dari beberapa kontrak sosial yang dijaga oleh konvensi — disiplin penulisan yang dipelajari penulis dari dokumentasi, bukan dari penegakan oleh compiler. Lihat vocabulary/social-contracts.md untuk daftar lengkap konvensi dan alasan arsitektural klasifikasi setiap kontrak.

Templating bidang source. Bidang source milik Recipe juga merupakan permukaan templating. Kedua bentuk source menerima template Go: bentuk string universal

source: "{{ optional .infra `module_path` \"./src\" }}"

dan bentuk objek terstruktur (setiap sub-bidang bernilai string dievaluasi sebagai template; sub-bidang non-string diteruskan apa adanya). Apa yang dapat dibaca template source bergantung pada apakah source menamai artefak remote. Koordinat source remote — version, chart, ref, dan module_subdir dari blok terstruktur yang menamai registry, repositori chart, atau repositori git — dievaluasi ketika aggrega pull me-resolve artefak untuk mem-pin-nya, terhadap .values, .infra, dan .locals saja, dengan helper milik Aggrega sendiri (optional, capitalizedWords, dan index) dan tanpa fungsi Sprig apa pun. .context tidak ada pada permukaan itu, sehingga artefak mana yang di-pin untuk sebuah komponen ditentukan oleh values dan infra yang diberikan kepadanya dan tidak pernah oleh nama instansnya. Entri locals: yang dievaluasi di sana adalah entri yang dibaca bidang-bidang tersebut, beserta entri yang dibaca oleh entri itu secara berantai: entri yang tidak dibaca oleh bidang source mana pun tidak dievaluasi saat source di-resolve, sehingga local yang hanya dibutuhkan render — yang memanggil fungsi Sprig, atau membaca .context.instance_id — tidak memengaruhi pinning, dan dievaluasi saat node dirender. Bidang yang membaca .locals dengan cara yang tidak menamai satu entri tertentu, seperti {{ index .locals "version" }}, menyebabkan semua entri dievaluasi. Source yang menamai path di workspace, seperti contoh di atas, tidak di-resolve untuk pinning: templatenya dievaluasi saat node dirender, terhadap konteks mandiri yang sama dengan locals Recipe — .context.instance_id, .values, .infra, dan .locals, yaitu seluruh blok node yang telah di-resolve — sehingga ia menerima dan menolak akar referensi yang sama seperti entri locals:, dengan satu perbedaan yang menguntungkannya: ia dapat membaca entri apa pun yang dideklarasikan blok, bukan hanya entri di atasnya. Koordinat remote juga dapat membaca entri apa pun yang dideklarasikan blok. .provides tidak ada pada kedua konteks tersebut, dan template source yang menjangkau provides milik node-nya sendiri akan menghentikan build dan menyebutkan referensi yang bermasalah. Itu adalah sifat tetap dari permukaan ini, bukan kekurangan yang menunggu pekerjaan lanjutan — locals sebuah node di-resolve sebelum provides-nya agar provides: dapat membaca .locals, dan template source membaca locals yang telah di-resolve tersebut alih-alih menjangkau ke depan ke provides. Referensi ke .context.inject dan .context.uses dilarang atas dasar kemandirian yang sama; URI source harus ter-resolve sebelum pipe topologi dihidrasi dan sebelum apa pun di hilir memuat isi chart, modul, atau artefak yang ditunjuk URI. Aturan ketersediaan lengkap dan alasan referensi terlarang ada di Template Expansion Matrix baris #5. Penggunaan kanonisnya adalah override infra.source_version yang diekspos Component dan dialirkan ke bidang version milik source — lihat entities/component “Pilar infra” — sehingga katalog tidak perlu menerbitkan ulang Recipe pada setiap kenaikan versi upstream yang kompatibel.

Inventaris skema bidang source. Bidang source: menerima beberapa varian bentuk dalam skema. Dukungan runtime setiap varian berbeda per provider; tabel di bawah mendokumentasikan apa yang dilakukan setiap bentuk.

BentukContohStatus
Path filesystem relatif polossource: "./charts/postgres"available — setiap provider yang tersedia (helm, helm-chart, compose, terraform, cloudformation) menerima string path filesystem polos.
Path filesystem absolut polossource: "/abs/path/to/chart"accepted but blocked — skema menerimanya dan setiap perintah yang membaca Recipe menolaknya: path absolut menamai lokasi di mesin tempat ia ditulis, bukan konten di dalam direktori Recipe itu sendiri, sehingga ia tidak akan ikut berpindah bersama Recipe. Pindahkan chart ke direktori Recipe dan namai secara relatif terhadapnya; lihat Path konten tetap berada di dalam direktori Recipe itu sendiri.
String kosongsource: ""accepted but blocked — skema menerima string kosong dan setiap perintah yang memuat Recipe menolaknya saat Recipe dibaca, karena string kosong tidak menyebut mode mana pun. Penolakan itu menyebutkan ambiguitasnya beserta dua jalan keluarnya: hilangkan bidang tersebut untuk mode tanpa source, atau berikan path atau URI yang nyata untuk mode bersource. aggrega validate <recipe-file> melaporkannya untuk Recipe, dan aggrega pull, aggrega build, serta aggrega validate --release melaporkannya untuk Release yang menjangkau Recipe tersebut. Lihat errors/fatal-halts.md “Recipe source: is an empty string (Recipe source berupa string kosong)”.
Objek terstruktur yang url:-nya membawa skema transportsource: { url: "oci://…/mariadb", version: "25.0.8" }available — source-resolver bawaan membaca bentuk {kind, url, version, chart, ref, module_subdir} (skema url: memilih jenisnya — oci:// → chart OCI, https://….tgz → arsip chart, akar repo https:// yang dipasangkan dengan chart: → chart repo — atau sebutkan jenisnya dengan kind:), mengambil dan mem-pin artefak saat aggrega pull, dan build mengekstraknya dari cache. Menyimpan chart secara lokal (vendoring) didukung sebagai alternatif, dan tidak diwajibkan. Skema menerima objek terstruktur terbuka. Lihat providers/helm.md “Keyset source:”.
Objek terstruktur yang url:-nya menyebutkan path sistem berkassource: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" }available — url: yang tidak membawa skema transport menyebutkan sebuah path, sehingga tidak ada yang diambil dan tidak ada yang di-pin; build membaca konten dari disk. url: relatif dijangkarkan ke direktori yang memuat recipe.yaml yang mendeklarasikannya, dan yang keluar dari direktori itu — termasuk yang absolut — ditolak: pembacaan yang sama dengan dua baris path polos di atas, dan bentuk penulisannya tidak mengubahnya. Hanya url: yang menentukan dari mana konten dibaca; field lainnya memilih apa yang akan diambil, dan tetap sampai ke templat Recipe sebagai .source.*.
URI OCI (oci://...)source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0"planned — target desain untuk distribusi katalog. Resolver tiga tingkat saat ini (file yang disebut sebuah Release melalui path, katalog workspace, registry OCI jarak jauh) didokumentasikan di architecture/13-catalog-and-registry.md; resolver tingkat entitas mengonsumsi URI OCI melalui kaskade tersebut, tetapi bentuk OCI dari field source: per Recipe belum terhubung di provider saat ini.
Skema URL lain (https://, git+https://, dll.)(ilustratif)planned — didokumentasikan sebagai maksud desain dalam peta jalan source yang dapat dipasang pada arsitektur; belum ada dukungan provider saat ini.

Bagaimana path source: dijangkarkan. Penjangkaran berlaku untuk path sistem berkas dan tidak untuk yang lain, dan berlaku apa pun bentuk yang membawa path tersebut dari kedua bentuk itu. Path relatif dijangkarkan ke direktori yang memuat recipe.yaml yang mendeklarasikannya, dan path yang keluar dari direktori itu — termasuk path absolut — ditolak, sebagaimana dijelaskan di Path konten tetap berada di dalam direktori Recipe itu sendiri. Referensi yang membawa skema transport — oci://, https://, http://, git://, ssh://, git+ssh://, atau referensi apa pun yang berakhiran .git — menyebutkan sesuatu yang akan diambil, bukan path, sehingga diteruskan persis seperti yang Anda tulis dan tidak pernah digabungkan dengan direktori.

Dalam bentuk terstruktur, path-nya adalah field url:, dan dibaca dengan cara yang sama: url: relatif dijangkarkan ke direktori yang memuat recipe.yaml, yang keluar dari direktori itu ditolak, dan yang membawa skema transport diambil. Setiap field lain dari source: terstruktur diteruskan tanpa diubah, termasuk yang didefinisikan oleh provider.

source: yang ditulis sebagai templat dijangkarkan terhadap nilai yang dihasilkan templat, bukan terhadap teks templat itu sendiri. Templat tidak menyebutkan apa pun sampai dievaluasi, sehingga pembacaan di atas diterapkan pada hasilnya: hasil berupa path relatif dijangkarkan ke direktori yang memuat recipe.yaml, yang keluar dari direktori itu — termasuk path absolut — menghentikan build, dan yang membawa skema transport diteruskan dan diambil. Karena itu, templat bebas menghasilkan bentuk mana pun dalam inventaris di atas, dan masing-masing diperlakukan persis seperti nilai yang sama jika ditulis secara literal; perbedaannya hanya kapan path dapat dinilai, yang untuk templat adalah saat build mengevaluasinya, bukan saat Recipe dibaca.

Templat yang tidak menghasilkan apa pun — hasil kosong — membuat Recipe tanpa source, yaitu mode tanpa source. Hal itu berbeda dari menulis source: "" sendiri, yang tidak menyebutkan mode mana pun dan ditolak; lihat baris inventaris di atas.

Inventaris ini adalah rujukan kanonis tentang apa yang dapat dimasukkan penulis ke dalam source:; labelnya adalah label yang didefinisikan oleh 10-status.md.

Path konten tetap berada di dalam direktori milik Recipe itu sendiri

Konten sebuah Recipe berada di direktori milik Recipe itu sendiri, karena setiap file yang dibawa oleh publikasinya diambil dari sana. Setiap path yang ditulis sebuah Recipe untuk konten yang dibawanya — source: miliknya, baik berupa path polos maupun url: dari bentuk terstruktur, dan setiap file yang diimpor oleh entri valuesMapping:, workload:, dan artifacts: miliknya dengan $import: — dibaca terhadap direktori yang memuat recipe.yaml dan harus tetap berada di dalamnya. Path tersebut juga merupakan apa yang dibawa oleh sebuah publikasi: file yang dinamainya ikut berpindah bersama Recipe, dan tidak ada hal lain di direktorinya yang ikut (lihat aggrega push). Path yang keluar dari direktori menunjuk ke file yang tidak akan ikut berpindah bersama Recipe, sehingga file tersebut tidak tersedia bagi siapa pun yang mengonsumsinya, dan pin yang dicatat atasnya akan menjamin byte yang tidak dapat mereka peroleh.

Dua bentuk keluar dari direktori, dan keduanya ditolak:

  • path yang naik ke atasnya, seperti ../shared/charts/app;
  • path absolut, seperti /opt/charts/app, yang menamai suatu lokasi pada mesin tempat path itu ditulis.

Path yang naik lalu kembali ke dalam adalah path biasa di dalam direktori: ./charts/../values.tmpl menamai values.tmpl di samping Recipe. Yang dinilai adalah tempat path itu berakhir, diukur dari direktori Recipe tanpa keluar darinya — sehingga naik keluar yang menamai direktori itu lagi saat kembali, seperti ../1.0.0/values.tmpl yang ditulis di direktori bernama 1.0.0, juga ditolak. Nama direktori itu sendiri tidak ikut berpindah: Recipe yang dipublikasikan dibaca dari direktori yang dinamai oleh cache konsumen, tempat nama tersebut tidak menemukan apa pun.

Tempat penolakan terjadi. Setiap perintah yang membaca Recipe menolak path semacam itu saat membacanya, sebelum apa pun diambil, dirender, atau dipublikasikan: aggrega validate, atas katalog maupun atas file milik Recipe itu sendiri, aggrega pull, aggrega build, aggrega pin, dan aggrega push. source: yang ditulis sebagai templat tidak menamai apa pun sampai build mengevaluasinya, sehingga templat yang menghasilkan path di luar direktori ditolak oleh build, pada saat nilai tersebut ada. Penghentiannya adalah A path names content outside the entity’s own directory (Sebuah path menamai konten di luar direktori milik entitas itu sendiri), dan penghentian itu menyebutkan path yang Anda tulis.

Apa yang sebaiknya dilakukan. Letakkan file di direktori Recipe, atau di direktori di bawahnya, dan namai secara relatif terhadap Recipe: ./charts/app, ./extras/netpol.yaml. Chart yang digunakan beberapa Recipes disalin ke direktori setiap Recipe, karena setiap Recipe dipublikasikan secara tersendiri; isi mapping, workload, atau artifact yang digunakan bersama oleh beberapa Recipes ditempatkan dalam MappingLibrary, WorkloadLibrary, atau ArtifactLibrary, yang dirujuk setiap Recipe berdasarkan identitas.

Mengapa Release berbeda. Sebuah Release menunjuk ke entitas lain — Aggregate miliknya, Manifest miliknya, Release yang diperluasnya — dan tidak pernah dipublikasikan, sehingga tidak ada yang dibacanya berpindah ke mana pun. Rujukan tersebut, serta file yang diimpor oleh parameters: miliknya, dibaca sebagaimana ditulis, yang memungkinkan satu Aggregate digunakan bersama oleh varian Release di subdirektori. Lihat entities/release.md.

Batas yang sama berlaku untuk FeatureRecipe, dan untuk setiap skema yang diimpor oleh Component atau Feature.

Field workload: — jenis input yang disintesis

Recipe.spec.workload: mendeklarasikan isi Workload yang disintesis oleh compiler menjadi resource native provider. Field ini adalah salah satu dari tiga jenis input yang dapat dideklarasikan oleh sebuah Recipe, di samping source: (rendering bersumber) dan artifacts: (manifest tambahan). Setidaknya salah satu dari ketiganya harus ada pada setiap provider; layanan yang tidak disediakan oleh build mendeklarasikan workload: dengan form: reference.

Field ini menerima tiga mode penulisan — block scalar inline, $import: file, atau $import: library. Compiler memilih mode berdasarkan bentuk konten field; anotasi $mode: tidak diperlukan.

Mode 1: Inline (scalar string template Go). Nilainya adalah block scalar YAML yang output-nya di-parse sebagai aggrega.ai/v1beta1 Workload:

spec:
capability: helm
implements: core/web-server:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra "replicas" 1 }}
containers:
app:
image: "{{ .values.image }}"
ports:
http: 8080

Field sebuah Workload berada di root dokumen — tidak ada pembungkus spec: — dan containers: serta ports: milik setiap container adalah map dengan kunci nama, bukan sequence, dengan urutan penulisan tetap dipertahankan. Provider menerjemahkan bentuk tersebut ke bentuk native-nya sendiri, sehingga entri map container muncul dalam output render helm sebagai elemen containers[] yang dinamai sesuai kuncinya; bentuk yang ditulis adalah map, bukan daftar hasil render.

Mode 2: $import: file. Nilainya adalah map dengan satu kunci $import: yang menunjuk ke file template Go lokal:

spec:
workload:
$import: ./workload/web-server.yaml.tmpl

Resolusi path sama dengan valuesMapping:: path relatif ditambatkan ke direktori yang memuat recipe.yaml yang mendeklarasikannya, bukan ke direktori tempat build dijalankan, dan path tersebut harus tetap berada di dalam direktori itu. Isi yang diimpor adalah template Go yang dievaluasi dalam konteks render Recipe, persis seperti isi inline.

Mode 3: $import: library. Nilainya adalah map dengan satu kunci $import: yang memuat referensi identitas berupa nama polos ke sebuah entri WorkloadLibrary:

spec:
workload:
$import: BaseWorkloads#/workloads/StatelessService

Fragmen #/workloads/ adalah yang memilih entri Workload, dan fragmen inilah yang membedakan referensi ini dari bentuk #/mappings/ yang digunakan valuesMapping: — bentuk tersebut menunjuk entri MappingLibrary dan tidak menamai isi Workload. Referensi ini tidak memuat host registry, versi yang diresolusi berasal dari lockfile per Release, batas bawah versi minimum :<version> yang opsional dapat dinyatakan sebagai <Library>:<version>#/workloads/<Entry>, dan entri yang isinya sendiri berupa $import: di root field diresolusi secara rekursif. Isi yang diimpor adalah template Go yang dievaluasi dalam konteks render Recipe yang memakainya, sehingga .values, .infra, dan .features mengalir ke dalamnya persis seperti ke isi inline. Lihat entities/workloadlibrary untuk entitas library dan tata bahasa referensi lengkapnya.

Provider target harus mendukung sintesis (katalog pustaka standar mendeklarasikan workloadSchema pada provider semacam itu sesuai konvensi); menargetkan provider yang tidak dapat melakukan sintesis ditolak saat node dirender, dengan diagnostik kapabilitas provider — yang didasarkan pada kapabilitas provider, bukan pada keberadaan workloadSchema. Untuk tata bahasa Workload lengkap, field pass-through berbentuk K8s, dan perilaku penerjemahan per provider, lihat entities/workload.md. Untuk model tiga jenis input yang lebih luas dan assembler yang menggabungkan hasil sintesis dengan output hasil render source serta artefak, lihat architecture/16-recipe-input-composition.md.

Mengirimkan nilai milik komponen sendiri ke image milik pengembang sendiri. Sesuai konvensi katalog pustaka standar, Recipe yang menjalankan image yang dibangun oleh pengembang diharapkan mengirimkan apa pun yang telah diresolusi oleh blok inject: milik pengembang, dari .context.inject, dan juga dapat mengirimkan nilai milik komponen itu sendiri dengan nama-nama pilihannya sendiri. Jika Component mendeklarasikan spec.inject, blok milik pengembang sendirilah yang memilih nama-namanya, dan .context.self_inject memberi tahu Recipe satu nilai milik sendiri yang dibaca oleh templat setiap entri — values.<key> untuk entri yang membaca tepat satu nilai milik sendiri dan tidak membaca yang lain. Konvensi katalog pustaka standar adalah memperlakukan nama-nama yang diberikan Recipe untuk nilai-nilai tersebut sebagai default, bukan sebagai kontrak yang harus dibaca oleh kode pengembang, dengan mengirimkan sebuah nilai dengan nama default-nya hanya jika tidak ada entri yang dipetakan ke nilai tersebut; katalog perusahaan dapat memilih sebaliknya. Kontrak konteks templat memberikan aturan persis untuk map tersebut beserta contoh templat lengkap.

Field artifacts: — manifest tambahan

Recipe.spec.artifacts: adalah map dari nama entri → penulisan isi artefak yang entri-entrinya menghasilkan file manifest tambahan di samping keluaran utama Recipe yang bersumber atau disintesis. Ini adalah salah satu dari tiga jenis masukan (bersumber / disintesis / artefak) — sebuah Recipe dapat mendeklarasikan artifacts: saja, atau bersama workload: dan/atau source:.

Nilai setiap entri membawa salah satu dari tiga mode yang dipilih berdasarkan bentuk konten, sejajar dengan workload: — konten inline, $import: file, atau $import: pustaka. Compiler memilih mode berdasarkan bentuk konten nilai; anotasi $mode: tidak diperlukan. Kunci map menamai apa yang dihasilkan entri pada ketiga mode: untuk dua mode file tunggal, kunci adalah nama file keluaran, dan untuk mode bundel, kunci adalah direktori tempat file-file bundel ditempatkan. Karena kunci menamai keluaran, kunci dibatasi pada apa yang dapat menjadi satu nama file: huruf atau angka di awal, lalu huruf, angka, titik, tanda hubung, dan garis bawah. Titik mempertahankan ekstensi yang secara konvensi dibawa sebuah kunci — main.tf, template.yaml, serviceaccount.yaml — sedangkan alfabet ini tidak mengizinkan /, yang akan membuat sebuah kunci menamai path alih-alih file, dan tidak mengizinkan . di awal, sehingga kunci tidak pernah dapat menjadi segmen direktori induk. Kunci di luar alfabet tersebut gagal dalam validasi envelope saat workspace dimuat, saat aggrega validate, dan dalam diagnostik editor.

spec:
capability: helm
implements: core/web-server:1.0.0
artifacts:
extra-configmap.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: "{{ .context.instance_id }}-extras"
data:
threshold: "{{ .values.threshold }}"
network-policy.yaml:
$import: ./artifacts/network-policy.tmpl
operator-support:
$import: PlatformArtifacts#/artifacts/OperatorSupport

Mode 1: Inline (skalar string template Go). Nilainya adalah skalar blok, dan kunci map adalah nama file keluaran, digunakan sebagaimana ditulis — entri pertama di atas menghasilkan extra-configmap.yaml.

Mode 2: $import: file. Nilainya adalah map dengan satu kunci $import: yang menunjuk ke file template Go lokal, dan kunci map adalah nama file keluaran, persis seperti pada mode 1. File yang diimpor menyediakan konten; file tersebut tidak menyediakan nama. Entri kedua di atas berkunci network-policy.yaml dan menghasilkan network-policy.yaml, meskipun file yang diimpornya bernama network-policy.tmpl. Jadi, penulis yang menginginkan nama file keluaran tertentu menuliskannya sebagai kunci, dan dua entri yang mengimpor file berbeda yang kebetulan bernama sama — ./extras/shared.yaml dan ./overrides/shared.yaml — adalah dua keluaran yang berbeda. Resolusi path sama dengan valuesMapping: dan workload:: path relatif ditambatkan pada direktori yang memuat recipe.yaml yang mendeklarasikannya, bukan pada direktori tempat build dijalankan, dan path tersebut harus tetap berada di dalam direktori itu.

Mode 3: $import: pustaka. Nilainya adalah map dengan satu kunci $import: yang membawa referensi identitas nama polos ke sebuah bundel ArtifactLibrary, <Library>#/artifacts/<name>. Bundel adalah sekumpulan file yang diimpor sebagai satu unit, sehingga satu entri diperluas menjadi satu keluaran per file dalam bundel, masing-masing ditempatkan di bawah kunci map sebagai <key>/<filename> — kunci menamai lokasi pemakaian dan merupakan direktori tempat file-file tersebut berada, bukan nama salah satu file. Entri ketiga di atas berkunci operator-support; jika PlatformArtifacts#/artifacts/OperatorSupport mendeklarasikan crd.yaml dan rbac.yaml, entri tunggal itu menghasilkan operator-support/crd.yaml dan operator-support/rbac.yaml. Referensi tidak membawa host registry — bentuk oci://… yang memuat host ditolak — versi yang diresolusi berasal dari lockfile per Release, dan batas bawah versi minimum :<version> yang opsional dapat dinyatakan sebagai <Library>:<version>#/artifacts/<name>. Lihat entities/artifactlibrary untuk entitas pustaka dan tata bahasa referensi lengkap.

$import: file dipin di samping Recipe. aggrega pin mencatat digest byte setiap file yang diimpor dalam entity.lock di direktori Recipe, dengan kunci berupa kunci map entri, dan aggrega build menghitung ulang digest file tersebut dan berhenti dengan [CATALOG_ERROR E0026] ketika digest tidak lagi cocok — atau lebih dahulu dengan E0130 jika lockfile Release, yang ditulis sebelum pengeditan, mencatat Recipe berdasarkan apa yang dibawanya — sehingga file yang diedit setelah dipin tidak pernah dirender tanpa verifikasi. Jika perubahan itu disengaja, jalankan aggrega pin pada Recipe untuk mencatat digest baru; jika tidak, pulihkan file tersebut. Entri inline adalah bagian dari file Recipe, dan entri pustaka dipin oleh versi pustaka yang dicatat lockfile, sehingga keduanya tidak membawa pin sendiri. aggrega pull menjelaskan file tersebut.

Template setiap entri artefak dievaluasi dengan konteks template yang sama seperti valuesMapping:, mode mana pun yang menyediakan isinya. Dua keluaran dengan nama file yang sama menghentikan build saat node dirender. Dua entri dari satu map artifacts: tidak dapat menamai satu keluaran yang sama: kunci map unik dalam satu dokumen dan mengeja satu nama file, sehingga keluaran entri file tunggal adalah kuncinya dan file-file entri bundel berada di bawah direktori yang dinamai oleh kuncinya — segmen pertama setiap path yang dihasilkan entri adalah kunci yang menghasilkannya, sehingga kunci yang berbeda tetap menjadi nama keluaran yang berbeda apa pun nama file yang diimpor. Yang dicakup penghentian ini adalah satu nama file yang disumbangkan oleh dua jenis masukan berbeda — template chart dan entri artefak yang sama-sama menghasilkan servicemonitor.yaml — yang dilaporkan terhadap Recipe tersebut dengan diagnostik yang menyebutkan setiap asal penyumbang.

Kasus penggunaan. artifacts: adalah tempat untuk resource tambahan yang tidak dihasilkan oleh chart atau modul utama: NetworkPolicy yang menyertai sebuah workload, HPA yang dipasangkan dengan Deployment, ConfigMap sidecar yang dikunci berdasarkan instance_id. Resource tambahan lintas bidang yang berlaku pada banyak komponen (misalnya sidecar cadangan yang dipasang pada setiap datastore) seharusnya ditempatkan pada Resource Generation FeatureRecipe, bukan pada artifacts: per Recipe — lihat entities/featurerecipe.md untuk permukaan ekstensi FeatureRecipe.

Blok boundary: — berkas untuk keluaran bersama boundary

Sebagian besar Recipes tidak pernah membutuhkan ini. Segala hal lain yang ditulis sebuah Recipe menjadi milik komponennya sendiri: provider menempatkannya di bawah posisi komponen tersebut dalam keluaran boundary. Sebaliknya, beberapa berkas menjadi milik boundary secara keseluruhan — berkas yang dibaca target satu kali untuk semua yang di-deploy oleh boundary. Konfigurasi provider Terraform adalah kasus yang umum: dokumentasi Terraform menjauhkan blok provider dari modul yang dipanggil oleh konfigurasi lain, dan modul yang memuat blok semacam itu sendiri tidak dapat dipanggil dengan depends_on, count, atau for_each. spec.boundary.artifacts adalah tempat sebuah Recipe menulis berkas semacam itu.

spec:
capability: terraform
implements: core/api-gateway/azure-api-management:1.0.0
artifacts:
main.tf:
$import: ./module/main.tf
boundary:
artifacts:
# Terraform reads this beside the root configuration; one copy serves every
# component of the boundary that declares it.
provider-azurerm.tf: |
provider "azurerm" {
features {}
}

Blok ini adalah artifacts: pada cakupan kedua. artifacts adalah satu-satunya anggotanya, dan bentuknya persis sama dengan artifacts: milik Recipe itu sendiri: tiga mode yang sama — konten inline, $import: berkas, $import: pustaka yang berkas-berkasnya bersarang di bawah kunci entri sebagai <key>/<filename> — aturan kunci-ke-nama-berkas yang sama dan alfabet yang sama untuk kunci, serta konteks template yang sama, sehingga sebuah entri membaca .values, .infra, .locals, dan lainnya persis seperti entri artifacts:. Blok ini memerlukan setidaknya satu entri, dan anggota lain apa pun di bawah boundary: ditolak saat Recipe dibaca. FeatureRecipe tidak memiliki blok semacam itu.

Tempat berkas ditulis. Satu kali, di direktori yang memuat keluaran boundary yang telah dirakit, di samping berkas-berkas yang ditulis di sana oleh perakitan provider itu sendiri — untuk terraform, di samping konfigurasi root aggrega.modules.tf, bukan di dalam modul komponen. Provider tidak diberi satu pun dari berkas-berkas ini: compiler mengevaluasi dan menulisnya sendiri, dan tidak membubuhkan apa pun ke dalamnya untuk menyatakan dari komponen mana berkas itu berasal, karena berkas itu milik setiap komponen yang mendeklarasikannya. Entri yang template-nya dirender menjadi kosong tidak menulis berkas apa pun.

Cara beberapa kontributor bertemu. Setiap entri dievaluasi untuk setiap komponen yang dirender oleh Recipe di dalam boundary, dan berkas-berkas yang dideklarasikan oleh setiap kontributor boundary digabungkan berdasarkan nama. Satu nama yang dievaluasi menjadi byte yang sama — oleh dua komponen yang terikat pada satu Recipe, atau oleh dua Recipes yang mengonfigurasi satu provider secara identik — adalah satu berkas. Satu nama yang dievaluasi menjadi byte yang berbeda menghentikan build, dengan menyebutkan berkas tersebut dan setiap kontributornya, karena tidak ada satu berkas pun yang merupakan tulisan mereka semua; demikian pula nama yang ditulis oleh perakitan provider itu sendiri, seperti aggrega.modules.tf. Keduanya adalah assembled-output collision (tabrakan keluaran rakitan). Dua Recipes yang mengonfigurasi satu provider dengan dua nama berkas berbeda tidak digabungkan — setiap berkas ditulis — dan targetlah yang kemudian melaporkan konfigurasi ganda tersebut, sehingga Recipes yang dimaksudkan untuk berbagi konfigurasi provider berbagi nama berkasnya, menurut konvensi satu nama sesuai provider yang dikonfigurasinya.

Provider mana yang menerimanya. Apakah sebuah berkas yang ditempatkan di samping keluaran rakitan boundary memiliki arti merupakan properti dari target provider, sehingga hal itu menjadi bagian dari deklarasi provider itu sendiri. Recipe yang mendeklarasikan blok ini sementara provider-nya tidak menerimanya ditolak sebelum apa pun dirender, apa pun hasil render entri-entrinya; lihat The provider does not support boundary artifacts (Provider tidak mendukung artefak boundary). Kisi kapabilitas mencantumkan klaim setiap provider.

Providerboundary.artifacts:
terraformDiterima. Setiap berkas ditulis di samping konfigurasi root boundary, yang dibaca Terraform bersama setiap berkas konfigurasi lain di direktori tersebut.
helm, compose, helm-chart, cloudformationDitolak sebelum apa pun dirender.

$import: berkas di sini di-pin seperti berkas yang diimpor oleh entri artifacts:. Entity lock mencatat digest-nya dalam daftar artifactDigests yang sama, di bawah boundary/<key> alih-alih di bawah kunci saja, sehingga entri dari masing-masing blok yang ditulis dengan satu kunci yang sama di-pin secara terpisah. Langkah pin mencatatnya, pull yang tidak melakukan pin berhenti jika pin-nya tidak ada atau tidak lagi cocok, dan build menolak berkas yang telah diubah sejak di-pin, persis seperti build menolak berkas artifacts:.

Field outputLabels: — label yang dideklarasikan penulis pada keluaran hasil render

Recipe.spec.outputLabels: adalah map kunci label → nilai yang dicapkan oleh provider ke setiap objek yang dihasilkan oleh keluaran hasil render Recipe tersebut. Inilah tempat yang tepat untuk sebuah sifat realisasi — properti tentang cara sebuah Recipe tertentu merealisasikan suatu komponen, bukan tentang apa komponen itu. Ambil contoh penyimpanan yang digunakan suatu realisasi untuk persistensi, yang di bawah ini ditulis sebagai kunci ilustratif example.io/storage-backing: sebuah Recipe Helm yang memasang PersistentVolumeClaim dan sebuah Recipe Compose yang memasang named volume merealisasikan komponen yang sama melalui mekanisme yang berbeda, sehingga keduanya membawa outputLabels yang berbeda dan perangkat hilir (alokasi biaya, kebijakan, inventaris) dapat membedakan keduanya pada sumber daya yang dihasilkan. Kunci tersebut bersifat ilustratif — example.io/ adalah namespace contoh, dan sebuah katalog memilih kunci yang dibaca oleh perangkatnya sendiri.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/storage-backing: persistent-volume
example.io/team: platform

Label keluaran menempuh jalur yang sama dengan label provenans build yang tetap: label tersebut digabungkan ke dalam kumpulan label yang dicapkan oleh setiap permukaan keluaran, sehingga label tersebut muncul di mana pun provenans muncul. Yang berbeda adalah kepemilikannya — kunci provenans dimiliki oleh compiler, sedangkan outputLabels dimiliki oleh penulis Recipe.

Label identitas komponen itu sendiri tidak diketik di sini — ini konvensi katalog, bukan aturan yang ditegakkan oleh compiler. Kunci yang menyatakan apa komponen itu adalah, bukan cara sebuah Recipe merealisasikannya — kategori kognitifnya, tipe operasionalnya, label kapabilitas per perannya, siapa yang mengoperasikan sumber daya yang mendasarinya, kelas lisensi dari apa yang dibungkusnya — dideklarasikan pada metadata.labels milik Component; lihat entities/component “The Semantic Label Taxonomy” untuk sumbu-sumbunya. Sebuah Recipe menempatkan salah satu kunci tersebut pada keluaran hasil rendernya dengan menyebut kunci itu dalam outputComponentLabels: di bawah, bukan dengan mengetik kunci dan nilainya di sini. Alasannya, entri literal adalah salinan kedua dari nilai yang sudah dibawa oleh komponen, dan salinan kedua dapat berbeda dari yang pertama: seorang penulis Recipe dapat mengetik satu postur pada sebuah node yang Component-nya mendeklarasikan postur lain, sehingga memberi tahu pembaca hilir sesuatu yang tidak dinyatakan oleh graf. Entri yang dipromosikan menyalin berdasarkan referensi sehingga tidak memiliki salinan kedua yang dapat menyimpang. Inti menerima apa pun yang Anda tulis, di luar aturan namespace tercadang di bawah; konvensi ini dijunjung oleh para penulis katalog.

Namespace tercadang. Namespace aggrega.ai/ dan app.kubernetes.io/ dicadangkan untuk provenans bawaan platform. Sebuah Recipe yang mendeklarasikan kunci outputLabels di bawah salah satu prefiks tersebut ditolak saat dimuat dengan galat katalog yang jelas yang menyebutkan kunci yang melanggar. Setiap kunci lain diterima. Selain itu, inti tidak mengawasi kunci atau nilai — kunci atau nilai yang tidak valid untuk permukaan label mesin target menjadi tanggung jawab penulis, dan runtime hilir akan menolaknya; compiler tidak ikut campur di luar aturan namespace tercadang.

Penerapan per provider. Setiap provider menerjemahkan label ke permukaan keluarannya sendiri:

  • helm, sintesis workload — pada metadata.labels objek dan metadata.labels pod-template, sesuai dengan tempat sintesis menempatkan provenans.
  • helm, source-render dan artifacts — pada metadata.labels objek.
  • compose — pada map labels: setiap service.
  • terraform — sebagai tag per sumber daya pada badan artefak .tf.json yang dapat dialamatkan secara struktural, secara upaya terbaik: blok sumber daya yang sudah mendeklarasikan map tags (AWS/azurerm) atau labels (Google) menerima label keluaran di sana, kunci yang dideklarasikan penulis tidak pernah ditimpa, dan sumber daya tanpa atribut tersebut dibiarkan apa adanya (atribut tidak pernah diciptakan). Badan HCL asli (main.tf, *.tf) dan modul vendored dihasilkan apa adanya dan tidak membawa tag yang disisipkan. Provenans Terraform tetap dibawa dalam file komentar pendampingnya, terpisah dari jalur tag.

Label keluaran hanyalah label; tidak ada permukaan anotasi keluaran yang terpisah. outputLabels dideklarasikan oleh penulis Recipe (lapisan realisasi yang ditulis tim ops), bukan oleh Aggregate — field ini menggambarkan realisasi, tidak pernah identitas graf abstrak milik developer.

Field outputComponentLabels: — mempromosikan label milik komponen itu sendiri

Recipe.spec.outputComponentLabels: adalah daftar kunci label, bukan pasangan kunci-nilai. Untuk setiap kunci yang disebutkannya, provider menempelkan kunci tersebut pada output yang dirender dengan nilai yang dibawa kunci itu pada instans komponen yang sedang dirender. Jika outputLabels menyatakan sebuah nilai, outputComponentLabels menyebutkan dari mana nilai tersebut harus dibaca.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/team: platform
outputComponentLabels:
- component.aggrega.ai/hosting

Diberikan sebuah Component yang metadata.labels-nya mendeklarasikan component.aggrega.ai/hosting: managed, setiap objek yang dirender Recipe ini untuk komponen tersebut membawa component.aggrega.ai/hosting: managed. Ikat Recipe yang sama ke komponen yang mendeklarasikan self-hosted, maka objek-objek komponen tersebut membawa self-hosted sebagai gantinya — satu Recipe, satu kunci yang disebutkan, satu nilai per komponen.

Promosi dilakukan berdasarkan referensi, dan justru itulah intinya. Nilai dibaca dari komponen setiap kali output dirender, sehingga nilai tersebut tidak dapat menyimpang dari identitas asalnya: tidak ada salinan kedua yang harus diselaraskan ketika label komponen berubah. Entri outputLabels literal yang menyatakan ulang label komponen adalah salinan kedua tersebut, dan keduanya menjadi tidak sesuai begitu salah satunya berubah. Jadi, gunakan outputLabels ketika nilai tersebut merupakan properti dari cara Recipe ini merealisasikan komponen, dan outputComponentLabels ketika nilai tersebut sudah ada pada komponen dan output yang dirender juga perlu membawanya.

Kunci yang dipromosikan mendarat pada permukaan yang persis sama dengan kunci literal — penempatan per provider yang dijelaskan di atas berlaku tanpa perubahan, dan tidak ada provider yang membedakan kunci yang dipromosikan dari kunci yang ditulis langsung.

Namespace yang dicadangkan. Namespace aggrega.ai/ dan app.kubernetes.io/ dicadangkan untuk provenance bawaan platform, dan kunci yang dipromosikan di bawah salah satu prefiks tersebut ditolak saat pemuatan dengan galat katalog yang menyebutkan kunci tersebut dan field tempat kunci itu muncul. Yang diuji adalah prefiks dasarnya: kunci seperti component.aggrega.ai/hosting berada dalam namespace tersendiri, bukan di bawah root yang dicadangkan, dan dapat dipromosikan.

Sebuah kunci hanya milik salah satu blok. Mendeklarasikan kunci yang sama di outputLabels dan outputComponentLabels sekaligus akan ditolak saat pemuatan, sehingga setiap kunci yang ditempelkan memiliki satu sumber saja — nilai literal yang ditulis pada Recipe atau label milik komponen itu sendiri, tidak pernah keduanya.

Kunci yang dipromosikan tetapi tidak dideklarasikan oleh komponen tidak menempelkan apa pun. Build tetap berlanjut dan mengeluarkan peringatan yang menyebutkan node, Recipe, dan kunci yang hilang. Hal ini disengaja: Recipe yang diikat ke komponen-komponen dengan kumpulan label berbeda tetap dirender, dan ketidaksesuaian tersebut dilaporkan alih-alih menghentikan build.

Komponen dengan satu postur — sebuah konvensi, bukan aturan. Promosi membawa nilai apa pun yang dideklarasikan komponen, dan compiler tidak menafsirkan nilai tersebut. Karena itu, komponen yang label identitasnya berisi placeholder yang mewakili “bervariasi” akan mempromosikan placeholder tersebut ke setiap objek yang dirender untuknya. Jika sebuah komponen memang memiliki lebih dari satu postur, konvensi katalog pustaka standar adalah agar setiap Recipe menyatakan postur realisasi miliknya sendiri melalui kunci outputLabels yang dimiliki Recipe tersebut, bukan melalui kunci identitas komponen, yang oleh konvensi yang sama dialirkan melalui outputComponentLabels: — atau tidak menempelkan apa pun sama sekali. Kedua kunci menjawab pertanyaan yang berbeda dan tidak saling menggantikan: kunci identitas menyatakan apa komponen itu di seluruh realisasi, sedangkan kunci milik Recipe menyatakan apa yang dilakukan oleh realisasi yang satu ini. Itu adalah konvensi katalog yang dijunjung oleh para penulisnya, bukan batasan yang ditegakkan oleh compiler.

Blok locals:

Recipe.spec.locals: adalah Private Ops State — sebuah map berisi string template Go bernama yang keluaran hasil render-nya mengekspos map .locals.* ke template-template berikutnya dalam Recipe. Blok ini adalah ruang kerja untuk menghitung realitas fisik (kontainer target, path JSON, nama host turunan) sekali saja lalu menggunakannya kembali di seluruh payload provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, dan pipeline[].with tanpa perhitungan ulang. Keluaran hasil render setiap entri disimpan setelah spasi putih di awal dan di akhirnya dihapus.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
locals:
primary_compute: postgresql
listen_port: "5432"
secret_target_db_password: "postgres-auth"
volumes_path: "/spec/template/spec/volumes"
valuesMapping: |
primary:
auth:
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"

locals: tidak pernah diekspos ke pemanggil — komponen hilir yang mengonsumsi Recipe ini melalui uses: hanya melihat provides:. Template provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, dan pipeline[].with milik Recipe itu sendiri semuanya melihat map .locals.* yang telah di-resolve. Nilai per kunci dapat berupa string biasa atau template Go; compiler me-resolve seluruh blok dalam preamble locals, sebelum provides: milik node tersebut, sehingga setiap template berikutnya mengamati nilai hasil resolve yang stabil.

Setiap entri dievaluasi terhadap konteks lokal node yang mandiri: .context.instance_id, .values, .infra, dan entri-entri blok yang sama yang telah di-resolve. Sebuah local tidak dapat membaca .provides — pilar tersebut tidak ada pada permukaan ini, dan entri yang mencoba mengaksesnya akan berhenti. Local juga tidak dapat membaca .context.rendered_name, yaitu nama yang diberikan oleh provider seperti helm kepada resource yang di-render-nya untuk node tersebut, sehingga local yang menamai salah satu resource itu hanya memuat bagian setelah nama tersebut, seperti yang dilakukan secret_target_db_password di atas, dan template yang menulis nama lengkapnya menggabungkan keduanya.

Urutan penulisan menentukan hasil

Entri diselesaikan sesuai urutan penulisannya, dan sebuah entri dapat membaca entri saudara yang didefinisikan di atasnya, dengan menerima nilai saudara tersebut yang sudah diselesaikan:

spec:
locals:
db_identifier: "{{ .context.instance_id }}-postgres" # defined first
secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above

Perangkaian hanya berjalan ke bawah. Ketika satu entri membaca entri lain, urutan entri menentukan apakah build berhasil: pindahkan db_identifier ke bawah secret_target dan build akan berhenti. Compiler tidak pernah mengurutkan atau menata ulang blok agar sebuah referensi dapat di-resolve, sehingga urutan tertulis adalah kontraknya — menata ulang blok locals: adalah perubahan perilaku, bukan perubahan kosmetik.

Dua penghentian membedakan dua kesalahan yang dapat dibuat oleh penulis, karena perbaikannya berbeda:

  • Referensi ke entri yang didefinisikan blok di bawahnya akan berhenti dengan menyebutkan kesalahan urutan; perbaikannya adalah memindahkan definisi ke atas pembacanya.
  • Referensi ke kunci yang sama sekali tidak dideklarasikan oleh blok akan berhenti dengan menyebutkan kunci tersebut; perbaikannya adalah membetulkan ejaannya.

Pemeriksaan mengikuti alias untuk blok. Kunci yang dicapai melalui titik yang di-rebind oleh badan with .locals, atau melalui variabel yang terikat ke .locals, diperiksa dengan ketentuan yang persis sama dengan ejaan langsungnya: {{ with .locals }}{{ .nope }}{{ end }} dan {{ $l := .locals }}{{ $l.nope }} keduanya berhenti dengan menyebutkan .locals.nope, sama seperti {{ .locals.nope }}, dan demikian pula {{ (.locals).nope }} dan {{ ($.locals).nope }}, karena tanda kurung menghasilkan blok itu sendiri dan tidak lebih. Satu ejaan lolos dari pemeriksaan: kunci yang dicapai melalui pemanggilan yang hasilnya tidak dapat dinamai oleh teks template — {{ index .locals "nope" }}, atau {{ (default dict .locals).nope }} — karena apa yang dihasilkan pemanggilan semacam itu ditentukan saat template dijalankan, bukan oleh apa yang tertulis. Kunci yang tidak ada yang dibaca sebagai field dari hasil pemanggilan semacam itu tidak menyebabkan berhenti, dan me-render teks literal <no value> alih-alih tidak me-render apa pun. Kunci yang tidak ada yang dicapai melalui index akan berhenti dengan menyebutkan kunci tersebut, karena index berhenti di setiap permukaan template ketika map yang dibacanya tidak memuat kunci yang diminta — laporan yang berbeda dari laporan pemeriksaan ini, didokumentasikan di errors/fatal-halts.md pada “A template indexes a map with a key the map does not hold (Template mengindeks map dengan kunci yang tidak dimuat map tersebut)”. Oleh karena itu, index tetap menjadi cara untuk mencapai kunci yang namanya sendiri dihitung, seperti {{ index .locals (printf "secret_target_%s" .values.slot) }}, dan nama hasil perhitungan yang tidak dideklarasikan blok tetap dilaporkan berdasarkan kuncinya.

provides: membaca .locals dan menerima nilai yang telah di-resolve, karena locals milik suatu node di-resolve sebelum provides-nya. Template provides: yang menyebut kunci yang tidak dideklarasikan blok locals akan berhenti. Artinya, nilai yang dibutuhkan baik oleh entri provides: maupun oleh sebuah artefak ditulis sekali saja, di locals:, dan dibaca dari kedua tempat.

Untuk padanan API publiknya, lihat Blok provides: di bawah. Permukaan FeatureRecipe mengikuti aturan yang sama — lihat entities/featurerecipe.md “Blok locals:”.

Blok provides:

Recipe.spec.provides: adalah API Developer Publik — sebuah map dari nama → string template Go yang mendeklarasikan nilai-nilai yang disumbangkan Recipe ini ke pipa .context.inject dan .context.uses milik pemanggil di hilir. Compiler mengevaluasi template provides: pada tahap evaluasi provides (mandiri, dalam urutan apa pun); kunci inject milik pemanggil diresolusi terhadap nilai-nilai ini pada tahap hidrasi inject.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
provides:
# The Service this chart names after its release name, suffixed "-postgresql"
host: "{{ .context.rendered_name }}-postgresql"
port: "5432"
database: "{{ .values.db_name }}"

Template setiap entri dievaluasi terhadap permukaan evaluasi provides yang mandiri — .context.instance_id, .context.rendered_name jika provider node tersebut melaporkannya, .values, .infra, .locals node yang telah diresolusi, dan teks statis. Namespace tempat node ditempatkan tidak ada di permukaan ini, sehingga host yang dipublikasikan tidak membawa namespace: konsumen di namespace lain menambahkannya di sisinya sendiri. .locals ada di permukaan ini karena locals node diresolusi di preambul tahap yang sama, sebelum provides-nya; template provides yang menyebut kunci yang tidak dideklarasikan oleh blok locals akan terhenti. Pemisahan evaluasi provides dari hidrasi inject bersifat krusial: provides: milik sebuah Recipe tidak dapat mereferensikan state pemanggil mana pun karena pemanggil belum diresolusi saat evaluasi provides berjalan — provides: bersifat mandiri sesuai invarian arsitektural. Pemanggil kemudian membaca nilai-nilai ini melalui .context.uses.<alias>.provides.<provided-name> dalam template mereka sendiri — nama-nama yang disediakan bersarang di bawah provides pada edge, berdampingan dengan field edge lainnya. Pemanggil yang mendeklarasikan allowlist inject: pada edge menjangkau nilai yang sama melalui pipa .context.inject miliknya.

Kunci provides: merupakan bagian dari permukaan kontrak Recipe. Mengganti nama atau menghapus sebuah kunci adalah perubahan yang merusak bagi setiap pemanggil yang bergantung pada nama lama; versi antarmuka implements: sebaiknya mencerminkan evolusi kontrak tersebut. Untuk semantik resolusi kaskade, kontrak pipa inject, dan contoh lengkap yang mencakup routing lintas namespace dan lintas region, lihat architecture/06-data-taxonomy-and-composition.md §3 dan templates/expansion-matrix.md.

Membaca nilai yang dipublikasikan oleh sebuah lampiran

Sebuah Recipe membaca Features yang dilampirkan pada komponennya di .features.<instance-name> dan Features kredensial di .features.<slot>. Keduanya memiliki bentuk lampiran yang sama — .type, .values, .infra, .provides — sehingga sebuah lampiran dibaca dengan cara yang sama, map mana pun yang memuatnya; yang membedakan keduanya adalah apa yang dihasilkan oleh lampiran tersebut.

.provides adalah keluaran yang dipublikasikan oleh lampiran, yang di-resolve dari FeatureRecipe yang terikat padanya. Ini merupakan padanan blok provides: di atas, dilihat dari sisi konsumen: jika sebuah Recipe memublikasikan ke pemanggilnya, sebuah lampiran memublikasikan ke komponen induknya.

workload: |
# The identity attachment emits a ServiceAccount and publishes its name;
# the pod binds to that published name rather than restating it.
serviceAccount: "{{ .features.identity.provides.name }}"
containers:
main:
env:
DB_SECRET: "{{ .features.app_credentials.provides.name }}"

Membaca nilai yang dipublikasikan alih-alih menghitungnya ulang dari masukan values/infra yang sama adalah perbedaan antara satu pernyataan sebuah nama dan dua pernyataan yang dapat menyimpang satu sama lain. Bentuk lengkap per bidang, termasuk aturan ketersediaannya, terdapat di templates/template-context-contract.md.

Sebuah lampiran yang ditulis pada salah satu koneksi komponen — kredensial yang diberikan komponen kepada satu target — dibaca dalam bentuk yang sama di bawah koneksi tersebut, di .context.uses.<alias>.features.<slot>, dan tidak pernah termasuk dalam .features. Sebuah Recipe yang menjangkau beberapa target membaca kredensial milik setiap target di bawah alias target tersebut, dan perulangan atas .features yang memilih lampiran berdasarkan tipe hanya menemukan lampiran milik komponen itu sendiri:

artifacts:
routes.yaml: |
{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
{{- end }}{{ end }}
{{- end }}

Lihat Lampiran sebuah koneksi untuk bentuknya dan untuk urutan sebuah templat menelusuri koneksi-koneksi tersebut.

Field pipeline:

Recipe.spec.pipeline: adalah array berurutan berisi langkah pipeline Wasm yang berjalan setelah render atas himpunan dokumen yang telah di-render, masing-masing mengembalikan patch RFC 6902 dan efek samping. Setiap entri mendeklarasikan id (pengenal per langkah: huruf, angka, dan garis bawah), plugin (entitas Plugin yang dijalankan langkah tersebut, dicakup menurut jenis plugin-nya — pipeline-step/<name>, opsional dengan versi; referensi .wasm atau artefak polos ditolak), function (ekspor plugin yang akan dipanggil), badan templat Go with: opsional yang menyediakan payload plugin, dan templat Go when: opsional yang menentukan apakah langkah tersebut dijalankan — hasil falsy melewati langkah tersebut sebagai pass-through, sehingga himpunan dokumen tidak berubah. Gerbang when:, independensinya dari optional:, dan aturan truthiness-nya dibahas lengkap di entities/featurerecipe.md “Conditional steps — when:”:

spec:
capability: helm
implements: core/web-server:1.0.0
source: { kind: helm-oci-chart, url: "oci://…", version: "…" }
pipeline:
- id: inject_sidecar
plugin: pipeline-step/envoy-sidecar:1.0.0
function: Inject
with: |
target_container: "{{ .locals.primary_compute }}"
envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"

Kompiler menjalankan langkah-langkah pipeline: milik Recipe dasar sesuai urutan deklarasinya, dengan cara yang sama seperti menjalankan pipeline: milik FeatureRecipe: kompiler mengirimkan plugin Wasm yang dinamai pada setiap langkah terhadap keluaran yang dirender, menerapkan operasi JSON Patch yang dikembalikan pada dokumen yang dituju, dan memancarkan efek samping langkah tersebut. Field pipeline: pada FeatureRecipe memiliki bentuk skema yang sama dan eksekusi yang sama — lihat entities/featurerecipe.md “Authoring Contract” dan Status Bahasa untuk status eksekusi setiap permukaan.

Mekanisme field ini mencerminkan semantik FeatureRecipe: evaluasi berurutan sesuai urutan deklarasi, operasi JSON Patch yang diterapkan pada dokumen yang dirender, efek samping yang dipancarkan bersamanya, dan galat yang dimunculkan dengan provenans yang menunjuk ke langkah penyebabnya. Langkah yang gerbang when:-nya dirender falsy dilewati sebagai pass-through, sehingga himpunan dokumen tidak berubah untuk langkah berikutnya.

Blok assertions:

Recipe.spec.assertions: adalah map opsional berisi aturan bernama yang menyatakan invarian implementasi dari Recipe — aturan lintas bidang yang berlaku untuk chart atau modul tertentu yang menjadi sumber Recipe tersebut. Setiap kunci adalah pengenal aturan yang muncul dalam pesan kegagalan; setiap nilai adalah isi templat Go. Berbeda dengan asersi Component (yang menyatakan invarian tingkat kontrak terlepas dari Recipe mana yang terikat), asersi Recipe adalah properti dari implementasi spesifik yang dipilih.

spec:
implements: core/datastore/mariadb:^1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}

Aturan di atas khusus untuk chart Bitnami 20.x; aturan ini tidak berlaku jika Recipe MariaDB yang lain yang terikat. Aturan tingkat Component dari kontrak tetap berlaku di sampingnya, dievaluasi pada fase pipeline yang lebih awal.

Asersi Recipe dievaluasi setelah pengikatan Recipe dan sebelum rendering, setelah locals dan provides setiap node terselesaikan. Konteks templat mencakup .provides, .locals, dan .recipe.source milik Recipe selain bidang instans entitas (.values, .infra, .uses, .features). .uses dan .features di sana adalah bentuk permukaan asersi yang lebih sempit, bukan bentuk milik templat Recipe: entri sebuah koneksi memuat target dan aliasnya, labels milik target, values milik koneksi itu sendiri, dan lampiran yang ditulis padanya di bawah features, tetapi tidak memuat apa pun yang dipublikasikan target; dan entri sebuah lampiran, baik milik komponen itu sendiri maupun milik koneksi, memuat type, resolved_version, dan values miliknya, tetapi tidak memuat infra maupun provides miliknya — FeatureRecipe dari sebuah lampiran belum menyelesaikan provides-nya ketika asersi dijalankan. Oleh karena itu, referensi ke .features.<name>.provides menghentikan build, dan pembacaan yang sadar-keberadaan terhadapnya mengembalikan nilai cadangannya. Untuk tata bahasa penulisan lengkap, pembagian tanggung jawab antara aturan tingkat kontrak dan tingkat implementasi, serta contoh lengkap, lihat templates/assertions-block.md.

Field omits: — mengecualikan dokumen hasil render dari sebuah sumber

Sebagian besar Recipes tidak pernah memerlukan ini. Ini ditujukan untuk sumber yang Anda ambil apa adanya — paling sering, chart yang diambil dari registry — yang merender dokumen yang tidak boleh dikirim oleh Release Anda: misalnya, Secret yang dibuat ulang oleh chart pada setiap render, yang membuat dua build berbeda dan, setelah diterapkan, menimpa Secret yang disediakan operator. Anda tidak mengedit chart yang diambil, dan tidak ada aturan ignore yang menjangkau ke dalamnya, sehingga omits: adalah cara sebuah Recipe mengecualikan dokumen semacam itu dari build. File compose yang diambil adalah kasus yang sama: file itu dapat menyertakan service, volume, atau config yang tidak boleh dimiliki Release, dan overlay valuesMapping: dapat mengubahnya tetapi tidak pernah menghapusnya. Demikian pula template CloudFormation yang diambil, yang dapat mendeklarasikan resource yang tidak boleh dibuat oleh Release: valuesMapping: dapat mengisi parameter yang dideklarasikannya tetapi tidak pernah menghapus salah satu resource-nya.

spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/gateway
version: "2.4.0"
omits:
# The chart generates this key on every render; the operator supplies it.
- kind: Secret
name: "{{ .context.rendered_name }}-session-key"
# Left out only where the Release asks for it.
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: "{{ .context.rendered_name }}-dashboards"
namespace: monitoring

Apa yang dicakupnya. Hanya apa yang dirender oleh source:. workload: dan entri artifacts: tidak pernah difilter: Anda menulisnya di dalam Recipe, sehingga dokumen yang tidak Anda inginkan di sana cukup tidak Anda tulis. Kunci ini memerlukan source:; dokumen yang melanggar aturan tersebut ditolak saat dibaca, dengan menyebutkan aturannya.

Sebuah entri. Setiap entri menyebutkan apa yang dikecualikan melalui tiga field, dan field keempat menentukan apakah entri tersebut berlaku. Apa yang disebutkan oleh tiga field pertama merupakan kosakata provider itu sendiri untuk apa yang dirender oleh sumbernya, yang diuraikan per provider dalam tabel di bawah:

  • kind — jenis dari apa yang dirender oleh sumber: untuk chart, kind dari dokumen yang dirender — Secret, ConfigMap, Deployment; untuk file compose, service, volume, atau config; untuk template CloudFormation, Type sebuah resource — AWS::S3::Bucket. Field ini tidak berkaitan dengan kind: yang dibawa oleh source: terstruktur, yang menyebutkan cara sumber diambil.
  • name — namanya: metadata.name sebuah dokumen; kunci sebuah unit compose di bawah services:, volumes:, atau configs:; logical ID sebuah resource CloudFormation, yaitu kuncinya di bawah Resources.
  • namespace (opsional) — namespace tempat dokumen berada, untuk provider yang keluarannya memiliki namespace. Tanpa field ini, entri menyebutkan kind dan nama di namespace mana pun; namespace yang dirender menjadi kosong diperlakukan sebagai tidak ada.
  • when (opsional) — apakah entri berlaku untuk build ini. Field ini dievaluasi terlebih dahulu dan dibaca dengan aturan yang sama seperti when: pada langkah pipeline: hasil false membuang entri, sehingga field lainnya tidak dievaluasi dan entri tersebut tidak diserahkan ke provider maupun diperiksa, sedangkan when: yang tidak ada atau kosong mempertahankannya.

kind dan name wajib diisi, dan entri yang membawa field lain ditolak saat Recipe dibaca.

Setiap nilai adalah template, yang dievaluasi terhadap konteks yang sama dengan valuesMapping:. Konteks tersebut membawa .context.rendered_name, nama yang diberikan provider pada resource node dan yang biasanya dipakai chart untuk menamainya, sehingga sebuah entri dapat menyebutkan dokumen persis seperti yang akan dilakukan chart. Template yang gagal dirender menghentikan build sebagaimana template valuesMapping: yang gagal.

Setiap entri yang berlaku harus mengecualikan sesuatu. Provider melaporkan berapa banyak unit yang dikecualikan oleh setiap entri, dan entri yang tidak mengecualikan apa pun menghentikan build, dengan menyebutkan entri tersebut; lihat An omits entry left out nothing the source rendered (Entri omits tidak mengecualikan apa pun yang dirender sumber). Penyebab umumnya adalah peningkatan versi sumber yang mengganti nama atau menghapus dokumen, dan penghentian inilah yang mencegah dokumen yang berganti nama mencapai keluaran Anda tanpa disadari. Untuk mengecualikan dokumen hanya pada kondisi tertentu, nyatakan hal itu dengan when: alih-alih mengandalkan ketiadaan dokumen.

Sumber tetap dirender sepenuhnya. Hanya keluarannya yang difilter: setiap template chart tetap dijalankan, sehingga template yang gagal tetap menggagalkan build, dan dokumen yang dikecualikan dirender lalu dibuang. Setelah dibuang, dokumen itu tidak mencapai apa pun yang dilakukan build sesudahnya — tidak ada file yang dihasilkan, tidak ada nama yang dibandingkan dengan nama komponen lain, tidak ada fakta tentang render yang dibaca Feature, dan tidak ada apa pun yang diserahkan ke langkah pipeline.

Release menjangkau kunci ini melalui infra dan parameters. Kunci ini milik Recipe, sehingga Release tidak dapat menulisnya. Namun, Release tetap dapat menentukan apa yang dilakukan sebuah entri: template entri membaca infra yang diisi Release, dan parameters yang disediakannya mencapai .values milik Recipe di mana pun Aggregate meneruskannya ke sana. Jadi, Release mengaktifkan atau menonaktifkan entri dengan when:, seperti yang dilakukan entri kedua di atas, atau menentukan apa yang disebutkannya.

Apa yang Anda kecualikan menjadi tanggung jawab Anda. Tidak ada bagian build yang mengetahui untuk apa sebuah dokumen. Mengecualikan dokumen yang diandalkan bagian lain chart saat runtime — Secret yang di-mount oleh Deployment, ServiceAccount yang digunakan pod — menghasilkan keluaran yang berhasil di-build lalu gagal saat diterapkan, kecuali ada hal lain yang diterapkan di sampingnya yang menyediakan dokumen tersebut. Untuk file compose dan template CloudFormation, build memang memeriksanya, karena masing-masing menyatakan referensinya sendiri: apa pun yang tersisa yang masih menyebutkan unit yang dikecualikan — service yang menyebutkan service yang dikecualikan, resource atau output yang menyebutkan resource yang dikecualikan — menghentikan build, seperti dijelaskan dalam tabel di bawah.

Provider mana yang mendukungnya. Mengecualikan dokumen adalah hal yang hanya dapat dilakukan provider, karena hanya provider yang mengetahui apa yang dirender oleh sumbernya, sehingga apakah sebuah provider mendukung kunci ini merupakan bagian dari deklarasi provider itu sendiri. Recipe yang mendeklarasikan omits: dengan provider yang tidak mendukungnya ditolak sebelum apa pun dirender, apa pun hasil render when: entri-entrinya; lihat The provider does not support omits (Provider tidak mendukung omits).

Provideromits:
helmDidukung. Sebuah entri menyebutkan dokumen yang dirender chart — dari template atau dari direktori crds/-nya — berdasarkan kind, metadata.name milik dokumen itu sendiri dan, jika entri menyebutkannya, namespace tempat dokumen berada. Lihat helm → Mode sourced.
composeDidukung. Sebuah entri menyebutkan service, volume, atau config dari file compose sumber berdasarkan kuncinya di bawah services:, volumes:, atau configs:, yang dicocokkan setelah valuesMapping: digabungkan ke dalam file, dan tidak menyebutkan namespace: entri yang menyebutkan kind lain, atau namespace, menghentikan build saat komponen dirender. File yang bagian tersisanya masih menyebutkan unit yang dikecualikan — melalui depends_on, links, volumes_from, mode network atau namespace service:, extends, build context, atau entri volumes: atau configs: — menghentikan build, dengan menyebutkan setiap referensi. Lihat compose → Mode sourced.
cloudformationDidukung. Sebuah entri menyebutkan resource dari template sumber berdasarkan Type dan logical ID-nya, di setiap template dari sumber berupa direktori, dan tidak menyebutkan namespace: entri yang membawa namespace menghentikan build saat komponen dirender. Template yang bagian tersisanya masih menyebutkan resource yang dikecualikan — melalui Ref, Fn::GetAtt, DependsOn, atau variabel Fn::Sub — menghentikan build, dengan menyebutkan setiap referensi. Lihat cloudformation → Mengecualikan resource dari template sumber.
helm-chart, terraformDitolak: provider meneruskan sumbernya untuk dirender saat di-deploy, sehingga tidak ada dokumen pada waktu build yang dapat dikecualikan. Untuk chart atau modul lokal, sebuah baris di .aggregaignore di samping Recipe akan mengecualikan file darinya sebagai gantinya.

Kunci yang sama ditulis pada FeatureRecipe; lihat entities/featurerecipe.md.

Untuk contoh lengkap — Secret yang dihasilkan oleh chart yang diambil dan dikecualikan, penghentian determinisme yang dialami chart yang sama tanpa entri tersebut, serta penghentian pada entri yang tidak cocok dengan apa pun, masing-masing dari build nyata — lihat ai-gateway-own-webhook-certificate.