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

Penamaan sumber daya hasil render

Sebuah Recipe secara rutin harus menamai sesuatu yang dihasilkan oleh keluarannya sendiri: nama host yang dipublikasikan melalui provides:, referensi di dalam valuesMapping:, pengenal yang ditulis ke dalam isi artifacts:. Dua kunci konteks templat membawa nama-nama yang tersedia untuk keperluan itu, dan keduanya menjawab pertanyaan yang berbeda. Membaca kunci yang salah menghasilkan keluaran yang salah secara diam-diam alih-alih ditolak — sebuah alamat yang menamai sumber daya yang tidak pernah dihasilkan — sehingga halaman ini menjelaskan kunci mana yang menjawab pertanyaan mana.

Halaman ini juga menjelaskan perbedaan yang menjadi dasar kedua kunci tersebut: target dan referensi bukanlah hal yang sama, dan target tidak pernah merupakan nama yang akan di-resolve oleh platform deployment.

Target menamai sebuah komponen; referensi menamai sebuah sumber daya yang dirender

Target adalah identitas penulisan. Target adalah nilai yang ditulis pengembang untuk menyatakan komponen mana yang dituju oleh sebuah edge — target: my_db dalam blok uses — dan merupakan identitas yang digunakan build untuk menemukan komponen tersebut, melaporkannya dalam diagnostik, dan menjadi kunci bagi fakta-faktanya. Target terbaca sama di bawah setiap provider, karena target adalah fakta tentang dokumen Anda, bukan tentang platform mana pun.

Referensi adalah hal yang membuat satu artefak yang dirender menunjuk ke artefak lain. Referensi ditulis dalam kosakata milik satu provider: alamat internal klaster di bawah helm, nama layanan di bawah compose, sebuah interpolasi di bawah terraform, nilai yang diimpor di bawah cloudformation. Referensi berbeda di bawah setiap provider, karena setiap platform me-resolve referensi dengan caranya sendiri.

🔴 Target tidak pernah ditulis ke dalam keluaran yang dirender. Setiap provider menurunkan namanya sendiri, sehingga identitas yang ditulis dan diserahkan ke platform sebagai nama akan salah setiap kali kedua ejaan itu berbeda — dan keduanya berbeda tepat pada karakter yang tidak diterima oleh alfabet target itu sendiri. Identitas yang tidak memuat karakter semacam itu tetap tidak berubah, dan inilah yang membuat kesalahan ini mudah terjadi: kesalahan itu tetap berfungsi sampai seseorang menamai komponen dengan garis bawah atau huruf kapital.

Oleh karena itu, referensi yang dibutuhkan konsumen dipublikasikan oleh produsen, karena Recipe milik produsen yang mengetahui kosakata provider-nya sendiri — konsumen mungkin mengikat provider yang sama sekali berbeda, dan tidak dapat mengeja referensi untuk platform yang tidak menjadi tujuan rendernya. Konsumen membaca string biasa yang telah dipublikasikan.

Pasangan contoh

Recipe milik produsen memublikasikan alamat; konsumen membacanya kembali melalui alias edge tersebut.

# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.
# It publishes an in-cluster address built from the name that chart's own
# templates render their resources against.
spec:
capability: helm
source: ./charts/postgres
provides:
host: "{{ .context.rendered_name }}.svc.cluster.local"
port: "5432"
# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an
# authoring identity and stays in the documents. The uses block is keyed by the
# socket the catalog entity declares, then by the alias you choose for the edge.
spec:
components:
api:
type: core/compute/api-server
uses:
databases:
primary:
target: my_db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.
# The context keys an edge by its alias, so the socket does not reappear here.
spec:
capability: helm
valuesMapping: |
{
"db_host": "{{ .context.uses.primary.provides.host }}"
}

Untuk chart yang disediakan penulis di bawah helm, komponen bernama my_db merender sumber dayanya di bawah nama rilis my-zudb. Jadi chart produsen menghasilkan sebuah Service dengan metadata.name berupa my-zudb, host yang dipublikasikan adalah my-zudb.svc.cluster.local, dan konsumen menghubungi Service yang memang ada — baik ia membaca nilai itu melalui .context.uses.primary.provides.host maupun menerimanya sebagai DB_HOST yang diinjeksikan.

Menulis {{ .context.uses.primary.target }} di sana justru akan memublikasikan my_db.svc.cluster.local. Nilai itu tidak tampak salah: nilai itu adalah identitas yang ditulis pengembang, dieja persis seperti yang mereka tulis. Nilai itu hanya tidak menamai Service apa pun, dan tidak ada apa pun dalam build yang menyatakannya.

Dua kunci, sebagai pasangan

Tidak satu pun kunci dapat dipahami secara terpisah, karena masing-masing didefinisikan oleh apa yang bukan kunci lainnya.

KunciApa yang dinamainya
{{ .context.instance_id }}Identitas node, dan nama sumber daya yang dibangun untuk node ini yang namanya tidak diturunkan oleh provider mana pun — set artefak yang ditempatkan dari blok artifacts: Anda, dan workload yang disintesis dari blok workload: Anda oleh provider yang menamainya berdasarkan identitas, seperti yang dilakukan compose. Selalu ada.
{{ .context.rendered_name }}Nama yang diturunkan oleh provider yang terikat untuk sumber daya yang dirender untuk node ini — untuk sumber yang Anda sediakan, nama yang dipakai oleh templat yang Anda sediakan untuk merender sumber dayanya, seperti nama rilis yang dibaca oleh sebuah chart; untuk workload: yang disintesisnya, nama yang diberikannya kepada sumber daya tersebut ketika provider itu menamainya berdasarkan nama miliknya sendiri, bukan identitas, seperti yang dilakukan helm. Hanya ada ketika provider tersebut menurunkan sebuah nama. Pada templat milik lampiran Feature, kunci ini adalah nama komponen inang — lihat di bawah.

Pembagian ini mengikuti dari tempat nama tersebut harus dapat digunakan. Chart atau modul yang Anda sediakan memiliki templat, dan templat tersebut menamai sumber dayanya berdasarkan identitas apa pun yang diberikan platform kepadanya — sehingga nama tersebut harus nama yang akan digunakan platform itu, dieja dalam alfabet platform itu sendiri. Workload yang disintesis tidak memiliki templat dari Anda, tetapi sumber dayanya tetap harus membawa nama yang diterima platform: provider yang namanya menerima semua karakter yang dapat dibawa nama yang ditulis penulis menamainya berdasarkan identitas, dan provider yang namanya tidak menerimanya menamainya berdasarkan nama yang diturunkannya — lalu melaporkan nama tersebut di sini, sehingga Anda tidak perlu menebaknya.

Node yang mendeklarasikan sumber yang disediakan sekaligus workload: menghasilkan kedua jenis keluaran sekaligus, dan tidak memerlukan kunci ketiga. Di bawah helm keduanya dinamai berdasarkan satu nama rilis yang sama, sehingga rendered_name berlaku untuk keduanya: sumber daya milik chart membawanya bagaimana pun templatnya menyusunnya, dan setiap Service yang disintesis adalah <rendered_name>-<service key>. Di bawah provider yang menamai workload yang disintesis berdasarkan identitas, namai sumber daya workload tersebut dengan instance_id dan sumber daya keluaran yang disediakan dengan apa pun yang dilaporkan provider untuknya.

Alfabetlah yang menjadi alasan keduanya bisa berbeda. Nama komponen yang ditulis penulis dapat membawa garis bawah atau huruf kapital; nama rilis chart tidak boleh, dan alih-alih melipat karakter semacam itu menjadi karakter yang mirip — yang akan membuat dua komponen yang dapat Anda bedakan berakhir dengan satu nama di dalam kluster — penurunan nama menuliskannya secara eksplisit. Lihat ../providers/helm.md “How the release name is derived” untuk alfabet dan batas panjang milik provider tersebut.

Provider mana yang melaporkan nama, dan mengapa yang lain tidak

helm melaporkan satu nama: nama rilis. Chart yang dijadikan sumber membacanya sebagai .Release.Name dan lazimnya menamai sumber dayanya menurut nama itu, dan provider juga menamai setiap sumber daya yang disintesisnya untuk sebuah komponen menurut nama itu — controller dengan nama rilis itu sendiri, dan setiap Service sebagai <release name>-<service key>. Jadi, alamat yang dipublikasikan untuk kedua jenis keluaran dibangun dari rendered_name. Untuk node yang hanya menempatkan sebuah set artefak, provider ini tidak melaporkan nama apa pun: nama-nama dalam set itu adalah nama yang ditulis oleh pembuatnya.

# A synthesized helm Recipe publishing the address of the Service its workload
# declares under the key `default`.
spec:
capability: helm
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
containers:
main:
image: "valkey/valkey:8"
ports:
redis: 6379
services:
default:
type: ClusterIP
ports:
redis: 6379
provides:
host: "{{ .context.rendered_name }}-default"
port: "6379"

Komponen bernama cache memublikasikan cache-default, dan komponen bernama my_cache memublikasikan my-zucache-default — dalam setiap kasus, itulah nama Service yang dihasilkan oleh build.

Empat provider lainnya tidak melaporkan nama, dan alasannya tidak sama. Tidak satu pun dari mereka adalah provider yang menunggu dukungan — dalam setiap kasus, entah tidak ada nama turunan untuk dilaporkan, atau nama yang Anda inginkan sudah dapat dijangkau dengan cara lain.

  • cloudformation dan compose — Anda yang menulis nama-namanya, atau identitas itulah namanya. Sebuah Recipe cloudformation menulis logical id sumber dayanya dan provider membacanya persis seperti yang ditulis; file compose yang Anda berikan menamai layanannya sendiri dan provider menggabungkan serta memberi label pada file itu tanpa mengganti nama apa pun di dalamnya. Workload yang disintesis compose dinamai menurut identitas node, yang diterima file compose apa adanya, sehingga {{ .context.instance_id }} adalah nama itu. Tidak ada penurunan nama untuk dilaporkan, dan nama-namanya adalah yang tertulis dalam dokumen Anda sendiri. Nama itu adalah layanan utama workload, yang dijangkau oleh peer; layanan sidecar atau init yang dibawanya dinamai dari identitas yang sama dan nama container, digabungkan dengan --, seperti yang dijelaskan dalam Cara layanan sidecar atau init dinamai.

  • terraform — nama merupakan fungsi dari tempat file-file ditempatkan. Blok module milik kontributor dinamai dari direktori keluaran tempat konfigurasinya ditulis, yang ditetapkan saat file-file boundary dirakit, bukan saat node dirender. Pada saat template sebuah Recipe dijalankan, posisi itu belum ada.

  • helm-chart — nama yang diturunkannya adalah alamat chart yang ditempatkan itu sendiri, yang merupakan hal yang berbeda dari nama yang menjadi acuan render template chart tersebut. Provider ini menetapkan field name dari chart yang Anda vendor ke identitas terenkode dari apa pun yang menyumbangkannya, yang juga merupakan alias yang digunakan umbrella untuk mengikat sub-chart itu dan kunci tempat nilai-nilainya dicakup. Untuk sebuah komponen, identitas itu adalah apa yang dibawa {{ .context.instance_id }}, sehingga nama chart yang ditempatkan sudah dapat dijangkau melalui kunci yang menyatakan apa nama itu. Nama yang menjadi acuan render template chart yang di-vendor itu sendiri adalah nama rilis, yang disediakan oleh rilis umbrella pada saat instalasi, bukan diturunkan oleh provider ini — sehingga di sini tidak ada nama semacam itu untuk dilaporkan oleh kunci ini. Lihat ../providers/helm-chart.md “The chart name the umbrella owns”.

Membaca kunci ketika tidak ada nama yang dilaporkan

Membaca {{ .context.rendered_name }} pada node yang provider-nya tidak melaporkan nama tersebut menghentikan build, dan diagnostiknya menyebutkan kunci mana yang harus ditulis sebagai gantinya. Nilai kosong tidak dirender: sebuah alamat yang kurang satu segmen adalah artefak keliru yang tetap ter-deploy, dan itu lebih buruk daripada build yang berhenti.

Solusi yang ditawarkan oleh penghentian tersebut bergantung pada node, bukan pada tempat Anda menulis referensi:

  • Node yang tidak menyediakan sumbernya sendiri, di bawah provider yang tidak melaporkan nama untuknya, memiliki sumber daya yang dinamai menurut identitasnya, sehingga penghentian tersebut menyebutkan {{ .context.instance_id }} — ada nilai yang benar dan diagnostik menyatakannya.
  • Node yang memang menyediakan sumber, di bawah provider yang tidak menurunkan nama untuknya, tidak memiliki pengganti. Penghentian tersebut menyatakan hal itu alih-alih menawarkan pengganti, karena mengarahkan Anda ke identitas di sana akan menamai sumber daya yang tidak dimiliki node Anda.

Penolakan ini mencakup provides: dan setiap templat lain yang ditulis inline oleh sebuah Recipe — valuesMapping:-nya, badan workload:-nya, setiap entri artifacts:, serta with: dan when: pada setiap langkah pipeline.

🔴 Kedua bentuk impor berada di luar cakupannya. Entri valuesMapping:, workload: atau artifacts: yang disediakan melalui $import: — baik impor tersebut menyebut berkas lokal maupun entri pustaka — tidak membawa teks apa pun dalam Recipe Anda sampai render menyelesaikannya, sehingga referensi ke kunci ini di dalam badan semacam itu tidak diperiksa. Referensi tersebut merender nama yang dilaporkan provider node pengimpor jika provider itu melaporkannya, dan nilai kosong alih-alih penghentian jika provider itu tidak melaporkannya. Karena itu, badan yang diimpor hanya membaca kunci ini jika setiap Recipe yang mengimpornya mengikat provider yang melaporkan nama — misalnya entri pustaka yang ditulis untuk Recipes helm yang menggunakan sumber chart, dan menyatakannya dalam deskripsinya. Badan yang ditujukan bagi pengimpor yang provider-nya mungkin tidak melaporkan nama mengambil nama tersebut melalui nilai yang ditetapkan oleh Recipe pengimpor.

Entri locals: sebuah Recipe sama sekali tidak membaca kunci ini. Sebuah local berbagi konteks dengan templat source: milik Recipe, dan apakah node menyediakan sumber adalah salah satu hal yang menentukan nama tersebut, sehingga nama itu tidak ditawarkan di sana. Karena itu, referensi ke {{ .context.rendered_name }} di dalam local selalu berhenti apa pun yang dilaporkan provider, dengan diagnostik untuk referensi yang tidak didefinisikan oleh konteks render (E0060), yang mencantumkan .context.instance_id sebagai satu-satunya kunci yang ditawarkan .context di sana. Bacalah kunci ini di entri provides: atau templat inline yang membutuhkannya.

Pada templat milik attachment Feature itu sendiri

Pada templat yang ditulis oleh FeatureRecipe sebuah attachment Feature — locals:, source:, provides:, injectMapping:, valuesMapping:, workload:, setiap entri artifacts:, serta with: dan when: pada setiap langkah pipeline — {{ .context.rendered_name }} adalah nama komponen host: nama yang dilaporkan oleh provider milik host untuk sumber daya yang dirender bagi host, yaitu nilai yang dibaca oleh Recipe milik host. Kunci ini berpasangan dengan {{ .context.instance_id }}, yang pada templat tersebut adalah identitas komponen host; attachment itu sendiri adalah .attachment_name. Attachment yang ditulis pada salah satu koneksi sebuah komponen membaca nama komponen konsumen, karena komponen itulah host-nya.

Itulah kunci untuk menyusun nama sumber daya milik attachment. FeatureRecipe yang menamai Secret, rute, atau kebijakan menurut komponen tempat ia dipasang memerlukan nama yang diterima platform, dan identitas host sebagaimana ditulis tidak memenuhinya di mana pun identitas itu mengandung garis bawah atau huruf kapital. Di bawah helm, komponen bernama my_db melaporkan my-zudb, sehingga Secret bernama {{ .context.rendered_name }}-{{ .attachment_name }} untuk attachment root dirender sebagai my-zudb-root, sedangkan {{ .context.instance_id }} akan menghasilkan my_db-root, yang ditolak oleh klaster. Nilainya tetap milik host, melalui provider mana pun attachment dirender.

Kunci ini tersedia di mana pun provider milik host melaporkan nama — di bawah helm, host yang Recipe-nya menyediakan chart atau mendeklarasikan workload: — dan tidak tersedia di mana provider tidak melaporkannya: host yang hanya menempatkan sekumpulan artefak, dan host pada provider lain mana pun. Membacanya pada attachment dari host semacam itu menghentikan build dengan diagnostik untuk referensi yang tidak didefinisikan oleh konteks render (E0060), yang mencantumkan kunci-kunci yang didefinisikan .context di sana. {{ .context.instance_id }} termasuk di antaranya, dan menurut nilai itulah sumber daya milik host dinamai pada host semacam itu, sehingga FeatureRecipe yang ditulis untuk host yang mungkin tidak melaporkan nama membaca identitas sebagai gantinya.

Penolakan ini mencakup templat yang ditulis FeatureRecipe secara inline, selain injectMapping:-nya. injectMapping:, serta entri valuesMapping:, workload:, atau artifacts: yang disediakan FeatureRecipe melalui $import:, tidak diperiksa: pada host yang tidak melaporkan nama, referensi di sana merender nilai kosong alih-alih menghentikan build.

Jika attachment mengirimkan chart yang disediakan penulisnya, templat chart tersebut dirender terhadap nama release komponen host, dengan sengaja: menurunkannya dari attachment justru akan mengganti nama sumber daya yang telah dideklarasikan penulis chart dan mungkin sudah di-deploy. .attachment_name adalah nilai yang membedakan dua attachment pada satu host — lihat ../providers/helm.md “How the release name is derived”.

Nama yang diturunkan dari attachment sebuah koneksi

Attachment yang dibawa sebuah koneksi adalah attachment milik komponen konsumen, dengan nama <alias>.<slot> — gpt.credential untuk slot credential pada koneksi yang ditulis dengan alias gpt (lihat entri koneksi pada Aggregate). Nama gabungan itu adalah .attachment_name yang menjadi dasar perenderan FeatureRecipe-nya, dan nama itu memuat titik.

Dua jenis nama diturunkan darinya, dan keduanya memperlakukan titik secara berbeda.

Nama yang disusun FeatureRecipe mempertahankan apa pun yang ditulis templatnya. Realisasi kredensial pustaka standar menamai sumber dayanya {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, sehingga kredensial pada koneksi gpt dari komponen bernama router dirender sebagai sumber daya bernama router-gpt.credential, termasuk titiknya, yang merupakan nama objek Kubernetes yang valid. Titik bertahan dalam nama jenis ini tepat ketika templat mempertahankannya.

Nama yang diturunkan build dari identitas attachment menuliskan titik secara eksplisit. Label identitas dan berkas yang dihasilkan disusun dari komponen host dan nama attachment melalui pengodean yang sama yang dilalui setiap nama yang diturunkan dari identitas, dan pengodean itu menuliskan titik sebagai zd dan huruf kapital sebagai escape dari code point-nya, karena identitas dipakai sebagai nama sumber daya sekaligus label, dan nama Service tidak menerima keduanya: koneksi yang ditulis di bawah alias gptPro akan menjadi cfr--router--gpt-zx000050ro-zdcredential. Sumber daya di atas diberi label aggrega.ai/component-id: cfr--router--gpt-zdcredential (demikian pula app.kubernetes.io/name), dan di bawah provider helm sumber daya itu dihasilkan sebagai router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Lihat Konvensi penamaan “The separator does not reach a name” untuk alasan titik dituliskan secara eksplisit alih-alih diganti.