Contoh yang dapat dijalankan
Sebagai awal, Memulai memasang Aggrega dan memandu dua dari contoh-contoh ini selangkah demi selangkah.
Workspace lengkap yang dapat di-fork dan dapat Anda kompilasi dengan CLI aggrega. Masing-masing adalah direktori mandiri — sebuah Aggregate yang ditulis oleh Developer dan satu atau lebih pasangan Release/Manifest — yang dapat di-build tanpa penyiapan selain yang disebutkan di halamannya. Untuk menemukan contoh berdasarkan produk yang di-deploy-nya atau apa yang ditunjukkannya, gunakan Contoh berdasarkan produk dan kapabilitas, yang mencantumkan setiap contoh di sini.
Contoh-contoh ini hadir dalam dua mode — dua ujung dari satu kurikulum:
-
Konsumsi — workspace mereferensikan entitas katalog pustaka standar dan hanya menulis secara lokal konten khusus pengajarannya sendiri. Workspace ini di-build tanpa flag
--catalog:Terminal window aggrega build --release release.yamlDari mana entitas yang direferensikan itu dibaca bergantung pada workspace. Direktori
catalog/di root workspace dibaca baik ada maupun tidak ada yang menyebutkannya, sehingga workspace yang menulis konten pengajarannya sendiri cukup menyimpannya di sana. Workspace yang membawa.aggrega-config.yamljuga membaca setiap direktori yang tercantum di bawahcatalog_dirs, masing-masing sebuah direktori tempat ia menyimpan entitas. Direktori yang tercantum dicari lebih dahulu dancatalog/terakhir, dan tumpukan ini bersifat first-win, sehingga entitas di direktori yang dicari lebih awal membayangi entitas dengan identitas yang sama di direktori berikutnya. Apa yang tidak dideklarasikan direktori lokal mana pun — entitas pustaka standar — di-resolve dari registry yang disebut konfigurasi sebagaidefault_registry, yaituhub.aggrega.ai. Workspace yang tidak menulis apa pun secara lokal tidak memerlukan entri lokal, dan workspace yang tidak membawa direktoricatalog/maupun.aggrega-config.yamldi-resolve sepenuhnya melalui registry yang dikonfigurasi. Menuliscatalog_dirssebagai daftar kosong menyatakan bahwa workspace sama sekali tidak memiliki katalog lokal. Setiap path dicatalog_dirsmenunjuk direktori di dalam workspace, sehingga salinan seluruh workspace yang diambil ke tempat lain dapat di-build apa adanya.Workspace multi-target yang menyimpan katalog terpisah untuk setiap target menyebut direktori setiap target di bawah
workspace.releases, dengan kunci berupa berkas Release-nya, sehingga setiap Release di-build terhadap katalognya sendiri. -
Authoring — workspace membangun entitas katalog (Components, Features, Recipes) dari awal di direktori lokal
catalog-*/.mariadb-admineradalah contoh authoring yang dikerjakan lengkap; entitas yang dibangunnya sejenis dengan yang dikonsumsi oleh contoh-contoh konsumsi.
Bangun satu release per eksekusi dengan aggrega build --release <release file>; halaman setiap contoh memberikan perintahnya sendiri. Workspace menyediakan katalognya seperti dijelaskan di atas; teruskan --catalog sendiri untuk direktori katalog yang tidak disebutkan oleh workspace, seperti yang ditunjukkan halaman-halaman yang memerlukannya.
Lockfile dihasilkan, bukan disertakan, sehingga clone baru tidak memilikinya dan build pertama memerlukannya. aggrega build bersifat read-only secara default: tanpa lockfile ia berhenti dan menyebutkan dua cara untuk melanjutkan. Teruskan --auto-pull untuk build pertama itu — aggrega build --release release.yaml --auto-pull — untuk me-resolve lockfile selama build; menjalankan aggrega pull --release <release file> sekali sebelumnya memberikan hasil yang sama dan memungkinkan setiap build berikutnya berjalan tanpa flag.
Di checkout repositori dokumentasi, sebagian besar workspace juga membawa helper build-release.sh yang digunakan oleh pemeriksaan repositori itu sendiri untuk build. Helper ini menjalankan aggrega build untuk satu release, menampilkan perintahnya terlebih dahulu, dan melaporkan binary aggrega mana yang digunakannya serta dari mana binary itu berasal; atur AGGREGA_BIN untuk memilih binary. Salinan yang ditulis oleh aggrega scaffold --example membawa helper tersebut tanpa skrip bersama yang dipanggilnya, jadi build salinan seperti itu langsung dengan aggrega build.
Jika sebuah contoh di sini menyebut checkout katalog pustaka standar, Impor menjelaskan dari mana mendapatkannya.
Workspace ini melengkapi halaman konsep yang dijelaskan di Ikhtisar contoh: halaman konsep menjelaskan satu gagasan dan menautkan workspace yang menunjukkannya; workspace di sini adalah stack utuh yang dapat Anda build, baca, dan adaptasi.
Jika sebuah halaman menampilkan apa yang dihasilkan build, blok tersebut disalin dari eksekusi nyata sehingga Anda dapat membandingkan output Anda sendiri dengannya — dan setiap baris yang dihilangkan diberi tanda. Membaca output di halaman-halaman ini menjelaskan konvensi tersebut dan tanda yang digunakannya.
Tidak setiap direktori di sini merupakan satu workspace. Contoh quickstart memuat satu workspace per langkah, dan contoh impor satu per tahap impor, sebagaimana dijelaskan paragraf berikutnya. Satu direktori sama sekali tidak memuat workspace: policy-in-ci memuat dua skrip aturan yang membaca direktori output build dan menolaknya jika melanggar suatu aturan, beserta langkah pipeline untuk masing-masing. Skrip ini dijalankan atas output workspace di sini, dan atas output Anda.
Setiap contoh import-* — yang tercantum di bawah kapabilitas import dalam Contoh berdasarkan produk dan kapabilitas — menyimpan proyek yang ditulis dalam format lain sebagaimana aggrega import menemukannya, dalam dua folder: source/, proyek tersebut, .aggrega-config.yaml yang menjadikannya workspace, dan file jawaban tempat impor membaca nilai-nilai yang tidak dapat dimuat oleh sumber mana pun; dan draft/, file-file yang ditulis impor, tanpa diubah, sebuah workspace yang dapat di-build sebagaimana ditulis, beserta apa yang dicetaknya ke keluaran standar (stdout.txt) dan galat standar (import.txt). Panduan langkah demi langkahnya di bawah Impor mengajarkan setiap tahap. check.sh-nya menjalankan scripts/check-import-example.sh bersama milik repositori ini, yang mengimpor lagi, membandingkan apa yang ditulis dan dicetaknya dengan draft/ serta blok-blok yang dikutip panduan dengan file-file contoh, lalu memvalidasi dan mem-build Release hasil draf.
Urutan pembelajaran
Setiap contoh di sini memiliki satu tempat dalam satu urutan pembelajaran, yang ditentukan oleh tier dan position di header-nya: tingkat demi tingkat, sesuai urutan yang diberikan daftar tingkat, dan yang paling sederhana lebih dulu dalam setiap tingkat. Dalam urutan pembelajaran mencantumkan setiap contoh dengan cara itu, dan bagian Contoh di sidebar mengikuti urutan yang sama. Baca tingkat-tingkatnya dari atas ke bawah, atau langsung ke tingkat yang sesuai dengan apa yang sedang Anda kerjakan; untuk menemukan contoh berdasarkan apa yang di-deploy-nya atau apa yang ditunjukkannya, halaman yang sama mencantumkannya per produk dan per kapabilitas.
Build juga dapat menjalankan plugin atas apa yang direndernya — lihat Kapan menggunakan langkah pipeline.
Header pada setiap contoh
README setiap contoh dibuka dengan header singkat, ditulis sebagai front matter YAML, yang menyatakan apa contoh itu: levelnya, tempatnya dalam urutan pembelajaran, produk yang di-deploy-nya, dan apa yang ditunjukkannya. Contoh berdasarkan produk dan kapabilitas dihasilkan dari header-header ini.
---example: level: start tier: catalog-only position: 1 products: [core/datastore/mariadb, core/devtool/adminer] shows: [connections, credentials]---level adalah salah satu dari level berikut:
start— level “Hanya katalog”: dirakit dari entitas katalog, tanpa ada yang ditulis selain Aggregate, Manifest, dan Release.authoring— level “Authoring”: menulis sebuah Component, sebuah Feature, atau sebuah Recipe, atau menunjukkan bentuknya.advanced— level “Lanjutan”: boundary, kebijakan tata kelola, Features berbasis anotasi, dan stack cloud yang dirakit.
tier adalah bagian dari urutan pembelajaran tempat contoh itu berada, salah satu dari kelompok berikut, yang diajarkan dalam urutan ini:
start-here— Mulai di sini: dua contoh yang dikembangkan panduan “Memulai” selangkah demi selangkah, lalu dua contoh awal untuk cloud.catalog-only— Hanya katalog: dirakit dari entitas katalog, tanpa ada yang ditulis selain Aggregate, Manifest, dan Release.authoring— Penulisan: menulis Component, Feature, atau Recipe miliknya sendiri, atau menunjukkan bagaimana bentuknya.advanced— Lanjutan: batas, kebijakan tata kelola, Features yang digerakkan anotasi, dan stack cloud yang dirakit, beberapa di antaranya digabungkan dalam satu build.importers— Pengimpor: proyek yang ditulis dalam format lain, dijadikan draf berkas Aggrega olehaggrega import, lalu ditinjau dan di-build.
position adalah tempat contoh di dalam kelompoknya, bilangan bulat positif yang tidak dipakai contoh lain di kelompok itu; sebuah kelompok mencantumkan contoh-contohnya dari posisi terendah ke atas, yang paling sederhana lebih dulu.
products mencantumkan setiap Component katalog yang di-deploy contoh, berdasarkan nama yang dibawa entri katalognya. Komponen komputasi generik (misalnya core/compute/server) dan entitas yang dideklarasikan contoh untuk dirinya sendiri tidak dicantumkan, sehingga sebuah contoh bisa tidak mencantumkan apa pun.
shows mencantumkan apa yang didemonstrasikan contoh, setiap entri diambil dari daftar ini:
multi-target— satu Aggregate yang di-build untuk dua target atau lebih, atau direalisasikan dengan dua cara atau lebih.recipe-selection— Manifest memilih Recipe mana yang merealisasikan sebuah komponen, atau FeatureRecipe mana yang merealisasikan sebuah lampiran: per tipe, per instans, atau per target.modules— sebuah Aggregate katalog yang diimpor sebagai modul.connections— komponen yang dihubungkan melalui socketuses, dengan nilai yang disalurkan melintasi setiap sisi.credentials— lampiran kredensial dan cara setiap target mengirimkannya.parameters— nilai yang diangkat menjadi parameter yang dipenuhi oleh sebuah Release.features— Features yang dilampirkan untuk keperluan selain kredensial, seperti perutean, pemantauan, anggaran, cache, atau penyamaran.boundaries— komponen atau modul yang ditempatkan dalam boundary, dan apa yang melintas di antaranya.policy— kebijakan tata kelola yang menerima atau menolak build, selama build atau atas keluarannya.guardrails— sebuah Release yang memang dimaksudkan untuk berhenti, dan pesan yang menyertai penghentiannya.catalog-authoring— sebuah Component, Feature, atau Recipe yang ditulis untuk contoh, disimpan di sampingnya atau dipublikasikan ke katalog.cloud-infrastructure— keluaran Terraform atau CloudFormation untuk layanan cloud terkelola.external-sources— sebuah Recipe yang mengambil apa yang direndernya: chart upstream, repositori git, atau modul.import— proyek yang ditulis dalam format lain, dijadikan draf berkas Aggrega olehaggrega import, lalu ditinjau dan di-build.
Sebuah contoh mencantumkan setidaknya satu produk atau satu kapabilitas, agar indeks dapat menempatkannya. README-nya juga memuat bagian ## Scaffold the example, yang berisi aggrega scaffold --example <name> di blok perintah pertamanya dan cd <name> di blok kedua, langsung diikuti bagian ## Build yang blok perintah pertamanya adalah apa yang dicetak aggrega scaffold --example sebagai langkah berikutnya untuk dijalankan setelah cd itu. scripts/gen-examples-index.sh --check, yang dijalankan dari root repositori ini, memeriksa setiap header terhadap daftar ini, menolak contoh yang tidak memiliki salah satu dari kedua bagian itu, serta contoh yang tidak memiliki check.sh yang dapat dieksekusi maupun build-release.sh, dan memastikan indeks mutakhir; jalankan tanpa --check untuk menulis ulang indeks.