MariaDB + Adminer — çalıştırılabilir, çift hedefli bir örnek
Bu örnek, küçük ama gerçek bir yığını — önünde bir Adminer web arayüzü bulunan bir MariaDB veritabanını — Developer tarafından yazılmış tek bir Aggregate’ten iki platforma derler:
- yerel geliştirme için Docker Compose ve
- Yerel bir küme (kind / minikube / k3d) için Kubernetes, üç farklı biçimde işlenir.
Aynı Aggregate her ikisini de yönlendirir. Yalnızca Release, onun Manifest’i ve derleme zamanında yüklenen Recipe katmanı değişir. Buradaki her dosya, birlikte gelen aggrega CLI ile derlenir ve oluşturulan çıktı çalışır: yığını ayağa kaldırın, Adminer’ı bir tarayıcıda açın ve canlı veritabanında oturum açın.
aggregate.yamlbir kez yazılır
Bir dizüstü bilgisayarda
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlBir Kubernetes kümesinde
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildKubernetes manifestleri
Her platform kendi Release’inden ve Manifest’inden derlenir. Uygulamanızı tanımlayan Aggregate aynı kalır.
Neyi gösteriyor
- Tek yazım yüzeyi, birçok hedef. Yığının ne olduğu konusunda tek doğruluk
kaynağı tek bir
aggregate.yamldosyasıdır. Her hedef, bunun nasıl gerçekleştirileceğini söyleyen ince bir katalog katmanıdır. - String Pipe. Adminer, MariaDB’ye yönelik bir
databaseskullanımı bildirir; veritabanı Recipe’ininprovides.hostdeğeri, Adminer’ınADMINER_DEFAULT_SERVERortam değişkenine aktarılır. Derleyici dizeyi yorumlamadan yönlendirir; böylece aynı kenardan compose derlemesi bir compose servis adını, Kubernetes derlemesi ise bir Service DNS adını bağlar. - Workload sentezi. Compose ve kendi kendine yeten Kubernetes Recipes,
yetenekten bağımsız bir
Workloadbildirir; provider birdocker-compose.yamlservisi ya da Workload’unformalanının gerektirdiği Kubernetes nesnelerini sentezler: durumsuz web arayüzü için birDeploymentve birService,form: statefulveritabanı için ise replika başına birim talep şablonu veri dizinini taşıyan birStatefulSet, onu yöneten HeadlessServiceve tüketicilerin bağlandığıClusterIPServiceile birlikte. - Kimlik bilgisi alt sistemi. Veritabanı parolaları, bileşenin
features:sütununda eklenir; her birifeature.aggrega.ai/kind: secretetiketli birFeatureolup uygulamavaluesdeğerlerinden ayrı tutulur. Component’infeaturesSchemaalanı iki yuva türü bildirir ve örnek ikisini de kullanır: FeatureRecipe’in değeri dahili olarak ilettiği kara kutu bir yuva ve değerini geliştiricinin ekleme üzerindeki birinject:bloğuyla açıkça ilettiği şeffaf bir yuva. - Uzak chart kaynakları. Yönetilen Kubernetes hedefi, upstream Bitnami MariaDB
chart’ını OCI referansıyla kaynak alır.
aggrega pull, chart’ı bir kilit dosyasında sabitler ve içerik adresli bir önbelleğe indirir;aggrega buildbu önbellekten oluşturur, böylece kilitleme zamanı ve derleme zamanı aynı chart’ı çözümler. Chart sürümü, Release bir sürüm sabitliyorsa operatörüninfra.source_versiondeğerinden, aksi halde geliştiricinin yazdığı bir değerden (kaynak çözümlemesine akan bir değer) gelir. Sürüm başına kilit dosyaları varlık kimliklerini ve özetlerini sabitler: katalog varlıkları yeniden adlandırıldıktan veya içerikleri değiştikten sonra eskimiş yerel kilit dosyasınıaggrega pull --release release-<variant>.yamlile yenileyin. Her sürüm varyantı,.aggrega-config.yamldosyasınınworkspace.releasesaltında onun için adlandırdığı kendi kardeş katalog dizinine göre çözümlenir; bu nedenle terminalde, bir düzenleyicide veya bir asistan aracılığıyla--cataloggerekmez. - Ek açıklama olarak köken bilgisi. Oluşturulan her Kubernetes nesnesi, onu
üreten Recipe’i kaydeden bir
aggrega.ai/recipe-uriek açıklaması taşır; bu bir etiket değil ek açıklamadır, çünkü URI değeri bir Kubernetes etiket değerinin içeremeyeceği karakterler içerir. - Chart birleştirme (sentezin karşısında). Aynı Aggregate, oluşturulmuş
manifestler yerine yeniden dağıtılabilir bir Helm chart’ı üretebilir.
helm-chartprovider’ı bir şemsiye chart birleştirir: her bileşenin yerel alt chart’ı olduğu gibi kopyalanır (Helm{{ }}ifadeleri dokunulmadan korunur) ve şemsiyeninvalues.yamldosyası, aktarılan veritabanı ana bilgisayarı dahil her bileşenin eşlenmiş değerlerini o bileşenin takma adı altına yönlendirir. - Bileşen türüne göre Provider seçimi. Her bileşeni oluşturan Recipe, hedefin Manifest’inin o bileşenin türünü eşlediği Recipe’dir ve derlemenin yüklediği katalog katmanı hangisiyse oradan alınır.
Yazma ve tüketme — karma bir çalışma alanı
Bu örnek kataloğun iki ucunu aynı anda işler: bazı varlıkları yerel olarak yazar, diğerlerini ise Aggrega’nın standart kütüphanesinden tüketir. MariaDB veritabanı Component’i, onun kimlik bilgisi Features’ı ve hedefe özgü Recipes, yerel catalog-*/ dizinlerinde sıfırdan oluşturulur — tek bir Aggregate, yerel olarak yazılmış bu veritabanını dört hedef üzerinde işler. Adminer web arayüzü ise buna karşılık tüketilir: web bileşeni, birlikte gelen core/devtool/adminer Component’ine doğrudan başvurur ve her hedef yalnızca onu uygulayan yerel bir Recipe yazar. Bu nedenle aynı çalışma alanı, veritabanı tarafındaki varlık yazımını arayüz tarafındaki katalog tüketimiyle yan yana gösterir. Burada oluşturduğunuz varlıklar, standart kütüphaneyle birlikte gelenlerle aynı türdendir: bir veritabanı Component’i, kimlik bilgisi Features’ı, sağlayıcı Recipes’ı.
catalog-only örneği aynı müfredatın saf tüketim ucunda yer alır: tam olarak bu yığını — Adminer arayüzlü bir MariaDB veritabanını — standart kütüphane varlıklarına başvurarak ve kendine ait hiçbir varlık yazmadan bir araya getirir. Katalog varlıklarının nasıl oluşturulduğunu öğrenmek için bu örneğin veritabanı tarafını okuyun; bütün bir yığının birlikte gelen katalogdan nasıl kullanıldığını öğrenmek için tüketim örneklerini okuyun.
Örneği oluşturun
Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.
Örneği, adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example mariadb-adminerArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:
cd mariadb-adminerDerleme
Her hedef bir Release’dir ve her çalıştırmada bir tane derlenir; pull, derlemenin okuduğu kilit dosyasını yazar. Önce Docker Compose — aşağıdaki her hedefin bölümü kendi komutlarını verir:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlBir yapay zekâ asistanıyla
Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz klasör oluşturmayın. Çalışma alanı klasöründe henüz `mariadb-adminer` klasörü yoksa `scaffold` aracını `example` değeri `mariadb-adminer` olacak şekilde ve `dir` olmadan bir kez çağırın: araç örneği yeni bir `mariadb-adminer` klasörüne yazar. Ardından `build` aracını `workspace_root` değeri `mariadb-adminer`, `release` değeri `release-compose.yaml`, `auto_pull` değeri true ve `write` değeri true olacak şekilde çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `mariadb-adminer/dist/` altındadır.Düzen
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)Her catalog-* dizini, yerel olarak yazılmış MariaDB Component ve Feature tanımlarını ve o tek hedefe ait Recipes’i içerir. Adminer Component’i bunların arasında değildir; standart kitaplıktan çözümlenir. Bir derleme, o standart kitaplığın üzerine tek bir catalog-* katmanı yükler ve hedefin Manifest’i her bileşen türünü bu katmandaki bir Recipe’e eşler.
Release, onun aggregate: ve manifest: dosyaları bu dizinde
yan yana bulunur; her Release’in karşısında derlendiği katalog dizini
.aggrega-config.yaml içinde o Release için belirtilir.
Paylaşılan Aggregate
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, db için bir databases kullanımı bildirir. inject bloğu, veritabanı Recipe’inin provides.host değerini Adminer kapsayıcısındaki ADMINER_DEFAULT_SERVER ortam
değişkenine bağlar. Aggregate’teki hiçbir şey bir sağlayıcı adlandırmaz;
bu seçim tamamen derlemenin yüklediği katalog katmanında yer alır.
Kimlik bilgileri hakkında bir not
MariaDB imajının başlamak için bir root parolasına, uygulama kullanıcısının ise kendi parolasına ihtiyacı vardır. İkisi de veritabanı bileşeninin features: sütununda — uygulama values değerlerinden ayrı tutularak — feature.aggrega.ai/kind: secret etiketli Features olarak eklenir. core/datastore/mariadb Component’inin featuresSchema alanı her biri için bir yuva bildirir ve örnek her iki teslim modelini de kullanır:
root_passwordbir kara kutu yuvasıdır (inject: []): FeatureRecipe değeri bileşenin hattına teslim eder. Geliştirici bunun nasıl yapılacağını belirlemez — ve belirleyemez.user_passwordşeffaf bir yuvadır (inject: [env, file]): kimlik bilgisi değerini açığa çıkarır ve geliştirici, ektekiinject:bloğuyla onu bir ortam değişkenine eşler.
Buradaki değerler satır içi sabitlerdir; böylece yığın tek bir komutla çalışır — yerel geliştirme ve demolar için uygundur. Paylaşılan veya üretim ortamlarında aynı ekler değerlerini bir gizli bilgi deposundan çözümler: hedefin kataloğu bunları getiren bir FeatureRecipe yükler ve Aggregate değişmez.
Hedef 1 — Docker Compose
Önce pull, ardından derleme — pull, derlemenin okuduğu release-compose.lock dosyasını yazar:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlÇıktı: dist/app/compose/docker-compose.yaml — tek bir ağ üzerinde iki servis.
db, veritabanı, kullanıcı, karakter kümesi ve enjekte edilen parolalarla
mariadb:11.4 çalıştırır; web, adminer:4 çalıştırır, 8080 portunu yayımlar, db’ye bağımlıdır ve
ADMINER_DEFAULT_SERVER: db değerini taşır (veritabanı Recipe’inin ürettiği
compose servis adı).
Çalıştırın:
docker compose -f dist/app/compose/docker-compose.yaml up -dhttp://localhost:8080 adresini açın ve oturum açın:
| Alan | Değer |
|---|---|
| Sistem | MySQL / MariaDB |
| Sunucu | db (önceden doldurulmuş) |
| Kullanıcı adı | appuser |
| Parola | dev-app-pw-change-me |
| Veritabanı | appdb |
(veya root / dev-root-pw-change-me). Kaldırmak için
docker compose -f dist/app/compose/docker-compose.yaml down -v komutunu kullanın.
Hedef 2 — Kubernetes (kendi kendine yeten)
Bu hedef, düz Kubernetes manifestlerini harici bir chart olmadan doğrudan Workload’dan oluşturur;
tek bir çevrimdışı derleme yeterlidir.
Veritabanının Workload’ı form: stateful bildirir; bu nedenle tek bir talebi paylaşan bir
Deployment yerine, veri dizini replika başına bir birim talebi şablonu olan bir StatefulSet sentezler.
Bu biçimle birlikte iki eşlikçi gelir: birim bir persistentTemplate olarak bildirilir ve bir Headless Service,
StatefulSet’in yönetici servisi olarak adlandırdığı, pod başına kararlı DNS kimliğini sağlar.
Adminer durum tutmaz; bu nedenle Workload’ı form’u varsayılan değerde bırakır
ve bir Deployment olarak kalır — kalıcılık farklı bir bileşen değil, Workload’ın bir özelliğidir.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamldist/app/helm/ altındaki çıktı:
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 8080ADMINER_DEFAULT_SERVER: db-default değerine dikkat edin: Kubernetes için veritabanı Recipe’i
küme içi Service DNS adını üretir; böylece aynı Aggregate kenarı bu hedefte
yönlendirilebilir bir adrese çözümlenir.
Uygulayın ve açın:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080http://localhost:8080 adresini açın ve Sunucu db-default, kullanıcı adı
appuser, parola dev-app-pw-change-me, veritabanı appdb ile oturum açın. Kaldırmak için
kubectl delete -f dist/app/helm/ komutunu kullanın.
Hedef 3 — Kubernetes (yönetilen Bitnami chart’ı)
Üçüncü katman, manifest sentezlemek yerine aynı core/datastore/mariadb Component’ini upstream Bitnami MariaDB Helm chart’ına karşı uygular.
Recipe, chart’ı OCI referansıyla kaynak olarak alır ve Component’in değerlerini chart’ın değer şemasına eşler:
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 …Recipe’nin source.version alanı, operatörün infra.source_version değerini tercih eder ve geliştiricinin yazdığı .values.chart_version değerine geri düşer. Chart sürümünün sabitlenmesi bir altyapı konusudur; bu nedenle bir Release bir sabitleme belirlediği her yerde operatörün sabitlemesi kazanır. Bu Release bilerek hiçbirini belirlemez, dolayısıyla gerçekte çözümlenen sürüm .values anahtarıdır. Hedefin bütün amacı da budur: kaynak çözümlemesine ulaşan bir geliştirici değeri, operasyonel sabitleme yokken yalnızca işlenmiş çıktıda gözlemlenebilir. release-helm-bitnami.yaml içindeki db bileşeninde source_version değerini sabitlerseniz işlenmiş helm.sh/chart etiketi bunun yerine o sürümü izler.
optional, sabitlemeyi noktalı bir yol olarak değil adıyla okur; bu da olmayan bir sabitlemenin boş bir sürüme çözümlenmek yerine geliştirici değerine düşmesini sağlar. Varlık denetimi semantiği için optional bölümüne bakın.
Bu hedefin derlenmesi iki adımlı bir akıştır: aggrega pull chart’ı çözümler, release-helm-bitnami.lock içinde sabitler ve içerik adresli derleme önbelleğine indirir (tek çevrimiçi adım); ardından aggrega build önbellekten işler, böylece kilitleme zamanı ve derleme zamanı aynı chart’ı çözümler. Enjekte edilen kimlik bilgileri chart’ın auth değerlerine akar ve chart, veritabanının okuduğu Kubernetes Secret nesnesini üretir. Adminer, Hedef 2’deki aynı sentezlenmiş Recipe ile işlenir ve chart’ın birincil Service’ine (db-mariadb) bağlanır. Yukarıdaki iki kendi kendine yeten hedef, yığını uçtan uca çalıştırmanın sıfır bağımlılıklı yoludur.
Hedef 4 — Kubernetes (oluşturulmuş Helm chart)
Dördüncü katman aynı bileşenleri helm-chart
sağlayıcısına karşı uygular; bu sağlayıcı manifest’leri işlemek (Hedef 2) ya da bir upstream chart’ı işlemek (Hedef 3) yerine yeniden dağıtılabilir bir Helm şemsiye chart’ı oluşturur. Her
Recipe küçük bir yerel chart’ı kaynak olarak alır:
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" }Derleyin:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamldist/app/helm-chart/ altındaki çıktı:
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]Kurun (alt chart’lar charts/ altına dahil edilmiştir, bu nedenle önce
helm dependency build çalıştırmak gerekmez):
helm install mariadb-adminer dist/app/helm-chart/Şemsiye chart’ın values.yaml dosyası her bileşenin çözümlenmiş değerlerini zaten taşır, bu nedenle
veritabanı kimlik bilgileriyle başlar ve Adminer MariaDB
Service’ine bağlanır — diğer hedeflerin ifade ettiği bağlantının aynısı, artık kurabileceğiniz ya da projenize dahil edebileceğiniz bir chart olarak sunulur.
Birbirinden ayrı iki sınırlayıcı düzeni geçerlidir ve bunlar çakışmaz:
- Kaynak olarak alınan alt chart’lar, kendi adları dışında olduğu gibi kopyalanır.
./charts/mariadbve./charts/admineraltındaki dosyalar şemsiye chart’a değiştirilmeden paketlenir — Helm{{ }}yönergelerine derleyici dokunmaz ve bunlarhelm installsırasında çözümlenir. Oluşturucunun buradaki tek işi şablonlama değil, birleştirmedir. Ayarladığı tek alan, yerleştirilen herChart.yamldosyasınınnamealanıdır; bu alan bileşen örneğinin kimliği (db,web) olur, böylece aynı adı bildiren chart’ları dahil eden iki bileşen birbirinden ayırt edilebilir kalır; bkz.providers/helm-chart.md. $import:artifact’ları çift sınırlayıcılıdır. Bir Recipe,artifacts: { name: { $import: ... } }aracılığıyla ek şablon dosyaları ekleyebilir. Bu dosyalar — ve yalnızca bunlar — yerlerine konmadan önce derleyici tarafından[[ ]]sınırlayıcılarıyla önceden işlenir,{{ }}ifadeleri ise Helm için korunur.netpol.yamlanahtarıyla tanımlanan ve./extras/mariadb-netpol.yamldosyasından içe aktarılannetpol.yamlartifact’ı — anahtar üretilen dosyayı adlandırır, içe aktarma ise içeriğini seçer — bu karışımı gösterir:[[ .context.instance_id ]](derlemede doldurulur) ve{{ .Release.Namespace }}(kurulum için bırakılır).
String Pipe chart terimleriyle ifade edilir: Adminer’ın MariaDB’yi databases olarak kullanması,
veritabanı Recipe’inin provides.host değerini şemsiye chart’ın values.yaml dosyasına
web takma adı altında (adminerDefaultServer: db-mariadb) çözümler; Adminer
alt chart’ı bunu {{ .Values.adminerDefaultServer }} olarak okur. Aynı değer
MariaDB alt chart’ının Service’ini adlandırır, böylece bağlantı kurulumda tutarlı biçimde çözümlenir. Çıktı, helm install ile kurulacak ya da projeye dahil edilecek bir chart’tır — uygulanmış bir manifest kümesi değil.
Bir hedef nasıl seçilir
Recipe seçimi bileşen türüne göre yapılır: her hedefin Manifest’i her türü, kendi Release’inin yüklediği katalog katmanındaki bir Recipe’e eşler; bu nedenle manifest-compose.yaml, core/datastore/mariadb türünü compose Recipe’ine bağlarken manifest-helm-synth.yaml onu Kubernetes Recipe’ine bağlar. Manifest’in eşlemediği bir tür, yüklenen katmanda yalnızca bir tane olsa bile, onu uygulayan Recipes’i adlandırarak derlemeyi durdurur. Bir düğümü işleyen sağlayıcı, hangi Recipe bağlandıysa onun spec.capability değeridir. Hedefleri değiştirmek, Release’i, onun Manifest’i ve .aggrega-config.yaml dosyasının onun için belirttiği katalog diziniyle birlikte değiştirmektir — Aggregate hiçbir zaman değişmez.