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

Helm Provider

Provider helm menghasilkan YAML Kubernetes hasil render yang datar untuk konsumen GitOps (ArgoCD, Flux). Provider ini melakukan perakitan per (path, provider): YAML hasil render dari setiap node yang menargetkan helm dirutekan ke assembler yang dikunci pada directory: hasil evaluasi dari boundary yang digabungkan dengan subDirectory: per komponen, dan assembler tersebut menghasilkan satu file YAML per resource Kubernetes. Perangkat hilir melakukan diff dan menerapkan file-file tersebut secara langsung tanpa langkah instalasi Helm.

Jika syncWave: <integer> milik boundary bukan 0, setiap resource Kubernetes yang dihasilkan membawanya sebagai anotasi argocd.argoproj.io/sync-wave: "<N>"; hook Helm juga membawa helm.sh/hook-weight: "<N>". ArgoCD membaca anotasi sync-wave, dan Helm membaca bobot hook, masing-masing mengurutkan resource berdasarkan nilai itu; boundary pada wave bawaan 0 tidak membawa keduanya, yang dibaca kedua alat sebagai wave 0.

Halaman ini adalah referensi penulisan untuk provider helm. Untuk model komposisi input lintas provider, lihat architecture/16-recipe-input-composition.md. Untuk kesiapan setiap provider, lihat Status Bahasa → Providers.

Jenis input yang didukung

Provider helm menerima ketiga jenis input Recipe dalam peran yang berbeda:

  • Mode bersumber. Sebuah Recipe dengan source: <chart-path> menunjuk ke direktori chart Helm di disk. Helm Go SDK memuat chart tersebut, kamus nilai rendering dasar digabungkan dengan nilai bawaan chart, dan templat chart dirender menjadi YAML Kubernetes datar.
  • Mode Workload (disintesis). Sebuah Recipe dengan workload: (inline atau dimuat melalui $import:) mendeklarasikan sebuah dokumen Workload. Provider menyintesis satu atau lebih resource Kubernetes per node — objek controller yang dipilih oleh form milik Workload beserta Services per layanan dan PVC per volume persisten — langsung dari spesifikasi Workload; lihat Mode Workload (disintesis).
  • Mode khusus artefak. Sebuah Recipe dengan artifacts: tanpa source: maupun workload: mengeluarkan manifest yang ditulis oleh pembuatnya, dengan label dan anotasi asal-usul build disisipkan ke dalam metadata masing-masing resource.

Ketiganya dapat digabungkan: sebuah Recipe dapat mendeklarasikan sebuah chart, sebuah Workload, dan artifacts: sekaligus, dan masing-masing dirender serta dikeluarkan secara terpisah, berdampingan dalam keluaran node — lihat Apa yang diterima setiap provider, secara lengkap.

Kumpulan kunci source:

source: milik provider helm menamai sebuah chart, dan menerima kedua bentuk yang dapat diambil oleh field source:: sebuah string path filesystem polos, dan sebuah objek terstruktur yang url:-nya membawa lokasinya. Di mana pun lokasi itu berupa path filesystem, lokasi tersebut ditambatkan ke direktori yang memuat recipe.yaml yang mendeklarasikannya, bukan ke direktori tempat build dijalankan, dan harus tetap berada di dalam direktori itu: path yang keluar dari direktori tersebut, atau path absolut, ditolak, karena setiap file yang dibawa oleh publikasi Recipe diambil dari direktorinya — lihat entities/recipe.md “Content paths stay inside the Recipe’s own directory”. Chart yang dinamai dengan cara ini dipublikasikan bersama Recipe, yaitu setiap file di bawahnya yang dipertahankan oleh aturan pengabaian yang tercatat saat Recipe di-pin — provider helm tidak menyertakan direktori kontrol versi dan file tersembunyi di bawah templates/ milik chart, serta mematuhi .helmignore milik chart itu sendiri, dan .aggregaignore milik penulis menjadi penentu akhir, sebagaimana dijelaskan dalam Which files ship with an entity — sedangkan file di samping Recipe yang tidak dinamai oleh apa pun yang dideklarasikannya tidak ikut dipublikasikan. Render membaca file yang sama dengan yang dibawa publikasi, sehingga sebuah chart dirender dengan hasil yang sama dari direktori Anda maupun dari registry. Bentuk yang Anda gunakan untuk menuliskannya tidak mengubah hal itu: source: terstruktur yang url:-nya adalah ./charts/api-server ditambatkan persis seperti string polos ./charts/api-server.

spec:
capability: helm
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicas: {{ optional .infra `replicas` 2 }}

source: terstruktur menyatakan hal yang sama dengan field bernama, dan apa yang dibawa url:-nya menentukan apakah ada sesuatu yang diambil. Jika url: membawa skema transport — oci://… untuk chart OCI, https://….tgz untuk arsip chart langsung, atau root repo https:// yang dipasangkan dengan chart: — chart akan diambil: jenisnya berasal dari skema URL atau dari kind: eksplisit, aggrega pull mengambil dan mem-pin chart di lockfile, dan build mengekstraknya dari cache. Jika url: menamai path filesystem, tidak ada yang diambil dan tidak ada yang di-pin — chart dibaca dari disk, ditambatkan persis seperti bentuk string polos di atas.

spec:
capability: helm
source:
kind: helm-oci-chart
url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned
version: "1.0.0"

Hanya url: yang menentukan dari mana chart dibaca. Field lainnya memilih apa yang akan diambil, sehingga untuk sebuah path field tersebut tidak memilih apa pun — field tersebut tetap sampai ke template milik Recipe sendiri sebagai .source.*.

Vendoring chart secara lokal didukung sebagai alternatif untuk pengambilan, dan tidak diwajibkan. Skema menerima objek terstruktur terbuka.

Chart pada path source harus berisi Chart.yaml yang valid. Render sourced yang gagal memuat chart menampilkan error Helm SDK yang mendasarinya apa adanya. source: "" yang kosong bukan urusan helm: nilai itu tidak menamai mode tanpa source maupun mode sourced, sehingga penolakan yang diterimanya sama apa pun provider yang dituju Recipe, dan penolakan itu terjadi saat Recipe dibaca, sebelum chart apa pun dimuat dan sebelum provider ini dijalankan. Perintah mana yang melaporkannya dijelaskan dalam entities/recipe.md “Source field scheme inventory” dan errors/fatal-halts.md “Recipe source: is an empty string (source: Recipe berupa string kosong)”.

Mode bersumber

Sebuah Recipe dengan source: <chart-path> dan valuesMapping: menjalankan pipeline berikut pada perenderan dasar:

  1. Chart di <chart-path> dimuat melalui Helm Go SDK.
  2. Template valuesMapping dievaluasi terhadap konteks template milik Recipe. Keluaran YAML-nya diperlakukan sebagai overlay nilai untuk chart tersebut.
  3. Overlay digabungkan dengan nilai bawaan values.yaml milik chart, satu kali; kunci overlay menang jika terjadi tabrakan (semantik standar helm install --values dari Helm). Kunci yang diatur overlay ke null menghapus nilai bawaan chart untuk kunci tersebut — di tingkat teratas, di dalam tabel, atau di nilai sebuah dependensi — seperti yang dilakukan helm install --values, sehingga template chart membaca kunci itu sebagai tidak ada; null pada kunci yang tidak diberi nilai bawaan oleh chart sampai ke template sebagai null.
  4. Helm SDK merender template chart terhadap nilai yang telah digabungkan.
  5. Aggrega menyisipkan metadata provenansnya ke dalam manifest yang dirender melalui penulisan ulang YAML setelah perenderan, sehingga keluaran mode sourced membawa pelabelan yang sama dengan keluaran mode workload. Nilai identitas menjadi label (app.kubernetes.io/name, aggrega.ai/component-id, aggrega.ai/provider, aggrega.ai/provider-version, aggrega.ai/environment, dan — bila diatur — aggrega.ai/aggregate-name, aggrega.ai/compiler-version), masing-masing ditulis dalam bentuk yang diterima Kubernetes sebagai nilai label; nilai yang tidak dapat direpresentasikan oleh label Kubernetes menjadi anotasi (aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave jika wave bukan 0, dan nilai apa adanya dari setiap label yang nilainya harus ditulis ulang — Aggregate bernama imported/flow diberi label imported-flow dan anotasi imported/flow di bawah kunci yang sama). Aturan penulisan ulang dinyatakan di well-known-annotations.md “Label provenans yang dihasilkan oleh penyedia”.
  6. Berkas keluaran ditempatkan secara datar di direktori keluaran Recipe, satu per sumber daya yang dirender, dengan nama <name-basis>-<kind>[-<namespace>]-<name>.yaml — basis yang sama dengan yang menjadi dasar penurunan nama rilis di bawah, diikuti oleh kind milik sumber daya itu sendiri, namespace jika ada, dan namanya, masing-masing diubah ke huruf kecil dengan setiap deretan karakter lain diringkas menjadi satu tanda hubung. Untuk komponen biasa, basis tersebut adalah identitas komponen itu sendiri, yang juga dibawa oleh label aggrega.ai/component-id milik sumber daya; untuk chart yang disediakan oleh penulis lampiran Feature, basis tetap milik komponen host, sedangkan label membawa identitas lampiran itu sendiri. Dokumen yang tidak membawa kind atau nama diberi nama berdasarkan path template-nya. Tata letak direktori chart diratakan: tidak ada subdirektori templates/ dalam keluaran yang dirender, dan dua template di subdirektori berbeda yang memiliki nama berkas sama tetap menjadi dua berkas karena nama berasal dari sumber daya, bukan dari template. Berkas yang disebut oleh blok artifacts: milik Recipe tidak ditempatkan di sini: berkas itu berada satu direktori di bawahnya, di bawah direktori yang dinamai sesuai komponen yang mendeklarasikannya, karena berkas semacam itu dinamai menurut kunci yang ditulis penulisnya, bukan menurut sumber daya yang dibawanya — sehingga tanpa direktori tersebut dua komponen yang terikat pada satu Recipe akan menulis satu path yang sama, tanpa ada penulis yang dapat memisahkannya.

Namespace yang menjadi target perenderan chart dibaca dari anotasi aggrega.ai/namespace yang diturunkan secara berjenjang dari boundary dan sampai ke chart sebagai namespace rilisnya; bila tidak ada boundary yang mendeklarasikannya, chart dirender terhadap default. Jika sebuah boundary mendeklarasikannya, setiap sumber daya namespaced yang dirender chart tanpa namespace — tanpa metadata.namespace, atau dengan nilai kosong atau null — dikeluarkan dalam namespace yang dideklarasikan, yaitu tempat sumber daya itu akan diletakkan jika chart dipasang dengan Helm di bawah namespace rilis tersebut, dan berkasnya dinamai dengan segmen namespace persis seperti sumber daya yang template-nya menulis field tersebut. Sumber daya yang template-nya menulis namespace mempertahankannya, apa pun namespace yang disebutkannya. Sumber daya cluster-scoped tetap tanpa namespace. Apakah sebuah kind bersifat namespaced ditentukan oleh cakupan API Kubernetes itu sendiri untuk kind yang dilayani API sendiri, dan untuk kind kustom oleh scope yang dideklarasikan untuknya oleh CustomResourceDefinition dalam perenderan yang sama — dari template chart atau dari direktori crds/-nya. Sumber daya dari kind yang tidak diklasifikasikan oleh keduanya dibiarkan seperti yang ditulis chart, dan build melaporkannya, sekali per kind, dengan menyebut kind dan grup API-nya; demikian pula dokumen kind: List, yang item-itemnya tidak ditempatkan. Jika tidak ada boundary yang mendeklarasikan namespace, tidak ada yang ditempatkan dan tidak ada yang dilaporkan: sumber daya yang ditulis chart tanpa namespace dikeluarkan tanpa namespace, dan ditempatkan oleh apa pun yang dipilih alat penerapannya.

Laporan tersebut berupa peringatan pada build, yang tetap selesai:

warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places them

Jika chart memiliki nilai yang merender CustomResourceDefinition untuk kind tersebut, atau nilai yang menulis namespace itu sendiri, mengaturnya melalui valuesMapping milik Recipe akan menempatkan sumber daya semacam itu.

Versi Kubernetes yang menjadi sasaran render sebuah chart

Template sebuah chart membaca versi Kubernetes yang menjadi sasaran render-nya sebagai .Capabilities.KubeVersion, dan banyak di antaranya memilih versi API, sebuah field, atau seluruh mekanisme berdasarkan versi itu — misalnya token service account yang diproyeksikan mulai 1.21, dan token bawaan di bawahnya. Build tidak memiliki cluster untuk ditanyai, sehingga versi tersebut adalah versi yang Anda nyatakan, di tempat Release menyatakan lokasi deploy sebuah komponen: anotasi aggrega.ai/kubernetes-version pada sebuah boundary, atau pada sebuah komponen, yang mengalahkan anotasi boundary-nya, dan diturunkan secara bertingkat persis seperti aggrega.ai/namespace.

spec:
boundaries:
production:
annotations:
aggrega.ai/kubernetes-version: "1.31"
components:
api: {}
legacy:
annotations:
aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older cluster

Nilai tersebut dibaca dengan cara helm template --kube-version membaca flag-nya, sehingga nilai ini menerima bentuk-bentuk yang diterima flag itu dan sebuah chart membaca persis apa yang akan diberikan flag itu: "1.31" dibaca sebagai v1.31, "v1.31.2" sebagai v1.31.2, dan teks setelah angka tetap ada di .Capabilities.KubeVersion.Version sebagaimana ditulis — "1.29.3-gke.100" dibaca sebagai v1.29.3-gke.100 — sedangkan .Capabilities.KubeVersion yang dicetak utuh membaca versi tanpa teks itu. Chart yang membandingkan .Capabilities.KubeVersion.Version dengan semverCompare membaca sufiks seperti itu sebagai pre-release, sehingga batasan tanpa batas bawah -0, seperti ">=1.21", tidak cocok dengannya, dan nilai yang mengandung spasi di sekelilingnya dibaca bersama spasi itu — " 1.30 " dibaca sebagai "v 1.30 " — dan langsung gagal dalam perbandingan seperti itu: tulis versi tanpa tambahan apa pun jika sebuah chart membandingkannya. Nilai yang bukan versi — "one.two", "latest", satu angka saja — menghentikan build dengan kondisi untuk nilai yang tidak dapat direpresentasikan oleh sebuah plugin, dengan menyebutkan nilai tersebut, komponennya, dan boundary-nya; chart tidak pernah di-render untuk versi lain sebagai gantinya. Lihat A Kubernetes version the helm provider cannot render a chart for (Versi Kubernetes yang tidak dapat digunakan provider helm untuk me-render chart). Nilai kosong diperlakukan sebagai tidak ditetapkan.

Jika tidak ada anotasi yang menyebutkan versi, sebuah chart di-render untuk versi yang digunakan oleh helm template standar dari rilis helm yang sama, yaitu versi pustaka klien Kubernetes yang digunakan untuk membangun provider: provider yang dibangun dengan pustaka klien v0.37 me-render untuk Kubernetes v1.37.0. Dengan demikian, sebuah chart di-render di Aggrega sebagaimana helm template milik pembuatnya sendiri me-render-nya, dan nilai default hanya berubah ketika pustaka klien yang digunakan untuk membangun provider berubah. Sebutkan versi cluster tujuan deploy Anda setiap kali versinya berbeda: chart yang di-render untuk versi yang lebih baru daripada yang dijalankan cluster dapat menghasilkan versi API yang tidak dilayani cluster tersebut.

Hanya versi yang ditetapkan dengan cara ini. Setiap kapabilitas lain yang dibaca chart — .Capabilities.APIVersions dan .Capabilities.HelmVersion — adalah kapabilitas bawaan pustaka helm, sehingga API yang dilayani cluster dari CustomResourceDefinition yang terpasang tidak dilaporkan ke chart. Rentang kubeVersion milik chart di Chart.yaml-nya tidak dibandingkan dengan versi tersebut: helm template menolak chart yang rentangnya mengecualikan versi sasaran render-nya, sedangkan build tetap me-render-nya. Anotasi ini hanya memengaruhi chart yang di-render dari source dan tidak ada yang lain: Workload yang disintesis dan body artifacts: tidak membaca .Capabilities, dan provider helm-chart meneruskan chart-nya tanpa di-render, untuk di-render saat dipasang.

Mengecualikan dokumen hasil render. Provider ini mematuhi entri omits: yang dideklarasikan sebuah Recipe atau FeatureRecipe, dalam mode ini dan tidak dalam mode lain: Workload yang disintesis dan body artifacts: di-render tanpa entri tersebut. Setiap dokumen yang di-render chart — dari sebuah template atau dari sebuah file di direktori crds/-nya — dicocokkan dengan setiap entri yang berlaku untuk build, dan dokumen yang disebutkan oleh entri mana pun dikecualikan. Sebuah entri menyebutkan dokumen berdasarkan kata-kata yang dibawa dokumen itu sendiri, kata-kata yang sama yang membentuk nama file output dan render fact-nya: kind-nya, metadata.name-nya, dan, hanya jika entri menyebutkannya, namespace tempat dokumen berada — namespace yang ditulis template-nya, atau namespace yang dideklarasikan boundary jika provider ini menempatkan dokumen tersebut seperti dijelaskan di atas. Namespace itu tidak pernah berupa namespace yang sekadar menjadi sasaran render chart: tanpa namespace yang dideklarasikan, chart di-render terhadap default, tetapi dokumen yang template-nya tidak menulis namespace tidak berada di namespace mana pun, sehingga entri yang menyebutkan default tidak cocok dengannya. Dokumen tanpa kind atau tanpa name tidak cocok dengan entri mana pun. Dokumen yang dikecualikan di-render lalu dibuang setelah nama setiap file ditetapkan, sehingga setiap dokumen yang dipertahankan diberi nama dan ditulis persis seperti tanpa entri tersebut, dan dokumen yang dikecualikan tidak mencapai apa pun yang dilakukan build sesudahnya — tidak ada file, tidak ada nama dalam perbandingan yang menolak dua kontributor yang mendarat di satu path, tidak ada render fact yang dibaca sebuah Feature, tidak ada apa pun yang diserahkan ke langkah pipeline. Provider melaporkan berapa banyak dokumen yang cocok dengan setiap entri, dan entri yang tidak cocok dengan satu pun menghentikan build; lihat An omits entry left out nothing the source rendered (Sebuah entri omits tidak mengecualikan apa pun yang di-render source).

Rilis Helm tempat chart dirender

Provider ini merender dengan SDK Helm 4, pada v4.3, sehingga chart membaca apa yang diberikan oleh helm template milik Helm 4 sendiri, dan chart serta nilai yang sama merender byte yang sama pada setiap build. Chart yang ditulis dan diperiksa terhadap Helm 3 dapat mengamati perilaku Helm 4 berikut:

  • .Capabilities.HelmVersion melaporkan versi Helm 4, yaitu v4.3.
  • Versi Kubernetes bawaan adalah v1.37.0, karena Helm 4 pada v4.3 dibangun terhadap pustaka klien v0.37, dan .Capabilities.APIVersions adalah kumpulan versi API pustaka klien tersebut. Sebutkan versi yang dijalankan klaster Anda, seperti yang dijelaskan dalam Versi Kubernetes tempat chart dirender.
  • Nilai bawaan chart null dibuang. Kunci yang diatur ke null oleh values.yaml milik chart — di tingkat teratas atau di dalam tabel — tidak ada dalam .Values kecuali nilai yang diberikan Recipe mengaturnya, sehingga hasKey melaporkannya tidak ada, toYaml menghilangkannya, dan values.schema.json milik chart diperiksa terhadap nilai tanpa kunci tersebut.
  • Block scalar mempertahankan jeda baris terakhirnya sebelum ---. Dokumen yang berakhir dengan block scalar dan diikuti dokumen lain dari templat yang sama mempertahankan jeda baris terakhir scalar tersebut, sehingga ditulis | alih-alih |-.
  • .Chart adalah map yang dikunci berdasarkan nama field. .Chart.Name, .Chart.Version, .Chart.AppVersion dan field lainnya dibaca seperti sebelumnya, tetapi toYaml .Chart atau toJson .Chart.Maintainers mencetak kunci sebagai Name, AppVersion dan seterusnya, dengan field kosong tetap ada, dan field yang tidak dimuat metadata chart dibaca sebagai kosong alih-alih menggagalkan render.
  • .Capabilities.KubeVersion.Version mempertahankan teks versi sebagaimana ditulis, seperti dijelaskan di atas untuk anotasi aggrega.ai/kubernetes-version.
  • values.yaml yang memuat beberapa dokumen YAML dibaca secara utuh, dengan dokumen yang lebih akhir digabungkan di atas dokumen sebelumnya.
  • .Files.Lines dari file kosong tidak mengembalikan baris apa pun alih-alih menggagalkan render.
  • Fungsi templat tambahan Helm 4 — mustToYaml, mustToJson, mustToToml, mustToDuration dan konversi duration… — tersedia bagi templat chart.
  • Dependensi yang diberi alias dua kali memberi setiap alias salinannya sendiri dari dependensi milik dependensi tersebut.
  • Validasi skema nilai menerima atau menolak secara berbeda hanya pada kasus tepi: bagian lokal email yang diberi tanda kutip, NaN dan bilangan tak hingga, bilangan yang dibandingkan dengan non-bilangan dalam enum dan const, serta lokasi yang dilaporkan untuk propertyNames, contentSchema atau item array berikutnya yang gagal.

Templat yang gagal dieksekusi oleh mesin itu sendiri — misalnya nilai yang dibaca melalui tabel yang tidak ada — dilaporkan dalam bentuk Helm 4: file, baris, dan kolom templat pada barisnya sendiri, lalu apa yang sedang dieksekusi dan pesannya, dengan indentasi, untuk setiap templat yang dilalui kegagalan tersebut. fail atau required milik chart sendiri tetap menggunakan bentuk satu baris execution error at (<file>:<line>:<col>): <message>, demikian pula galat yang dikembalikan fungsi templat.

Cara nama rilis diturunkan

Chart bersumber dirender terhadap sebuah nama rilis, yang sampai ke setiap templat sebagai .Release.Name. Chart lazimnya menamai sumber daya berdasarkan nama tersebut, sehingga nama rilis merupakan identitas di dalam kluster, bukan sekadar label pada build.

Nama rilis adalah bentuk terenkode dari basis yang sama yang menjadi awalan nama file keluaran sumber daya yang dirender, sehingga keduanya adalah satu nama yang ditulis dua kali. Basis tersebut adalah instance_id untuk komponen biasa, dan identitas tersusun yang dibawa oleh Feature yang dilampirkan pada sebuah batas. Untuk chart yang disediakan oleh penulis lampiran Feature, basisnya adalah nama komponen host: templat chart itu sendiri dirender terhadap nama rilis, sehingga menurunkannya dari lampiran justru akan mengganti nama sumber daya yang dideklarasikan chart, di kluster tempat sumber daya itu sudah di-deploy. Sumber daya tersebut tetap membawa identitas lampiran itu sendiri dalam label aggrega.ai/component-id miliknya — nama sebuah sumber daya dan pemiliknya adalah dua pertanyaan terpisah di sini, dan hanya untuk komponen biasa keduanya memiliki jawaban yang sama. Nama rilis Helm menerima himpunan karakter yang lebih sempit daripada yang dapat dibawa sebuah identitas: huruf kecil, digit, tanda hubung, dan titik, diawali dan diakhiri dengan huruf kecil atau digit, hingga 53 karakter. Alih-alih mengganti karakter yang tidak diterima target, penurunan ini menuliskannya secara eksplisit, sehingga dua identitas komponen yang hanya berbeda dalam tanda baca atau huruf besar-kecil selalu menghasilkan dua nama rilis.

  • Huruf kecil dan digit diteruskan persis seperti yang ditulis.
  • Tanda hubung dipertahankan seperti yang ditulis di mana pun karakter sesudahnya diteruskan secara langsung dan bukan huruf kecil z. Tanda hubung yang diikuti huruf kecil z membuka escape, sehingga tanda hubung yang ditulis pada posisi itu sendiri dituliskan secara eksplisit — api-zone menjadi api-zhzone, yang memungkinkan nama apa pun dibaca kembali tanpa menebak. Tanda hubung yang tidak diikuti apa pun dituliskan secara eksplisit dengan alasan yang sama, sehingga db- menghasilkan db-zh.
  • Setiap karakter lain ditulis sebagai -z diikuti huruf yang menamainya: d untuk titik, u untuk garis bawah, s untuk pemisah path, h untuk tanda hubung yang tidak dipertahankan oleh aturan di atas. Karakter lainnya — termasuk huruf besar — ditulis sebagai x dan titik kode heksadesimal enam digit dari karakter tersebut, dan byte yang tidak mengawali karakter apa pun sebagai b dan nilainya sendiri dalam dua digit.
  • Nilai kosong ditulis -ze, yang tidak dapat dihasilkan oleh nilai tidak kosong mana pun.

Titik ditulis secara eksplisit alih-alih diteruskan, meskipun Helm menerimanya dalam nama rilis, karena Helm mensyaratkan huruf kecil atau digit di kedua sisi titik, sementara penurunan ini menempatkan tanda hubungnya sendiri.

Karena dua Features yang dilampirkan pada satu komponen sama-sama dirender terhadap nama rilis komponen tersebut, dua chart yang masing-masing menamai sumber daya berdasarkan .Release.Name menghasilkan dua sumber daya dengan satu nama. Provider ini melaporkan nama yang dibawa setiap sumber daya yang dihasilkan oleh perenderannya sendiri, dengan cakupan jenis sumber daya tersebut dan, untuk jenis yang disimpan kluster di dalam namespace, namespace-nya, dan build menolak dua kontributor yang mendarat pada satu nama yang sama alih-alih menghasilkan keluaran yang, bila keduanya diterapkan, hanya menyisakan yang terakhir — lihat ../errors/fatal-halts.md “The same name is derived more than once inside the output (Nama yang sama diturunkan lebih dari sekali di dalam keluaran)”. Jenis yang disimpan kluster di luar semua namespace — ClusterRole, CustomResourceDefinition, atau jenis kustom yang dideklarasikan oleh CustomResourceDefinition dalam render yang sama dengan cakupan Cluster — hanya dicakup oleh jenisnya, diklasifikasikan persis seperti klasifikasi penempatan namespace di atas, sehingga dua komponen dari satu keluaran yang masing-masing menulis satu objek semacam itu dengan satu nama ditolak meskipun Release menempatkannya di namespace yang berbeda. Solusinya adalah menyusun nama tersebut, dan koordinat yang dibutuhkan bergantung pada susunannya. Dua lampiran pada satu komponen sudah berbagi host, sehingga lampiranlah yang harus sampai ke templat: teruskan .attachment_name ke dalam chart melalui valuesMapping: milik FeatureRecipe dan tetapkan pada nilai chart mana pun yang menjadi dasar nama sumber dayanya. Satu chart yang dilampirkan pada dua komponen adalah kebalikannya — nama rilis sudah berbeda per host, sehingga sumber daya yang dinamai berdasarkan .Release.Name membawa nama tersendiri di masing-masing host, sedangkan nama literal tidak. FeatureRecipe yang mengirimkan sumber dayanya melalui artifacts: dilaporkan dengan ketentuan yang sama: provider ini membaca nama yang dibawa setiap dokumen yang dihasilkan, baik dokumen itu berasal dari templat chart maupun dari badan artifacts, sehingga nama literal dalam badan semacam itu yang dilampirkan pada dua komponen juga menghentikan build. Badan artifacts adalah templat, jadi susun nama dari .context.rendered_name — nama rilis host, yang berbeda per host dan dieja dengan karakter yang diizinkan untuk nama Kubernetes — dan .attachment_name bila nama itu harus berbeda per host; pada host yang hanya menempatkan satu set artefak, yang tidak melaporkan nama rilis, susun dari .context.instance_id sebagai gantinya. Tidak semua nama dilaporkan, sehingga build yang tidak berhenti belum membandingkan semua yang pada akhirnya akan dibawa keluarannya. Yang paling mungkin Anda temui saat menulis chart adalah sumber daya yang mendeklarasikan generateName, yang diserahkan kepada kluster untuk dilengkapi sehingga belum ada yang dapat dibandingkan. Halaman yang ditautkan di atas memuat daftar lengkapnya.

Jadi, instance_id bernilai api menghasilkan nama rilis api, data.main-db menghasilkan data-zdmain-db, dan db_host menghasilkan db-zuhost. Identitas yang hanya tersusun dari huruf kecil, digit, dan tanda hubung yang dipertahankan oleh penurunan ini muncul persis seperti yang ditulis. Masukan yang identik selalu menghasilkan nama yang identik.

Dua syarat Helm merupakan sifat basis, bukan sifat penurunan: nama rilis harus diawali dengan huruf kecil atau digit, dan panjangnya paling banyak 53 karakter. Basis yang karakter pertamanya ditulis secara eksplisit mengawali namanya dengan tanda hubung yang membuka setiap escape, dan basis yang membawa karakter yang ditulis secara eksplisit akan terenkode lebih panjang daripada saat ditulis. Build menanyakan keduanya kepada provider ini, dan bertindak berdasarkan jawabannya pada saat build, alih-alih menyerahkan penolakan kepada kluster pada saat penerapan — lihat ../errors/fatal-halts.md “The target will not accept a name derived from an authored identity (Target tidak akan menerima nama yang diturunkan dari identitas yang ditulis)”. Tindakannya bergantung pada siapa yang menulis basis tersebut. Nama yang Anda tulis ditolak alih-alih diubah, dan penolakan itu menyebutkan field yang Anda tulis dan batas yang Anda miliki; nama yang disusun Aggrega dipersingkat hingga diterima oleh provider ini.

Kluster menerapkan satu aturan yang lebih ketat daripada Helm pada sumber daya yang dinamai berdasarkan komponen: nama Service harus diawali dengan huruf, sedangkan nama rilis boleh diawali dengan digit. Chart lazimnya menamai Services-nya berdasarkan nama rilis, dan Services dari workload yang disintesis juga diawali dengannya, sehingga provider ini juga menolak nama komponen yang diawali digit, dan melaporkannya sebagai Service name yang tidak dapat digunakan target. Tidak ada panjang yang dapat memperbaiki karakter pertama, sehingga penolakan tersebut tidak menyebutkan panjang apa pun. Jadi, awali instance_id dengan huruf kecil, dan buat cukup pendek agar bentuk terenkodenya tetap muat.

Mengubah basis asal nama rilis diturunkan akan mengganti nama sumber daya kluster yang dinamai chart berdasarkan .Release.Name, serta setiap sumber daya yang disintesis provider ini untuk komponen tersebut, dan Kubernetes tidak mengganti nama sumber daya di tempat. Alat penerap membuat sumber daya dengan nama barunya dan menghapus sumber daya dengan nama lama, yang bagi sumber daya stateful berarti penyimpanan yang terikat pada nama lama dilepaskan. Perlakukan perubahan semacam itu sebagai penggantian yang harus direncanakan — dikosongkan, dimigrasikan, atau dijadwalkan — bukan sebagai pembaruan yang tinggal diluncurkan.

Mode Workload (disintesis)

Sebuah Recipe dengan workload: (inline atau dimuat melalui $import:) menyintesis sumber daya Kubernetes dari intent abstrak Workload. Skema Workload didokumentasikan di entities/workload.md; bagian ini membahas apa yang dihasilkan oleh provider helm.

Untuk setiap node:

  • Satu objek controller yang dipilih oleh form milik Workload: stateless (dan default) menghasilkan sebuah Deployment, stateful sebuah StatefulSet, daemon sebuah DaemonSet, task sebuah Job, scheduled sebuah CronJob yang spec.schedule-nya adalah field schedule milik Workload (ekspresi cron 5 field atau makro @); workload scheduled tanpa jadwal, atau dengan jadwal yang salah bentuk, dihentikan secara eksplisit. Workload scheduled yang mendeklarasikan suspend: true menghasilkan CronJob-nya dengan spec.suspend: true, sehingga tidak ada eksekusi yang dimulai dari jadwal hingga dilanjutkan kembali, sementara Job tetap dapat dibuat dari CronJob secara manual; workload yang tidak mendeklarasikannya sama sekali tidak menghasilkan kunci suspend. Deployment dan StatefulSet membawa jumlah replika; DaemonSet, Job, dan CronJob tidak membawanya. Workload stateful memerlukan tepat satu Service type: Headless yang dideklarasikan di dalam Workload untuk mengatur StatefulSet; provider menghubungkan serviceName milik StatefulSet ke nama Service tersebut setelah dirender, dan build dihentikan jika tidak ada Service headless yang dideklarasikan (atau jika ada lebih dari satu). Volume persistentTemplate adalah pendamping form: stateful — mendeklarasikannya pada form lain menghentikan build dengan pesan yang menyebutkan perbaikannya.
  • Satu Service per entri services: yang dideklarasikan pada Workload, yang mengekspos port bernama yang dicantumkan oleh spesifikasi service. type entri tersebut menjadi tipe Service — ClusterIP, NodePort, dan LoadBalancer apa adanya, dan Headless sebagai Service ClusterIP dengan clusterIP: None. Entri Loopback justru menghentikan build, dengan menyebutkan node dan service-nya: Service Kubernetes tidak memiliki tipe yang terikat ke alamat loopback host, dan alamat node mana yang didengarkan oleh Service NodePort merupakan pengaturan seluruh cluster, sehingga entri tersebut ditolak alih-alih dirender dengan jangkauan yang tidak dimintanya. Lihat A service type the helm provider cannot render (Tipe service yang tidak dapat dirender oleh provider helm).
  • Satu PersistentVolumeClaim per volume persistent, dengan ukuran dan bentuk dari spesifikasi volume tersebut. Volume persistentTemplate tidak menghasilkan claim tersendiri: volume itu menjadi entri volumeClaimTemplates di dalam spesifikasi StatefulSet itu sendiri, itulah sebabnya volume tersebut merupakan pendamping form: stateful.

Nama sumber daya. Setiap sumber daya yang dihasilkan mode ini untuk sebuah component dinamai berdasarkan nama release component tersebut — nama yang sama yang digunakan untuk merender chart bersumber, diturunkan sebagaimana dijelaskan dalam Cara nama release diturunkan — dan provider melaporkan nama tersebut ke build sebagai {{ .context.rendered_name }}. Objek controller membawa nama release itu sendiri; setiap Service adalah <release name>-<service key>; setiap claim tersendiri adalah <release name>-<volume>, dan volume pod merujuk tepat ke claim tersebut; secret yang dikirim sebagai file di-mount dari volume pod bernama <release name>-secret-<slot>, dengan slot ditulis dalam alfabet yang diterima cluster, seperti halnya nama release — sehingga slot server_certificate di-mount dari <release name>-secret-server-zucertificate, dan slot yang dibaca melalui koneksi menulis titik setelah nama koneksi dengan cara yang sama; serviceName milik StatefulSet adalah nama Service headless yang dihasilkannya; dan Workload yang diekspos hanya melalui nama eksternal menghasilkan satu Service yang membawa nama release. Jadi component api menghasilkan Deployment api dan Service default api-default, dan component my_api menghasilkan my-zuapi dan my-zuapi-default — nama yang diterima cluster, sedangkan identitas sebagaimana ditulis tidak akan diterima. Recipe yang memublikasikan alamat salah satu Service tersebut membangunnya dari {{ .context.rendered_name }}, sebagaimana ditunjukkan ../templates/rendered-resource-names.md; untuk component yang namanya tidak mengandung garis bawah maupun huruf kapital, nama release sama dengan instance_id-nya, sehingga nama-namanya terbaca persis seperti identitasnya. Workload yang disintesis oleh attachment Feature adalah satu-satunya pengecualian: workload tersebut dinamai berdasarkan identitas komposit attachment itu sendiri — nilai yang dibawa label aggrega.ai/component-id-nya — karena attachment dirender terhadap component host-nya, dan nama release yang diturunkan di sana akan menamai workload attachment berdasarkan host dan bertabrakan dengan milik host sendiri. Identitas itu tidak pernah membawa huruf kapital: huruf kapital pada nama host atau nama attachment ditulis sebagai escape, sama seperti setiap karakter lain yang ditolak nama sumber daya, sehingga attachment worker pada component myApi menghasilkan Deployment cfr--my-zx000041pi--worker dan Service default cfr--my-zx000041pi--worker-default, dan setiap nama yang dibawa workload itu diterima oleh cluster.

Panjang nama yang bergantung pada Workload. Dua dari nama-nama ini dikenai batas tersendiri oleh cluster, dan build memeriksa keduanya begitu Workload diresolusi, alih-alih membiarkan penolakan terjadi di cluster saat penerapan. Nama CronJob paling banyak 52 karakter, lebih pendek daripada nama lain di cluster karena controller menamai Job setiap eksekusi menurut CronJob dengan akhiran yang ditambahkan; nama ini hanya diperiksa untuk Workload scheduled. Setiap nama Service, <release name>-<service key>, paling banyak 63 karakter. Jika salah satu batas terlampaui, apa yang terjadi bergantung pada siapa yang menulis nama itu, persis seperti untuk nama release: nama komponen yang Anda tulis ditolak, dengan build berhenti pada kunci spec.components yang Anda tulis beserta jenis nama, panjangnya, dan anggaran yang dimiliki nama Anda — lihat ../errors/fatal-halts.md “The target will not accept a name derived from an authored identity (Target tidak akan menerima nama yang diturunkan dari identitas yang ditulis)”; identitas yang disusun, seperti identitas yang menjadi dasar penamaan workload sebuah lampiran Feature, dipendekkan sampai setiap nama muat. Nama Service dibangun dari nama komponen Anda dan sebuah kunci yang dideklarasikan workload — di Recipe, atau di FeatureRecipe — sehingga penolakan menyebutkan kunci tersebut dan tempat workload mendeklarasikannya, spec.workload.services.<key>; kunci yang tidak menyisakan ruang untuk nama komponen apa pun harus dipendekkan sendiri. Jadi komponen yang membawa Workload scheduled dapat memiliki nama terenkode hingga 52 karakter, dan komponen web dapat membawa kunci Service hingga 59 karakter. Feature yang dilekatkan pada seluruh boundary memiliki identitas yang ditetapkan sebelum Workload-nya diresolusi, karena tempat output-nya dirakit dapat bergantung pada identitas itu, sehingga tidak satu pun batas diperiksa untuk sumber daya yang disintesisnya.

Setiap sumber daya yang dihasilkan membawa label dan anotasi provenans Aggrega lengkap ditambah pasangan selector (app: <instance_id>) yang menghubungkan Deployment/StatefulSet dengan Service-nya. Nilai label menerima identitas sebagaimana ditulis, sehingga selector mempertahankannya sementara nama-nama di atas menggunakan nama release. Nama container dalam Deployment yang dirender adalah kunci container milik Workload dengan karakter . dan _ diganti dengan - (sanitasi nama Kubernetes).

Transport port. Port container yang mendeklarasikan transport menghasilkannya apa adanya sebagai protocol: pada containerPort yang dirender, dan setiap port Service yang menyebut port container tersebut membawa nilai yang sama — transport dideklarasikan sekali, pada port container, sehingga eksposurnya tidak dapat berbeda darinya. Port yang tidak mendeklarasikan transport tidak menghasilkan kunci protocol pada kedua sumber daya, sehingga default cluster tetap berlaku. Ketiga nilai yang diterima Workload (TCP, UDP, SCTP) dihasilkan apa adanya; helm tidak memerlukan degradasi, karena Kubernetes mengekspresikan masing-masing secara langsung.

Berjalan di jaringan node. Workload yang mendeklarasikan hostNetwork: true menghasilkan hostNetwork: true pada spesifikasi pod yang dirender, sehingga pod berjalan di namespace jaringan node itu sendiri dan port yang dibuka container-nya dapat dijangkau pada alamat node. Kubernetes mengekspresikan pilihan ini secara langsung, sehingga tidak ada yang didegradasi. Deklarasi ini hanya mencapai spesifikasi pod: deklarasi ini tidak menambah, menghapus, atau menulis ulang port apa pun, dan Service yang dihasilkan identik dengan maupun tanpanya. Workload yang tidak mendeklarasikannya sama sekali tidak menghasilkan kunci hostNetwork.

Kuantitas sumber daya. Setiap kuantitas yang disalin provider ke dalam manifest dihasilkan apa adanya, dan masing-masing terlebih dahulu diperiksa terhadap bentuk kuantitas yang dijelaskan dalam Workload → Kuantitas sumber daya: nilai resources.requests dan resources.limits setiap container dan init container — cpu, memory, dan setiap extended resource seperti nvidia.com/gpu — serta ephemeral.sizeLimit, persistent.size, dan persistentTemplate.size setiap volume. Pemeriksaan dijalankan pada Workload sebagaimana dievaluasi oleh template Recipe, sehingga nilai yang datang melalui infra atau parameter Release dinilai berdasarkan hasil rendernya. Nilai di luar bentuk tersebut menghentikan build dengan TRANSLATION_ERROR yang menyebutkan node, path field dalam Workload, dan nilainya — misalnya containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number — padahal tanpa pemeriksaan ini chart akan ter-build tanpa masalah lalu ditolak oleh cluster saat instalasi. cpu, memory, atau sizeLimit yang dibiarkan kosong dihilangkan dari manifest sehingga tidak diperiksa; nilai extended resource atau ukuran persistent yang dibiarkan kosong akan tetap dihasilkan, sehingga ditolak. Pemeriksaan hanya menilai bentuk: apakah cluster dapat menjadwalkan jumlah tersebut bukanlah sesuatu yang dapat diketahui provider saat build.

Penamaan file output memiliki dua bentuk. Objek controller dinamai berdasarkan nama release dan kind-nya — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. File per sumber daya dinamai berdasarkan sumber daya yang dibawanya, dengan kind di akhir: <release name>-<svcName>-service.yaml dan <release name>-<volName>-pvc.yaml, masing-masing diambil dari metadata.name milik sumber daya tersebut sesuai konvensi nama sintesis di entities/workload.md. Workload yang diekspos hanya melalui nama eksternal menghasilkan <release name>-service.yaml, karena tidak ada kunci service untuk dibawa.

Fakta render

Selain file yang dirender, Provider ini melaporkan empat fakta render tentang setiap node: apa yang dinyatakan oleh dokumen Kubernetes yang dihasilkannya tentang pod, selector, port, dan namespace tempat masing-masing dokumen dihasilkan. FeatureRecipe yang dilampirkan pada komponen membaca fakta komponen itu sendiri di .context.render_facts; FeatureRecipe yang menetapkan readsCallerRenderFacts: true juga membaca, pada setiap entri .context.used_by, fakta komponen yang terhubung ke host-nya, dan FeatureRecipe yang menetapkan readsTargetRenderFacts: true membaca, pada setiap entri .context.uses, fakta komponen yang terhubung dari host-nya. Dengan cara itulah sebuah Feature dapat menyebut pod dari komponen yang memanggil host-nya, atau dari komponen yang dijangkau host-nya — misalnya network policy yang mengizinkan tepat pod-pod tersebut — berdasarkan apa yang benar-benar dihasilkan oleh render mereka, tanpa seorang pun menuliskan ulang label secara manual. Nama dan entri di bawah ini adalah kontrak Provider ini.

FaktaSatu entri perSetiap entri memuat
pod_template_labelspod template yang dihasilkan: spec.template milik Deployment, StatefulSet, DaemonSet, ReplicaSet, atau Job, job template milik CronJob, dan Pod tunggal, yang merupakan template-nya sendirikind, name, dan namespace dari resource yang memuat template; labels, label template tersebut
controller_selectorsDeployment, StatefulSet, DaemonSet, ReplicaSet, Job, dan CronJob yang dihasilkankind, name, namespace; match_labels, matchLabels dari selector-nya
service_selectorsService yang dihasilkanname, namespace; selector, label yang menjadi tujuan traffic-nya
container_portscontainer dari pod template yang mendeklarasikan daftar ports, termasuk init containerkind, name, dan namespace dari resource yang memuat template; container, nama container; ports, satu entri per port dengan name, container_port, dan protocol-nya

Cara membaca fakta:

  • Setiap fakta adalah daftar. Template selalu melakukan iterasi atas fakta, bahkan ketika fakta itu hanya berisi satu entri; tidak ada nilai tunggal yang dapat dibaca tersendiri.
  • Keempatnya, pada setiap render. Masing-masing dilaporkan setiap kali Provider ini merender node, sebagai daftar kosong jika render tidak menghasilkan apa pun yang dideskripsikannya — komponen yang chart-nya hanya menghasilkan ConfigMap melaporkan empat daftar kosong. Render oleh Provider lain tidak melaporkan satu pun nama ini, dan nama yang tidak dilaporkan siapa pun terbaca sebagai kosong.
  • Dibaca dari apa yang dihasilkan, pada setiap jalur. Fakta berasal dari dokumen yang dihasilkan render, mode mana pun yang menghasilkannya: manifest hasil render chart, manifest Workload yang disintesis, dan manifest yang ditempatkan penulis melalui artifacts:, yang melaporkan tepat apa yang dimuat manifest tersebut. Fakta dibaca dalam pass yang sama, atas dokumen yang sama, dengan nama resource yang dilaporkan Provider ini untuk pemeriksaan nama duplikat pada build. Label provenance milik resource sendiri merupakan bagian dari apa yang dimuatnya, sehingga labels sebuah Pod tunggal menyertakannya; pod template milik chart atau artifact mempertahankan label yang ditulis penulisnya.
  • Entri dapat berasal dari render komponen itu sendiri dan dari render Features-nya. Satu komponen dapat dirender oleh lebih dari satu pemanggilan — misalnya sebuah chart dan sebuah penempatan artifacts: — dan daftar yang diperoleh satu nama dari pemanggilan-pemanggilan itu digabungkan menjadi satu, sesuai urutan pemanggilan dijalankan. Pada .context.used_by dan .context.uses, fakta komponen di ujung lain sebuah koneksi juga menggabungkan apa yang dirender oleh Features yang dilampirkan padanya, setelah render miliknya sendiri; .context.render_facts hanya memuat render komponen itu sendiri.
  • Sesuai urutan dihasilkan. Entri mengikuti urutan render menghasilkan resource. Map label adalah map berkunci seperti map lain pada konteks, sehingga template yang melakukan iterasi atasnya menemui kunci-kuncinya sesuai urutan kunci.
  • Apa yang dihilangkan dokumen, dihilangkan pula oleh entrinya. Resource yang dinamai dengan generateName tidak memiliki name; resource yang tidak menulis metadata.namespace tidak memiliki namespace, begitu pula resource yang menulisnya kosong atau null, yang juga tidak menyebut namespace; controller yang ditulis tanpa matchLabels — Job yang mengandalkan selector yang dibuat cluster — tidak memiliki match_labels; Service tanpa selector tidak memiliki selector; port tanpa nama atau protokol tidak memiliki keduanya. Bagian lain yang ditulis kosong dilaporkan kosong. protocol hanya dilaporkan jika dokumen menuliskannya, sehingga template yang membutuhkannya menuliskan sendiri default cluster, TCP. container_port berupa angka di mana pun dokumen menuliskannya.
  • namespace adalah yang ditulis dokumen, tidak pernah tebakan. Nilainya adalah metadata.namespace milik resource itu sendiri — untuk pod template, milik resource yang memuatnya, yaitu tempat pod-nya berjalan; namespace yang ditulis di dalam pod template itu sendiri tidak dibaca. Workload yang disintesis menulis namespace yang dideklarasikan boundary-nya pada setiap resource yang dihasilkannya, sehingga entrinya memuat namespace tersebut. Entri sebuah chart memuat apa yang ditulis dokumen yang dihasilkannya: jika boundary mendeklarasikan namespace, namespace tersebut — baik template chart memproyeksikannya maupun Provider menempatkan resource di dalamnya (lihat Mode sourced) — kecuali template menetapkan namespace sendiri, yang kemudian dimuat entri sebagai gantinya; jika tidak ada yang dideklarasikan, release namespace, default, jika template memproyeksikannya, dan tidak ada apa pun jika template tidak menulisnya. Jika tidak ada yang ditulis, entri tidak memuat namespace alih-alih default boundary atau cluster, karena resource semacam itu ditempatkan di mana pun alat yang menerapkan output menempatkannya, yang tidak diketahui saat build berjalan. Template membedakan keduanya dengan optional: {{ optional . "namespace" "" }} kosong tepat ketika dokumen tidak menuliskannya, sehingga Feature yang menempatkan sesuatu di samping pod sebuah komponen dapat membedakan komponen yang namespace pod-nya diketahui dari yang tidak.
  • Dikenali berdasarkan kind dan API group. Pod dan Service dibaca di core group, keempat controller di apps, Job dan CronJob di batch, pada versi group apa pun. Custom resource dari group lain yang kebetulan memuat salah satu nama kind ini tidak dibaca sebagai kind tersebut. matchExpressions milik selector tidak dilaporkan, begitu pula resource yang dibungkus di dalam dokumen kind: List atau nilai yang ditulis melalui merge key YAML.

Apa yang tidak dapat dilihat fakta. Fakta mendeskripsikan dokumen yang dihasilkan build, dan tidak mencakup apa pun yang dibuat cluster kemudian. Pod yang dibuat controller saat runtime dari custom resource — misalnya cluster database milik sebuah operator — tidak muncul di dokumen yang dihasilkan mana pun, sehingga pod tersebut dengan sendirinya tidak ada; demikian pula label yang ditambahkan mutating admission controller saat manifest diterapkan. Feature yang harus mengizinkan pod semacam itu mengambil labelnya dari dokumentasi custom resource itu sendiri, seperti yang akan dilakukan penulis tanpa fakta ini.

FeatureRecipe yang mengizinkan masuk ke pod host-nya tepat pod dari komponen yang memanggilnya, dengan memilih pod milik host berdasarkan selector controller host:

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: admit-callers
version: 1.0.0
spec:
capability: helm
implements: example/admit-callers:1.0.0
readsCallerRenderFacts: true
artifacts:
allow-callers.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: {{ .context.rendered_name }}-allow-callers
spec:
podSelector:
matchLabels:
{{- range .context.render_facts.controller_selectors }}
{{- range $k, $v := .match_labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
policyTypes:
- Ingress
ingress:
- from:
{{- range .context.used_by }}
{{- range .render_facts.pod_template_labels }}
- podSelector:
matchLabels:
{{- range $k, $v := .labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
{{- end }}

Untuk host api yang dipanggil oleh komponen web yang Workload-nya disintesis Provider ini, policy memilih app: "api" dan mengizinkan podSelector yang memuat setiap label pod template web — label yang sama dengan yang dimuat spec.template.metadata.labels milik Deployment yang dihasilkannya. Karena FeatureRecipe menetapkan kunci tersebut, lampirannya dirender setelah setiap komponen selesai dirender, sehingga fakta tersedia mana pun di antara api dan web yang dicapai build lebih dulu; tanpa kunci tersebut, template yang membaca render_facts pada .context.used_by menghentikan build sebelum apa pun dirender.

podSelector di from milik policy mencocokkan pod di namespace policy itu sendiri, sehingga policy di atas mengizinkan pemanggil yang dihasilkan ke dalam namespace tempat policy diterapkan. Pemanggil yang entrinya memuat namespace lain diizinkan dengan memasangkan podSelector-nya dengan namespaceSelector pada label kubernetes.io/metadata.name namespace tersebut, yang ditetapkan Kubernetes pada setiap namespace.

Kekhasan khusus Provider

  • Pengunduhan chart hanya menggunakan handler bawaan Helm. Chart yang diambil dari repositori Helm diunduh dengan handler http dan https bawaan Helm sendiri. Plugin pengunduh Helm — yang dipasang untuk perintah helm, atau yang berada di direktori tempat build dijalankan — tidak pernah digunakan, sehingga isi direktori tersebut tidak dapat mengubah cara chart diambil.

  • Injeksi provenans. Jalur sourced dan synthesized menghasilkan himpunan label dan anotasi yang sama; render sourced menyuntikkannya melalui penulisan ulang YAML pasca-render (setelah Helm SDK selesai merender), sehingga penulis chart tidak perlu meneruskan label Aggrega melalui template mereka sendiri.

  • Urutan environment — entri yang membaca Secret lebih dulu. Daftar env pada container yang disintesis memuat dua jenis entri: setiap entri attachments yang dikirim as: env membaca nilainya dari Secret melalui valueFrom.secretKeyRef, dan setiap entri variables memuat value biasa. Provider menulis setiap entri yang membaca Secret lebih dulu dan setiap variabel biasa sesudahnya, masing-masing jenis dalam urutan penulisannya, dan mencantumkan sumber envFrom secara terpisah di bawah envFrom. Kubernetes mengekspansi referensi $(NAME) dalam nilai env dari entri yang tercantum sebelumnya dalam container yang sama, tidak pernah dari entri yang tercantum sesudahnya, sehingga urutan ini memungkinkan variabel biasa menyusun nilai yang dibaca dari Secret melalui referensi, sementara rahasianya sendiri tetap berada di Secret:

    containers:
    api:
    image: "api:1.0"
    variables:
    DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"
    attachments:
    DB_PASSWORD: { from: db-credentials, as: env }

    Container hasil render mencantumkan DB_PASSWORD sebelum DATABASE_URL, sehingga proses menerima URL dengan kata sandi sudah terpasang. Sebuah variabel juga dapat mereferensikan variabel apa pun yang ditulis sebelumnya, sehingga urutan penulisan tetap bermakna di dalam variables. Init container mengikuti urutan yang sama. Container yang memberikan satu nama sebagai entri variables sekaligus sebagai entri attachments yang dikirim as: env menghentikan build alih-alih menulis kedua entri, karena urutan ini saja yang kemudian akan menentukan nilai mana yang dilihat proses (lihat A container gives one environment variable two values (Sebuah container memberikan dua nilai untuk satu variabel environment)).

  • Kaskade namespace — kedua mode menjangkau resource secara berbeda. Keduanya membaca aggrega.ai/namespace dari kaskade anotasi boundary, dan tidak ada yang mengarang namespace ketika tidak ada boundary yang mendeklarasikannya. Dalam mode synthesized, provider menulis metadata.namespace secara langsung, dan menghilangkan field tersebut sepenuhnya ketika kaskade tidak menghasilkan nilai. Dalam mode sourced, provider menyediakan nilai tersebut sebagai release namespace chart — default ketika kaskade tidak menghasilkan nilai — dan template chart sendiri yang menentukan apakah nilai itu diproyeksikan; jika namespace dideklarasikan, provider kemudian menuliskannya ke setiap resource ber-namespace yang dirender chart tanpa namespace (lihat Mode sourced). Jadi, dengan namespace yang dideklarasikan, kedua mode menempatkan setiap resource ber-namespace di dalamnya — kecuali namespace yang dipatok chart sendiri dan kind yang tidak dapat diklasifikasikan provider. Tanpa deklarasi, keduanya berbeda: chart yang memproyeksikan release namespace menempatkan resource-nya di default, sementara output synthesized tidak menulis namespace, dan chart yang tidak menulis namespace tidak menempatkannya di namespace mana pun, sehingga resource tersebut berakhir di tempat yang ditentukan alat yang menerapkan manifest. Chart lokal yang dibawa FeatureRecipes pustaka standar membaca nilai kaskade secara langsung melalui valuesMapping mereka: dengan begitu field tersebut dapat dihilangkan ketika tidak ada boundary yang mendeklarasikan namespace, sesuai dengan output synthesized, hal yang tidak dapat diungkapkan oleh release namespace saja karena nilainya tidak pernah kosong.

Contoh lengkap

Mode sourced — Recipe yang menunjuk ke chart yang di-vendor:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helm
version: 1.0.0
spec:
capability: helm
implements: core/api-server
source: ./vendor/charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}
service:
type: ClusterIP
port: {{ .values.port }}
env:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"

Mode Workload — Recipe yang mendeklarasikan Workload inline:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-workload
version: 1.0.0
spec:
capability: helm
implements: core/api-server
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
api:
image: "{{ .values.image }}"
ports:
web: {{ .values.port }}
services:
svc:
type: ClusterIP
ports:
web: {{ .values.port }}

Rujukan silang