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

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.yaml

ditulis sekali

Di laptop

release-compose.yaml
manifest-compose.yaml
aggrega build
docker-compose.yaml

Di klaster Kubernetes

release-helm-synth.yaml
manifest-helm-synth.yaml
aggrega build

Manifes 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.yaml menjadi sumber kebenaran tentang apa stack tersebut. Setiap target adalah lapisan katalog tipis yang menyatakan bagaimana mewujudkannya.
  • String Pipe. Adminer mendeklarasikan penggunaan databases atas MariaDB; provides.host milik Recipe basis data dialirkan ke variabel lingkungan ADMINER_DEFAULT_SERVER milik 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 Workload yang agnostik terhadap kapabilitas; provider menyintesis layanan docker-compose.yaml, atau objek Kubernetes yang diminta oleh form milik Workload — sebuah Deployment dan sebuah Service untuk UI web tanpa status, dan untuk basis data form: stateful sebuah StatefulSet yang templat klaim volume per replikanya memuat direktori data, di samping Service Headless yang mengaturnya dan ClusterIP Service yang dihubungi oleh konsumen.
  • Subsistem kredensial. Kata sandi basis data dilampirkan dalam pilar features: milik komponen — masing-masing sebuah Feature berlabel feature.aggrega.ai/kind: secret, terpisah dari values aplikasi. featuresSchema milik 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 blok inject: pada lampiran.
  • Sumber chart jarak jauh. Target Kubernetes terkelola mengambil chart Bitnami MariaDB upstream melalui referensi OCI. aggrega pull menyematkan chart dalam lockfile dan mengambilnya ke dalam cache beralamat konten; aggrega build merender dari cache tersebut, sehingga waktu penguncian dan waktu build me-resolve chart yang sama. Versi chart berasal dari infra.source_version milik 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 dengan aggrega pull --release release-<variant>.yaml. Setiap varian release di-resolve terhadap direktori katalog saudaranya sendiri, yang dinamai oleh .aggrega-config.yaml untuknya di bawah workspace.releases, sehingga --catalog tidak diperlukan di terminal, di editor, maupun melalui asisten.
  • Provenans sebagai anotasi. Setiap objek Kubernetes yang dirender membawa anotasi aggrega.ai/recipe-uri yang 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-chart menyusun chart payung: sub-chart lokal setiap komponen disalin apa adanya ({{ }} Helm-nya dipertahankan tanpa diubah), dan values.yaml milik 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:

Terminal window
aggrega scaffold --example mariadb-adminer

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd mariadb-adminer

Build

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:

Terminal window
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.yaml

Dengan 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: host

web 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_password adalah slot kotak hitam (inject: []): FeatureRecipe mengirimkan nilainya ke dalam pipa komponen. Pengembang tidak — dan tidak boleh — menentukan caranya.
  • user_password adalah slot transparan (inject: [env, file]): kredensial mengekspos nilainya, dan pengembang memetakannya ke variabel lingkungan dengan blok inject: 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:

Terminal window
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.yaml

Keluaran: 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:

Terminal window
docker compose -f dist/app/compose/docker-compose.yaml up -d

Buka http://localhost:8080 dan masuk:

FieldNilai
SystemMySQL / MariaDB
Serverdb (sudah terisi)
Usernameappuser
Passworddev-app-pw-change-me
Databaseappdb

(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.

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

Keluaran di bawah dist/app/helm/:

db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysql
db-default-service.yaml # ClusterIP Service "db-default" on 3306
db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceName
web-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-default
web-default-service.yaml # NodePort Service "web-default" on 8080

Perhatikan 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:

Terminal window
kubectl apply -f dist/app/helm/
kubectl rollout status statefulset/db
kubectl port-forward svc/web-default 8080:8080

Buka 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:

Terminal window
aggrega pull --release release-helm-chart.yaml
aggrega build --release release-helm-chart.yaml

Keluaran di bawah dist/app/helm-chart/:

Chart.yaml # umbrella; lists db and web as sub-chart dependencies
values.yaml # alias-keyed: db.* and web.* value blocks
charts/
├── 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):

Terminal window
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/mariadb dan ./charts/adminer dibundel ke dalam umbrella tanpa perubahan — direktif Helm {{ }} di dalamnya tidak disentuh oleh compiler dan diselesaikan saat helm install. Satu-satunya tugas composer di sana adalah perakitan, bukan templating. Satu-satunya field yang ditetapkannya adalah name pada setiap Chart.yaml yang ditempatkan, yang menjadi identitas instans komponen (db, web) sehingga dua komponen yang mem-vendor chart dengan nama yang sama tetap dapat dibedakan; lihat providers/helm-chart.md.
  • Artefak $import: menggunakan delimiter ganda. Sebuah Recipe dapat menyisipkan berkas template tambahan melalui artifacts: { name: { $import: ... } }. Berkas tersebut — dan hanya berkas tersebut — dirender terlebih dahulu oleh compiler dengan delimiter [[ ]] sebelum ditempatkan, sementara {{ }} di dalamnya dipertahankan untuk Helm. Artefak netpol.yaml — dengan kunci netpol.yaml dan 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.