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

aggrega inspect

aggrega inspect merender tampilan yang mudah dibaca manusia untuk entitas Aggrega apa pun — Component katalog, berkas entitas yang Anda tulis, entitas yang diterbitkan di registry, atau Release yang telah diresolusi sepenuhnya. Ini adalah antarmuka debug kanonis untuk memahami apa yang akan dihasilkan kompiler: Components mana yang memperluas basis mana, Recipe mana yang dipetakan ke setiap tipe, Features mana yang terlampir pada setiap node, dan dari mana tepatnya kontribusi setiap Feature berasal.

Setiap jenis entitas memiliki tampilan “kontrak” yang alami. inspect menampilkan kontrak itu — skema yang diterbitkan Component, pemetaan yang dideklarasikan Manifest, topologi yang dibangun Aggregate, lampiran Feature per node yang menjadi hasil resolusi Release. Materi tutorial dan konseptual berada di tempat lain; inspect menjawab “sebenarnya diresolusi menjadi apa entitas ini?”

Satu argumen posisional diarahkan berdasarkan bentuk isinya; tidak diperlukan subperintah. Perintah ini mengarahkan sesuai heuristik berikut:

Bentuk pengenalPengarahanOutput
Diawali ./, ../, atau /, atau diakhiri .yaml / .ymlCabang berkasPemeriksaan per berkas berdasarkan header kind: berkas.
Diawali oci://Cabang registryEntitas yang diterbitkan di koordinat itu, dibaca dari registry-nya dan dirender dengan tampilan yang diperoleh berkas dari jenisnya. Lihat Membaca entitas yang diterbitkan.
Selain ituCabang katalogCari pengenal di tumpukan pencarian katalog di semua jenis entitas; resolusikan rantai extends:; render tampilan milik jenis yang cocok.

Tiga tingkat detail

--list, tingkat bawaan, dan --detail membentuk disiplin verbositas tiga tingkat yang seragam dan dipatuhi setiap jenis. --list dan --detail saling eksklusif — memberikan keduanya ditolak alih-alih diresolusi secara diam-diam.

  • --list — hanya pengenal. Component mencantumkan namanya dan nama socket uses-nya; MappingLibrary mencantumkan nama pemetaannya; Aggregate mencantumkan nama komponennya beserta tipenya.
  • bawaan — ringkasan terstruktur yang disesuaikan untuk penggunaan interaktif. Ringkasan ini dibuka dengan identitas entitas dan, untuk setiap jenis kecuali Manifest dan Release, deskripsinya jika entitas menuliskannya; entitas tanpa deskripsi tidak mencetak deskripsi alih-alih mencetak baris kosong. Bentuk selebihnya bergantung pada jenisnya: Component menampilkan skema dan socket-nya; Aggregate menampilkan komponen, nilai dan sisinya beserta lampiran yang dibawa setiap koneksi, dan graf dependensi; Release menampilkan pohon node per boundary dengan lampiran Feature, dan setiap lampiran yang ditulis pada sebuah koneksi dicantumkan di bawah koneksi itu.
  • --detail — isi bidang secara lengkap. Semua yang dimuat jenis tersebut: Component menambahkan mekanisme self-inject, Features yang diwajibkan, dan label; MappingLibrary menguraikan isi template lengkap setiap pemetaan; Recipe menambahkan isi workload, provides, dan asersinya.

Beberapa jenis menggunakan tingkat-tingkat ini untuk menampilkan secara bertahap lebih banyak bagian dari isi yang ditulis. MappingLibrary pada --list menampilkan nama pemetaan; pada tingkat bawaan menambahkan contoh penggunaan yang disintesis untuk setiap pemetaan; pada --detail menguraikan isi template lengkap.

Resolusi: --raw dan --resolved

Setiap jenis memiliki kedalaman resolusi bawaan yang alami (lihat tabel di bawah). --raw dan --resolved adalah penimpaan yang selalu tersedia, dan keduanya saling eksklusif — memberikan keduanya ditolak alih-alih diresolusi secara diam-diam:

  • --raw menonaktifkan semua resolusi — entitas dikeluarkan sebagaimana ditulis, langsung dari berkas.
  • --resolved mengaktifkan kedalaman resolusi penuh jenis tersebut.

Untuk jenis yang secara bawaan ditampilkan sebagaimana ditulis, --raw tidak berpengaruh dan --resolved memicu resolusi yang didukung jenis itu. Untuk jenis yang secara bawaan diresolusi, --raw adalah jalan pintas ke bentuk sebagaimana ditulis.

--raw mereproduksi berkas, sehingga nilai yang dideklarasikan penulis sebagai sensitif muncul di dalamnya persis sebagaimana ditulis. Itulah kontraknya, bukan celah — tampilan sebagaimana ditulis yang diam-diam menyembunyikan sebagian dirinya tidak lagi sebagaimana ditulis. Perlakukan output --raw seperti Anda memperlakukan berkas entitas asalnya. --output yaml mereproduksi berkas dengan cara yang sama, untuk setiap jenis termasuk Release.

Release menjawab dua pertanyaan tambahan, dan masing-masing adalah dokumen berbeda dengan flag-nya sendiri. Graf terkompilasi yang menjadi hasil resolusi Release adalah --ir-graph; penutupan dependensinya adalah --closure. Lihat Output yang dapat dibaca mesin dan Penutupan dependensi: --closure di bawah.

Bawaan per jenis

inspect mengenal jenis yang dapat diperiksa secara mandiri dalam tabel di bawah. Jenis katalog secara bawaan dirender sebagaimana ditulis — berkasnya adalah kontrak yang mandiri. Jenis instans secara bawaan menggunakan tampilan yang telah diresolusi, karena YAML yang ditulis hanyalah titik awal untuk sebuah kaskade atau pipeline.

JenisDefaultArti “diresolusi”
Componentsebagaimana ditulisBerkas adalah kontrak yang mandiri; resolusi dilakukan terhadap binding Manifest, yang ditampilkan melalui --show-implements.
Featuresebagaimana ditulisSama seperti Component.
Recipesebagaimana ditulis--show-implements meresolusi referensi Component di spec.implements.
FeatureRecipesebagaimana ditulis--show-implements meresolusi referensi Feature di spec.implements.
MappingLibrarysebagaimana ditulisEntri adalah string template Go yang buram; perenderan terjadi pada saat konsumsi.
SchemaLibrarysebagaimana ditulisEntri adalah definisi skema dan template yang dapat digunakan ulang dan diresolusi pada saat konsumsi.
WorkloadLibrarysebagaimana ditulisEntri adalah badan Workload yang dapat digunakan ulang yang diimpor sebuah Recipe, dievaluasi pada saat digunakan.
ArtifactLibrarysebagaimana ditulisEntri adalah bundel artefak yang dapat digunakan ulang yang diimpor sebuah Recipe, dirender pada saat digunakan.
Pluginsebagaimana ditulisBerkas adalah kontrak plugin yang mandiri: tipe socket, kapabilitas per ekspor, batasan runtime, dan penunjuk tanda tangan. Dapat dialamatkan melalui jalur berkas, atau melalui koordinat <pluginType>/<name>-nya terhadap katalog.
ManifestdiresolusiRantai extends: diterapkan; pemetaan komponen dan feature yang telah diresolusi ditampilkan.
AggregatediresolusiTopologi dibangun — graf uses dan urutannya dihitung.
ReleasediresolusiPipeline lengkap dijalankan: resolusi, perluasan anotasi, menjalankan guard, membangun topologi, membangun IR.

Berkas yang kind:-nya adalah Workload ditolak: Workload hanya ada sebagai bagian tertanam dalam Recipe dan bukan entitas yang dapat diperiksa secara mandiri. Periksa Recipe untuk melihat Workload-nya.

Kedalaman resolusi per jenis

Sebagian besar jenis tidak memiliki pipeline — inspect membaca berkas dan merendernya. Tiga jenis instans diresolusi secara berarti:

  • Manifest menerapkan rantai extends:-nya — mengikuti impor berkas — dan merender pemetaan komponen dan feature yang telah digabungkan. --raw menampilkan berkas sebagaimana ditulis.
  • Aggregate membangun topologinya: graf uses disusun dan urutan dependensi dihitung. Tampilan bawaan menampilkan komponen beserta nilai dan sisinya, diikuti graf dependensi. --raw menampilkan pohon subsistem sebagaimana ditulis.
  • Release menjalankan seluruh pipeline kompilasi hingga IR — resolusi, perluasan anotasi, menjalankan guard, membangun topologi, membangun IR — dan merender pohon node per boundary dengan lampiran Feature setiap node beserta asal-usulnya. Lampiran tata kelola yang membentuk graf dijalankan dalam pipeline itu alih-alih dilewati demi sebuah tampilan, sehingga apa yang Anda baca mencerminkan keputusan mereka: label dari lampiran label-transform sudah terpasang sebelum apa pun dicocokkan dengannya, dan anotasi yang disuntikkan lampiran annotation-transform diperluas menjadi lampiran Feature persis seperti anotasi yang Anda tulis. Lampiran yang plugin-nya tidak dapat diresolusi oleh perintah ini akan menghentikannya, alih-alih meninggalkan graf yang digambar tanpa keputusan plugin tersebut. Release yang memperluas Release lain digambar, dalam tampilan ini dan dalam --ir-graph, sebagai Release hasil komposisi rantai extends: miliknya — Release yang dibaca oleh build-nya — sehingga Release yang hanya menyebut induknya menampilkan Aggregate, Manifest, dan boundary milik induk itu di bawah namanya sendiri. Manifest yang disebut sebuah Release juga dikomposisikan melalui rantai extends: miliknya sendiri, baik Release itu memperluas sesuatu maupun tidak, sehingga lampiran yang mapping-nya diwarisi Manifest tersebut menampilkan realisasi yang digunakan build. --raw mengeluarkan berkas Release apa adanya tanpa pipeline. --closure mengajukan pertanyaan berbeda tentang Release yang sama dan tidak menjalankan pipeline sama sekali; lihat Penutupan dependensi: --closure.

Tidak ada flag kedalaman terpisah; sakelar --raw / --resolved adalah satu-satunya kendali resolusi, yang diterapkan di atas bawaan alami setiap jenis.

Perilaku saat terjadi kesalahan

Berkas terkait yang dirujuk dan gagal dimuat akan langsung menghentikan perintah — Release yang menunjuk ke Aggregate yang tidak ada, entitas katalog yang rusak di tumpukan pencarian. Perintah berhenti dengan pesan yang jelas alih-alih merender output parsial, dan tidak ada mode continue-on-error untuk kegagalan pemuatan: begitu dokumen yang dibutuhkan resolusi tidak dapat dibaca, tidak ada lagi yang dapat diresolusi. Jika resolusi sebuah nama berhenti pada dokumen katalog yang ditolak pemuatan, pesan menyatakan penolakan itu satu kali: kepala yang memuat kategori dan, jika penolakan menyebutkan sebuah kondisi, kode pendeknya, lalu dokumennya, lalu apa yang salah dengannya — untuk dokumen yang ditolak skema jenisnya, baris dan batasan yang dilanggarnya. Pesan itu tidak menyarankan untuk memindahkan berkas — katalog membacanya, dan karena itulah berkas itu ditolak.

Release yang komposisinya ditolak pemeriksaan kompiler akan ditolak alih-alih dirender. Meresolusi Release membangun graf, dan pemeriksaan yang dilakukan build atas graf yang sudah jadi — sisi uses: yang targetnya tidak memenuhi selector: socket-nya, Feature yang terlampir pada komponen yang tidak diterima oleh appliesTo:-nya, dan lainnya — juga dilakukan di sini, dengan diagnostik yang dicetak oleh build atas dokumen yang sama. Penolakan menyebutkan setiap temuan dalam satu kali eksekusi alih-alih berhenti pada yang pertama, sehingga satu kali jalan menunjukkan seluruh daftar yang harus diperbaiki, bukan hanya entri pertamanya. Itulah yang menjaga perintah ini tetap jujur terhadap sebuah deployment: tampilan yang merender komposisi yang ditolak build akan melaporkan workspace sebagai baik-baik saja padahal tidak. Pilihan yang tidak meresolusi apa pun tidak terpengaruh — --raw, --output yaml, dan --closure mereproduksi atau meresolusi apa yang Anda tulis tanpa membangun graf.

Release yang lockfile-nya tidak lagi cocok dengan hasil resolusinya ditolak dengan penghentian yang dicetak oleh aggrega build. Jika ada lockfile di samping Release, setiap pilihan yang meresolusi Release — tampilan bawaan, --resolved, --ir-graph, dan --closure — mewajibkan lockfile tersebut cocok dengan hasil resolusi Release, dengan perbandingan penyimpangan yang dijalankan build sebelum melakukan render. Lockfile yang tidak lagi cocok menghentikan perintah dengan penolakan E0130 milik build: setiap entri yang menyimpang, lalu aggrega pull --release <release> yang menghapus penyimpangan tersebut. Tidak ada yang ditulis ke keluaran standar dan perintah keluar dengan kode bukan nol, karena gambaran yang dibuat dari katalog sebagaimana adanya akan menunjukkan sesuatu yang tidak dirender oleh build mana pun dari Release tersebut. --raw dan --output yaml saja tidak membaca lockfile maupun katalog, dan tidak diwajibkan cocok dengannya. Release tanpa lockfile di sampingnya diresolusi terhadap katalog sebagaimana adanya.

Berkas yang kind:-nya tidak dikenali melaporkan jenis yang tidak dikenal itu dan berkas asalnya. Berkas Workload melaporkan bahwa jenis itu hanya ada sebagai bagian tertanam dan menyebutkan entitas tempatnya ditanamkan. Pengenal oci:// yang tidak dapat dibaca ditolak dengan kondisi yang menyebutkan alasannya; Membaca entitas yang diterbitkan mencantumkannya.

Resolusi katalog

Tumpukan pencarian katalog disusun dengan prioritas berlapis: flag --catalog (ditambahkan di depan, sesuai urutan) didahulukan, lalu catalog_dirs workspace dari .aggrega-config.yaml — untuk Release yang diberi direktori sendiri oleh konfigurasi di bawah workspace.releases, direktori milik Release itulah yang menggantikannya — lalu direktori catalog di akar workspace, yang dibaca baik ada yang menyebutkannya maupun tidak. Workspace yang catalog_dirs-nya ditulis sebagai daftar kosong tidak membaca katalog lokal sama sekali. Tumpukan ini bersifat first-win — direktori paling awal yang mendeklarasikan sebuah identitas entitas menjadi pemiliknya; salinan di direktori berikutnya tertutupi. Cabang katalog meresolusi pengenal terhadap tumpukan ini di semua jenis entitas, dalam urutan prioritas tetap, dan merender kecocokan pertama melalui tampilan milik jenis itu; cabang berkas dan release memuat entitas katalog yang dirujuk darinya ketika pemetaan Manifest atau induk extends: harus diresolusi. Induk extends: yang tidak ada di tumpukan dibaca dari tempat build membacanya: dari cache artefak, di bawah pin yang dicatat lockfile sebuah Release untuknya — lockfile milik Release yang disebutkan, atau milik setiap Release di workspace jika tidak ada yang disebutkan. Jadi, basis yang diterbitkan ke registry teresolusi di sini begitu aggrega pull telah mengambil dan mem-pin-nya, dan sebelum itu perintah ditolak dengan menyebutkan aggrega pull --release <release>. Tidak ada yang diambil.

Mencari nama menurut ketentuan sebuah Release

Nama yang diberikan sendiri dicari di tumpukan milik workspace. Berikan --release <release-path> di sampingnya, dan nama itu justru dicari di tumpukan Release tersebut — direktori yang diberikan konfigurasi workspace kepada Release itu, dengan --catalog apa pun ditambahkan di depan — yaitu apa yang dibaca oleh build Release tersebut. Karena itu, workspace yang menyimpan satu varian katalog per Release, masing-masing mendeklarasikan entitas yang sama, menjawab sebuah nama dengan varian yang digunakan untuk membangun Release tersebut:

aggrega inspect core/datastore/mariadb --release release-helm-synth.yaml

Nama yang tidak dapat diresolusi oleh tumpukan Release itu ditolak, dan keterangan tentang tempat entitas lokal dibaca menyebutkan entri Release itu di bawah workspace.releases, karena entri itulah yang dibaca pencarian. --release memilih tumpukan tempat sebuah nama dicari, sehingga hanya berlaku untuk nama yang diberikan sendiri: jalur berkas dan referensi registry dibaca apa adanya dan menolaknya. --release yang menyebutkan berkas yang tidak ada, atau menyebutkan direktori, ditolak sebelum apa pun dicari.

Membaca entitas yang diterbitkan

aggrega inspect oci://<host>/<repository>:<tag> membaca entitas yang diterbitkan di koordinat itu; @<digest> sebagai pengganti :<tag> menyebutkan tepat satu manifest. Dengan cara inilah Anda melihat entitas yang hanya ada di registry — repositori adalah segmen jenis yang diikuti identitas entitas, seperti diuraikan dalam Katalog dan registry §6, dan aggrega push mencetak referensi tempat ia menerbitkan, yang di sini dibaca dengan oci:// di depannya.

Apa yang Anda lihat adalah entitas sebagaimana diterbitkan. Entitas yang diterbitkan bersama berkas-berkas yang dideklarasikannya — Recipe dengan chart lokal atau lock-nya, Component dengan skema yang diimpornya — dikirim sebagai arsip, dan entitas dibongkar darinya: dokumen di akar arsip yang mendeklarasikan jenis yang dapat diterbitkan, sehingga template chart atau fragmen compose yang dikirim di sampingnya tidak tertukar dengannya. Entitas yang tidak mendeklarasikan berkas apa pun dikirim sebagai dokumennya tanpa perubahan, dan entitas sebuah Plugin dibaca dari manifest-nya, bukan dari berkas eksekusi yang diterbitkan bersamanya. Dokumen itu kemudian dirender dengan tampilan yang sama yang diperoleh berkas dari jenis tersebut, dengan tingkat detail yang sama serta --raw dan --output yaml yang sama. Tidak ada pewarisan yang diterapkan: tampilan itu adalah apa yang ditempatkan penerbit di koordinat tersebut. Tata letak yang dapat dibaca diakhiri dengan apa yang dibaca: koordinatnya, apakah koordinat itu memuat entitas sebagai arsip atau sebagai dokumen itu sendiri, tipe media yang dideklarasikan manifest-nya, dan digest manifest tersebut, yang membaca byte yang sama lagi jika ditulis sebagai @<digest> sebagai pengganti :<tag>; --output yaml mencetak dokumen dan tidak ada apa pun sesudahnya.

Apa yang diperiksa, dan apa yang tidak. Byte yang diambil diperiksa terhadap digest yang dicatat manifest artefak itu sendiri untuknya, yang memastikan bahwa itulah byte yang disebutkan manifest tersebut. Itu adalah pemeriksaan terhadap apa yang disajikan registry, bukan terhadap apa pun yang dicatat sebelumnya: tidak ada tanda tangan yang dilampirkan pada artefak yang diverifikasi, dan tidak ada penarikan yang tercatat untuknya yang dilaporkan. Tidak ada yang ditulis — tidak ada entri cache dan tidak ada lockfile — sehingga membaca sebuah koordinat tidak mengubah apa pun yang diresolusi build berikutnya.

Perintah ini menjangkau jaringan. Registry dihubungi dengan kredensial yang disimpan mesin ini untuknya, dari penyimpanan yang sama yang dibaca aggrega push dan aggrega pull, dan registry di mesin ini dihubungi melalui HTTP biasa. Workspace yang sedang offline menolak pembacaan sebelum koneksi apa pun dibuat.

Pembacaan yang tidak dapat memberikan jawaban keluar dengan kode bukan nol dan tidak mencetak apa pun ke output standar. Setiap kegagalan di bawah menyebutkan kondisinya beserta apa yang perlu dilakukan; registry yang sama sekali tidak dapat dijangkau dilaporkan dengan kesalahan jaringan yang menghentikan pembacaan:

Apa yang terjadiKondisi
Tidak ada yang diterbitkan di bawah referensi tersebutE0137
Registry menolak kredensial, atau tidak ada kredensial yang disimpan untuknyaE0138
Workspace sedang offlineE0125
Artefak adalah arsip yang tidak dapat dibongkarE0300
Arsip tidak memuat dokumen entitas di akarnyaE0298
Arsip memuat lebih dari satu dokumen entitas di akarnyaE0299
Dokumen bukan entitas dari jenis yang diterbitkan registryE0301

Setiap kode tercantum dalam referensi kesalahan. Referensi yang tidak menyebutkan repositori, atau tidak menyebutkan tag maupun digest, ditolak dengan bentuk yang seharusnya ditulis. --ir-graph dan --closure ditolak sebelum apa pun diambil, karena tidak ada jenis yang diterbitkan registry yang merupakan Release.

Pemberitahuan usang dan penarikan

Penerbit dapat mencatat penanda pada sebuah artefak setelah menerbitkannya, yang menyatakan bahwa versi terbitan itu usang atau ditarik. Ketika cabang katalog meresolusi sebuah entitas, inspect melaporkan penanda semacam itu di bawah tampilan entitas itu sendiri — untuk setiap jenis yang diresolusinya berdasarkan nama, bukan hanya untuk Component.

Pemberitahuan menyebutkan tingkat keparahan yang dicatat penerbit — warning, error, atau retracted — beserta versi tempat penanda itu dicatat, alasannya, penggantinya jika ada yang disebutkan, dan tanggal penerbitannya. Ketiga tingkat keparahan dilaporkan. Cakupan itu lebih luas daripada himpunan yang mengubah hasil resolusi build: versi yang ditandai retracted dikecualikan dari pemilihan versi, sedangkan warning dan error bersifat anjuran dan tetap dipilih. inspect menunjukkan apa yang dinyatakan penerbit; perintah ini tidak memutuskan apa yang Anda dapatkan.

Pemberitahuan dibaca dari indeks lokal registry tempat entitas diresolusi, yang dibangun oleh aggrega registry update — sehingga tidak memerlukan jaringan dan berfungsi di workspace offline. Karena indeks adalah sebuah snapshot, pemberitahuan diakhiri dengan menyatakan kapan snapshot itu diambil dan menyebutkan perintah yang memperbaruinya. Workspace yang belum membangun indeks tidak melaporkan apa pun, dan karena itu pemberitahuan yang tidak ada berarti “tidak ada yang tercatat dalam snapshot ini”, bukan “tidak ada yang tercatat”.

Penanda hanya dilaporkan jika tanda tangannya sendiri berhasil diverifikasi terhadap penanda tangan yang diakui kebijakan kepercayaan registry. Penanda tanpa tanda tangan, atau yang tanda tangannya tidak berhasil diverifikasi, tidak dilaporkan: klaim yang tidak dapat diautentikasi tidak disajikan sebagai fakta.

Pemberitahuan menyertai tampilan yang mudah dibaca manusia. Baik --output yaml maupun --ir-graph tidak menambahkannya, sehingga konsumen yang mengurai salah satunya menerima sebuah dokumen dan tidak ada yang lain.

Contoh lengkap

Pencarian Component katalog

$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0
Schema:
|
values: { port?: int | *8080 }
Uses sockets:
db: selector="component.aggrega.ai/type=stateful-server"

Tampilan bawaan menampilkan deskripsi Component jika Component tersebut menulis deskripsi, lalu skema yang telah di-resolve (setelah penggabungan extends: apa pun) dan uses-socket yang dideklarasikan. Component di atas tidak menulis deskripsi, itulah sebabnya transkrip langsung dimulai dari skema. --detail menambahkan mekanisme self-inject, Features yang diwajibkan, dan label; --list hanya menampilkan pengenal Component dan nama-nama socket-nya.

Feature

$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0
Schema:
|
values: { port?: int | *9090 }
Uses sockets:
backend: selector="component.aggrega.ai/type=stateful-server"
inject: [env]
Secret slots:
token (required)
Targeting:
appliesTo: component.aggrega.ai/type=server
Labels:
feature.aggrega.ai/category: observability

Recipe dengan --show-implements

Tampilan bawaan sebuah Recipe menampilkan satu bagian per mode input yang dideklarasikannya, kapabilitasnya, dan pemetaan nilainya. --show-implements me-resolve referensi spec.implements terhadap katalog dan merender Component yang terikat, beserta lampiran yang diwajibkan oleh Component tersebut:

$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Synthesized
workload: inline
valuesMapping: (none)
Implements Component: core/api-server:1.0.0
requires attachment (observability): core/metrics

Recipe yang mendeklarasikan beberapa mode input

Mode input sebuah Recipe tersusun secara penjumlahan: source: untuk dirender, workload: untuk disintesis, dan map artifacts: masing-masing menyumbang output, dan sebuah Recipe dapat mendeklarasikan kombinasi apa pun dari ketiganya. inspect melaporkan setiap mode yang dideklarasikan Recipe alih-alih memilih salah satunya, sehingga yang Anda lihat adalah himpunan yang Anda tulis:

$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Sourced
source: oci://charts.example.com/api-server:2.1.0
## Synthesized
workload: inline
valuesMapping: inline template
Artifacts: 2
- servicemonitor.yaml
- networkpolicy.yaml

Bagian-bagian diurutkan source: → workload: → artifacts:, urutan yang sama yang diterapkan build ketika me-resolve sebuah Recipe ke satu nama mode dan ketika melaporkan mode terdeklarasi mana yang tidak dapat dipenuhi oleh provider yang terikat — sehingga tampilan ini dan diagnostik build menyebut mode-mode tersebut dalam satu urutan. Recipe yang tidak mendeklarasikan source: maupun workload: dilaporkan sebagai hanya-artifacts, yang merupakan satu-satunya kasus ketika tampilan menyebut satu mode saja.

Manifest (di-resolve secara bawaan)

$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings:
Type → Recipe
core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0
core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0
core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings:
Type → FeatureRecipe
core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings:
(none)

Tampilan bawaan menerapkan rantai extends: milik Manifest dan menyajikan pemetaan komponen dan fitur yang telah di-resolve beserta binding anotasi. --raw menampilkan file sebagaimana ditulis, sebelum resolusi extends.

Aggregate (di-resolve secara bawaan)

$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components:
backend (type: core/compute/api-server)
Values: (none)
Uses:
databases:
- data.main-db
frontend (type: core/compute/web-ui)
Values: (none)
Uses:
apis:
- my-api → backend
main-db (type: core/datastore/postgres)
Values:
database_name: app_production
Uses: (none)
Dependency Graph:
data.main-db
↑ backend
backend
↑ frontend

Tampilan bawaan membangun topologi dan menampilkan setiap komponen beserta nilai dan edge uses-nya, diikuti graf dependensi yang dihitung. Pohon subsistem dirender secara bersarang; --flat merender satu bagian per node, masing-masing diberi kunci berupa path bertitik lengkapnya.

Koneksi yang ditulis dalam bentuk panjang diikuti oleh lampiran yang dibawanya, masing-masing di bawah nama yang dipakainya pada komponen konsumen — alias koneksi dan slot yang digabung dengan titik — dengan tipe Feature yang disebutnya dan klausa yang menyatakan slot yang diisinya serta apakah lampiran tersebut menangani materi yang dinyatakan sensitif:

gateway (type: conn/gateway)
Values:
region: eu
Uses:
models:
- gpt → model
- gpt.credential (feature.conn/token) [slot: credential, sensitive]

Slot dan tanda tersebut adalah fakta yang dicatat oleh build sebuah Release yang men-deploy Aggregate ini untuk lampiran tersebut, dibaca dengan cara yang sama seperti tampilan Release membacanya (lihat Koneksi, slot, dan klausa sensitivitas lampiran); keduanya berasal dari deklarasi slot milik socket dan deklarasi milik Feature itu sendiri, sehingga tidak bergantung pada Release mana yang men-deploy Aggregate. Aggregate tidak menyebut Manifest apa pun, sehingga realisasi yang dipilih Manifest sebuah Release untuk lampiran tersebut tidak ditampilkan di sini. Tampilan ini mencantumkan koneksi sebuah komponen dan apa yang dibawanya; lampiran dari blok milik komponen itu sendiri muncul di tampilan Release.

Release (di-resolve secara bawaan)

Tampilan Release adalah inspeksi dengan taruhan tertinggi. Tampilan ini menjalankan pipeline lengkap dan merender, per batas, setiap node Component, edge uses-nya, dan setiap Feature yang dilampirkan ke node tersebut — yang ditulis pada koneksi berada di bawah edge koneksi tersebut — masing-masing dengan slot lampiran yang diisinya, apakah ia menangani materi yang dinyatakan sensitif, dan FeatureRecipe yang merealisasikannya, ditambah kurung provenans yang mengungkap dari mana lampiran tersebut berasal:

$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns
Directory: ./dist/backend
Annotations (provider-consumed):
aggrega.ai/namespace: backend-zone
Component: backend (type: core/compute/api-server:1.0.0)
Uses:
data.main-db → data.main-db [cross-boundary]
Features: (none)
Boundary: frontend-ns
Directory: ./dist/frontend
Annotations (provider-consumed):
aggrega.ai/namespace: frontend-zone
Component: frontend (type: core/compute/web-ui:1.0.0)
Uses:
my-api → backend [cross-boundary]
Features:
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns
Directory: ./dist/data
Annotations (provider-consumed):
aggrega.ai/namespace: database-zone
Component: data.main-db (type: core/datastore/postgres:1.0.0)
Features: (none)

Setiap batas membawa direktori output-nya dan anotasi yang dikonsumsi provider; setiap komponen di bawah sebuah batas membawa tipe komponen Aggregate-nya, edge uses-nya (edge lintas batas ditandai), masing-masing diikuti lampiran yang dibawa koneksi tersebut, serta lampiran Feature miliknya sendiri, setiap lampiran dengan klausa fakta dan kurung provenansnya. --flat meringkas pohon batas menjadi satu bagian per batas yang diberi kunci berupa path lengkapnya. --raw mengeluarkan file Release apa adanya tanpa pipeline.

Output YAML

$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
db:
selector: component.aggrega.ai/type=stateful-server
schema:
values:
port: {type: integer, default: 8080}

Component yang disebut dari katalog dicetak sebagai entitas hasil resolusi katalog, sehingga setelah penggabungan extends: Anda melihat entitas hasil penggabungan, bukan file yang ditulis; file Component dicetak sebagaimana ditulis.

Output yang dapat dibaca mesin

Dua flag menghasilkan output yang dapat dibaca mesin, dan keduanya menjawab pertanyaan yang berbeda. --output memilih format untuk dokumen yang memang sudah dirender perintah ini; --ir-graph meminta dokumen yang berbeda — graf terkompilasi yang menjadi hasil resolusi sebuah Release — sebagai tambahan. Keduanya independen: memberikan keduanya akan memberi Anda graf dan YAML sebagaimana ditulis, masing-masing sekali.

--output yaml mengeluarkan entitas sebagaimana ditulis, cocok untuk piping dan diffing. Output tersebut apa adanya, termasuk nilai yang dinyatakan sensitif oleh penulis — output yang mengklaim mereproduksi input tidak dapat menyembunyikan sebagian darinya dan tetap mereproduksinya. Salurkan, simpan, dan bagikan output itu sebagaimana Anda memperlakukan file entitas asalnya.

Graf terkompilasi: --ir-graph

aggrega inspect <release> --ir-graph menulis graf hasil resolusi run ke output standar sebagai JSON, sebelum tampilan yang tetap dirender perintah tersebut. Satu dokumen JSON, satu baris baru penutup, sehingga konsumen yang mendekode aliran tersebut membaca graf lalu berhenti.

Flag ini berlaku untuk sebuah Release, satu-satunya jenis yang di-resolve menjadi graf. Jika diminta untuk jenis lain, atau untuk entitas katalog berdasarkan nama, perintah menolak dan menyatakannya, alih-alih merender tampilan milik entitas tersebut dan diam-diam mengabaikan permintaan.

Komposisi yang ditolak oleh pemeriksaan compiler tidak menghasilkan graf. Penolakan yang dijelaskan di Perilaku galat terjadi sebelum apa pun ditulis ke aliran ini, sehingga pipeline yang membacanya tidak pernah menerima graf yang akan ditolak oleh build atas dokumen yang sama — pipeline menerima temuan yang sama dengan yang akan dilaporkan build, dan exit code bukan nol.

Flag yang sama, dengan makna yang sama, ada pada aggrega build dan aggrega validate: masing-masing mengembalikan graf yang dihitung run tersebut, sebagai tambahan atas apa pun yang dihasilkan perintah itu. Integrasi editor membaca graf yang sama melalui protokol daemon.

--output yaml tidak mengeluarkan graf. Flag ini mereproduksi Release sebagaimana ditulis, persis seperti untuk setiap jenis lainnya. Pipeline yang menginginkan graf membacanya dari --ir-graph, dan menerima JSON alih-alih YAML.

Graf menyembunyikan nilai. Graf bukan file yang ditulis seseorang — graf adalah hasil perhitungan kompilasi dari Aggregate, Release, dan katalog — sehingga tidak ada kontrak sebagaimana-ditulis yang harus dipegang, dan deklarasi yang sama yang mengatur tata letak yang dapat dibaca juga mengatur graf. Di mana pun graf membawa daun yang dinyatakan sensitif oleh penulis, nilainya diganti dengan objek berkunci tunggal yang menandainya sebagai disembunyikan:

"values": {
"secretName": "db-creds",
"vault": {
"token": { "aggrega_withheld": "declared" }
}
}

Kuncinya tetap ada, sehingga graf masih menjawab daun mana yang dibawa sebuah node dan lampirannya; hanya nilainya yang hilang. Saudara yang tidak dideklarasikan dalam payload yang sama dikeluarkan sebagaimana ditulis — secretName di atas adalah lokator publik yang sengaja tidak dideklarasikan penulisnya, dan nilainya dicetak. Alasan yang menyertai penanda menyatakan mengapa nilai tidak ada: declared untuk daun yang dicakup deklarasi, dan unreadable ketika payload tiba dalam bentuk yang tidak dapat dibaca perintah ini, dan dalam hal itu seluruh payload disembunyikan alih-alih menebak bagian mana pun darinya.

Konfigurasi milik koneksi itu sendiri disembunyikan dengan cara yang sama. values per koneksi yang ditulis Aggregate pada entri uses dan infra per koneksi yang ditulis Release pada entri tersebut diatur oleh socket komponen yang mengonsumsi — valueSchema dan infraSchema yang dideklarasikannya, yaitu kontrak tempat konfigurasi itu divalidasi — tidak pernah oleh deklarasi target. Leaf yang dideklarasikan sensitive: true oleh salah satu kontrak diganti dengan penanda di values dan infra milik edge, serta di entri uses milik node yang mengonsumsi, yang memuat nilai-nilai sebagaimana ditulis penulisnya; setiap edge mencantumkan leaf yang disembunyikannya di bawah sensitive_payload_leaves, field yang digunakan node untuk leaf miliknya sendiri. Leaf dengan nama yang sama pada koneksi yang socket-nya mendeklarasikannya sebagai dapat dibaca dikeluarkan sebagaimana ditulis.

Berikan --unredacted ketika pipeline benar-benar membutuhkan nilai-nilainya, dan perlakukan hasilnya sebagaimana Anda memperlakukan file entitas itu sendiri. aggrega build dan aggrega validate menerima flag yang sama di samping --ir-graph, dengan ketentuan yang sama: graf yang dikembalikannya menyembunyikan nilai kecuali flag tersebut diberikan.

Protokol daemon memberikan graf yang sama dengan aturan yang sama. aggrega/irGraph menjawab dengan nilai-nilai ini disembunyikan, dan mengembalikannya dalam bentuk teks biasa hanya kepada permintaan yang menetapkan field unredacted-nya — ejaan flag ini dalam protokol. Jadi apa yang digambar panel editor mengikuti deklarasi yang sama, dan klien yang menampilkan nilai melakukannya karena memintanya.

Closure dependensi: --closure

aggrega inspect <release> --closure melaporkan closure dependensi Release: setiap entitas katalog yang dijangkaunya, pada versi hasil resolusi masing-masing, beserta identitas Aggregate dan Manifest hasil resolusi kedua pointernya dan dokumen bersama yang digunakan entitas-entitas tersebut. Tidak ada yang dirender dan tidak ada artefak yang dihasilkan — closure di-resolve, bukan di-build, sehingga tidak ada provider yang dimuat untuk menjawabnya.

Closure dan tampilan yang di-resolve adalah dokumen yang berbeda, dan tidak ada yang dapat dipulihkan dari yang lain. Tampilan yang di-resolve — yang dirender perintah ini secara bawaan untuk sebuah Release — menyatakan seperti apa deployment-nya: batas-batasnya, node komponennya, apa yang terhubung ke apa, dan apa yang dilampirkan ke setiap node. Closure menyatakan apa yang ditarik masuk untuk membangunnya, dan pada versi mana. Sebuah entitas dapat dijangkau tanpa pernah muncul sebagai node — Recipe yang menjadi tujuan pemetaan tipe komponen oleh Manifest dijangkau oleh setiap build dan tidak menjadi node di build mana pun — dan sebuah node mencatat tipe komponen yang dipakai saat dideklarasikan, bukan versi hasil resolusi tipe tersebut. Jadi pembaca yang bertanya “mengapa versi ini berubah?”, “apa yang akan terdampak jika dokumen bersama ini diubah?”, atau “sebenarnya deployment ini bergantung pada apa?” sedang meminta closure, dan pembaca yang memegang tampilan yang di-resolve tidak akan mendapatkannya hanya dengan membaca lebih teliti.

Kata yang sama meminta dokumen yang sama di setiap antarmuka. --closure di sini, aggrega/releaseClosure melalui protokol daemon (lihat aggrega serve “Closure bukanlah graf”), dan mode release dari tool describe melalui protokol tool asisten semuanya menjawab pertanyaan ini tentang sebuah Release; nama Release melalui salah satunya mencapai resolusi yang sama, sehingga ketiganya tidak dapat berbeda pendapat tentang apa yang menjadi dependensi sebuah Release. Pada lockfile yang tidak lagi cocok dengan hasil resolusi Release, perintah ini dan tool describe menolak dengan penghentian drift milik build; sedangkan daemon, yang melayani editor selagi pengeditan berlangsung, menjawab.

Ini satu dokumen, sehingga diminta secara tersendiri. --closure memilih closure sebagai pengganti tampilan yang di-resolve, dan tidak dapat digabungkan dengan --raw, --resolved, --output, atau --ir-graph — masing-masing meminta dokumen yang berbeda tentang Release yang sama, dan perintah yang menerima dua permintaan harus diam-diam hanya menjawab salah satunya. Penggabungan ditolak, dengan menyebut pasangannya.

Ini berlaku untuk sebuah Release dan tidak untuk yang lain. Entitas katalog, file Aggregate, Manifest — tidak ada yang me-resolve closure, sehingga permintaan ditolak alih-alih dijawab dengan merender tampilan milik subjek tersebut sambil mengabaikan permintaan. Permintaan yang diabaikan terlihat bagi pemanggil persis seperti subjek yang closure-nya kosong.

Setiap hasil dibedakan. Release yang berhasil di-resolve dijawab dengan daftar. Path Release yang tidak menyebut file apa pun ditolak, dengan menyatakan bahwa file tersebut tidak ada. Release yang ada tetapi closure-nya tidak dapat di-resolve ditolak dengan menyebut apa yang tidak dapat di-resolve dan dari mana referensi itu berasal, diikuti file apa pun yang ditolak saat pemuatan katalog — karena file yang ditolak adalah alasan umum mengapa entitas yang dijangkau Release hilang. Catatan kepercayaan plugin di samping Release yang ada tetapi tidak dapat dibaca ditolak dengan menyebut apa yang tidak dapat dibaca, karena daftar yang melewatinya akan melaporkan tidak ada plugin yang ditarik padahal tidak ada yang dapat diperiksa. Release yang lockfile-nya tidak lagi cocok dengan hasil resolusinya ditolak dengan penghentian drift yang dicetak oleh build, sebagaimana dijelaskan dalam Perilaku saat terjadi kesalahan, karena versi yang dicantumkan akan merupakan versi yang tidak digunakan oleh build mana pun dari Release tersebut. Daftar kosong tidak pernah menjadi jawaban untuk satu pun di antaranya: daftar kosong akan melaporkan path yang salah ketik, atau workspace yang rusak, sebagai Release yang tidak bergantung pada apa pun.

Ketiga tingkat verbositas berlaku seperti pada setiap jenis. --list hanya mencetak referensi, satu per baris, untuk piping. Tingkat bawaan menambahkan identitas yang di-resolve, versi hasil resolusi setiap referensi, dokumen bersama yang digunakan, setiap pemetaan Manifest yang targetnya tidak mengimplementasikan tipe yang dipetakan kepadanya, dan setiap pemberitahuan penghentian atau penarikan yang dicatat terhadap apa yang menjadi dependensi Release — dalam lockfile-nya, terhadap referensi yang di-pin, dan dalam catatan kepercayaan plugin di sampingnya, terhadap plugin yang dilampirkan dalam peran yang mengembalikan putusan terima-atau-tolak — dengan kata-kata yang dicetak aggrega build untuk penanda yang sama. --detail menambahkan jenis setiap referensi jika lokasi referensi mencatatnya — sebagian posisi dalam dokumen menyatakan jenis yang dirujuknya dan sebagian tidak, sehingga jenis dilaporkan di tempat yang diketahui alih-alih ditebak dari bentuk namanya.

$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0
Aggregate: fullstack-app
Manifest: prod-manifest
Environment: production
Entities (11):
./aggregate.yaml
./manifest.yaml
core/compute/api-server (1.0.0)
core/compute/web-ui (1.0.0)
core/datastore/postgres (1.0.0)
core/k8s-dns-resolver (1.0.0)
db-module (1.0.0)
helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0)
k8s-dns-patcher:1.0.0 (1.0.0)

Jika sebuah workspace telah mencatat versi hasil resolusi sebuah Release, catatan tersebut menjadi titik awal resolusi, sehingga versi yang dilaporkan adalah versi yang digunakan untuk membangun deployment ini, bukan apa pun yang kebetulan ada di katalog saat ini. Workspace tanpa catatan semacam itu melakukan resolusi atas katalog sebagaimana adanya.

Koneksi, slot, dan klausa sensitivitas lampiran

Setiap lampiran Feature dalam tampilan Release membawa klausa yang menyebut fakta-fakta yang dicatat compiler tentang lampiran itu sendiri: slot lampiran mana yang diisinya, apakah ia menangani materi yang dinyatakan sensitif, dan FeatureRecipe yang merealisasikannya — dan, untuk lampiran yang ditulis pada salah satu koneksi komponen, koneksi tempat lampiran itu ditulis. Klausa berada di antara nama lampiran dan kurung provenansnya, dan dibaca secara identik dalam kedua bentuk provenans di bawah.

Lampiran yang ditulis pada koneksi dicantumkan di bawah baris koneksi tersebut dalam Uses:, bukan di bawah Features:, sehingga Features: hanya memuat lampiran milik komponen itu sendiri. Baris di atasnya menyebut koneksi melalui alias dan komponen yang dijangkaunya, dan klausanya sendiri menyatakan sisanya:

  • [socket: <socket>] — socket yang dilalui koneksi, yang tidak disebut oleh baris koneksi. Socket ini mengawali klausa karena mengubah cara sisanya dibaca: separuh slot yang mengikutinya menyebut slot yang dideklarasikan socket koneksi, bukan slot yang dideklarasikan komponen untuk lampirannya sendiri.
  • [connection: <alias> through socket <socket>] — fakta yang sama untuk lampiran yang koneksinya tidak memiliki baris di blok Uses:, yang kemudian dicantumkan di bawah Features: dan menyebut koneksinya di sini. Dengan cara mana pun, sebuah koneksi disebut sekali per lampiran, tidak pernah dua kali.
  • [slot: <name>] — lampiran mengisi slot bernama <name>. Sebuah slot diisi dengan melampirkan Feature di bawah nama slot itu sendiri, sehingga <name> adalah nama tempat lampiran ditulis, dicocokkan dengan slot yang dideklarasikan: featuresSchema milik Component host untuk salah satu lampirannya sendiri, dan featuresSchema yang dideklarasikan socket koneksi untuk lampiran yang ditulis pada koneksi.
  • [free] — lampiran tidak mengisi slot terdeklarasi mana pun: Component yang di-resolve tidak mendeklarasikan slot featuresSchema dengan nama tersebut. Ini adalah temuan, bukan diagnostik. Lampiran bentuk bebas diterima, dan operator yang ingin melarangnya menyatakan hal itu sebagai kebijakan tata kelola alih-alih mengandalkan tool untuk menolaknya.
  • [sensitive] — lampiran menangani materi yang dinyatakan sensitif oleh penulis, karena Feature yang dilampirkan mendeklarasikan daun sensitif, karena slot yang diisinya mendeklarasikan sensitive: true, atau keduanya.
  • [realization: <name>:<version>] — FeatureRecipe yang diikat Manifest milik Release untuk lampiran tersebut: berdasarkan nama lampiran itu sendiri jika Manifest memetakan nama tersebut — untuk lampiran yang ditulis pada koneksi, alias dan slot yang digabung dengan titik — dan jika tidak, berdasarkan tipe Feature-nya. Ini adalah realisasi yang digunakan build atas dokumen yang sama untuk merender lampiran, dan nilai yang sama yang dibawa graf terkompilasi pada lampiran sebagai realization (lihat --ir-graph), sehingga tampilan ini dan graf tidak dapat menyebut realisasi yang berbeda. Bagian ini berada paling akhir dalam klausa.

Jika beberapa fakta berlaku, semuanya berbagi satu klausa. core/storage/s3-object-store mendeklarasikan slot secret_access_key yang ditandai sensitive: true, sehingga kredensial yang dilampirkan dengan nama tersebut melaporkan kedua fakta, sedangkan Feature yang dilampirkan dengan nama yang tidak dideklarasikan sebagai slot oleh Component tidak melaporkan slot maupun sensitivitas. Dengan Manifest yang memetakan setiap tipe Feature ke sebuah FeatureRecipe, setiap baris juga menyebut realisasinya:

Features:
- secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit]
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]

Komponen yang socket models-nya mendeklarasikan slot credential yang ditandai sensitive: true, dan yang menyambungkan koneksi dengan alias gpt yang mengisinya, mencantumkan lampiran tersebut di bawah koneksi — di samping kredensial miliknya sendiri, yang tetap berada di bawah Features::

Uses:
gpt → model
- gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit]
Features:
- db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]

Lampiran yang ditulis pada koneksi tidak pernah melaporkan [free]: sebuah socket hanya menerima slot yang dideklarasikannya, dan koneksi yang membawa nama lain ditolak saat build dimuat.

Klausa dihilangkan seluruhnya jika tidak ada fakta yang berlaku, dan setiap separuhnya dihilangkan secara independen:

  • Tidak ada separuh socket atau koneksi berarti lampiran ditulis pada blok milik komponen itu sendiri, atau mencapainya dari cakupan yang lebih luas atau melalui ekspansi berbasis anotasi.
  • Tidak ada separuh slot berarti himpunan slot terdeklarasi milik Component host tidak dapat di-resolve — misalnya, tipenya tidak cocok dengan entitas katalog mana pun. Hal ini sengaja dibedakan dari [free]: [free] menjawab “tidak ada slot dengan nama itu yang dideklarasikan”, sedangkan separuh yang tidak ada berarti pertanyaannya sama sekali tidak dapat dijawab.
  • Tidak ada sensitive mencatat bahwa tidak ada deklarasi yang menandai lampiran tersebut. Itu lebih sempit daripada putusan bahwa lampiran tidak membawa apa pun yang rahasia; sumbu ini melaporkan deklarasi, dan tidak ada yang disimpulkan dari nama sebuah field atau nilainya.
  • Tidak ada separuh realisasi berarti Manifest tidak mengikat lampiran ke FeatureRecipe mana pun yang ada di katalog.

Slot yang nama terdeklarasinya secara harfiah free juga dirender sebagai [free], tidak dapat dibedakan dari lampiran bentuk bebas — tidak ada yang mencadangkan kata tersebut dalam namespace slot.

Tata bahasa kurung provenans IR

Setiap lampiran Feature dalam tampilan Release membawa kurung provenans. Kurung dapat berbentuk ringkas (satu kurung per Feature jika provenans lampiran seragam di semua daun) atau berbentuk per daun (satu kurung per daun jika daun-daun lampiran berasal dari sumber yang heterogen). Ada tiga isi kurung; ketiganya berlaku secara identik untuk kedua bentuk.

Tiga isi kurung

  • [explicit] — lampiran Feature dideklarasikan oleh penulis. Aggregate atau Release secara eksplisit menyebut Feature pada node yang bersangkutan. Lampiran eksplisit adalah sumber dengan prioritas tertinggi; lampiran ini selalu mengalahkan kontribusi berbasis anotasi pada daun yang sama.

  • [annotation: <key> from <source>] — lampiran Feature berbasis anotasi. Compiler menyintesisnya karena sebuah anotasi pada <source> cocok dengan binding Manifest yang mendeklarasikan Feature ini. <key> adalah kunci anotasi yang memicu binding tersebut (misalnya, business.aggrega.ai/team); <source> adalah entitas yang membawa anotasi tersebut (aggregate, release, component, atau manifest). Lampiran yang disintesis secara struktural identik dengan lampiran eksplisit — rendering hilir memperlakukan keduanya dengan cara yang sama — tetapi kurung provenans membedakan keduanya agar debugging tetap dapat diputuskan.

  • [explicit; overrides annotation: <key> from <source>] — bentuk per daun yang muncul ketika deklarasi eksplisit penulis pada satu daun menekan kontribusi anotasi yang seharusnya menetapkan daun yang sama. Komposisi lintas sisi menghasilkan kasus ini: anotasi Aggregate mungkin menyediakan pilar values: sebuah Feature, anotasi Release menyediakan pilar infra:-nya, dan deklarasi Release eksplisit pada Feature yang sama menimpa satu daun infra. Kurung daun mencatat baik penulis eksplisit maupun anotasi yang ditekan; anotasi yang ditekan tidak berkontribusi pada output yang dirender, tetapi keberadaannya muncul dalam tampilan inspect sehingga operator dapat melihat anotasi mana yang ditimpa dan di mana.

Bentuk ringkas vs bentuk per daun

Compiler memilih antara rendering ringkas dan per daun dengan menelusuri provenans per daun dari lampiran dan memeriksa keseragamannya. Provenans sebuah lampiran seragam jika setiap daun yang terisi (di seluruh pilar values: dan infra: milik Feature) berbagi asal yang sama (eksplisit vs anotasi), kunci anotasi yang sama jika berbasis anotasi, entitas sumber yang sama, dan tidak ada daun yang membawa penanda “overrides annotation”. Jika provenans seragam, compiler mengeluarkan satu kurung per lampiran:

- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]

Jika provenans berbeda — kasus yang umum adalah komposisi lintas sisi, ketika anotasi Aggregate menyediakan values: dan anotasi Release menyediakan infra: pada Feature yang sama — compiler mengeluarkan satu kurung per daun yang terisi:

- core/pii-redaction
values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate]
values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate]
infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]

Urutan penelusuran adalah pilar values terlebih dahulu (dalam urutan penulis), lalu pilar infra (dengan disiplin yang sama). Prefiks pilar (values. / infra.) dan path bertitik di dalam pilar menunjukkan secara tepat daun mana yang dianotasi setiap kurung.

Nilai yang dinyatakan sensitif

Daun yang skemanya mendeklarasikan sensitive: true mencetak teks tetap <redacted> sebagai pengganti nilainya. Kunci, prefiks pilar, dan kurung provenans semuanya dipertahankan — hanya nilainya yang diganti — sehingga tata letak tetap menjawab daun mana yang dibawa sebuah entitas dan dari mana masing-masing berasal. Dua antarmuka yang dapat dibaca terdampak: blok Values: per node milik Aggregate, dan blok lampiran per daun milik Release yang di-resolve — termasuk lampiran yang ditulis pada koneksi, dicetak di bawah baris koneksi tersebut, yang menyembunyikan tepat daun-daun yang disembunyikan Feature yang sama ketika komponen itu sendiri memegangnya. Graf terkompilasi sebuah Release di bawah --ir-graph menyembunyikan daun yang sama dalam bentuk terstruktur yang dijelaskan di Output yang dapat dibaca mesin.

Components:
app (type: core/app)
Values:
appName: demo
dbPassword: <redacted>
tuning.poolSize: 25
tuning.adminToken: <redacted>

Hanya daun yang dideklarasikan yang disembunyikan, dan klausa [sensitive] pada tingkat lampiran bukan instruksi penyembunyian: klausa itu menyatakan bahwa lampiran menangani materi rahasia, bukan daun mana yang membawanya. Lokator yang dipublikasikan dari sebuah Feature kredensial — nama resource dan kunci data — bersifat publik dan sengaja dibiarkan tidak dideklarasikan dalam katalog pustaka standar, sehingga dicetak dalam bentuk teks biasa di samping materi yang tidak publik:

- credentials (feature.test/db-credential)
values.secretName: db-creds [explicit]
values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]

Tidak ada yang disimpulkan dari nama sebuah field: field bernama password yang tidak membawa deklarasi mencetak nilainya, dan field terdeklarasi bernama key tidak. Penyensoran mencakup apa yang dicetak tool; penyensoran tidak pernah menjangkau artefak yang dirender, dan dist/ dikeluarkan persis seperti yang dihasilkan render. Kata kunci dan batas penuh dari apa yang dicapai dengan mendeklarasikannya ada di vocabulary/compact-form-authoring.md “Mendeklarasikan daun sebagai sensitif”.

Menampilkan nilai yang disembunyikan

--unredacted mencetak nilai yang dinyatakan sensitif alih-alih menyembunyikannya, di setiap antarmuka inspect sekaligus — baik tata letak yang dapat dibaca di atas maupun graf terkompilasi sebuah Release. Flag ini ada karena nilai yang disembunyikan terkadang justru yang sedang diselidiki: kredensial yang datang dari lampiran yang salah tampak identik dengan yang benar ketika keduanya terbaca sebagai disembunyikan.

Cakupannya adalah perintah tempat flag ini diberikan. aggrega build dan aggrega validate juga menerimanya, dan di sana flag ini menjangkau graf yang dikembalikan --ir-graph dan tidak ada yang lain, serta menolaknya jika tidak ada graf yang diminta. aggrega build --trace-unredacted adalah gagasan yang sama untuk file trace build, dan tidak satu pun dari kedua flag build menjangkau output yang lain; artefak yang dirender di bawah dist/ tidak terpengaruh oleh semuanya, karena dikeluarkan persis seperti yang dihasilkan render, apa pun yang diberikan.

Apa pun yang dijangkau output kemudian membawa nilai-nilai tersebut dalam bentuk teks biasa — terminal, pipe, file, rekaman layar, laporan bug yang ditempel. Tidak seperti file trace, yang masing-masing dibuka dengan header yang menyatakan bahwa file tersebut ditangkap tanpa penyensoran, output di terminal tidak membawa tanda semacam itu: hanya baris perintah yang menunjukkan bahwa flag tersebut diberikan.

Kapan menggunakan inspect

  • Men-debug “mengapa Feature ini ada di sini?” — lampiran berbasis anotasi tidak terlihat di file YAML Aggregate dan Release (anotasinya ada di sana, tetapi lampiran Feature yang disintesisnya hanya ada di IR). Inspect menampilkannya beserta provenansnya.
  • Memverifikasi pewarisan skema — aggrega inspect <ComponentName> menampilkan skema gabungan setelah rantai extends: di-resolve; file yang ditulis saja hanya menampilkan delta lokal.
  • Mendiagnosis kejutan komposisi lintas sisi — ketika anotasi Aggregate dan anotasi Release sama-sama menyediakan payload pilar pada Feature yang sama, daun-daun yang di-resolve bisa membingungkan untuk direkonstruksi di kepala. Bentuk kurung per daun membuat resolusinya eksplisit.
  • Pemeriksaan verifikasi pra-deployment — aggrega inspect ./prod-release.yaml mencantumkan setiap Feature pada setiap Component sebelum aggrega build menghasilkan artefak; operator dapat memastikan topologi sesuai dengan maksud sebelum meng-commit manifest yang dirender ke GitOps.

Untuk mekanisme yang mendasarinya — bagaimana anotasi mengalir secara bertingkat, bagaimana partisi sisi-vs-pilar mengarahkan nilai anotasi ke pilar Feature, dan bagaimana disiplin lampiran-eksplisit-menang berinteraksi dengan kontribusi berbasis anotasi — lihat providers/well-known-annotations.md dan entities/manifest.md “Binding Feature berbasis anotasi”.

Sinopsis

aggrega inspect [identifier] [flags]

Deskripsi

Render a readable view of any Aggrega entity — a catalog entity by name, an
authored entity file by path, an entity published in a registry, or a
fully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extend
which bases, which Recipe maps to each type, which Features attach to each node,
and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../
or /, or ending in .yaml or .yml — is read as a file and inspected by its own
kind: header. A registry reference — oci://<host>/<repository>:<tag>, or
@<digest> in place of :<tag> — is read from the registry that publishes it.
Anything else is looked up by name in the catalog search stack: the
workspace's own, or, with --release, the one the workspace configuration
gives that Release, so a name several catalog variants declare, one per
Release, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpacked
from the archive its kind is published as where it is one, and rendered by the
same view a file of that kind gets. Reading it reaches the network, using the
credentials this machine holds for that registry, and an offline workspace
refuses it. The fetched bytes are checked against the digest the artifact's
own manifest records for them, which establishes that they are the bytes that
manifest names and nothing more: no signature attached to the artifact is
verified, no withdrawal recorded against it is reported, and nothing is
written — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, the
default for a structured overview, and --detail for full field bodies. --list
and --detail are mutually exclusive. Resolution depth has its own pair, --raw
for the entity exactly as authored and --resolved for the kind's full depth,
also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declared
sensitive appears as authored. That is what as-authored means; handle such
output as you would the entity file itself. --output yaml reproduces the file
the same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag because
neither answer contains the other. --ir-graph asks for the IR graph a Release
resolves to — what the Release looks like, as JSON on stdout in addition to
whatever else this command produces. --closure asks for the Release's dependency
closure — every catalog entity it reaches and the version each resolved to,
which is what was pulled in to build the Release. An entity can be reached
without appearing as a node, and a node does not carry the version its type
resolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command's
own view. Values an author declared sensitive are withheld from the graph, as
they are from the readable layouts. Pass --unredacted to print them instead.

Flag

FlagDefaultDeskripsi
--catalog[]Direktori katalog; dapat diulang. Setiap —catalog <dir> ditambahkan di awal tumpukan pencarian katalog (kecocokan pertama yang menang): catalog_dirs milik workspace, atau, untuk Release yang diberi direktori sendiri oleh konfigurasi workspace di bawah workspace.releases, milik Release tersebut; tumpukan diakhiri dengan direktori bernama catalog di root workspace jika ada. Daftar catalog_dirs yang ditulis kosong tidak membaca katalog lokal sama sekali.
--closurefalseMelaporkan closure dependensi Release — setiap entitas katalog yang dijangkaunya, pada versi hasil resolusi masing-masing — sebagai pengganti tampilan node yang di-resolve. Berlaku untuk sebuah Release, satu-satunya jenis yang me-resolve closure; jenis lain menolak permintaan alih-alih diam-diam mengabaikannya.
--colorautoMewarnai output: auto|always|never.
--detailfalseMerender isi field secara lengkap.
--flatfalseMerender entitas berbentuk pohon (Aggregate, Release) sebagai daftar datar, dengan setiap node diawali path bertitik lengkapnya. Tidak berpengaruh pada jenis tabular.
--ir-graphfalseJuga menulis graf IR yang dihitung run ini ke stdout, sebagai JSON, sebagai tambahan atas semua yang sudah dihasilkan perintah ini. Nilai yang dinyatakan sensitif oleh penulis disembunyikan di dalamnya; berikan —unredacted untuk mencetaknya. Berlaku untuk sebuah Release, satu-satunya jenis yang di-resolve menjadi graf; jenis lain menolak permintaan alih-alih diam-diam mengabaikannya
--listfalseHanya merender pengenal.
--no-colorfalseMenonaktifkan output berwarna (alias untuk —color=never).
--output, -otextFormat output: text|yaml.
--plugin—Path sistem file ke artefak <file.wasm> mentah; menurunkan dan mencetak fungsi host yang diimpornya, sebelum aggrega plugin sync mencatatnya dalam entitas Plugin. Tidak menerima argumen pengenal.
--rawfalseMerender entitas sebagaimana ditulis, tanpa resolusi.
--release—Mencari nama katalog dalam konteks file Release ini: melalui direktori katalog yang diberikan konfigurasi workspace kepada Release tersebut, dengan —catalog ditambahkan di depan. Berlaku untuk sebuah nama; file atau referensi registry diinspeksi sebagaimana adanya dan menolaknya. Path relatif di-resolve terhadap direktori tempat Anda menjalankan perintah, bukan terhadap root workspace. Jika direktori tersebut tidak berada dalam workspace mana pun dan tidak ada root yang disebutkan, path absolut menemukan workspace dari folder milik Release itu sendiri
--resolvedfalseMerender entitas yang sepenuhnya di-resolve.
--show-implementsfalseUntuk Recipe atau FeatureRecipe, me-resolve spec.implements terhadap katalog dan merender Component atau Feature yang terikat.
--unredactedfalseMencetak nilai yang dinyatakan sensitif oleh penulis alih-alih menyembunyikannya. Apa pun yang dijangkau output — terminal, pipe, file, rekaman layar — kemudian membawa nilai-nilai tersebut dalam bentuk teks biasa.