Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Mengimpor proyek Compose

Panduan langkah demi langkah ini mengimpor sebuah proyek Compose kecil — sebuah API, basis data PostgreSQL tempat API itu menyimpan catatannya, dan sebuah cache Redis — dan membangun hasilnya untuk Docker Compose. Impor membuat draf setiap berkas yang dibaca build, dengan membawa apa yang dinyatakan berkas Compose: koneksi API ke basis data dan cache, pengguna dan nama basis data, kata sandi sebagai referensi variabel, dan tag setiap image. Setiap berkas dan setiap blok keluaran di bawah ini berasal dari eksekusi nyata; proyek dan setiap tahap panduan ini ada dalam contoh import-compose, tempat sebuah skrip pemeriksaan menjalankan impor lagi, membandingkan apa yang ditulisnya, apa yang dicetaknya, dan blok-blok yang dikutip halaman ini dengan berkas-berkas yang disimpan di sana, serta memvalidasi dan membangun apa yang ditulis impor.

Membuat contoh

Anda dapat menjalankan impor ini dengan perintah di halaman ini, atau meminta asisten AI Anda menjalankannya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

Terminal window
aggrega scaffold --example import-compose

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru; perintah sesudahnya, di bawah, berpindah ke folder source milik folder baru itu, yang berisi apa yang diimpor halaman ini dan merupakan tempat impor dijalankan:

Terminal window
cd import-compose

Folder source dari contoh hasil scaffold terbuka di Visual Studio Code, menampilkan file Compose-nya: API layanan catatan, basis data PostgreSQL-nya, dan cache Redis-nya.

Proyek

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:

Di sampingnya, sebuah .aggrega-config.yaml menjadikan folder itu ruang kerja, sehingga impor menulis drafnya di sana:

# 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.ai

Impor menimbang setiap layanan terhadap Components dalam katalog ruang kerja, dan --target membuat draf Manifest dari Recipes katalog tersebut. Ruang kerja tidak menyebutkan folder katalog apa pun, jadi impor membaca katalog pustaka standar dari registri tempat ia mengambil pengimpornya: snapshot bertanda tangan dari katalog yang diterbitkan, yang diambil, diverifikasi, dan disimpan di cache konten ruang kerja oleh impor pertama, serta disebutkan dengan digest-nya dalam catatan yang ditulis impor di samping drafnya. Ruang kerja yang menyebutkan folder katalognya sendiri — di AGGREGA_CATALOG_DIRS, atau di bawah workspace.catalog_dirs — mengimpor terhadap folder-folder itu sebagai gantinya.

Berkas jawaban

Build untuk Docker Compose tidak memerlukan apa pun yang tidak dinyatakan oleh berkas Compose, sehingga impor ini tidak menanyakan apa pun. Build proyek yang sama untuk Kubernetes, dengan --target helm, memerlukan satu nilai yang tidak dimuat oleh berkas Compose mana pun: nama Secret Kubernetes tempat kata sandi basis data dibaca, karena build Kubernetes membaca kata sandi dari Secret, bukan dari shell Anda. Contoh ini menyimpan jawaban tersebut di import-answers.yaml, di samping compose.yaml, tempat impor mencarinya:

# 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"

Impor menulis berkas itu sendiri, saat pertama kali dijalankan dengan --target helm: ia mencantumkan nilai yang tidak dapat dibuat drafnya, dengan kuncinya kosong, lalu berhenti. Jawabannya adalah nama Secret, tidak pernah kata sandinya. Impor untuk Docker Compose tidak memerlukan nilai seperti itu, menyimpan jawabannya di berkas, dan tidak menggunakannya. Berkas jawaban impor menjelaskan berkas tersebut, pertanyaan yang diajukan impor di terminal sebagai gantinya, dan apa yang dilakukannya tanpa keduanya.

aggrega import mencantumkan setiap flag yang diterima perintah ini, termasuk --answers, yang menyebutkan file jawaban yang disimpan di tempat lain.

Pindah ke source:

Terminal window
cd source

Menjalankan impor

Terminal window
aggrega import compose.yaml --target compose

Pada keluaran standar, impor mencantumkan apa yang ditulisnya:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Pada galat standar, dengan <workspace> mewakili folder tempat Anda menjalankannya:

[… 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 empty
warn: 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 empty
mapped api (ghcr.io/example/notes-api) to core/compute/server as a reference, NONE
mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9
mapped cache (redis) to core/datastore/redis as a reference, HIGH at 0.9
Pull complete: <workspace>/release.lock (entities=10, source_artifacts=0, external_inputs=0)

Impor yang dijalankan dari editor: draf Aggregate, Release, dan Manifest muncul di samping file Compose, output Aggrega mencantumkan bagaimana setiap layanan dipetakan dan file yang ditulis, dan sebuah notifikasi menyatakan bahwa impor membuat draf 3 file, dikenali sebagai compose.

  • Baris warn menyebut setiap nilai yang dibawa draf sebagaimana tertulis, berdasarkan layanan dan variabelnya dan tidak pernah berdasarkan nilainya: Compose tidak menandai nilai apa pun sebagai kredensial, dan nilai mana pun bisa saja membawa kredensial. Di sini keduanya tidak membawanya. Variabel yang dibaca API dari layanan lain sama sekali tidak dibawa sebagai nilai — koneksi yang mengirimkannya — dan dua yang berbunyi ${POSTGRES_PASSWORD} hanyalah referensi variabel dan tidak lebih, sehingga tidak ada peringatan yang menyebutnya.
  • Baris mapped menyatakan menjadi apa setiap layanan. api menjalankan image miliknya sendiri, sehingga ia merupakan instans dari server generik pustaka standar, core/compute/server. db dan cache menjalankan image yang dijalankan oleh Recipes Compose pustaka standar untuk core/datastore/postgres dan core/datastore/redis; masing-masing cocok dengan Component tersebut pada tingkat tinggi, dengan 0.9, dan draf merujuk ke Component itu.
  • Baris Pull complete adalah impor yang mengambil apa yang menjadi dependensi Release yang dirancang, seperti yang dilakukan aggrega pull, ke dalam release.lock, sehingga draf dapat langsung divalidasi dan di-build. Dengan --offline, impor tidak mengambil apa pun dan menyebutkan perintah aggrega pull yang perlu dijalankan.

Apa yang ditulisnya

Aggregate, Release, dan Manifest diberi nama imported/notes, berdasarkan name: milik proyek Compose — file Compose tanpa name: dinamai berdasarkan filenya, compose, dan direktori yang memuatnya, bila diimpor sebagai direktori, berdasarkan direktori tersebut, sebagaimana Compose menamai proyek — di bawah namespace yang ditetapkan oleh pengaturan target_namespace milik pengimpor, yaitu imported kecuali Anda menetapkan yang lain (Pengaturan).

aggregate.yaml — satu entri per layanan, koneksi yang menjadi sumber lingkungan API, serta nilai dan kata sandi yang ditetapkan berkas Compose:

# Not carried, since the draft reads the services and the models alone: volumes.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
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/redis

Setiap variabel API yang menyebut layanan lain menjadi blok inject koneksi tersebut: berkas Compose menetapkan DATABASE_HOST ke db, dan koneksi mengirimkan host yang dipublikasikan basis data dengan nama itu, sehingga nilai itu mengikuti basis data pada target mana pun alih-alih disalin. DATABASE_USER dan DATABASE_NAME cocok dengan pengguna dan basis data yang digunakan untuk membuat layanan PostgreSQL, sehingga keduanya juga dikirimkan dari apa yang dipublikasikannya, dan kedua nilai itu menjadi values milik basis data sendiri. Setiap kata sandi menjadi lampiran core/secret-value, yang dideklarasikan dengan kunci tempat variabelnya dibaca.

release.yaml — lingkungan, image dan port API, versi engine setiap penyimpanan data, dan asal setiap kata sandi:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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"

Lingkungan, development, adalah nilai bawaan yang ditulis impor karena tidak ada berkas Compose yang menyebutkannya; ubah nilai itu bila Release di-deploy di tempat lain. Tag image menjadi versi engine yang diterima Components pustaka standar. port milik API adalah port tempat container-nya mendengarkan, dan published_port adalah port host yang dipublikasikan entri ports-nya, keduanya 8080 sebagaimana dinyatakan berkas Compose; seperti kata komentarnya, setiap proses di mesin ini dapat menjangkau API di http://127.0.0.1:8080 dan tidak ada yang lain yang bisa, dan menghapus baris tersebut membuat API hanya berada di jaringan stack. Apa yang tidak diterima kunci mana pun tetap menjadi komentar di atas entrinya: entri ports dari sumber, yang sudah dibawa oleh port dan published_port, dan volume bernama milik basis data.

manifest.yaml — Recipe Compose untuk setiap tipe komponen, dan realisasi yang menulis referensi variabel kata sandi ke berkas Compose sebagaimana tertulis:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/notes
version: 0.1.0
spec:
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-secret

release.lock mencatat entitas katalog tempat Release diselesaikan, berdasarkan digest, dan .aggrega-import.json adalah catatan tentang apa yang ditulis impor, yang dibaca oleh aggrega import --sync berikutnya.

Validasi dan build

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

Draf Release terbuka di editor setelah divalidasi, dengan output Aggrega dan sebuah notifikasi yang keduanya melaporkan tidak ada masalah yang ditemukan.

Build draf Release: sebuah folder dist muncul di Explorer, output Aggrega mencantumkan file Docker Compose yang ditulis, dan sebuah notifikasi menyatakan bahwa 1 file telah ditulis.

Validasi mencetak:

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)

dan build, dengan <workspace> mewakili folder tempat Anda menjalankannya:

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>/dist

Baris notice hanya bersifat informatif: Feature kata sandi menerima origin-nya dari values milik Aggregate atau infra milik Release, dan pemberitahuan itu melaporkan bahwa satu daun dideklarasikan di keduanya. Baris ini tidak mengubah putusan apa pun.

Layanan api di dist/compose/docker-compose.yaml membaca lingkungan yang diberikan proyek Compose kepadanya, yang dikirimkan oleh koneksi dan lampiran kata sandi:

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]

dan basis data serta cache menjalankan image yang disebutkan berkas Compose:

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]

Dua perbedaan dari proyek awal Anda terlihat dalam berkas hasil render. Port dipublikasikan hanya pada alamat loopback, sebagaimana Recipe Compose server generik memublikasikannya. Dan volume bernama yang dipasang berkas Compose untuk data basis data tidak muncul di mana pun: draf mencantumkannya dalam komentar di atas entri basis data, tidak ada kunci Component PostgreSQL yang menerimanya, dan layanan basis data hasil render tidak memasang volume apa pun.

Dengan asisten AI

Asisten AI yang disiapkan dengan alat-alat Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke dalamnya.

Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder Workspace belum berisi folder `import-compose`, panggil alat `scaffold` sekali dengan `example` diatur ke `import-compose` dan tanpa `dir`: alat ini menulis contoh ke folder `import-compose` yang baru, yang folder `source`-nya berisi apa yang diimpor halaman ini. Lalu panggil alat `import` dengan `workspace_root` diatur ke `import-compose/source`, `source` diatur ke `compose.yaml`, dan `target` diatur ke `compose`: alat ini membaca jawaban yang dibutuhkannya dari `import-answers.yaml` di samping `compose.yaml`, menulis drafnya ke `import-compose/source`, dan menarik apa yang dibutuhkan draf tersebut. Lalu panggil alat `validate` dengan `workspace_root` diatur ke `import-compose/source` dan `release` diatur ke `release.yaml`, serta alat `build` dengan `workspace_root` diatur ke `import-compose/source`, `release` diatur ke `release.yaml`, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis build; file tersebut berada di bawah `import-compose/source/dist/`.

Membukanya di VS Code

Dengan ekstensi Aggrega untuk Visual Studio Code terpasang, buka folder import-compose/source di VS Code, tempat impor menulis drafnya. Folder tersebut berisi satu Release, yaitu draf release.yaml, sehingga editor memilihnya untuk Anda dan memeriksa draf terhadap Release tersebut saat Anda mengeditnya, menandai apa yang ditemukannya di file dan di panel Problems. Aggrega: Show topology graph, di Command Palette, menggambar komponen Release dan koneksi di antara mereka. Aggrega: Build, Aggrega: Preview build, dan Aggrega: Pull bekerja pada Release yang sama, dan masing-masing juga merupakan tombol di panel Commands pada tampilan Aggrega di activity bar; Build menulis file-filenya ke dist/ di dalam folder tersebut. Menggunakan Aggrega di Visual Studio Code membahas sisanya.

Menjalankannya

ghcr.io/example/notes-api:2.3.0 mewakili image API Anda sendiri. Ini adalah placeholder, dan Docker Compose berhenti padanya dengan Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Sebutkan image API Anda di infra.image milik api dalam release.yaml. Sampai API Anda siap, image yang menjawab HTTP di port 8080 dapat menggantikannya. Eksekusi di bawah menggunakan mendhak/http-https-echo:39, yang menjawab setiap permintaan dengan deskripsi permintaan yang diterimanya:

api:
infra:
image: "mendhak/http-https-echo:39"
port: 8080

Lakukan build lagi dengan perubahan itu. Release tidak lagi cocok dengan release.lock yang ditulis impor, jadi build memerlukan --auto-pull, yang me-resolve-nya lagi; tanpanya build berhenti dan menyebut aggrega pull. Docker Compose mengisi kedua referensi ${POSTGRES_PASSWORD} dari shell Anda, jadi tetapkan kata sandi sebelum Anda memulai stack: jika tidak ditetapkan, Compose memperingatkan The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. dan menulis nilai kosong sebagai gantinya.

Terminal window
aggrega build --release release.yaml --auto-pull
export POSTGRES_PASSWORD='a password of your own'
docker compose -p notes -f dist/compose/docker-compose.yaml up -d --wait

-p menamai proyek, seperti yang dijelaskan langkah menjalankan di Cara impor berjalan. --wait kembali setelah database dan cache lulus pemeriksaan kesehatan yang diberikan build kepada keduanya dan kontainer API sedang berjalan: build tidak memberikan pemeriksaan kesehatan kepada API.

Mengujinya

Tanyakan ke API di http://127.0.0.1:8080, alamat yang dipublikasikan oleh published_port:

Terminal window
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]
}

Apa yang dikirimkan oleh koneksi ada di lingkungan layanan API, dengan nama-nama yang dibaca API Anda:

Terminal window
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST
db
notes
notes
cache

Hentikan stack dengan:

Terminal window
docker compose -p notes -f dist/compose/docker-compose.yaml down

Di Kubernetes

Proyek yang sama diimpor untuk Kubernetes dengan --target helm, dan impor membaca nama Secret, notes-db-password, dari file jawaban di atas. Draf untuk Docker Compose sudah berada di source, jadi buat draf ini di folder tersendiri, sebutkan image API di release.yaml-nya seperti untuk Docker Compose, lalu lakukan build dari folder itu:

Terminal window
aggrega import compose.yaml --target helm --output-dir helm
cd helm
aggrega build --release release.yaml --auto-pull

Build menulis manifest Kubernetes biasa di bawah dist/helm/ pada root workspace, source, yang dari helm adalah ../dist/helm/. Buat Secret notes-db-password di namespace tempat Anda menerapkan, yang menyimpan kata sandi di bawah kunci data value, lalu terapkan folder tersebut seperti yang dijelaskan langkah menjalankan di Cara impor berjalan. Service milik API adalah api-default: teruskan sebuah port lokal ke Service itu, dan biarkan perintah tetap berjalan:

Terminal window
kubectl port-forward -n <namespace> svc/api-default 8080:8080

Dari terminal lain, permintaan di atas mencapai API di alamat yang sama, tanpa perubahan, dan image pengganti menjawab dengan cara yang sama, "host": "127.0.0.1:8080". Koneksi mengirimkan nama-nama Service: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST mencetak db-default, notes, notes, dan cache-default. Di Kubernetes, API belum menerima kata sandi basis datanya: Secret notes-db-password hanya mencapai basis data, sehingga DATABASE_PASSWORD tidak ditetapkan di container api.

Saat berkas Compose berubah

Simpan .aggrega-import.json di samping draf, dan setelah berkas Compose berubah, jalankan:

Terminal window
aggrega import compose.yaml --sync

Perintah ini hanya mengubah apa yang ditulis impor, dan membaca berkas jawaban yang sama. Bagian yang tidak diubah sumber tetap seperti adanya di disk, diedit atau tidak; jika sumber mengubah bagian yang Anda edit, perintah ini berhenti, menyebut bagian tersebut, dan tidak menulis apa pun, agar Anda merekonsiliasinya secara manual. aggrega import menjelaskan aturannya dan setiap flag secara lengkap.