MariaDB + Adminer — contoh dua target yang dapat dijalankan
Contoh ini mengompilasi sebuah stack kecil yang nyata — basis data MariaDB dengan antarmuka web Adminer di depannya — dari satu Aggregate yang ditulis oleh Developer ke dua platform:
- Docker Compose untuk pengembangan lokal, dan
- Kubernetes untuk klaster lokal (kind / minikube / k3d), dirender dengan tiga cara.
Aggregate yang sama menggerakkan keduanya. Hanya Release, Manifest-nya, dan lapisan Recipe yang dimuat saat build yang berubah. Setiap berkas di sini dapat dikompilasi dengan CLI aggrega yang disertakan, dan keluaran yang dirender dapat dijalankan: jalankan stack, buka Adminer di peramban, lalu masuk ke basis data yang aktif.
aggregate.yamlditulis sekali
Di laptop
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlDi klaster Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildManifes Kubernetes
Setiap platform di-build dari Release dan Manifest miliknya sendiri. Aggregate, yang mendeskripsikan aplikasi Anda, tetap sama.
Apa yang didemonstrasikan
- Satu permukaan penulisan, banyak target. Satu
aggregate.yamlmenjadi sumber kebenaran tentang apa stack tersebut. Setiap target adalah lapisan katalog tipis yang menyatakan bagaimana mewujudkannya. - String Pipe. Adminer mendeklarasikan penggunaan
databasesatas MariaDB;provides.hostmilik Recipe basis data dialirkan ke variabel lingkunganADMINER_DEFAULT_SERVERmilik Adminer. Compiler merutekan string tersebut tanpa menafsirkannya — sehingga build compose menyambungkan nama layanan compose dan build Kubernetes menyambungkan nama DNS Service, dari edge yang sama. - Sintesis workload. Recipes compose dan Kubernetes mandiri mendeklarasikan
Workloadyang agnostik terhadap kapabilitas; provider menyintesis layanandocker-compose.yaml, atau objek Kubernetes yang diminta olehformmilik Workload — sebuahDeploymentdan sebuahServiceuntuk UI web tanpa status, dan untuk basis dataform: statefulsebuahStatefulSetyang templat klaim volume per replikanya memuat direktori data, di sampingServiceHeadless yang mengaturnya danClusterIPServiceyang dihubungi oleh konsumen. - Subsistem kredensial. Kata sandi basis data dilampirkan dalam pilar
features:milik komponen — masing-masing sebuahFeatureberlabelfeature.aggrega.ai/kind: secret, terpisah darivaluesaplikasi.featuresSchemamilik Component mendeklarasikan dua jenis slot, dan contoh ini menggunakan keduanya: slot kotak hitam yang nilainya dikirimkan secara internal oleh FeatureRecipe, dan slot transparan yang nilainya dikirimkan secara eksplisit oleh pengembang dengan blokinject:pada lampiran. - Sumber chart jarak jauh. Target Kubernetes terkelola mengambil chart
Bitnami MariaDB upstream melalui referensi OCI.
aggrega pullmenyematkan chart dalam lockfile dan mengambilnya ke dalam cache beralamat konten;aggrega buildmerender dari cache tersebut, sehingga waktu penguncian dan waktu build me-resolve chart yang sama. Versi chart berasal dariinfra.source_versionmilik operator jika Release menyematkannya, dan jika tidak, dari nilai yang ditulis pengembang (nilai yang mengalir ke resolusi sumber). Lockfile per release menyematkan identitas dan digest entitas: setelah entitas katalog diganti nama atau kontennya berubah, perbarui lockfile lokal yang usang denganaggrega pull --release release-<variant>.yaml. Setiap varian release di-resolve terhadap direktori katalog saudaranya sendiri, yang dinamai oleh.aggrega-config.yamluntuknya di bawahworkspace.releases, sehingga--catalogtidak diperlukan di terminal, di editor, maupun melalui asisten. - Provenans sebagai anotasi. Setiap objek Kubernetes yang dirender membawa
anotasi
aggrega.ai/recipe-uriyang mencatat Recipe yang menghasilkannya — sebuah anotasi, bukan label, karena nilai URI berisi karakter yang tidak boleh ada dalam nilai label Kubernetes. - Komposisi chart (vs sintesis). Aggregate yang sama dapat menghasilkan
chart Helm yang dapat didistribusikan ulang alih-alih manifest yang dirender.
Provider
helm-chartmenyusun chart payung: sub-chart lokal setiap komponen disalin apa adanya ({{ }}Helm-nya dipertahankan tanpa diubah), danvalues.yamlmilik chart payung merutekan nilai yang dipetakan dari setiap komponen — termasuk host basis data yang dialirkan — di bawah alias komponen tersebut. - Pemilihan Provider berdasarkan tipe komponen. Recipe yang merender setiap komponen adalah Recipe yang dipetakan oleh Manifest target untuk tipe komponen tersebut, diambil dari lapisan katalog mana pun yang dimuat oleh build.
Penulisan dan konsumsi — workspace campuran
Contoh ini menggarap kedua ujung katalog sekaligus: contoh ini menulis sebagian entitas secara lokal dan mengonsumsi entitas lainnya dari pustaka standar Aggrega. Component basis data MariaDB, Features kredensialnya, dan Recipes per target dibangun dari awal di direktori catalog-*/ lokal — satu Aggregate merender basis data yang ditulis secara lokal itu ke empat target. Sebaliknya, UI web Adminer dikonsumsi: component web langsung mereferensikan Component core/devtool/adminer yang disertakan, dan setiap target hanya menulis satu Recipe lokal yang mengimplementasikannya. Dengan demikian, workspace yang sama menunjukkan penulisan entitas di sisi basis data berdampingan dengan konsumsi katalog di sisi UI. Entitas yang Anda bangun di sini memiliki jenis yang sama dengan yang disertakan dalam pustaka standar: sebuah Component basis data, Features kredensial, dan Recipes provider.
Contoh catalog-only berada di ujung konsumsi murni dari kurikulum yang sama: contoh itu menyusun stack yang persis sama ini — basis data MariaDB dengan UI Adminer — dengan mereferensikan entitas pustaka standar, tanpa menulis satu pun entitas sendiri. Bacalah sisi basis data dari contoh ini untuk mempelajari cara entitas katalog dibangun; bacalah contoh-contoh konsumsi untuk mempelajari cara seluruh stack digunakan dari katalog yang disertakan.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example mariadb-adminerKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd mariadb-adminerBuild
Setiap target adalah satu Release, di-build satu per eksekusi; pull menulis lockfile yang dibaca build. Docker Compose lebih dulu — bagian setiap target di bawah memberikan perintahnya sendiri:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlDengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder ruang kerja belum berisi folder `mariadb-adminer`, panggil alat `scaffold` sekali dengan `example` diatur ke `mariadb-adminer` dan tanpa `dir`: alat ini menulis contoh ke folder `mariadb-adminer` yang baru. Kemudian panggil alat `build` dengan `workspace_root` diatur ke `mariadb-adminer`, `release` diatur ke `release-compose.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis oleh build; file tersebut berada di bawah `mariadb-adminer/dist/`.Tata letak
mariadb-adminer/├── aggregate.yaml # Developer intent — shared by every target│├── manifest-compose.yaml # Ops mapping, Docker Compose target├── release-compose.yaml # Operator release, Docker Compose target├── catalog-compose/ # Recipe layer: compose│├── manifest-helm-synth.yaml # Ops mapping, self-contained Kubernetes target├── release-helm-synth.yaml # Operator release, self-contained Kubernetes target├── catalog-helm-synth/ # Recipe layer: helm (Workload synthesis)│├── manifest-helm-bitnami.yaml # Ops mapping, managed-chart Kubernetes target├── release-helm-bitnami.yaml # Operator release, managed-chart Kubernetes target├── catalog-helm-bitnami/ # Recipe layer: helm (upstream Bitnami chart)│├── manifest-helm-chart.yaml # Ops mapping, composed-Helm-chart target├── release-helm-chart.yaml # Operator release, composed-Helm-chart target└── catalog-helm-chart/ # Recipe layer: helm-chart (umbrella composition)Setiap direktori catalog-* memuat definisi Component dan Feature MariaDB yang ditulis secara lokal beserta Recipes untuk target tersebut. Component Adminer tidak termasuk di dalamnya — Component tersebut di-resolve dari pustaka standar. Sebuah build memuat satu lapisan catalog-* di atas pustaka standar tersebut, dan Manifest target memetakan setiap tipe komponen ke sebuah Recipe di lapisan itu.
Release, aggregate:-nya, dan manifest:-nya berada sejajar di direktori
ini; direktori katalog yang menjadi dasar build setiap Release disebutkan untuknya di
.aggrega-config.yaml.
Aggregate bersama
spec: components: db: type: core/datastore/mariadb values: database: appdb user: appuser charset: utf8mb4 collation: utf8mb4_general_ci chart_version: "25.0.8" # the managed-chart target's chart, absent an operator pin features: root_password: # black-box slot: the FeatureRecipe delivers it type: core/secret-value values: { key: MARIADB_ROOT_PASSWORD, origin: dev-root-pw-change-me } user_password: # transparent slot: the developer delivers it type: core/secret-provided values: { origin: dev-app-pw-change-me } inject: env: [{ in: MARIADB_PASSWORD, from: value }]
web: type: core/devtool/adminer values: design: pepa-linha-dark uses: databases: db: target: db inject: env: - in: ADMINER_DEFAULT_SERVER from: hostweb mendeklarasikan penggunaan databases atas db. Blok inject mengikat provides.host milik Recipe basis data ke variabel lingkungan
ADMINER_DEFAULT_SERVER pada kontainer Adminer. Tidak ada bagian dalam Aggregate yang menyebut penyedia;
pilihan itu sepenuhnya berada di lapisan katalog yang dimuat oleh build.
Catatan tentang kredensial
Image MariaDB memerlukan kata sandi root untuk dijalankan, dan pengguna aplikasi memerlukan kata sandinya sendiri. Keduanya dilampirkan di pilar features: milik komponen basis data — dipisahkan dari values aplikasi — sebagai Features berlabel feature.aggrega.ai/kind: secret. featuresSchema milik Component core/datastore/mariadb mendeklarasikan satu slot untuk masing-masing, dan contoh ini menjalankan kedua model pengiriman:
root_passwordadalah slot kotak hitam (inject: []): FeatureRecipe mengirimkan nilainya ke dalam pipa komponen. Pengembang tidak — dan tidak boleh — menentukan caranya.user_passwordadalah slot transparan (inject: [env, file]): kredensial mengekspos nilainya, dan pengembang memetakannya ke variabel lingkungan dengan blokinject:pada lampiran.
Nilai di sini berupa literal inline agar stack dapat dijalankan dengan satu perintah — cocok untuk pengembangan lokal dan demo. Untuk lingkungan bersama atau produksi, lampiran yang sama mengambil nilainya dari penyimpanan rahasia: katalog target memuat FeatureRecipe yang mengambilnya, dan Aggregate tidak berubah.
Target 1 — Docker Compose
Lakukan pull, lalu build — pull menulis release-compose.lock, yang dibaca oleh build:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlKeluaran: dist/app/compose/docker-compose.yaml — dua layanan dalam satu jaringan.
db menjalankan mariadb:11.4 dengan basis data, pengguna, charset, dan kata sandi
yang diinjeksikan; web menjalankan adminer:4, memublikasikan port 8080, bergantung pada db, dan
membawa ADMINER_DEFAULT_SERVER: db (nama layanan compose yang dikeluarkan oleh Recipe
basis data).
Jalankan:
docker compose -f dist/app/compose/docker-compose.yaml up -dBuka http://localhost:8080 dan masuk:
| Field | Nilai |
|---|---|
| System | MySQL / MariaDB |
| Server | db (sudah terisi) |
| Username | appuser |
| Password | dev-app-pw-change-me |
| Database | appdb |
(atau root / dev-root-pw-change-me). Hentikan dan hapus dengan
docker compose -f dist/app/compose/docker-compose.yaml down -v.
Target 2 — Kubernetes (mandiri)
Target ini merender manifest Kubernetes biasa langsung dari Workload,
tanpa chart eksternal — satu build luring.
Workload milik database mendeklarasikan form: stateful, sehingga ia menyintesis sebuah
StatefulSet yang direktori datanya berupa templat klaim volume per replika, alih-alih
sebuah Deployment yang berbagi satu klaim. Dua pendamping menyertai bentuk tersebut: volume
dideklarasikan sebagai persistentTemplate, dan sebuah Service Headless menyediakan
identitas DNS per pod yang stabil yang disebut oleh StatefulSet sebagai layanan
pengaturnya. Adminer tidak menyimpan state, sehingga Workload miliknya membiarkan form pada nilai bawaan
dan tetap menjadi Deployment — persistensi adalah properti dari Workload, bukan
komponen yang berbeda.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlKeluaran di bawah dist/app/helm/:
db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysqldb-default-service.yaml # ClusterIP Service "db-default" on 3306db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceNameweb-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-defaultweb-default-service.yaml # NodePort Service "web-default" on 8080Perhatikan ADMINER_DEFAULT_SERVER: db-default — untuk Kubernetes, Recipe database
mengeluarkan nama DNS Service di dalam klaster, sehingga edge Aggregate yang sama ter-resolve menjadi
alamat yang dapat dirutekan pada target ini.
Terapkan dan buka:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Buka http://localhost:8080 dan masuk dengan Server db-default, nama pengguna
appuser, kata sandi dev-app-pw-change-me, database appdb. Hapus dengan
kubectl delete -f dist/app/helm/.
Target 3 — Kubernetes (chart Bitnami terkelola)
Lapisan ketiga mengimplementasikan Component core/datastore/mariadb yang sama
terhadap chart Helm Bitnami MariaDB upstream alih-alih menyintesis
manifest. Recipe mengambil chart melalui referensi OCI dan memetakan
nilai-nilai Component ke skema nilai chart:
spec: capability: helm implements: core/datastore/mariadb source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` .values.chart_version }}" # operator pin, else the value valuesMapping: | auth: database: "{{ .values.database }}" rootPassword: "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" username: "{{ .values.user }}" password: "{{ .context.inject.env.MARIADB_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" primary: persistence: size: "{{ .infra.storage.size }}" # … resources, read replicas, metrics mapped from infra …source.version milik Recipe mengutamakan infra.source_version dari operator dan
beralih ke .values.chart_version yang ditulis pengembang. Penyematan versi chart
adalah urusan infrastruktur, sehingga sematan operator menang di mana pun sebuah
Release menetapkannya; Release ini sengaja tidak menetapkan apa pun, sehingga kunci .values adalah
versi yang benar-benar di-resolve — dan itulah inti target ini, karena
nilai pengembang yang mencapai resolusi sumber hanya dapat diamati pada output
yang dirender selama sematan operasional tidak ada. Sematkan source_version pada komponen db
di release-helm-bitnami.yaml, dan label helm.sh/chart yang dirender
akan mengikuti versi tersebut.
optional membaca sematan berdasarkan nama, bukan sebagai jalur bertitik; itulah yang memungkinkan
sematan yang tidak ada beralih ke nilai pengembang alih-alih di-resolve menjadi versi
kosong — lihat optional
untuk semantik pemeriksaan keberadaan.
Membangun target ini adalah alur dua langkah: aggrega pull me-resolve chart,
menyematkannya di release-helm-bitnami.lock, dan mengambilnya ke dalam cache build
beralamat konten (satu-satunya langkah daring); aggrega build kemudian merender dari cache,
sehingga waktu penguncian dan waktu build me-resolve chart yang identik. Kredensial yang diinjeksi
mengalir ke nilai auth milik chart, dan chart menghasilkan Secret Kubernetes
yang dibaca basis data. Adminer dirender oleh Recipe tersintesis yang sama
seperti Target 2 dan terhubung ke Service utama chart (db-mariadb). Kedua
target mandiri di atas adalah cara tanpa dependensi untuk menjalankan stack
secara menyeluruh.
Target 4 — Kubernetes (Helm chart terkomposisi)
Lapisan keempat mengimplementasikan komponen yang sama terhadap penyedia helm-chart,
yang menyusun Helm umbrella chart yang dapat didistribusikan ulang alih-alih
merender manifes (Target 2) atau merender chart upstream (Target 3). Setiap
Recipe mengambil sumber dari sebuah chart lokal kecil:
spec: capability: helm-chart implements: core/datastore/mariadb source: ./charts/mariadb # copied as the sub-chart, bar its own name valuesMapping: | { "database": "{{ .values.database }}", "rootPassword": "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}", "serviceName": "{{ .context.instance_id }}-mariadb" }Bangun:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlKeluaran di bawah dist/app/helm-chart/:
Chart.yaml # umbrella; lists db and web as sub-chart dependenciesvalues.yaml # alias-keyed: db.* and web.* value blockscharts/├── db/ # the local ./charts/mariadb; its Chart.yaml name is `db`│ ├── Chart.yaml│ ├── values.yaml│ └── templates/│ ├── deployment.yaml│ ├── service.yaml│ ├── pvc.yaml│ └── netpol.yaml # injected artifact (see below)└── web/ # the local ./charts/adminer; its Chart.yaml name is `web` [… omitted: web's own Chart.yaml, values.yaml, and a templates/ holding deployment.yaml and service.yaml — Adminer keeps no state, so it has no pvc.yaml, and the injected netpol.yaml is db's alone]Instal (sub-chart telah di-vendor di bawah charts/, sehingga
helm dependency build tidak perlu dijalankan terlebih dahulu):
helm install mariadb-adminer dist/app/helm-chart/values.yaml milik umbrella sudah memuat nilai terselesaikan dari setiap komponen, sehingga
database dimulai dengan kredensialnya dan Adminer terhubung ke Service MariaDB
— koneksi yang sama dengan yang dinyatakan target lain, kini dikirim sebagai chart
yang dapat Anda instal atau vendor.
Dua rezim delimiter yang berbeda berlaku, dan keduanya tidak tumpang tindih:
- Sub-chart yang bersumber disalin, kecuali namanya sendiri. Berkas di bawah
./charts/mariadbdan./charts/adminerdibundel ke dalam umbrella tanpa perubahan — direktif Helm{{ }}di dalamnya tidak disentuh oleh compiler dan diselesaikan saathelm install. Satu-satunya tugas composer di sana adalah perakitan, bukan templating. Satu-satunya field yang ditetapkannya adalahnamepada setiapChart.yamlyang ditempatkan, yang menjadi identitas instans komponen (db,web) sehingga dua komponen yang mem-vendor chart dengan nama yang sama tetap dapat dibedakan; lihatproviders/helm-chart.md. - Artefak
$import:menggunakan delimiter ganda. Sebuah Recipe dapat menyisipkan berkas template tambahan melaluiartifacts: { name: { $import: ... } }. Berkas tersebut — dan hanya berkas tersebut — dirender terlebih dahulu oleh compiler dengan delimiter[[ ]]sebelum ditempatkan, sementara{{ }}di dalamnya dipertahankan untuk Helm. Artefaknetpol.yaml— dengan kuncinetpol.yamldan diimpor dari./extras/mariadb-netpol.yaml, karena kunci menamai berkas yang dihasilkan dan impor memilih isinya — menunjukkan campurannya:[[ .context.instance_id ]](diisi saat build) dan{{ .Release.Namespace }}(dibiarkan untuk instalasi).
String Pipe dinyatakan dalam istilah chart: penggunaan MariaDB oleh databases milik Adminer
menyelesaikan provides.host dari Recipe database ke dalam values.yaml milik umbrella
di bawah alias web (adminerDefaultServer: db-mariadb), yang dibaca oleh sub-chart
Adminer sebagai {{ .Values.adminerDefaultServer }}. Nilai yang sama menamai
Service sub-chart MariaDB, sehingga koneksi terselesaikan secara konsisten saat instalasi.
Keluarannya adalah chart untuk helm install atau di-vendor — bukan sekumpulan manifes yang diterapkan.
Cara target dipilih
Pemilihan Recipe dilakukan berdasarkan tipe komponen: Manifest setiap target memetakan setiap tipe ke sebuah Recipe di lapisan katalog yang dimuat oleh Release-nya, sehingga manifest-compose.yaml mengikat core/datastore/mariadb ke Recipe compose, sedangkan manifest-helm-synth.yaml mengikatnya ke Recipe Kubernetes. Tipe yang tidak dipetakan oleh Manifest akan menghentikan build dan menyebut Recipes yang mengimplementasikannya, bahkan jika lapisan yang dimuat hanya berisi satu. Provider yang merender sebuah node adalah spec.capability dari Recipe mana pun yang diikat. Mengganti target berarti mengganti Release, beserta Manifest-nya dan direktori katalog yang disebutkan oleh .aggrega-config.yaml untuknya — Aggregate tidak pernah berubah.