Provider helm-chart
Provider helm-chart menghasilkan Helm umbrella chart yang dikemas untuk setiap jalur perakitan. Jika provider helm menghasilkan YAML Kubernetes datar untuk dikonsumsi langsung oleh GitOps, helm-chart menghasilkan kerangka chart — Chart.yaml + values.yaml umbrella ditambah satu sub-chart per node yang berkontribusi — yang dapat dipasang oleh perkakas hilir melalui helm install atau di-vendor untuk kustomisasi lebih lanjut per lingkungan. Provider ini merakit per-(path, provider): setiap node yang terikat pada Recipe helm-chart berkontribusi pada umbrella di directory: hasil evaluasi batas yang digabungkan dengan subDirectory: per komponen. Dua batas yang dievaluasi ke jalur yang sama digabungkan menjadi satu umbrella chart yang mencantumkan setiap kontributor sebagai dependensi sub-chart.
Template sub-chart yang disalin dari chart sumber membawa apa yang ditulis penulisnya: nilai syncWave: <integer> milik boundary, helm.sh/hook-weight pada hook, dan label provenans Aggrega hanya sampai ke template itu jika chart menuliskannya. Provider helm adalah yang membubuhkan argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>", dan label provenans pada setiap resource yang direndernya. Artefak yang dimuat dengan $import: yang ditambahkan provider ini ke sub-chart membawa label provenans dan anotasi argocd.argoproj.io/sync-wave, dan tidak membawa helm.sh/hook-weight (lihat “aturan injeksi artifacts:” di bawah). ArgoCD membaca anotasi sync-wave, dan Helm membaca bobot hook.
Halaman ini adalah referensi penulisan untuk provider helm-chart. Untuk pembagian antara helm dan helm-chart, lihat bagian Providers di halaman Status; untuk model komposisi input lintas provider, lihat architecture/16-recipe-input-composition.md.
Jenis input yang didukung
Provider helm-chart menerima dua jenis input:
- Mode bersumber. Sebuah Recipe dengan
source: <chart-path>menunjuk ke direktori chart Helm di disk. Chart tersebut disalin ke dalam struktur umbrella sebagai sub-chart, apa adanya kecualinamemilik chart itu sendiri — lihat “Nama chart yang dimiliki umbrella”; tidak ada rendering atau templating yang dilakukan pada tingkat per node. Peran Aggrega adalah komposisi (perakitan umbrella di seluruh node boundary), bukan evaluasi template. - Mode
artifacts:yang dimuat dengan$import:. Sebuah Recipe dengan entriartifacts:yang ditulis sebagai$import:per entri mendeklarasikan file template tambahan yang disuntikkan oleh provider helm-chart ke direktoritemplates/milik sub-chart setelah penyalinan chart sumber. Setiap file diproses template terlebih dahulu terhadap konteks template Aggrega menggunakan pembatas[[ ]](lihat “aturan injeksiartifacts:” di bawah) sehingga templating Helm{{ }}apa pun dalam file yang sama tetap bertahan hingga renderhelm installdi hilir.
Sebuah Recipe yang menargetkan helm-chart dan mendeklarasikan workload: ditolak sebelum dirender, dengan penolakan yang sama yang diberikan provider mana pun untuk jenis input yang tidak dideklarasikannya — penolakan itu menyebutkan jenis yang didukung provider ini dan mengarahkan penulis ke provider yang melakukan sintesis:
provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (provider tidak mendukung jenis input node (node “api”). Provider “helm-chart” tidak mendukung recipe yang disintesis (provider ini mendukung: sourced); deklarasikan salah satu jenis input yang didukung, atau targetkan provider yang mendukung sintesis)
Pemisahan ini disengaja: sintesis workload (menerjemahkan Workload abstrak menjadi resource Kubernetes) adalah urusan eksklusif provider helm. Peran helm-chart adalah komposisi umbrella + sub-chart untuk chart yang sudah dibuat oleh penulis.
Sebuah Recipe yang menargetkan helm-chart juga dapat mendeklarasikan entri artifacts: berkonten inline (entri yang nilainya berupa block scalar yang membawa isi file secara inline di dalam Recipe, alih-alih referensi yang dimuat dengan $import:). Entri berkonten inline ditempatkan di root sub-chart di bawah key yang ditulis — tanpa prefiks templates/ dan tanpa penyisipan provenance. Template milik chart sendiri membaca file lepas semacam itu melalui .Files.Get / .Files.Glob dari Helm (pola kanonis ConfigMap-dari-file), sehingga file di root chart adalah bentuk yang sah dan kelas satu, bukan kesalahan.
Kedua bentuk dievaluasi dengan pembatas Aggrega [[ ]] sebelum penempatan, sehingga isi dari bentuk mana pun dapat membaca konteks pilar Recipe; {{ }} dalam isi mana pun dibiarkan apa adanya dan menjadi direktif Helm saat helm install di hilir. Yang berbeda di antara kedua bentuk adalah lokasi file ditempatkan dan apakah provenance digabungkan ke dalamnya:
- Entri yang dimuat dengan
$import:adalah file template: setelah evaluasi (lihat “aturan injeksiartifacts:” di bawah) file tersebut disuntikkan ke direktoritemplates/milik sub-chart dengan provenance digabungkan, sehingga Helm me-render-nya sebagai manifest bersama template milik chart sendiri. - Entri berkonten inline adalah file data lepas: setelah evaluasi file tersebut ditempatkan di root chart, tidak berubah dari hasil evaluasi dan tanpa provenance yang digabungkan, untuk dikonsumsi berbasis
.Files.
Aturan injeksi artifacts:
Ketika sebuah Recipe helm-chart mendeklarasikan entri artifacts: melalui $import: per entri, setiap nilai $import: adalah path ke sebuah file templat yang di-resolve relatif terhadap direktori Recipe itu sendiri (direktori yang berisi YAML Recipe di disk). Provider ini:
- Membaca konten setiap file.
- Melakukan pra-templating konten dengan delimiter Aggrega
[[ ]]terhadap konteks template milik Recipe (konteks yang sama dengan yang digunakan untuk mengevaluasivaluesMapping:milik Recipe).{{ }}di dalam konten file dibiarkan apa adanya — bagian tersebut menjadi direktif templat Helm pada saathelm install. - Menulis setiap file ke
charts/<instance-id>/templates/<authored-key>di bawah jalur perakitan umbrella, dengan file-file sebuah bundle bersarang di bawah kunci tersebut. Kunci tempat entri ditulis menentukan nama file; path$import:memilih kontennya dan tidak berkontribusi apa pun pada nama, sehingga struktur direktori di dalam path tersebut tidak pernah sampai ke output.
Disiplin delimiter ganda [[ ]] / {{ }} adalah detail yang paling menentukan. File artefak yang dimuat dengan $import: umumnya dapat mencampur interpolasi waktu Aggrega (misalnya, [[ .values.image ]]) dengan interpolasi waktu Helm (misalnya, {{ .Release.Namespace }}). Setiap pasangan delimiter dijalankan pada fasenya sendiri: Aggrega me-resolve [[ ]] pada waktu kompilasi sebelum file ditempatkan; Helm me-resolve {{ }} pada waktu instalasi setelah umbrella dikirimkan.
Tabrakan nama file antara templat source-chart dan injeksi artefak yang dimuat dengan $import: memunculkan CATALOG_ERROR — diagnostiknya menyebutkan path output yang bertabrakan, misalnya templates/cm.yaml, dan dua jenis input yang menghasilkannya. Penulis menyelesaikan tabrakan tersebut dengan mengganti nama kunci artefak atau templat milik chart itu sendiri.
Kumpulan kunci source:
source: milik provider helm-chart menamai sebuah chart, dan menerima kedua bentuk yang dapat diambil oleh field source:, dibaca persis seperti yang dijelaskan oleh kumpulan kunci source: milik provider helm: sebuah string path sistem berkas polos, dan sebuah objek terstruktur yang url:-nya memuat lokasi. Jika url: menamai path sistem berkas, tidak ada yang diambil dan chart dibaca dari disk; jika memuat skema transport — misalnya oci://…, dengan kind: helm-oci-chart — aggrega pull mengambil dan mengunci chart tersebut, dan build menyalinnya dari cache ke dalam umbrella sebagai sub-chart, dengan ketentuan yang sama seperti chart yang dibaca dari disk.
spec: capability: helm-chart source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Chart pada path sumber harus memuat Chart.yaml yang valid di akarnya; jika tidak ada, sebuah galat yang jelas muncul sebelum penyalinan berjalan. Tata letak direktori chart dipertahankan saat disalin — templates/, values.yaml, Chart.yaml, dan berkas lainnya ada di direktori sub-chart setelah komposisi. Setiap berkas tiba dengan byte yang Anda tulis, hingga komentar, urutan kunci, dan tanda kutip; satu-satunya pengecualian adalah field name pada Chart.yaml milik chart itu sendiri, yang ditetapkan oleh umbrella — lihat “Nama chart yang dimiliki umbrella”.
Kedua cara gagal menamai chart ditolak, dan kedua penolakan itu berasal dari
tempat yang berbeda — hal ini perlu diketahui, karena hanya salah satunya yang berubah jika Anda beralih
kapabilitas. source: yang ada tetapi tidak mendeklarasikan apa pun ditolak oleh
compiler sebelum provider mana pun berjalan, sehingga hasilnya sama apa pun
kapabilitas yang dinamai oleh Recipe; diagnostiknya meminta Anda menghilangkan field tersebut untuk
mode tanpa sumber atau menamai path yang tidak kosong. Menghilangkan source: sama sekali adalah
penulisan yang sah — begitulah cara sebuah Recipe meminta mode tanpa sumber — dan hal itu ditolak
di sini karena helm-chart hanya mendeklarasikan jenis input bersumber, sehingga compiler
menolak kombinasi tersebut dengan pesan yang sama yang diberikannya untuk kapabilitas apa pun yang diminta
untuk jenis input yang tidak dideklarasikannya. Yang menjadi milik helm-chart sendiri adalah deklarasinya, bukan
penolakan tersendiri: untuk resource Kubernetes yang dihasilkan dari blok workload:,
gunakan kapabilitas helm sebagai gantinya.
Recipe yang mendeklarasikan omits: ditolak. Kunci omits:
mengeluarkan dokumen yang dirender sebuah sumber dari build, dan provider ini tidak merender
dokumen apa pun saat build: ia menyalin chart ke dalam umbrella, dan template chart
dirender saat umbrella diinstal. Karena tidak ada yang dirender, tidak ada
yang perlu dikeluarkan, sehingga provider ini tidak mendeklarasikan bahwa ia menghormati kunci tersebut, dan
Recipe atau FeatureRecipe yang mendeklarasikannya ditolak sebelum apa pun disalin — lihat
The provider does not support omits (Provider tidak mendukung omits).
Untuk chart yang Anda simpan di samping Recipe, satu baris dalam .aggregaignore di sana mengeluarkan
sebuah berkas chart sebagai gantinya, mulai saat Recipe berikutnya dikunci; untuk chart
yang diambil dan keluarannya harus kehilangan sebuah dokumen, render chart tersebut melalui provider helm, yang
menghormati kunci tersebut.
Komposisi berbasis path — bentuk umbrella
Provider ini berjalan dalam dua fase untuk setiap path perakitan:
- Penyalinan per kontributor. Untuk setiap node yang terikat pada Recipe helm-chart, provider menyalin seluruh pohon direktori chart sumber ke dalam slot sub-chart. File ditempatkan secara datar di peta output per kontributor; assembler menetapkan
chartssebagai sub-direktori tempat kontributornya berada, dan orkestrator memberi setiap kontributor direktorinya sendiri di sana saat merakit umbrella —charts/<instance_id>/untuk sebuah component. Attachment Feature juga merupakan kontributor — baik ia menyertakan (vendor) sebuah chart maupun merender manifest melalui provider helm — dan mendapatkan direktori di samping direktori component, bukan di dalamnya; lihat “Tempat chart attachment ditempatkan”. - Perakitan umbrella per
(path, provider). Setelah semua penyalinan per node untuk path tersebut selesai, assembler menghasilkanChart.yaml+values.yamlumbrella di root path perakitan. Umbrella mendeklarasikan satu dependensi per node kontributor dan merutekan nilai per node di bawah sub-blok yang dikunci dengan instance-id. Ketika path perakitan menerima kontributor dari lebih dari satu boundary (boundary dengandirectory:yang sama), setiap kontributor ditempatkan sebagai dependensi dalam umbrella yang sama.
Chart.yaml umbrella memiliki bentuk:
apiVersion: v2name: <effective-chart-name> # see "Chart-name resolution" belowversion: 0.1.0description: Aggrega umbrella chart for boundary "<assembly-path>"dependencies: - name: <encoded-instance-id> # the name the placed sub-chart carries version: <user-chart-version> # from the source chart's Chart.yaml alias: <encoded-instance-id> # see "How a name is derived" below repository: file://charts/<instance_id> # the sub-chart's own directoryResolusi nama chart
name chart umbrella di-resolve melalui kaskade anotasi boundary. Anotasi aggrega.ai/chart-name efektif dari setiap boundary kontributor (nilai hasil resolusi kaskade, dengan menelusuri pohon boundary ke atas) menentukan nama umbrella; nilai hasil resolusi dienkode untuk posisi nama chart persis seperti identitas lainnya, sehingga nilai yang hanya memuat huruf, digit, garis bawah, dan tanda hubung yang dipertahankan oleh aturan di bawah mencapai chart apa adanya. Ketika path perakitan menerima kontributor dari lebih dari satu boundary, aggrega.ai/chart-name efektif dari setiap kontributor HARUS di-resolve ke nilai yang sama; ketidakcocokan menghentikan build dengan diagnostik yang menyebutkan nilai-nilai yang bertentangan dan boundary kontributornya.
Kaskade menyelesaikan ketegangan DRY secara alami: deklarasikan aggrega.ai/chart-name sekali pada boundary induk dan boundary anak mewarisinya melalui kaskade; boundary bersaudara tanpa induk bersama harus mendeklarasikan nilai yang cocok secara eksplisit. Boundary yang tidak mendeklarasikan aggrega.ai/chart-name di mana pun dalam kaskadenya akan menggunakan nama aggregate dan jalur perakitan — direktori output umbrella di bawah dist/, misalnya boundaries/data/helm-chart — masing-masing dienkode dan digabungkan seperti dijelaskan di bawah.
name setiap entri dependensi adalah nama yang dibawa oleh sub-chart yang ditempatkan — identitas terenkode milik instance component itu sendiri, nilai yang sama dengan alias — karena alasan yang dijelaskan di “Nama chart yang dimiliki umbrella”. version-nya tetap versi dari Chart.yaml milik chart sumber. Alias membatasi cakupan nilai sub-chart di bawah values.yaml.<alias>.*, sesuai dengan konvensi umbrella-values Helm sehingga nilai per instance diteruskan dengan benar saat umbrella diinstal.
Direktori sub-chart sebuah component mempertahankan instance_id persis seperti yang ditulis, sehingga charts/<instance_id>/ adalah tempat file-filenya ditempatkan dan tujuan yang ditunjuk oleh repository dependensi. Karena itu, dua instance dari chart sumber yang sama dapat berdampingan tanpa bentrokan sistem file, dan masing-masing mempertahankan blok nilainya sendiri di bawah aliasnya sendiri.
name dan repository dependensi adalah string yang berbeda, dan hal itu memang dirancang demikian. name adalah apa yang DIDEKLARASIKAN oleh chart di lokasi tersebut, karena Helm mengikat dependensi ke chart anak berdasarkan nama yang dideklarasikan oleh anak itu sendiri; repository adalah tempat chart tersebut berada. Untuk sebuah component, keduanya kebetulan terbaca sama, karena keduanya diturunkan dari instance id yang sama. Untuk attachment Feature keduanya berbeda — nama yang dideklarasikan membawa identitas tersusun attachment, sedangkan direktori membawa dua koordinatnya yang digabungkan — sehingga membaca salah satunya sebagai yang lain akan merujuk pada sesuatu yang tidak ada.
Tempat chart attachment ditempatkan
Attachment Feature yang menyertakan sebuah chart mendapatkan direktorinya sendiri di samping component tempatnya dilampirkan, satu tingkat di bawah charts/:
charts/├── api/ # the component's own chart├── api--guardrail/ # a Feature attached to `api` under `guardrail`└── api--audit/ # a second Feature attached to the same componentFeature yang dilampirkan pada boundary, bukan pada component, tidak memiliki component host untuk disebutkan, sehingga direktorinya hanya berupa nama instance-nya: charts/aux/.
Mengapa di samping, bukan di dalam. Helm menemukan chart anak di charts/* — satu tingkat, bukan penelusuran rekursif. Chart yang ditempatkan lebih dalam dari itu bukan anak dari apa pun; chart tersebut adalah data di dalam direktori anak lain, yang hanya dapat dijangkau melalui .Files. Jadi, chart yang ditempatkan di dalam direktori chart milik component akan disalin ke output, membuat build berhasil, dan tidak menyumbangkan satu pun resource-nya ke apa yang Anda deploy — tanpa ada yang melaporkannya. Menempatkan setiap kontributor di direktori tingkat atasnya sendiri itulah yang membuat resource attachment dirender.
Umbrella juga mendeklarasikan attachment sebagai salah satu dependensinya. Kedua bagian diperlukan: chart yang ada di bawah charts/ tetapi tidak ada di dependencies: merupakan error lint, dan chart yang dideklarasikan di dependencies: tanpa chart anak yang cocok membuat umbrella menolak untuk dimuat.
Kedua koordinat digabungkan, bukan sekadar disambung. Nama direktori disusun dari host dan instance melalui aturan escaping yang sama yang dijelaskan di bawah, diterapkan pada setiap koordinat sebelum digabungkan dengan --. Menyambungkannya langsung dengan -- akan menimbulkan ambiguitas: host bernama a--b dengan instance c, dan host a dengan instance b--c, akan menuju satu direktori yang sama. Mengenkode setiap koordinat terlebih dahulu menjaga keduanya tetap terpisah, sehingga -- yang ditulis di dalam sebuah koordinat muncul sebagai -zh-.
Apa yang diterima nama direktori. Huruf ASCII besar dan kecil, digit, titik, dan garis bawah diteruskan seperti yang Anda tulis, sehingga API--aux dan web.api--aux terbaca seperti yang Anda harapkan. Tanda hubung yang Anda tulis dipertahankan di mana pun karakter sesudahnya adalah salah satu dari karakter tersebut, sehingga web-api--aux tidak berubah; tanda hubung ganda di-escape, karena pasangan itu adalah penggabungnya. Karakter lain di-escape dengan aturan yang sama seperti nama chart. Batasan ini ditetapkan demikian karena nama-nama direktori ini sekaligus merupakan path di disk dan lokasi yang dituju oleh pointer file:// sebuah dependensi, dan karakter yang aman dalam nama file dapat memotong atau mendekode ulang URL.
Nilai mengikuti nama yang dideklarasikan, bukan direktori. Nilai chart anak dibatasi cakupannya di bawah nama yang dideklarasikan chart tersebut, sehingga nilai untuk chart di atas dialamatkan sebagai nama yang dideklarasikan oleh api--guardrail — cfr-zh-api-zh-guardrail — bukan sebagai direktorinya.
Anda tidak pernah menulis kunci tersebut sendiri. Anda menulis nilai pada attachment, dan values.yaml umbrella disusun untuk Anda dengan blok yang sudah berada di alamat yang digunakan untuk chart yang ditempatkan. Untuk Feature yang dilampirkan pada component, itu adalah values: yang Anda deklarasikan pada attachment, yang dibaca oleh valuesMapping: milik FeatureRecipe itu sendiri; untuk Feature yang dilampirkan pada boundary, itu adalah infra: yang Anda deklarasikan di sana, karena Feature yang dilampirkan pada boundary tidak memiliki pilar nilai component. Apa pun itu, peta hasil resolusi valuesMapping: menjadi blok milik attachment itu sendiri di dalam umbrella:
# the umbrella's values.yaml, composed for youapi: # the component's own chart replicaCount: 3cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought auditEndpoint: "https://audit.internal"Ini satu-satunya jalur yang dimiliki nilai-nilai tersebut. Chart yang dibawa oleh sebuah Feature tiba dengan file-filenya seperti yang ditulis penulisnya — kecuali satu field manifest yang dijelaskan di “Nama chart yang dimiliki umbrella” — sehingga tidak ada yang menulis nilai Anda ke dalam chart tersebut, dan blok umbrella-lah yang menyediakannya. Chart yang bloknya tidak pernah tiba bukanlah chart yang rusak: chart tersebut merender nilai default yang disertakan values.yaml-nya sendiri dan melaporkan keberhasilan, jadi berikan nilai default yang akan Anda sadari jika Anda ingin melihat perbedaannya saat menulis.
Attachment yang FeatureRecipe-nya dirender melalui provider helm
FeatureRecipe dengan capability helm, yang dilampirkan ke component pada target ini, membawa manifest Kubernetes yang sudah jadi, bukan chart. Manifest tersebut ditempatkan di direktori milik attachment itu sendiri persis seperti yang dirender oleh provider helm, dan provider memberi direktori itu dua hal yang menjadikannya chart yang dapat dipasang Helm: Chart.yaml minimal, yang mendeklarasikan nama attachment itu sendiri pada versi 0.1.0, dan satu template, templates/rendered.yaml, yang mengeluarkan setiap file YAML yang dirender melalui .Files.Get milik Helm berdasarkan namanya:
charts/api--guardrail/├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0├── guardrail-config.yaml # the manifest the helm provider rendered└── templates/ └── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}Nama yang dideklarasikan adalah nama yang akan dideklarasikan chart yang di-vendor oleh attachment yang sama, sehingga entri dependensi umbrella dan blok values-nya dialamatkan persis seperti dijelaskan di atas. .Files.Get mengembalikan byte file apa adanya alih-alih mengevaluasinya untuk kedua kalinya, sehingga manifest yang membawa kurung kurawal template literal — {{ $labels.instance }} milik aturan peringatan, kueri milik dasbor — terpasang dengan kurung kurawal itu tetap utuh. Nilai-nilainya sudah di-resolve ke dalam manifest tersebut ketika provider helm merendernya, sehingga blok yang dibawa values.yaml umbrella di bawah nama itu tidak dibaca oleh apa pun.
Nama chart yang dimiliki umbrella
Satu-satunya hal yang diubah Aggrega di dalam chart yang Anda vendor adalah field name milik chart itu sendiri. Dalam Chart.yaml chart yang ditempatkan, name diatur ke identitas terenkode dari apa pun yang menyumbangkan chart tersebut.
Untuk sebuah komponen, itu adalah identitas instans komponen itu sendiri — nilai yang sama dengan alias dependensi — dan entri dependensi umbrella juga menyebut nilai tersebut, sehingga kedua sisi selalu sesuai.
Chart yang dibawa oleh lampiran Feature adalah kontributor tersendiri, dan chart itu mendeklarasikan identitasnya sendiri alih-alih mengulang identitas komponen tempat ia dilampirkan. Identitas itu disusun dari dua hal yang Anda tulis — komponen yang menampung lampiran, dan nama yang digunakan untuk melampirkan Feature — di belakang awalan pendek yang menandainya sebagai identitas lampiran, bukan identitas komponen; nilai yang tersusun kemudian ditulis untuk posisi nama chart melalui derivasi di bawah, persis seperti identitas lainnya.
Jadi, melampirkan Feature yang mem-vendor chart ke komponen bernama api dengan nama guardrail menempatkan chart yang mendeklarasikan cfr-zh-api-zh-guardrail, sementara chart milik komponen itu sendiri tetap mendeklarasikan api. Keduanya adalah kontributor terpisah, dan masing-masing mendeklarasikan namanya sendiri alih-alih keduanya mendeklarasikan nama host.
Tidak ada hal lain dalam chart yang disentuh. Setiap file lain tiba byte demi byte sebagaimana Anda menulisnya, dan di dalam Chart.yaml setiap field lain, setiap komentar, urutan kunci, dan pengutipan tetap persis seperti yang ditulis. Kunci yang bersarang di tempat lain dalam manifest yang kebetulan juga bernama name — misalnya nama maintainer — dibiarkan apa adanya.
Mengapa umbrella memerlukan field itu. name sebuah chart adalah hal yang digunakan Helm untuk mengikat dependensi umbrella. Field itu ditulis oleh siapa pun yang membuat chart, yang untuk chart yang diperoleh dari upstream bukanlah orang yang men-deploy-nya — sehingga dua komponen dalam satu jalur assembly sangat mungkin mem-vendor chart yang manifest-nya mendeklarasikan nama yang sama. Jika kedua sub-chart mempertahankan nama bersama itu, kedua dependensi umbrella akan terselesaikan ke chart mana pun dari keduanya yang dimuat Helm lebih dulu: chart satu komponen akan dirender dua kali dan chart yang lain sama sekali tidak, sementara nilai setiap komponen tetap tiba, sehingga keluaran akan tampak lengkap padahal salah. Menurunkan nama yang ditempatkan dari instans komponen menghilangkan nama bersama itu sepenuhnya, itulah sebabnya tidak ada yang perlu ditolak — termasuk dua kasus yang tidak memiliki solusi lain: mem-vendor chart yang sama di bawah dua komponen, di mana nama itu memang dipakai bersama secara konstruksi, dan mem-vendor chart yang tidak Anda tulis, yang namanya tidak dapat Anda ubah.
Satu hal yang dapat Anda amati. Template yang membaca nama chart-nya sendiri — {{ .Chart.Name }}, dan apa pun yang diturunkan darinya seperti idiom penamaan resource umum {{ .Chart.Name }}-{{ .Release.Name }} — membaca identitas instans terenkode, bukan nama yang ditulis dalam Chart.yaml chart sumber. Itulah yang sudah dibaca template semacam itu sebelum field tersebut diatur, karena Helm melaporkan sub-chart di bawah alias yang digunakan induknya untuk mengikatnya; mengatur field itu membuat file di disk sesuai dengan apa yang sudah dihasilkan render. Jadi untuk contoh lengkap di bawah, template dalam sub-chart api-east membaca api-east.
Jika nama resource harus memuat nama chart yang ditulis, letakkan nama itu di values.yaml chart tersebut dan bacalah dari sana — nilai adalah milik Anda dan Aggrega tidak menyentuhnya.
Cara nama diturunkan
Nama chart Helm dan alias dependensi Helm masing-masing menerima himpunan karakter yang lebih sempit daripada yang dapat dimuat oleh nama aggregate, jalur boundary, atau instance_id. Alih-alih mengganti karakter yang tidak diterima target, derivasi menuliskannya secara eksplisit, sehingga dua identitas yang hanya berbeda dalam tanda baca selalu menghasilkan dua nama — dan nilai yang ditulis di bawah satu alias hanya dapat mencapai sub-chart yang dinamai oleh alias itu.
- Huruf, digit, dan garis bawah diteruskan persis seperti yang ditulis.
- Tanda hubung dipertahankan seperti yang ditulis di mana pun karakter sesudahnya diteruskan secara langsung dan bukan
zhuruf kecil. Tanda hubung yang diikutizhuruf kecil membuka escape, sehingga tanda hubung yang ditulis pada posisi itu juga dituliskan secara eksplisit —api-zonemenjadiapi-zhzone, yang memungkinkan nama apa pun dibaca kembali tanpa menebak. - Setiap karakter lain ditulis sebagai
-zdiikuti huruf yang menamainya:duntuk titik,suntuk pemisah jalur,huntuk tanda hubung yang tidak dipertahankan oleh aturan di atas. Karakter lainnya ditulis sebagaixdan code point heksadesimal enam digit karakter tersebut, dan byte yang tidak memulai karakter apa pun sebagaibdan nilai dua digitnya sendiri — sehingga nama yang bukan teks valid tetap dituliskan secara berbeda alih-alih digabungkan. - Nilai kosong ditulis
-ze, yang tidak dapat dihasilkan oleh nilai tidak kosong mana pun. - Ketika dua identitas menyusun satu nama chart — nama aggregate yang mengkualifikasi jalur perakitan — keduanya digabungkan dengan
--. Satu identitas terenkode tidak pernah memuat pasangan itu, sehingga nama gabungan menunjukkan dengan jelas identitas mana yang mana.
Jadi instance_id data.main-db menghasilkan alias data-zdmain-db, dan aggregate fullstack-app dengan jalur perakitan boundaries/data/helm-chart menghasilkan nama chart fullstack-app--boundaries-zsdata-zshelm-chart. Masukan yang identik selalu menghasilkan nama yang identik.
values.yaml umbrella dikunci berdasarkan alias:
api-server: # sub-chart alias = encoded instance_id image: "registry/api-server:v2" replicaCount: 3billing-svc: image: "registry/billing:v1" replicaCount: 2Ketika valuesMapping: sebuah sub-chart dievaluasi terhadap konteks template-nya, peta nilai yang dihasilkan otomatis mengisi sub-blok yang dikunci berdasarkan alias ini. Hal itu berlaku untuk setiap kontributor umbrella, tidak hanya untuk komponen: lampiran Feature yang mem-vendor chart adalah kontributor tersendiri, sehingga valuesMapping: milik FeatureRecipe-nya mengisi bloknya sendiri, yang dikunci berdasarkan nama yang dideklarasikan chart yang ditempatkannya. Lihat “Tempat chart lampiran ditempatkan”.
Kunci yang diatur valuesMapping: ke null ditulis ke dalam bloknya sebagai null. Saat diinstal dengan Helm 4, null dalam values.yaml milik umbrella sendiri menghapus default sub-chart untuk kunci itu hanya ketika instalasi juga menyediakan nilai untuk sub-chart tersebut; instalasi yang tidak menyediakan nilai apa pun untuknya membuang null, dan default sub-chart tetap berlaku. null dalam nilai yang diberikan ke helm install menghapus default dalam kedua kasus.
Kekhasan khusus Provider
Chart.yamlsub-chart wajib ada. Operasi penyalinan mengharuskan adanyaChart.yamldi root source-path. Jika tidak ada, build dihentikan sebelum langkah umbrella dijalankan.namedari chart yang ditempatkan adalah milik umbrella. Nilainya ditetapkan ke identitas terenkode dari apa pun yang menyumbangkan chart tersebut — identitas instance komponen itu sendiri, atau, untuk chart yang dibawa oleh lampiran Feature, identitas lampiran itu sendiri — dan hanya itulah yang diubah Aggrega di dalam chart yang di-vendor. Lihat “Nama chart yang dimiliki umbrella”.- Chart sumber harus mendeklarasikan versi dan nama. Versi entri dependensi adalah versi yang dideklarasikan oleh
Chart.yamlmilik chart sumber itu sendiri, sehingga chart yang tidak mendeklarasikan versi menghentikan build alih-alih diberi versi — dependensi yang disematkan ke versi yang tidak dimiliki sub-chart akan membuat nilai per-instance dari umbrella tidak dapat menjangkaunya. Chart yangChart.yaml-nya tidak mendeklarasikan nama, memuat lebih dari satu dokumen YAML, atau tidak dapat di-parse juga dihentikan karena alasan yang sama: umbrella tidak dapat menyusun sub-chart yang tidak dapat dibacanya. - Alias dan nama chart yang terenkode. Sebuah instance_id, nama aggregate, atau boundary path yang memuat karakter yang tidak diterima oleh nama chart Helm atau alias dependensi akan muncul dalam bentuk terenkode di umbrella yang dirender, sesuai “Cara nama diturunkan” di atas. Identitas yang hanya dibangun dari huruf, digit, garis bawah, dan tanda hubung yang dipertahankan oleh derivasi akan muncul persis seperti yang ditulis.
- Penunjuk repositori
file://. Entri dependensi umbrella menggunakan penunjuk repositorifile://yang menamai direktori chart anak itu sendiri —file://charts/<instance_id>untuk komponen, dan direktori lampiran itu sendiri untuk chart yang dibawa oleh Feature. Ini adalah konvensi sistem berkas lokal untuk chart anak di dalam pohon dan memungkinkanhelm dependency buildme-resolve umbrella tanpa panggilan ke registry eksternal. Penunjuk ini menamai lokasi dan tidak pernah nama chart yang dideklarasikan; keduanya berbeda untuk lampiran, danhelm dependency buildadalah langkah yang menolak penunjuk yang menamai direktori yang tidak ada. - Tidak ada perenderan templat di tingkat helm-chart. Provider ini tidak memanggil pipeline render dari Helm SDK; provider ini menyalin dan menyusun. Penulis yang membutuhkan manifest datar yang sudah dirender sebaiknya menggunakan mode sourced dari provider helm.
Contoh lengkap
Sebuah boundary dengan dua node, masing-masing node terikat ke sebuah Recipe helm-chart yang menunjuk ke source chart yang sama:
# Recipe — used by both `api-east` and `api-west` instancesapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helmchart version: 1.0.0spec: capability: helm-chart implements: core/api-server source: ./charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Setelah komposisi, jalur perakitan boundary yang telah dievaluasi (default dist/<boundary-directory>/<capability>/ karena subDirectory: secara default bernilai {{ .capability }}) berisi:
dist/<boundary-directory>/helm-chart/├── Chart.yaml # umbrella; lists api-east and api-west as dependencies├── values.yaml # alias-keyed: api-east + api-west values blocks└── charts/ ├── api-east/ # ./charts/api-server, name: api-east │ ├── Chart.yaml │ ├── values.yaml │ └── templates/ │ └── deployment.yaml └── api-west/ # ./charts/api-server, name: api-west ├── Chart.yaml ├── values.yaml └── templates/ └── deployment.yamlKedua sub-chart merupakan salinan dari satu source chart yang sama, dan masing-masing membawa nama instance-nya sendiri di dalam Chart.yaml miliknya — hal inilah yang memungkinkan satu chart di-vendor dua kali dalam satu umbrella. Semua hal lain di kedua salinan identik dengan sumbernya.
Perintah helm install <release-name> dist/<boundary-directory>/helm-chart terhadap tata letak ini memasang kedua instance sebagai satu Helm release, dengan values umbrella yang dikunci per alias menggerakkan templat masing-masing sub-chart.
Rujukan silang
providers/helm.md— provider saudara yang menghasilkan YAML Kubernetes datar hasil render alih-alih kerangka chart; mendukung sintesis workload.entities/recipe.md— permukaan penulisan Recipe dan ketiga jenis input.entities/release.md— semantik batas Release dan direktori keluaran per batas.architecture/16-recipe-input-composition.md— Matriks Kapabilitas Provider lintas provider.10-status.md#providers— klasifikasi kesiapan saat ini.