Nhập một dự án Compose
Hướng dẫn từng bước này nhập một dự án Compose nhỏ — một API, cơ sở dữ liệu PostgreSQL nơi API lưu các ghi chú của mình và một bộ nhớ đệm Redis — và xây dựng kết quả cho Docker Compose. Quá trình nhập tạo bản nháp cho mọi tệp mà bản dựng đọc, mang theo những gì tệp Compose nêu: các kết nối của API tới cơ sở dữ liệu và bộ nhớ đệm, người dùng và tên của cơ sở dữ liệu, mật khẩu dưới dạng tham chiếu biến, và tag của từng image. Mọi tệp và mọi khối đầu ra bên dưới đều đến từ một lần chạy thực; dự án và từng giai đoạn của hướng dẫn nằm trong ví dụ import-compose, nơi một script kiểm tra chạy lại quá trình nhập, so sánh những gì nó ghi, những gì nó in ra và các khối mà trang này trích dẫn với các tệp được lưu giữ ở đó, rồi xác thực và dựng những gì quá trình nhập đã ghi.
Tạo ví dụ
Bạn có thể chạy lần nhập này bằng các lệnh trên trang này, hoặc để trợ lý AI của bạn chạy 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 import-composeSau đó 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; lệnh tiếp sau đó, ở bên dưới, chuyển vào thư mục source của thư mục mới, nơi chứa những gì trang này nhập và là nơi chạy lệnh nhập:
cd import-compose
Dự án
compose.yaml:
# A small notes service: its API, the PostgreSQL database it keeps the notes in,# and the Redis cache in front of it.name: notes
services: api: image: ghcr.io/example/notes-api:2.3.0 ports: - "8080:8080" environment: DATABASE_HOST: db DATABASE_USER: notes DATABASE_NAME: notes DATABASE_PASSWORD: ${POSTGRES_PASSWORD} CACHE_HOST: cache depends_on: - db - cache db: image: postgres:16 environment: POSTGRES_USER: notes POSTGRES_DB: notes POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - db-data:/var/lib/postgresql/data cache: image: redis:7
volumes: db-data:Bên cạnh nó, một tệp .aggrega-config.yaml biến thư mục thành một không gian làm việc, vì vậy quá trình nhập ghi các bản nháp của nó vào đó:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside compose.yaml.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.aiQuá trình nhập cân nhắc từng dịch vụ so với các Components trong danh mục của không gian làm việc, và --target tạo bản nháp một Manifest từ các Recipes của danh mục đó. Không gian làm việc không chỉ định thư mục danh mục nào, nên quá trình nhập đọc danh mục thư viện chuẩn từ registry mà nó tải trình nhập của mình về: một bản chụp nhanh đã ký của danh mục đã phát hành, được lần nhập đầu tiên tải về, xác minh và giữ trong bộ nhớ đệm nội dung của không gian làm việc, và được nêu bằng digest của nó trong bản ghi mà quá trình nhập ghi cạnh các bản nháp của nó. Một không gian làm việc có chỉ định các thư mục danh mục riêng — trong AGGREGA_CATALOG_DIRS, hoặc dưới workspace.catalog_dirs — thì thay vào đó nhập so với các thư mục đó.
Tệp câu trả lời
Một bản dựng cho Docker Compose không cần bất cứ thứ gì mà tệp Compose không nêu, vì vậy lần nhập này không hỏi gì cả. Một bản dựng của cùng dự án cho Kubernetes, với --target helm, cần một giá trị mà không tệp Compose nào chứa: tên của Secret Kubernetes mà mật khẩu của cơ sở dữ liệu được đọc từ đó, vì một bản dựng Kubernetes đọc mật khẩu từ một Secret chứ không phải từ shell của bạn. Ví dụ giữ câu trả lời đó trong import-answers.yaml, cạnh compose.yaml, nơi quá trình nhập tìm nó:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.db.features.password.infra.origin: "notes-db-password"Quá trình nhập tự ghi tệp này, vào lần đầu tiên nó được chạy với --target helm: nó liệt kê giá trị mà nó không thể tạo bản nháp, với khóa để trống, rồi dừng lại. Câu trả lời là tên của một Secret, không bao giờ là mật khẩu. Quá trình nhập cho Docker Compose không cần giá trị nào như vậy, giữ câu trả lời trong tệp và không sử dụng nó. Tệp câu trả lời của quá trình nhập mô tả tệp này, các câu hỏi mà quá trình nhập đặt ra tại terminal thay vào đó, và những gì nó làm khi không có cả hai.
aggrega import liệt kê mọi cờ mà lệnh nhận, trong đó có --answers, cờ nêu tên một tệp câu trả lời được lưu ở nơi khác.
Chuyển vào source:
cd sourceChạy lệnh nhập
aggrega import compose.yaml --target composeTrên đầu ra chuẩn, nó liệt kê những gì đã ghi:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonTrên luồng lỗi chuẩn, với <workspace> đại diện cho thư mục nơi bạn đã chạy nó:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the compose format, with drafted paths relative to <workspace>warn: the value of environment.POSTGRES_USER of node db is carried as written in the drafts: its format marks the field as no credential, though it can carry one, and setting empty_credentials to all writes it emptywarn: the value of environment.POSTGRES_DB of node db is carried as written in the drafts: its format marks the field as no credential, though it can carry one, and setting empty_credentials to all writes it emptymapped api (ghcr.io/example/notes-api) to core/compute/server as a reference, NONEmapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9mapped cache (redis) to core/datastore/redis as a reference, HIGH at 0.9Pull complete: <workspace>/release.lock (entities=10, source_artifacts=0, external_inputs=0)
- Các dòng
warnnêu tên từng giá trị mà các bản nháp mang theo đúng như đã viết, theo dịch vụ và biến của nó và không bao giờ theo giá trị của nó: Compose không đánh dấu giá trị nào là thông tin xác thực, và bất kỳ giá trị nào trong số đó cũng có thể chứa một thông tin xác thực. Ở đây cả hai đều không chứa. Các biến mà API đọc từ một dịch vụ khác hoàn toàn không được mang theo dưới dạng giá trị — các kết nối cung cấp chúng — và hai biến có nội dung${POSTGRES_PASSWORD}chỉ là một tham chiếu biến và không gì khác, vì vậy không cảnh báo nào nêu tên chúng. - Các dòng
mappedcho biết mỗi dịch vụ đã trở thành gì.apichạy một image riêng, vì vậy nó là một thể hiện của máy chủ chung của thư viện chuẩn,core/compute/server.dbvàcachechạy chính các image mà các Recipes Compose của thư viện chuẩn chạy chocore/datastore/postgresvàcore/datastore/redis; mỗi dịch vụ khớp với Component đó ở bậc cao, với 0.9, và các bản nháp tham chiếu đến nó. - Dòng
Pull completelà quá trình nhập đang tải những gì mà Release bản nháp phụ thuộc vào, nhưaggrega pulllàm, vàorelease.lock, để các bản nháp được xác thực và build ngay lập tức. Với--offline, quá trình nhập không tải gì và nêu lệnhaggrega pullcần chạy.
Những gì được ghi
Aggregate, Release và Manifest được đặt tên imported/notes, theo name: của dự án Compose — một tệp Compose không có name: được đặt tên theo tệp của nó, compose, và thư mục chứa nó, khi được nhập như một thư mục, được đặt tên theo thư mục đó, đúng như cách Compose đặt tên một dự án — dưới namespace mà thiết lập target_namespace của trình nhập đặt ra, là imported trừ khi bạn đặt namespace khác (Thiết lập).
aggregate.yaml — một mục cho mỗi dịch vụ, các kết nối mà môi trường của API lấy giá trị từ đó, cùng các giá trị và mật khẩu mà tệp Compose đặt:
# Not carried, since the draft reads the services and the models alone: volumes.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/notes version: 0.1.0 description: Draft Aggregate imported from a source in the compose format.spec: components: api: type: core/compute/server features: # For the compose target, the lines below declare database_password on api: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. database_password: type: core/secret-value values: key: DATABASE_PASSWORD uses: cache: cache: target: cache # The variables the source sets to what cache publishes, delivered from it under the names the source gives them. inject: env: - in: "CACHE_HOST" from: host db: db: target: db # The variables the source sets to what db publishes, delivered from it under the names the source gives them. inject: env: - in: "DATABASE_HOST" from: host - in: "DATABASE_USER" from: user - in: "DATABASE_NAME" from: database db: type: core/datastore/postgres # The values of core/datastore/postgres the source sets as POSTGRES_USER, POSTGRES_DB, the variables its Compose Recipes set from them. values: user: "notes" database: "notes" features: # For the compose target, the lines below declare password on db: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. password: type: core/secret-value values: key: POSTGRES_PASSWORD cache: type: core/datastore/redisMỗi biến của API nêu tên một dịch vụ khác trở thành khối inject của kết nối đó: tệp Compose đặt DATABASE_HOST thành db, và kết nối cung cấp host đã công bố của cơ sở dữ liệu dưới tên đó, để nó đi theo cơ sở dữ liệu trên bất kỳ đích nào thay vì bị sao chép. DATABASE_USER và DATABASE_NAME khớp với người dùng và cơ sở dữ liệu mà dịch vụ PostgreSQL được tạo cùng, vì vậy chúng cũng được cung cấp từ những gì dịch vụ đó công bố, và hai giá trị đó trở thành values riêng của cơ sở dữ liệu. Mỗi mật khẩu trở thành một phần đính kèm core/secret-value, được khai báo với khóa mà biến của nó được đọc dưới đó.
release.yaml — môi trường, image và cổng của API, phiên bản engine của mỗi kho dữ liệu, và nơi mỗi mật khẩu được lấy:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/notes # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the compose format.spec: aggregate: imported/notes manifest: imported/notes components: # The source also states, for the Release to carry where core/compute/server takes it: # ports: # - "8080:8080" api: infra: image: "ghcr.io/example/notes-api:2.3.0" port: 8080 # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 8080 features: database_password: type: core/secret-value infra: # Attached by reference, never as a value: the value api reads as DATABASE_PASSWORD, read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" # The source states, for the Release to carry where core/datastore/postgres takes it: # volumes: # - "db-data:/var/lib/postgresql/data" db: infra: # The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run. engine_version: "16" features: password: type: core/secret-value infra: # Attached by reference, never as a value: the password of db, which the source sets as POSTGRES_PASSWORD, read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" cache: infra: # The tag of the image the source runs, redis:7, the engine_version of core/datastore/redis its Compose Recipes run. engine_version: "7"Môi trường, development, là giá trị mặc định mà quá trình nhập ghi vì không tệp Compose nào nêu tên một môi trường; hãy thay đổi nó khi Release được triển khai ở nơi khác. Các tag image trở thành các phiên bản engine mà các Components của thư viện chuẩn nhận. port của API là cổng mà container của nó lắng nghe, và published_port là cổng máy chủ mà mục ports của nó công bố, cả hai đều là 8080 như tệp Compose nêu; như chú thích của nó nói, mọi tiến trình trên máy này đều đến được API tại http://127.0.0.1:8080 và không gì khác có thể, còn xóa dòng đó thì giữ API chỉ trên mạng của stack. Những gì không khóa nào nhận vẫn là một chú thích phía trên mục của nó: mục ports của nguồn, mà port và published_port đã mang, và volume có tên của cơ sở dữ liệu.
manifest.yaml — Recipe Compose của mỗi loại thành phần, và việc hiện thực hóa ghi tham chiếu biến của một mật khẩu vào tệp Compose đúng như đã viết:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/notes version: 0.1.0spec: mappings: components: type: core/compute/server: compose/server core/datastore/postgres: compose/postgres core/datastore/redis: compose/redis features: type: core/secret-value: compose/dotenv-secretrelease.lock ghi lại, theo digest, các thực thể danh mục mà Release đã được phân giải tới, và .aggrega-import.json là bản ghi về những gì quá trình nhập đã ghi, được một lệnh aggrega import --sync sau đó đọc.
Xác thực và dựng
aggrega validate --release release.yamlaggrega build --release release.yaml

Bước xác thực in ra:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)và bản dựng, với <workspace> đại diện cho thư mục mà bạn đã chạy nó:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distDòng notice chỉ mang tính tư vấn: Feature mật khẩu nhận origin của nó từ values của Aggregate hoặc infra của Release, và thông báo cho biết một nút lá được khai báo ở cả hai nơi. Nó không thay đổi phán quyết nào.
Dịch vụ api trong dist/compose/docker-compose.yaml đọc môi trường mà dự án Compose đã cung cấp cho nó, được cung cấp bởi các kết nối và phần đính kèm mật khẩu:
api: image: ghcr.io/example/notes-api:2.3.0 environment: CACHE_HOST: cache DATABASE_HOST: db DATABASE_NAME: notes DATABASE_PASSWORD: ${POSTGRES_PASSWORD} DATABASE_USER: notes ports: - 127.0.0.1:8080:8080 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] networks: - compose depends_on: - cache - db [… omitted: the CPU and memory the server's defaults reserve]và cơ sở dữ liệu cùng bộ nhớ đệm chạy các image mà tệp Compose đã chỉ định:
db: image: postgres:16 environment: POSTGRES_USER: notes POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: notes [… omitted: the labels, the network and a health check running PostgreSQL's pg_isready] cache: image: redis:7 [… omitted: the labels, the network and a health check running redis-cli ping]Hai điểm khác biệt so với dự án ban đầu của bạn hiện ra trong tệp đã kết xuất. Cổng chỉ được công bố trên địa chỉ loopback, giống như cách Recipe Compose của máy chủ chung công bố nó. Và volume có tên mà tệp Compose đã gắn cho dữ liệu của cơ sở dữ liệu không xuất hiện ở đâu cả: bản nháp liệt kê nó trong một chú thích phía trên mục của cơ sở dữ liệu, không khóa nào của Component PostgreSQL nhận nó, và dịch vụ cơ sở dữ liệu đã kết xuất không gắn volume nào.
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ó thể làm điều tương tự: dán prompt này vào nó.
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 `import-compose`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `import-compose` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `import-compose` mới, có thư mục `source` chứa những gì trang này nhập. Sau đó gọi công cụ `import` với `workspace_root` đặt thành `import-compose/source`, `source` đặt thành `compose.yaml` và `target` đặt thành `compose`: công cụ này đọc các câu trả lời nó cần từ `import-answers.yaml` bên cạnh `compose.yaml`, ghi các bản nháp vào `import-compose/source` và kéo về những gì các bản nháp cần. Sau đó gọi công cụ `validate` với `workspace_root` đặt thành `import-compose/source` và `release` đặt thành `release.yaml`, và công cụ `build` với `workspace_root` đặt thành `import-compose/source`, `release` đặt thành `release.yaml` và `write` đặt thành true. Cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `import-compose/source/dist/`.Mở trong VS Code
Khi đã cài tiện ích mở rộng Aggrega cho Visual Studio Code, hãy mở thư mục import-compose/source trong VS Code, nơi quá trình nhập đã ghi các bản nháp. Thư mục chứa một Release duy nhất, bản nháp release.yaml, nên trình soạn thảo tự chọn nó cho bạn, và kiểm tra các bản nháp đối chiếu với Release đó khi bạn chỉnh sửa, đánh dấu những gì nó tìm thấy trong tệp và trong bảng Problems. Aggrega: Show topology graph, trong Command Palette, vẽ các thành phần của Release và các kết nối giữa chúng. Aggrega: Build, Aggrega: Preview build và Aggrega: Pull tác động lên cùng Release đó, và mỗi lệnh cũng là một nút trên bảng Commands của chế độ xem Aggrega trong thanh hoạt động; Build ghi các tệp của nó vào dist/ của thư mục. Dùng Aggrega trong Visual Studio Code trình bày phần còn lại.
Chạy thử
ghcr.io/example/notes-api:2.3.0 đại diện cho image API của riêng bạn. Đây là một giá trị giữ chỗ, và Docker Compose dừng lại ở đó với Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Hãy chỉ định image API của bạn trong infra.image của api trong release.yaml. Cho đến khi API của bạn sẵn sàng, một image trả lời HTTP trên cổng 8080 có thể thay thế cho nó. Lần chạy bên dưới đã dùng mendhak/http-https-echo:39, image này trả lời mọi yêu cầu bằng một mô tả về yêu cầu mà nó nhận được:
api: infra: image: "mendhak/http-https-echo:39" port: 8080Build lại với thay đổi đó. Release không còn khớp với release.lock mà quá trình nhập đã ghi, vì vậy bản build cần --auto-pull, tùy chọn phân giải lại nó; không có nó, bản build dừng lại và nêu tên aggrega pull. Docker Compose điền cả hai tham chiếu ${POSTGRES_PASSWORD} từ shell của bạn, vì vậy hãy đặt mật khẩu trước khi khởi động stack: nếu không đặt, Compose sẽ cảnh báo The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. và ghi một giá trị rỗng vào vị trí đó.
aggrega build --release release.yaml --auto-pullexport POSTGRES_PASSWORD='a password of your own'docker compose -p notes -f dist/compose/docker-compose.yaml up -d --wait-p đặt tên cho dự án, như bước chạy của Cách một lần nhập diễn ra giải thích. --wait trả về khi cơ sở dữ liệu và bộ nhớ đệm vượt qua các kiểm tra sức khỏe mà bản dựng gán cho chúng và container của API đang chạy: bản dựng không gán kiểm tra sức khỏe nào cho API.
Kiểm thử
Gửi yêu cầu tới API tại http://127.0.0.1:8080, địa chỉ mà published_port công bố:
curl -sS http://127.0.0.1:8080/notes{ "path": "/notes", "headers": { "host": "127.0.0.1:8080", [… omitted: the user agent and the media types the client sent] }, "method": "GET", [… omitted: the rest of the request as the stand-in received it, the client's address and the container's host name]}Những gì các kết nối chuyển giao nằm trong môi trường của dịch vụ API, dưới các tên mà API của bạn đọc:
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOSTdbnotesnotescacheDừng stack bằng:
docker compose -p notes -f dist/compose/docker-compose.yaml downTrên Kubernetes
Cùng dự án đó được nhập cho Kubernetes với --target helm, và quá trình nhập đọc tên của Secret, notes-db-password, từ tệp câu trả lời ở trên. Các bản nháp cho Docker Compose đã nằm trong source, nên hãy soạn nháp những bản này vào một thư mục riêng, ghi image của API trong release.yaml của nó như với Docker Compose, rồi build từ đó:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pullBản build ghi các manifest Kubernetes thuần trong dist/helm/ tại thư mục gốc của workspace, source, mà từ helm là ../dist/helm/. Tạo Secret notes-db-password trong namespace mà bạn áp dụng vào, chứa mật khẩu dưới khóa dữ liệu value, và áp dụng thư mục như bước chạy của Cách một lần nhập diễn ra giải thích. Service của API là api-default: hãy chuyển tiếp một cổng cục bộ tới nó, và để lệnh tiếp tục chạy:
kubectl port-forward -n <namespace> svc/api-default 8080:8080Từ một terminal khác, yêu cầu ở trên đến API tại cùng địa chỉ, không thay đổi, và image thay thế trả lời theo cùng cách, "host": "127.0.0.1:8080". Các kết nối cung cấp tên của các Service: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST in ra db-default, notes, notes và cache-default. Trên Kubernetes, API chưa nhận được mật khẩu cơ sở dữ liệu của nó: Secret notes-db-password chỉ đến được cơ sở dữ liệu, nên DATABASE_PASSWORD không được đặt trong container api.
Khi tệp Compose thay đổi
Giữ .aggrega-import.json bên cạnh các bản nháp, và sau khi tệp Compose thay đổi, hãy chạy:
aggrega import compose.yaml --syncNó chỉ thay đổi những gì quá trình nhập đã ghi, và đọc cùng một tệp câu trả lời. Một phần mà nguồn không động đến vẫn giữ nguyên như trên đĩa, dù đã chỉnh sửa hay chưa; ở nơi nguồn thay đổi một phần mà bạn đã chỉnh sửa, nó dừng lại, nêu tên phần đó và không ghi gì, để bạn tự đối chiếu bằng tay. aggrega import mô tả đầy đủ các quy tắc và mọi cờ.