MariaDB + Adminer — một ví dụ chạy được với hai đích triển khai
Ví dụ này biên dịch một stack nhỏ nhưng thực tế — một cơ sở dữ liệu MariaDB với giao diện web Adminer đứng trước nó — từ một Aggregate duy nhất do Developer viết ra hai nền tảng:
- Docker Compose cho phát triển cục bộ, và
- Kubernetes cho một cluster cục bộ (kind / minikube / k3d), được render theo ba cách.
Cùng một Aggregate điều khiển cả hai. Chỉ có Release, Manifest của nó và lớp Recipe được nạp lúc build là thay đổi. Mọi tệp ở đây đều biên dịch được bằng CLI aggrega đi kèm, và đầu ra đã render chạy được: khởi động stack, mở Adminer trong trình duyệt, và đăng nhập vào cơ sở dữ liệu đang chạy.
aggregate.yamlviết một lần
Trên laptop
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlTrên một cluster Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildCác manifest Kubernetes
Mỗi nền tảng được build từ Release và Manifest riêng của nó. Aggregate, vốn mô tả ứng dụng của bạn, vẫn giữ nguyên.
Ví dụ này minh họa điều gì
- Một bề mặt soạn thảo, nhiều đích. Một tệp
aggregate.yamlduy nhất là nguồn sự thật cho việc stack là gì. Mỗi đích là một lớp catalog mỏng cho biết cách hiện thực hóa nó. - String Pipe. Adminer khai báo một mục dùng
databasestới MariaDB; giá trịprovides.hostcủa Recipe cơ sở dữ liệu được dẫn vào biến môi trườngADMINER_DEFAULT_SERVERcủa Adminer. Trình biên dịch định tuyến chuỗi mà không diễn giải nó — vì vậy bản build compose nối một tên service compose còn bản build Kubernetes nối một tên DNS của Service, từ cùng một cạnh. - Tổng hợp Workload. Các Recipes compose và Kubernetes tự chứa
khai báo một
Workloadkhông phụ thuộc vào năng lực; provider tổng hợp một service trongdocker-compose.yaml, hoặc các đối tượng Kubernetes màformcủa Workload yêu cầu — mộtDeploymentvà mộtServicecho web UI không trạng thái, và với cơ sở dữ liệuform: statefullà mộtStatefulSetcó mẫu volume claim theo từng bản sao chứa thư mục dữ liệu, cùng vớiServiceHeadless quản lý nó vàServiceClusterIPmà các bên tiêu thụ kết nối tới. - Hệ thống con thông tin xác thực. Mật khẩu cơ sở dữ liệu được gắn trong
trụ cột
features:của component — mỗi mật khẩu là mộtFeatuređược gắn nhãnfeature.aggrega.ai/kind: secret, tách biệt khỏivaluescủa ứng dụng.featuresSchemacủa Component khai báo hai loại slot, và ví dụ này dùng cả hai: một slot hộp đen mà FeatureRecipe của nó cung cấp giá trị bên trong, và một slot minh bạch mà nhà phát triển cung cấp giá trị một cách tường minh bằng một khốiinject:trên phần gắn kèm. - Nguồn chart từ xa. Đích Kubernetes được quản lý lấy chart MariaDB
Bitnami thượng nguồn qua tham chiếu OCI.
aggrega pullghim chart vào một lockfile và tải nó vào bộ nhớ đệm định địa chỉ theo nội dung;aggrega buildkết xuất từ bộ nhớ đệm đó, nên lúc khóa và lúc build phân giải cùng một chart. Phiên bản chart lấy từinfra.source_versioncủa operator nếu Release ghim một giá trị, và nếu không thì từ một giá trị do nhà phát triển soạn (một giá trị chảy vào việc phân giải nguồn). Các lockfile theo từng release ghim danh tính và digest của thực thể: sau khi thực thể catalog được đổi tên hoặc nội dung thay đổi, hãy làm mới một lockfile cục bộ đã cũ bằngaggrega pull --release release-<variant>.yaml. Mỗi biến thể release phân giải dựa trên thư mục catalog anh em riêng của nó, được.aggrega-config.yamlđặt tên dướiworkspace.releases, nên không cần--catalogkhi dùng terminal, trình soạn thảo hay qua trợ lý. - Nguồn gốc dưới dạng annotation. Mọi đối tượng Kubernetes được kết xuất đều mang một
annotation
aggrega.ai/recipe-urighi lại Recipe đã tạo ra nó — là annotation chứ không phải label, vì giá trị URI chứa các ký tự mà giá trị label của Kubernetes không cho phép. - Kết hợp chart (so với tổng hợp). Cùng một Aggregate có thể tạo ra một
Helm chart có thể phân phối lại thay vì các manifest đã kết xuất. Provider
helm-chartkết hợp một umbrella chart: sub-chart cục bộ của mỗi component được sao chép nguyên văn (giữ nguyên{{ }}của Helm), vàvalues.yamlcủa umbrella định tuyến các giá trị đã ánh xạ của mỗi component — kể cả host cơ sở dữ liệu được dẫn — dưới alias của component đó. - Chọn Provider theo loại component. Recipe dùng để render mỗi component là Recipe mà Manifest của target ánh xạ loại component đó tới, lấy từ lớp catalog nào mà bản build tải vào.
Soạn thảo và sử dụng — một workspace kết hợp
Ví dụ này làm việc với cả hai đầu của catalog cùng lúc: nó soạn thảo một số thực thể cục bộ và sử dụng các thực thể khác từ thư viện chuẩn của Aggrega. Component cơ sở dữ liệu MariaDB, các Features thông tin xác thực của nó và các Recipes theo từng target được xây dựng từ đầu trong các thư mục catalog-*/ cục bộ — một Aggregate kết xuất cơ sở dữ liệu được soạn thảo cục bộ đó trên bốn target. Ngược lại, giao diện web Adminer được sử dụng: component web tham chiếu trực tiếp đến Component core/devtool/adminer đi kèm, và mỗi target chỉ soạn thảo một Recipe cục bộ triển khai nó. Do đó, cùng một workspace cho thấy việc soạn thảo thực thể ở phía cơ sở dữ liệu bên cạnh việc sử dụng catalog ở phía giao diện. Các thực thể bạn xây dựng ở đây cùng loại với những thực thể đi kèm trong thư viện chuẩn: một Component cơ sở dữ liệu, các Features thông tin xác thực, các Recipes của provider.
Ví dụ catalog-only nằm ở đầu thuần sử dụng của cùng lộ trình học: nó lắp ráp chính stack này — một cơ sở dữ liệu MariaDB với giao diện Adminer — bằng cách tham chiếu các thực thể của thư viện chuẩn, không tự soạn thảo thực thể nào. Hãy đọc phía cơ sở dữ liệu của ví dụ này để tìm hiểu cách các thực thể catalog được xây dựng; hãy đọc các ví dụ về sử dụng để tìm hiểu cách cả một stack được sử dụng từ catalog đi kèm.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example mariadb-adminerSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd mariadb-adminerBuild
Mỗi đích là một Release, mỗi lần chạy build một Release; lệnh pull ghi lockfile mà bản build đọc. Docker Compose trước — mục của mỗi đích bên dưới đưa ra các lệnh riêng của nó:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlVới trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `mariadb-adminer`, hãy gọi công cụ `scaffold` một lần với `example` được đặt thành `mariadb-adminer` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `mariadb-adminer` mới. Sau đó gọi công cụ `build` với `workspace_root` được đặt thành `mariadb-adminer`, `release` được đặt thành `release-compose.yaml`, `auto_pull` được đặt thành true và `write` được đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `mariadb-adminer/dist/`.Bố cục
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)Mỗi thư mục catalog-* chứa các định nghĩa Component và Feature MariaDB được tạo cục bộ cùng với các Recipes cho riêng target đó. Component Adminer không nằm trong số đó — nó được phân giải từ thư viện chuẩn. Một lần build nạp một lớp catalog-* lên trên thư viện chuẩn đó, và Manifest của target ánh xạ mỗi loại component tới một Recipe trong lớp đó.
Release, aggregate: của nó và manifest: của nó nằm cạnh nhau trong
thư mục này; thư mục catalog mà mỗi Release build dựa trên được chỉ định cho nó trong
.aggrega-config.yaml.
Aggregate dùng chung
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 khai báo một lần dùng databases đối với db. Khối inject gắn provides.host của Recipe cơ sở dữ liệu vào biến môi trường
ADMINER_DEFAULT_SERVER trên container Adminer. Không có gì trong Aggregate nêu tên một provider;
lựa chọn đó nằm hoàn toàn trong lớp catalog mà bản build nạp.
Ghi chú về thông tin xác thực
Image MariaDB cần mật khẩu root để khởi động, và người dùng ứng dụng cần mật khẩu riêng. Cả hai được gắn vào trụ features: của component cơ sở dữ liệu — tách riêng khỏi values của ứng dụng — dưới dạng các Features được gắn nhãn feature.aggrega.ai/kind: secret. featuresSchema của Component core/datastore/mariadb khai báo một vị trí cho mỗi mật khẩu, và ví dụ sử dụng cả hai mô hình cung cấp:
root_passwordlà một vị trí hộp đen (inject: []): FeatureRecipe đưa giá trị vào đường ống của component. Nhà phát triển không — và không được phép — quy định cách thức.user_passwordlà một vị trí trong suốt (inject: [env, file]): thông tin xác thực để lộ giá trị của nó, và nhà phát triển ánh xạ giá trị đó tới một biến môi trường bằng khốiinject:trên phần gắn.
Các giá trị ở đây là literal nội tuyến để stack chạy được chỉ bằng một lệnh — phù hợp cho phát triển cục bộ và demo. Với môi trường dùng chung hoặc production, cùng các phần gắn đó lấy giá trị từ một kho bí mật: catalog của target nạp một FeatureRecipe để lấy chúng, và Aggregate không thay đổi.
Mục tiêu 1 — Docker Compose
Pull, rồi build — lệnh pull ghi release-compose.lock, tệp mà bản build sẽ đọc:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlĐầu ra: dist/app/compose/docker-compose.yaml — hai dịch vụ trên cùng một mạng.
db chạy mariadb:11.4 với cơ sở dữ liệu, người dùng, bộ ký tự và các mật khẩu
được chèn vào; web chạy adminer:4, công bố cổng 8080, phụ thuộc vào db, và
mang ADMINER_DEFAULT_SERVER: db (tên dịch vụ compose mà Recipe cơ sở dữ liệu
đã sinh ra).
Chạy nó:
docker compose -f dist/app/compose/docker-compose.yaml up -dMở http://localhost:8080 và đăng nhập:
| Trường | Giá trị |
|---|---|
| Hệ thống | MySQL / MariaDB |
| Máy chủ | db (đã được điền sẵn) |
| Tên người dùng | appuser |
| Mật khẩu | dev-app-pw-change-me |
| Cơ sở dữ liệu | appdb |
(hoặc root / dev-root-pw-change-me). Gỡ bỏ bằng
docker compose -f dist/app/compose/docker-compose.yaml down -v.
Mục tiêu 2 — Kubernetes (tự chứa)
Mục tiêu này kết xuất trực tiếp các manifest Kubernetes thuần từ Workload, không dùng chart bên ngoài — một lần build ngoại tuyến duy nhất.
Workload của cơ sở dữ liệu khai báo form: stateful, nên nó tổng hợp một StatefulSet có thư mục dữ liệu là một volume claim template riêng cho từng replica, thay vì một Deployment dùng chung một claim. Hai thành phần đi kèm với dạng này: volume được khai báo dưới dạng persistentTemplate, và một Service Headless cung cấp danh tính DNS ổn định cho từng pod mà StatefulSet chỉ định làm dịch vụ quản lý của nó. Adminer không lưu trạng thái, nên Workload của nó để form ở giá trị mặc định và vẫn là một Deployment — tính bền vững là một thuộc tính của Workload, không phải một thành phần khác.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlĐầu ra trong 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 8080Lưu ý ADMINER_DEFAULT_SERVER: db-default — với Kubernetes, Recipe của cơ sở dữ liệu phát ra tên DNS của Service trong cluster, nên cùng một cạnh Aggregate được phân giải thành một địa chỉ có thể định tuyến trên mục tiêu này.
Áp dụng và mở nó:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Mở http://localhost:8080 và đăng nhập với Server db-default, tên người dùng appuser, mật khẩu dev-app-pw-change-me, cơ sở dữ liệu appdb. Gỡ bỏ bằng kubectl delete -f dist/app/helm/.
Mục tiêu 3 — Kubernetes (chart Bitnami được quản lý)
Lớp thứ ba triển khai cùng Component core/datastore/mariadb
dựa trên Helm chart MariaDB của Bitnami ở thượng nguồn thay vì tổng hợp
manifest. Recipe lấy chart qua tham chiếu OCI và ánh xạ
các giá trị của Component vào lược đồ giá trị của 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 của Recipe ưu tiên infra.source_version của người vận hành và
quay về .values.chart_version do nhà phát triển viết. Việc ghim phiên bản chart
là mối quan tâm của hạ tầng, nên phiên bản ghim của người vận hành thắng ở bất cứ đâu một
Release đặt nó; Release này cố ý không đặt, nên khóa .values là
phiên bản thực sự được phân giải — đó chính là mục đích của mục tiêu này, vì một
giá trị của nhà phát triển đi đến bước phân giải nguồn chỉ quan sát được trong đầu ra
đã render khi không có phiên bản ghim vận hành. Hãy ghim source_version trên component db
trong release-helm-bitnami.yaml và nhãn helm.sh/chart được render
sẽ theo phiên bản đó.
optional đọc phiên bản ghim theo tên thay vì theo đường dẫn có dấu chấm, đó là điều cho phép
một phiên bản ghim vắng mặt rơi về giá trị của nhà phát triển thay vì phân giải thành một phiên bản
rỗng — xem optional
để biết ngữ nghĩa kiểm tra sự hiện diện.
Việc build mục tiêu này gồm hai bước: aggrega pull phân giải chart,
ghim nó trong release-helm-bitnami.lock, và tải nó vào bộ nhớ đệm build định địa chỉ theo nội dung
(bước trực tuyến duy nhất); sau đó aggrega build render từ bộ nhớ đệm,
nên thời điểm khóa và thời điểm build phân giải cùng một chart. Thông tin xác thực được chèn
đi vào các giá trị auth của chart, và chart tạo ra Secret Kubernetes
mà cơ sở dữ liệu đọc. Adminer được render bởi cùng Recipe tổng hợp
như Mục tiêu 2 và kết nối tới Service chính của chart (db-mariadb). Hai
mục tiêu tự chứa ở trên là cách không phụ thuộc để chạy toàn bộ stack
từ đầu đến cuối.
Mục tiêu 4 — Kubernetes (Helm chart tổng hợp)
Lớp thứ tư triển khai cùng các component đó dựa trên provider helm-chart,
provider này tổng hợp một Helm umbrella chart có thể phân phối lại thay vì
render manifest (Mục tiêu 2) hay render một chart upstream (Mục tiêu 3). Mỗi
Recipe lấy nguồn từ một chart cục bộ nhỏ:
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" }Build nó:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlĐầu ra nằm trong 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]Cài đặt nó (các sub-chart đã được vendor sẵn trong charts/, nên không cần chạy
helm dependency build trước):
helm install mariadb-adminer dist/app/helm-chart/values.yaml của umbrella đã chứa sẵn các giá trị đã được phân giải của từng component, nên
cơ sở dữ liệu khởi động với thông tin xác thực của nó và Adminer được nối tới Service của MariaDB
— cùng kết nối mà các mục tiêu khác thể hiện, giờ được phân phối dưới dạng một chart
mà bạn có thể cài đặt hoặc vendor.
Có hai chế độ dấu phân cách riêng biệt được áp dụng, và chúng không chồng lấn nhau:
- Các sub-chart lấy từ nguồn được sao chép nguyên vẹn, trừ tên của chính chúng. Các tệp trong
./charts/mariadbvà./charts/adminerđược đóng gói vào umbrella mà không thay đổi — các chỉ thị Helm{{ }}của chúng không bị trình biên dịch động đến và được phân giải lúchelm install. Việc duy nhất của bộ tổng hợp ở đó là lắp ráp, không phải tạo template. Trường duy nhất nó thiết lập lànamecủa mỗiChart.yamlđược đặt vào, trường này trở thành danh tính của instance component (db,web) để hai component vendor các chart khai báo cùng một tên vẫn phân biệt được; xemproviders/helm-chart.md. - Các artifact
$import:dùng hai loại dấu phân cách. Một Recipe có thể chèn thêm các tệp template quaartifacts: { name: { $import: ... } }. Những tệp đó — và chỉ những tệp đó — được trình biên dịch render trước với dấu phân cách[[ ]]trước khi chúng được đặt vào, trong khi{{ }}của chúng được giữ nguyên cho Helm. Artifactnetpol.yaml— có khóanetpol.yamlvà được import từ./extras/mariadb-netpol.yaml, vì khóa đặt tên cho tệp được xuất ra còn import chọn nội dung của nó — cho thấy sự kết hợp này:[[ .context.instance_id ]](được điền lúc build) và{{ .Release.Namespace }}(để dành cho lúc cài đặt).
String Pipe được thể hiện theo thuật ngữ của chart: việc Adminer dùng MariaDB trong databases
phân giải provides.host của Recipe cơ sở dữ liệu vào values.yaml của umbrella
dưới alias web (adminerDefaultServer: db-mariadb), giá trị mà sub-chart Adminer
đọc dưới dạng {{ .Values.adminerDefaultServer }}. Cùng giá trị đó đặt tên cho
Service của sub-chart MariaDB, nên việc nối kết được phân giải nhất quán lúc cài đặt.
Đầu ra là một chart để helm install hoặc vendor — không phải một tập manifest đã được áp dụng.
Cách chọn một target
Recipe được chọn theo kiểu component: Manifest của mỗi target ánh xạ mọi kiểu tới một Recipe trong lớp catalog mà Release của nó nạp, nên manifest-compose.yaml gắn core/datastore/mariadb với Recipe compose, còn manifest-helm-synth.yaml gắn nó với Recipe Kubernetes. Một kiểu mà Manifest không ánh xạ sẽ làm bản build dừng lại và nêu tên các Recipes triển khai nó, kể cả khi lớp đã nạp chỉ chứa một. provider render một node là spec.capability của Recipe nào đã được gắn. Đổi target chính là đổi Release, cùng với Manifest của nó và thư mục catalog mà .aggrega-config.yaml chỉ định cho nó — Aggregate không bao giờ thay đổi.