İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

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

bir kez yazılır

Bir dizüstü bilgisayarda

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

Bir Kubernetes kümesinde

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

Kubernetes 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.yaml dosyası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 databases kullanımı bildirir; veritabanı Recipe’inin provides.host değeri, Adminer’ın ADMINER_DEFAULT_SERVER ortam 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 Workload bildirir; provider bir docker-compose.yaml servisi ya da Workload’un form alanının gerektirdiği Kubernetes nesnelerini sentezler: durumsuz web arayüzü için bir Deployment ve bir Service, form: stateful veritabanı için ise replika başına birim talep şablonu veri dizinini taşıyan bir StatefulSet, onu yöneten Headless Service ve tüketicilerin bağlandığı ClusterIP Service ile birlikte.
  • Kimlik bilgisi alt sistemi. Veritabanı parolaları, bileşenin features: sütununda eklenir; her biri feature.aggrega.ai/kind: secret etiketli bir Feature olup uygulama values değerlerinden ayrı tutulur. Component’in featuresSchema alanı 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 bir inject: 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 build bu ö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ün infra.source_version değ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>.yaml ile yenileyin. Her sürüm varyantı, .aggrega-config.yaml dosyasının workspace.releases altı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 --catalog gerekmez.
  • Ek açıklama olarak köken bilgisi. Oluşturulan her Kubernetes nesnesi, onu üreten Recipe’i kaydeden bir aggrega.ai/recipe-uri ek 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-chart provider’ı bir şemsiye chart birleştirir: her bileşenin yerel alt chart’ı olduğu gibi kopyalanır (Helm {{ }} ifadeleri dokunulmadan korunur) ve şemsiyenin values.yaml dosyası, 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:

Terminal window
aggrega scaffold --example mariadb-adminer

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd mariadb-adminer

Derleme

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:

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

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

web, 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_password bir 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, ekteki inject: 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:

Terminal window
aggrega pull --release release-compose.yaml
aggrega 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:

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

http://localhost:8080 adresini açın ve oturum açın:

AlanDeğer
SistemMySQL / MariaDB
Sunucudb (önceden doldurulmuş)
Kullanıcı adıappuser
Paroladev-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.

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

dist/app/helm/ altındaki çıktı:

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

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

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

http://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:

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

dist/app/helm-chart/ altındaki çıktı:

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]

Kurun (alt chart’lar charts/ altına dahil edilmiştir, bu nedenle önce helm dependency build çalıştırmak gerekmez):

Terminal window
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/mariadb ve ./charts/adminer altındaki dosyalar şemsiye chart’a değiştirilmeden paketlenir — Helm {{ }} yönergelerine derleyici dokunmaz ve bunlar helm install sırasında çözümlenir. Oluşturucunun buradaki tek işi şablonlama değil, birleştirmedir. Ayarladığı tek alan, yerleştirilen her Chart.yaml dosyasının name alanı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.yaml anahtarıyla tanımlanan ve ./extras/mariadb-netpol.yaml dosyasından içe aktarılan netpol.yaml artifact’ı — 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.