Chỉ dùng catalog — MariaDB + Adminer mà không cần tự viết nền tảng
Ví dụ này triển khai một stack nhỏ nhưng thực tế — một cơ sở dữ liệu MariaDB với giao diện web Adminer đặt phía trước — bằng cách chỉ tham chiếu đến các thực thể của catalog thư viện chuẩn. Không có Component, Feature hay Recipe nào được viết ở đây: ba tệp YAML ngắn định tuyến mọi thứ đến các thực thể mà catalog đã cung cấp sẵn.
Đây là bề mặt soạn thảo nhỏ nhất mà Aggrega cung cấp, và là điểm tiếp xúc đầu tiên tự nhiên với ngôn ngữ. Ví dụ anh em ở tầng Authoring triển khai cùng stack này trong khi tự xây dựng tầng catalog của riêng nó — hãy đọc ví dụ này trước để thấy một catalog hoàn chỉnh mang lại cho bạn điều gì, sau đó đọc ví dụ kia để tìm hiểu tầng bên dưới được tạo ra như thế nào.
Ba tệp
aggregate.yaml— ý định của Developer: stack là gì. Hai component được chọn từ catalog bằngtype:, một thông tin xác thực bắt buộc dưới dạng attachment lấp slot, và một cạnhusesnối cơ sở dữ liệu vào socketdatabasescủa Adminer.release.yaml— phần hiện thực hóa theo từng môi trường của Operator: lớn đến đâu và ở đâu. Các khốiinfra:(phiên bản engine, dung lượng lưu trữ, cổng công bố) thuộc về Operator; Aggregate không bao giờ mang chúng.manifest.yaml— phần định tuyến của Operator: Recipe nào hiện thực hóa từng type trên target này. Xem bên dưới để biết vì sao các tham chiếu được định danh theo provider.
Ví dụ này minh họa điều gì
- Components dưới dạng tham chiếu catalog.
type: core/datastore/mariadbvàtype: core/devtool/adminerlà toàn bộ khai báo compute. Developer chỉ viết các giá trị mà schema của Component công bố — mọi trường bị bỏ qua đều nhận giá trị mặc định của schema (hãy so sánh các biến môi trường charset và collation trong đầu ra đã render với khốivalues:một dòng đã tạo ra chúng). - String Pipe. Component trong catalog của Adminer khai báo một uses-socket
databaseschấp nhận bất kỳ component nào được gắn nhãncomponent.aggrega.ai/type=stateful-server. Cạnh của Aggregate chènprovides.hostcủa Recipe cơ sở dữ liệu vàoADMINER_DEFAULT_SERVER. Trình biên dịch định tuyến chuỗi mà không diễn giải nó — trên target này nó là tên một service compose; cùng cạnh đó trên một target Kubernetes sẽ mang tên DNS của một Service. - Trụ cột attachment.
featuresSchemacủa Component cơ sở dữ liệu yêu cầu một slotroot_password, được lấp bằng Featurecore/secret-valuecủa catalog. Slot này là hộp đen: FeatureRecipe được Manifest chọn sẽ kiểm soát cách cung cấp, và Developer không thể quyết định điều đó. - Định tuyến Recipe định danh theo Provider. Manifest ánh xạ
core/datastore/mariadb:1.0.0sangcompose/mariadb:1.0.0— được định danh theo provider — vì thư viện chuẩn cung cấp một Recipe mariadb dưới nhiều provider (trong đó có compose và helm). Chính ánh xạ của Operator phân định target: một tham chiếu trần, không định danh, khớp với Recipe của nhiều provider sẽ dừng bản build một cách rõ ràng thay vì âm thầm chọn một. Hãy chuyển target của stack bằng cách trỏ lại các ánh xạ này; Aggregate không thay đổi.
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 catalog-onlySau đó 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 catalog-onlyBuild
Từ thư mục này, với các thực thể catalog được phân giải từ hub.aggrega.ai, registry mặc định mà .aggrega-config.yaml chỉ định:
aggrega pull --release release.yamlaggrega build --release release.yamlLệnh pull phân giải mọi thực thể được tham chiếu và ghim chúng trong release.lock (định danh + digest nội dung; hãy chạy lại pull để tạo lại một lockfile đã cũ). Khi có bản checkout catalog thư viện chuẩn (lấy ở đâu), hãy chỉ định thư mục aggrega-catalog của nó bằng --catalog trên cả hai lệnh để đọc các thực thể từ đó. Bản build đọc lockfile đó — không có nó, bản build dừng lại và nêu hai hướng đi tiếp, pull hoặc --auto-pull — và render ra dist/compose/docker-compose.yaml. Release khai báo các component của nó trực tiếp (không có khối boundaries:), nên trình biên dịch gộp chúng vào phạm vi mặc định được tổng hợp và xuất phẳng dưới dist/ — một boundary, không có đoạn tên boundary trong đường dẫn.
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ỉ 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 workspace chưa có thư mục `catalog-only`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `catalog-only` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `catalog-only` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `catalog-only`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặ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 `catalog-only/dist/`.Đọc đầu ra
Tệp compose đã render là nơi việc nối kết trở nên rõ ràng:
- service
webmangADMINER_DEFAULT_SERVER: db—provides.hostcủa Recipe cơ sở dữ liệu (tên service compose) được truyền qua cạnh uses; - cùng cạnh đó đã tạo ra
depends_on: [db]— topology, không chỉ là chuỗi; MARIADB_CHARACTER_SET_SERVERvàMARIADB_COLLATION_SERVERcủa servicedbđến từ các giá trị mặc định của schema mà Aggregate không hề nhắc đến;image: mariadb:11.4và ràng buộc cổng8080:8080đến từ các khốiinfra:của Release — trụ cột của Operator, được render bên cạnh trụ cột của Developer.
Chạy
cd dist/composedocker compose up -dMở http://localhost:8080: trường server đã được điền sẵn db.
Đăng nhập bằng root với mật khẩu phát triển từ attachment của
Aggregate (dev-root-pw-change-me — một giá trị giữ chỗ cần thay thế ở
bất kỳ đâu ngoài môi trường phát triển cục bộ), cơ sở dữ liệu appdb.
Tiếp theo
Tầng Authoring tự xây dựng chính tầng nền tảng này — các Components, Recipes và FeatureRecipes thông tin xác thực mà ví dụ này đã dùng sẵn — và biên dịch một Aggregate ra bốn target.