Bir Compose projesini içe aktarma
Bu adım adım kılavuz küçük bir Compose projesini — bir API, notlarını sakladığı PostgreSQL veritabanı ve bir Redis önbelleği — içe aktarır ve sonucu Docker Compose için derler. İçe aktarma, derlemenin okuduğu her dosyanın taslağını oluşturur ve Compose dosyasının belirttiklerini aktarır: API’nin veritabanına ve önbelleğe bağlantıları, veritabanının kullanıcısı ve adı, değişken başvurusu olarak parola ve her imajın etiketi. Aşağıdaki her dosya ve her çıktı bloğu gerçek bir çalıştırmadan gelir; proje ve kılavuzun her aşaması import-compose örneğindedir; orada bir denetim betiği içe aktarmayı yeniden çalıştırır, yazdıklarını, yazdırdıklarını ve bu sayfanın alıntıladığı blokları orada tutulan dosyalarla karşılaştırır ve içe aktarmanın yazdıklarını doğrulayıp derler.
Örneği oluşturun
Bu içe aktarmayı bu sayfadaki komutlarla çalıştırabilir ya da yapay zekâ asistanınıza sizin için çalıştırtabilirsiniz.
Örneği, adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example import-composeArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer; ondan sonraki, aşağıda, yeni klasörün içindeki, bu sayfanın içe aktardıklarını barındıran ve içe aktarmanın çalıştığı yer olan source klasörüne geçer:
cd import-compose
Proje
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:Yanındaki bir .aggrega-config.yaml klasörü bir çalışma alanı yapar; böylece içe aktarma taslaklarını oraya yazar:
# 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İçe aktarma her hizmeti çalışma alanının kataloğundaki Components ile karşılaştırır ve --target kataloğun Recipes’inden bir Manifest taslağı oluşturur. Çalışma alanı hiçbir katalog klasörü belirtmez, bu nedenle içe aktarma standart kütüphane kataloğunu, içe aktarıcısını getirdiği kayıt defterinden okur: bu, yayımlanmış kataloğun imzalı bir anlık görüntüsüdür; ilk içe aktarma tarafından getirilir, doğrulanır ve çalışma alanının içerik önbelleğinde tutulur, içe aktarmanın taslaklarının yanına yazdığı kayıtta da özet değeriyle adlandırılır. Kendi katalog klasörlerini — AGGREGA_CATALOG_DIRS içinde veya workspace.catalog_dirs altında — belirten bir çalışma alanı bunun yerine onlara karşı içe aktarır.
Yanıt dosyası
Docker Compose için bir derleme, Compose dosyasının belirtmediği hiçbir şeye ihtiyaç duymaz; bu yüzden bu içe aktarma hiçbir şey sormaz. Aynı projenin --target helm ile Kubernetes için derlenmesi, hiçbir Compose dosyasının içermediği bir değere ihtiyaç duyar: veritabanı parolasının okunduğu Kubernetes Secret’ının adı; çünkü bir Kubernetes derlemesi parolayı kabuğunuzdan değil, bir Secret’tan okur. Örnek bu yanıtı, içe aktarmanın onu aradığı yerde, compose.yaml dosyasının yanındaki import-answers.yaml içinde tutar:
# 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"İçe aktarma dosyayı, --target helm ile ilk kez çalıştırıldığında kendisi yazdı: taslağını oluşturamadığı değeri anahtarı boş olarak listeledi ve durdu. Yanıt bir Secret’ın adıdır, asla parola değildir. Docker Compose için içe aktarma böyle bir değer gerektirmez, yanıtı dosyada tutar ve onu kullanmaz. İçe aktarma yanıt dosyası, dosyayı, bir içe aktarmanın bunun yerine bir terminalde sorduğu soruları ve ikisi de olmadığında ne yaptığını açıklar.
aggrega import, komutun aldığı her bayrağı listeler; bunlar arasında başka bir yerde tutulan bir yanıtlar dosyasını adlandıran --answers da vardır.
source klasörüne geçin:
cd sourceİçe aktarmayı çalıştırma
aggrega import compose.yaml --target composeStandart çıktıda yazdıklarını listeler:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonStandart hatada, <workspace> onu çalıştırdığınız klasörü temsil edecek şekilde:
[… 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)
warnsatırları, taslakların yazıldığı gibi taşıdığı her değeri değeriyle değil, hizmeti ve değişkeniyle adlandırır: Compose hiçbir değeri kimlik bilgisi olarak işaretlemez ve bunlardan herhangi biri bir kimlik bilgisi taşıyabilir. Burada ikisi de taşımıyor. API’nin başka bir hizmetten okuduğu değişkenler hiç değer olarak taşınmaz — bunları bağlantılar iletir — ve içeriği${POSTGRES_PASSWORD}olan ikisi bir değişken referansından başka bir şey değildir; bu yüzden hiçbir uyarı onları adlandırmaz.mappedsatırları her hizmetin neye dönüştüğünü söyler.apikendine ait bir imaj çalıştırır; bu yüzden standart kütüphanenin genel sunucusu olancore/compute/serverbileşeninin bir örneğidir.dbvecache, standart kütüphanenin Compose Recipes’inincore/datastore/postgresvecore/datastore/redisiçin çalıştırdığı imajları çalıştırır; her biri yüksek kademede, 0.9 ile o Component’le eşleşti ve taslaklar ona başvurur.Pull completesatırı, içe aktarmanın taslağı oluşturulan Release’in bağlı olduğu şeyleriaggrega pullgibirelease.lockiçine getirmesidir; böylece taslaklar hemen doğrulanır ve derlenir.--offlineile içe aktarma hiçbir şey çekmez ve çalıştırılacakaggrega pullkomutunu belirtir.
Ne yazar
Aggregate, Release ve Manifest, Compose projesinin name: değerinden imported/notes olarak adlandırılır — name: içermeyen bir Compose dosyası kendi dosyasının adını, compose, alır; onu içeren dizin ise dizin olarak içe aktarıldığında o dizinin adını alır, tıpkı Compose’un bir projeyi adlandırdığı gibi — ve içe aktarıcının target_namespace ayarının belirlediği ad alanı altında yer alır; bu ad alanı, başka birini ayarlamadığınız sürece imported olur (Ayarlar).
aggregate.yaml — hizmet başına bir girdi, API ortamının beslendiği bağlantılar ve Compose dosyasının ayarladığı değerler ile parolalar:
# 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/redisAPI’nin başka bir hizmeti adlandıran her değişkeni, o bağlantının inject bloğu olur: Compose dosyası DATABASE_HOST değerini db olarak ayarlamıştı ve bağlantı, veritabanının yayımladığı host değerini bu adla iletir; böylece kopyalanmak yerine herhangi bir hedefte veritabanını izler. DATABASE_USER ve DATABASE_NAME, PostgreSQL hizmetinin oluşturulduğu kullanıcı ve veritabanıyla eşleşti; bu yüzden onlar da hizmetin yayımladıklarından iletilir ve bu iki değer veritabanının kendi values değerleri olur. Her parola, değişkeninin okunduğu anahtarla bildirilen bir core/secret-value ekine dönüşür.
release.yaml — ortam, API’nin imajı ve portu, her veri deposunun motor sürümü ve her parolanın nereden geldiği:
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"Ortam, development, hiçbir Compose dosyası bir ortam belirtmediği için içe aktarmanın yazdığı bir varsayılandır; Release başka bir yere dağıtıldığında bunu değiştirin. İmaj etiketleri, standart kütüphane Components’inin aldığı motor sürümlerine dönüşür. API’nin port değeri, container’ının dinlediği porttur; published_port ise ports girdisinin yayımladığı ana makine portudur; ikisi de Compose dosyasının belirttiği gibi 8080’dir. Yorumunun dediği gibi, bu makinedeki her süreç API’ye http://127.0.0.1:8080 adresinden ulaşır ve başka hiçbir şey ulaşamaz; satırı silmek API’yi yalnızca yığının ağında tutar. Hiçbir anahtarın almadığı şey, girdisinin üstünde bir yorum olarak kalır: port ve published_port değerlerinin zaten taşıdığı kaynaktaki ports girdisi ve veritabanının adlandırılmış birimi.
manifest.yaml — her bileşen türünün Compose Recipe’i ve bir parolanın değişken referansını Compose dosyasına yazıldığı gibi yazan gerçekleştirme:
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, Release’in çözümlendiği katalog varlıklarını özetleriyle (digest) kaydeder; .aggrega-import.json ise içe aktarmanın yazdıklarının kaydıdır ve sonraki bir aggrega import --sync onu okur.
Doğrulama ve derleme
aggrega validate --release release.yamlaggrega build --release release.yaml

Doğrulama şunu yazdırır:
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)ve derleme; burada <workspace>, onu çalıştırdığınız klasörü temsil eder:
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>/distnotice satırı yalnızca bilgilendirme amaçlıdır: parola Feature’ı origin değerini Aggregate’in values alanından ya da Release’in infra alanından kabul eder ve bildirim, bir yaprağın her ikisinde de bildirildiğini raporlar. Hiçbir kararı değiştirmez.
dist/compose/docker-compose.yaml içindeki api hizmeti, Compose projesinin ona verdiği ortamı okur; bu ortam bağlantılar ve parola eki tarafından iletilir:
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]ve veritabanı ile önbellek, Compose dosyasının adlandırdığı imajları çalıştırır:
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]Başladığınız projeden iki fark işlenen dosyada görünür. Bağlantı noktası, genel sunucunun Compose Recipe’sinin yayımladığı gibi yalnızca geri döngü (loopback) adresinde yayımlanır. Ve Compose dosyasının veritabanının verileri için bağladığı adlandırılmış birim hiçbir yerde görünmez: taslak onu veritabanının girdisinin üzerindeki bir yorumda listeler, PostgreSQL Component’inin hiçbir anahtarı onu almaz ve işlenen veritabanı hizmeti hiçbir birim bağlamaz.
Bir yapay zekâ asistanıyla
Aggrega’nın araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz hiçbir klasör oluşturmayın. Workspace klasöründe henüz bir `import-compose` klasörü yoksa, `example` değerini `import-compose` olarak ayarlayıp `dir` vermeden `scaffold` aracını bir kez çağırın: araç, örneği yeni bir `import-compose` klasörüne yazar; bu klasörün `source` klasörü, bu sayfanın içe aktardığı içeriği barındırır. Ardından `workspace_root` değerini `import-compose/source`, `source` değerini `compose.yaml` ve `target` değerini `compose` olarak ayarlayıp `import` aracını çağırın: araç, ihtiyaç duyduğu yanıtları `compose.yaml` dosyasının yanındaki `import-answers.yaml` dosyasından okur, taslaklarını `import-compose/source` içine yazar ve taslakların ihtiyaç duyduğu şeyleri çeker. Ardından `workspace_root` değerini `import-compose/source` ve `release` değerini `release.yaml` olarak ayarlayıp `validate` aracını, `workspace_root` değerini `import-compose/source`, `release` değerini `release.yaml` ve `write` değerini true olarak ayarlayıp `build` aracını çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `import-compose/source/dist/` altındadır.VS Code’da açın
Visual Studio Code için Aggrega uzantısı yüklüyken, içe aktarmanın taslaklarını yazdığı import-compose/source klasörünü VS Code’da açın. Klasörde tek bir Release, yani taslak release.yaml bulunur; bu nedenle düzenleyici onu sizin için seçer ve siz taslakları düzenlerken onları bu Release’e göre denetler, bulduklarını dosyada ve Sorunlar panelinde işaretler. Komut Paleti’ndeki Aggrega: Show topology graph, Release’in bileşenlerini ve aralarındaki bağlantıları çizer. Aggrega: Build, Aggrega: Preview build ve Aggrega: Pull aynı Release üzerinde çalışır ve her biri etkinlik çubuğundaki Aggrega görünümünün Commands panelinde bir düğmedir de; Build dosyalarını klasörün dist/ dizinine yazar. Gerisini Aggrega’yı Visual Studio Code’da kullanma anlatır.
Çalıştırın
ghcr.io/example/notes-api:2.3.0, kendi API’nizin imajını temsil eder. Bu bir yer tutucudur ve Docker Compose bunda Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied hatasıyla durur. API’nizin imajını release.yaml içinde api öğesinin infra.image alanında belirtin. API’niz hazır olana kadar, 8080 portunda HTTP yanıtı veren bir imaj onun yerine kullanılabilir. Aşağıdaki çalıştırmada, her isteğe aldığı isteğin bir açıklamasıyla yanıt veren mendhak/http-https-echo:39 kullanıldı:
api: infra: image: "mendhak/http-https-echo:39" port: 8080Değişiklikle yeniden derleyin. Release artık içe aktarmanın yazdığı release.lock ile eşleşmez, bu yüzden derleme onu yeniden çözümleyen --auto-pull seçeneğine ihtiyaç duyar; bu seçenek olmadan derleme durur ve aggrega pull komutunu adlandırır. Docker Compose her iki ${POSTGRES_PASSWORD} başvurusunu kabuğunuzdan doldurur, bu yüzden yığını başlatmadan önce parolayı ayarlayın: ayarlanmadığında Compose The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. uyarısını verir ve yerine boş bir değer yazar.
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, Bir içe aktarma nasıl çalışır bölümünün çalıştırma adımında açıklandığı gibi projeye ad verir. --wait, veritabanı ve önbellek derlemenin onlara verdiği sağlık denetimlerini geçtiğinde ve API’nin konteyneri çalıştığında döner: derleme API’ye hiçbir sağlık denetimi vermez.
Test edin
API’yi, published_port değerinin yayımladığı adres olan http://127.0.0.1:8080 üzerinden sorgulayın:
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]}Bağlantıların ilettikleri, API servisinin ortamında, API’nizin okuduğu adlar altında bulunur:
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOSTdbnotesnotescacheStack’i şu komutla durdurun:
docker compose -p notes -f dist/compose/docker-compose.yaml downKubernetes üzerinde
Aynı proje --target helm ile Kubernetes için içe aktarılır ve içe aktarma, Secret’ın adını, notes-db-password, yukarıdaki yanıtlar dosyasından okur. Docker Compose taslakları zaten source içinde durduğundan, bunların taslağını ayrı bir klasöre oluşturun, API’nin imajını Docker Compose’da olduğu gibi o klasörün release.yaml dosyasında belirtin ve oradan derleyin:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pullDerleme, düz Kubernetes manifestlerini çalışma alanının kökü olan source içindeki dist/helm/ altına yazar; bu, helm klasöründen bakıldığında ../dist/helm/ olur. Uyguladığınız namespace içinde, parolayı value veri anahtarı altında tutan notes-db-password Secret’ını oluşturun ve klasörü Bir içe aktarma nasıl çalışır bölümünün çalıştırma adımında açıklandığı gibi uygulayın. API’nin Service’i api-default’tur: yerel bir portu ona yönlendirin ve komutu çalışır durumda bırakın:
kubectl port-forward -n <namespace> svc/api-default 8080:8080Başka bir terminalden, yukarıdaki istek API’ye aynı adreste değişmeden ulaşır ve yerine geçen imaj da aynı şekilde yanıt verir, "host": "127.0.0.1:8080". Bağlantılar Service’lerin adlarını iletir: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST komutu db-default, notes, notes ve cache-default yazdırır. Kubernetes’te API henüz veritabanı parolasını almaz: notes-db-password Secret’ı yalnızca veritabanına ulaşır, bu nedenle api container’ında DATABASE_PASSWORD ayarlı değildir.
Compose dosyası değiştiğinde
.aggrega-import.json dosyasını taslakların yanında tutun ve Compose dosyası değiştikten sonra şunu çalıştırın:
aggrega import compose.yaml --syncYalnızca içe aktarmanın yazdıklarını değiştirir ve aynı yanıt dosyasını okur. Kaynağın dokunmadığı bir bölüm, düzenlenmiş olsun ya da olmasın, diskte olduğu gibi kalır; kaynağın sizin düzenlediğiniz bir bölümü değiştirdiği yerde durur, bölümü adlandırır ve hiçbir şey yazmaz; uzlaştırmayı elle siz yaparsınız. aggrega import kuralları ve her bayrağı eksiksiz olarak açıklar.