Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

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

viết một lần

Trên laptop

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

Trên một cluster Kubernetes

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

Cá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.yaml duy 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 databases tới MariaDB; giá trị provides.host của Recipe cơ sở dữ liệu được dẫn vào biến môi trường ADMINER_DEFAULT_SERVER củ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 Workload không phụ thuộc vào năng lực; provider tổng hợp một service trong docker-compose.yaml, hoặc các đối tượng Kubernetes mà form của Workload yêu cầu — một Deployment và một Service cho web UI không trạng thái, và với cơ sở dữ liệu form: stateful là một StatefulSet có mẫu volume claim theo từng bản sao chứa thư mục dữ liệu, cùng với Service Headless quản lý nó và Service ClusterIP mà 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ột Feature được gắn nhãn feature.aggrega.ai/kind: secret, tách biệt khỏi values của ứng dụng. featuresSchema củ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ối inject: 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 pull ghim chart vào một lockfile và tải nó vào bộ nhớ đệm định địa chỉ theo nội dung; aggrega build kế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_version củ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ằng aggrega 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ưới workspace.releases, nên không cần --catalog khi 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-uri ghi 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-chart kế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.yaml củ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ó:

Terminal window
aggrega scaffold --example mariadb-adminer

Sau đó 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:

Terminal window
cd mariadb-adminer

Build

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

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

Vớ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: host

web 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_password là 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_password là 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ối inject: 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:

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

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

Mở http://localhost:8080 và đăng nhập:

TrườngGiá trị
Hệ thốngMySQL / MariaDB
Máy chủdb (đã được điền sẵn)
Tên người dùngappuser
Mật khẩudev-app-pw-change-me
Cơ sở dữ liệuappdb

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

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

Đầu ra trong 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

Lư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ó:

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

Mở 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ó:

Terminal window
aggrega pull --release release-helm-chart.yaml
aggrega 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 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]

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

Terminal window
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/mariadb và ./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úc helm 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à name của mỗi Chart.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; xem providers/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 qua artifacts: { 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. Artifact netpol.yaml — có khóa netpol.yaml và đượ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.