Compose Provider
compose provider는 Aggrega Recipes를 Docker Compose 파일로 렌더링합니다. 이 provider는 (path, provider) 단위로 조립합니다. 각 경계의 compose 기여자는 경계의 평가된 directory:와 component별 subDirectory:를 결합한 값을 키로 하는 어셈블러로 라우팅되며, 그 어셈블러는 해당 경로의 모든 기여자를 담은 docker-compose.yaml 하나를 출력합니다. 같은 경로로 평가되는 두 형제 경계는 병합된 하나의 compose 파일로 합쳐집니다. 대표적인 예는 상위 경계 하나와 directory: "{{ .parent_boundary.directory }}"를 가진 하위 경계 두 개입니다(compose-bridge 패턴).
지원되는 입력 종류
compose provider는 세 가지 Recipe 입력 종류를 모두 받습니다.
- 소스 모드.
source:가 기존 compose 파일을 가리키고valuesMapping:이 오버레이 문서를 생성하는 Recipe입니다. 기본 compose 파일을 로드하고, 오버레이를 평가한 뒤, docker-compose의 기본 오버레이 의미 체계에 따라 두 문서를 깊은 병합합니다. - Workload 모드.
workload:(인라인 또는$import:로 로드)가 있는 Recipe는Workload문서를 선언합니다. provider는 Workload 명세로부터 하나 이상의 compose 서비스를 합성합니다. - 아티팩트 모드. Recipe의
artifacts:항목은 compose 조각으로 평가되며, 이 조각은 아티팩트가 생성한 compose 조각의 규칙에 따라 조립된 파일에 병합됩니다. 아티팩트는 소스나 Workload와 함께 쓸 수 있고, Recipe의 출력 전체가 될 수도 있습니다.artifacts:를 선언하고source:도workload:도 선언하지 않은 Recipe는 여기서 렌더링되며, 조각이 선언한 내용을 그대로 기여합니다. 이렇게 하면 리소스만으로 이루어진 component(공유 네트워크와 볼륨 세트, 초기 설정 등)가 갖고 있지도 않은 컴퓨트를 대신하는 자리표시자 Workload 없이 compose 배포에 포함될 수 있습니다.
세 종류는 더하는 방식으로 결합되며, 어느 것도 선언하지 않은 Recipe는 로드 시 거부됩니다. 옆에 source:가 없는 valuesMapping:도 어떤 provider를 지정하든 Recipe 로드 시 거부됩니다. 오버레이를 적용할 대상이 없기 때문이며, 진단 메시지는 source: 포인터를 선언하거나 valuesMapping:을 제거하라고 안내합니다.
Workload 기능 매핑
Recipe가 workload:를 선언하면 provider는 플랫폼이 소유하는 Workload 형태를 compose 기본 요소로 변환합니다. 이 매핑은 의도적으로 좁게 설계되어 있습니다. Compose의 표현 범위는 Kubernetes보다 형태가 빈약하며, 여러 Workload 기능은 문서화된 손실과 함께 가장 가까운 compose 대응 요소로 축소됩니다.
컨테이너 필드
| Workload 필드 | Compose 필드 |
|---|---|
image | image |
imagePullPolicy: Always / IfNotPresent / Never | pull_policy: always / if_not_present / never |
command | entrypoint(리스트 형식) — 이미지의 진입점을 재정의하며, 이를 수행하는 compose 키입니다 |
args | command(리스트 형식) — 진입점이 받는 인수를 제공하며, 이는 compose의 command가 재정의하는 대상입니다 |
variables | environment(맵 형식) |
attachments[as: env] | 값이 비어 있는 environment 항목과 해당 항목을 명시하는 경고(compose provider가 제공하지 않는 것 참조) |
attachments[as: file] | volumes 긴 형식 바인드 마운트, 읽기 전용 |
volumeMounts | 참조된 Volume 변형이 매핑되는 compose 기본 요소 — volumes 긴 형식 항목, 서비스 수준 tmpfs: 항목 또는 서비스 수준 configs: 참조(Volumes 참조) |
ports | 암묵적(compose 컨테이너는 이미지가 수신 대기하는 포트를 노출합니다) |
restartPolicy: Always | restart: unless-stopped |
restartPolicy: OnFailure | restart: on-failure |
restartPolicy: Never | restart: "no" |
variables와 attachments[as: env]는 하나의 environment 맵에 들어가며, attachment 항목이 먼저, variables가 그 뒤에 오고 각각 작성된 순서를 따릅니다. 이는 helm provider가 쓰는 순서와 같으므로 하나의 Workload는 모든 대상에서 하나의 환경 변수 순서로 렌더링됩니다. Compose는 서비스의 환경 항목 사이에서 $(NAME) 참조를 확장하지 않으므로 compose에서는 이 순서가 런타임상 의미를 갖지 않습니다. 맵은 각 이름을 한 번만 담으므로, 한 이름을 variables 항목과 as: env로 전달되는 attachments 항목 양쪽으로 지정한 컨테이너는 두 값 중 하나를 유지하는 대신 빌드를 중단합니다(A container gives one environment variable two values (컨테이너가 하나의 환경 변수에 두 개의 값을 지정함) 참조).
컨테이너 리소스
컨테이너의 resources는 compose의 deploy.resources 블록에 반영되며, docker compose는 이를 non-swarm 모드에서 적용합니다. Kubernetes requests는 보장된 최솟값을 나타내므로 compose reservations가 되고, limits는 엄격한 상한을 나타내므로 그대로 limits로 유지됩니다.
| Workload 필드 | Compose 필드 | 변환 |
|---|---|---|
resources.requests.cpu | deploy.resources.reservations.cpus | 10진수 코어 수입니다. 숫자만으로 작성된 코어 수(2, 0.5)는 작성된 그대로 출력되며, 그 밖의 형식은 값에서 변환됩니다(500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10) |
resources.limits.cpu | deploy.resources.limits.cpus | 동일한 변환 |
resources.requests.memory | deploy.resources.reservations.memory | 정확한 바이트 수로, 어떤 형식으로 작성되었든 값에서 변환됩니다. 8Gi는 8589934592, 1.5Gi는 1610612736, 1e3은 1000이 됩니다 |
resources.limits.memory | deploy.resources.limits.memory | 동일한 변환 |
resources.limits, resources.requests 또는 둘 다에 있는 nvidia.com/gpu | deploy.resources.reservations.devices | 컨테이너 서비스의 NVIDIA 장치 항목 하나 — driver: nvidia, GPU 수를 담은 count:, capabilities: [gpu]. 수는 limit이 작성된 경우 limit의 값(Kubernetes가 확장 리소스에 대해 스케줄링하는 수)이고, 그렇지 않으면 request의 값입니다. 수가 0이면 GPU를 요청하지 않으며 항목을 쓰지 않습니다 |
그 밖의 모든 확장 리소스 키 — amd.com/gpu 및 그 밖의 모든 <domain>/<name> | — | 단일 호스트 compose에는 대응 요소가 없습니다. 키는 삭제되고 빌드는 이를 명시하는 unsupported-field 경고를 발생시키며, requests와 limits 중 몇 곳에 있었든 서로 다른 키마다 하나씩 발생합니다. 값은 출력되지 않으므로 검사되지 않습니다 |
각 cpu, memory, nvidia.com/gpu 값은 Recipe의 템플릿이 평가한 Workload에서 Workload → Resource quantities에 설명된 형식의 수량으로 읽힙니다. 다음 두 가지는 TRANSLATION_ERROR로 빌드를 중단시키며, 오류는 둘 중 어느 것에 해당하는지를 밝히고 컨테이너의 경로, 값이 request인지 limit인지, 리소스와 값을 명시합니다.
- 수량이 아닌 값 —
lots,1.5 cores, 또는 빈 템플릿이"{{ .infra.cpu }}m"에 남기는m; - compose가 정확히 표현할 수 없는 수량 — 음수; 바이트 단위의 정수가 아니거나(
1500m,4u) 9223372036854775807바이트보다 큰(8Ei) 메모리 양; Kubernetes 수량 자체가 유지하는 가장 세밀한 정밀도인 코어의 소수점 아홉째 자리보다 세밀하거나 9223372036.854775807코어보다 큰 cpu 양; 장치 단위의 정수가 아닌 GPU 수(0.5,500m).
nvidia.com/gpu request와 limit이 서로 다른 수를 요청하는 컨테이너도 같은 방식으로 중단되며, 두 경로를 모두 명시합니다. compose는 서비스 하나에 하나의 수만 예약하므로, 그렇지 않으면 변환이 둘 중 하나를 선택해야 하기 때문입니다. 양쪽에 같은 수를 쓰거나 limit만 쓰십시오.
어떤 값도 반올림되지 않으며, 다른 의미를 갖는 값은 출력되지 않습니다.
GPU request는 NVIDIA GPU를 예약합니다. nvidia.com/gpu: "1"을 요청하는 Workload 컨테이너는 request가 예약하는 cpus 및 memory와 함께 다음 예약을 담은 서비스로 렌더링됩니다.
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpuDocker Compose는 Docker 호스트에 그만큼의 NVIDIA GPU가 있고 컨테이너에 GPU를 제공하도록 설정되어 있을 때 예약된 GPU를 컨테이너에 전달합니다. 빌드는 호스트를 볼 수 없으므로 GPU를 예약하는 파일은 어디에서 실행되든 동일하게 조립됩니다. Compose는 수가 없는 장치 항목을 호스트의 모든 GPU로 읽기 때문에 항목은 항상 수를 명시합니다. NVIDIA 키만 변환됩니다. amd.com/gpu 및 그 밖의 모든 벤더 키는 삭제된 키 행의 경고를 그대로 유지합니다. Pod-level fields의 runtimeClassName 행은 변경되지 않습니다. compose에는 runtime-class 대응 요소가 없으므로, GPU 지원 런타임을 지정한 Workload는 런타임이 생략되었다는 알림을 받지만 GPU 수는 예약됩니다.
프로브
Workload의 세 프로브 슬롯(live, ready, startup)은 서비스당 하나인 compose의 healthcheck로 합쳐지며, 우선순위는 live > ready > startup입니다(가장 정석적인 liveness 신호가 우선합니다). 이 병합으로 작성자가 선언한 슬롯이 버려지는 경우, 빌드는 변환된 슬롯과 삭제된 슬롯을 명시하는 unsupported-field 경고를 발생시켜 출력 어디에도 반영되지 않는 의도가 사라지지 않고 보고되도록 합니다. 슬롯 하나를 선언한 health 블록은 손실 없이 변환되며 아무것도 발생시키지 않습니다. 단, 슬롯이 successThreshold를 설정한 경우는 예외입니다. compose healthcheck에는 이에 해당하는 필드가 없으므로, 작성된 값은 1을 포함하여 생략되고 이를 명시하는 unsupported-field 경고(containers.<name>.health.<slot>.successThreshold)가 발생하며, 슬롯의 나머지는 아래 표와 같이 변환됩니다.
| Workload 프로브 형태 | Compose healthcheck.test |
|---|---|
http: /path | ["CMD-SHELL", "curl -f http://localhost:<port>/path || exit 1"] |
tcp: <port> | ["CMD-SHELL", "nc -z localhost <port>"] |
exec: [cmd, ...] | ["CMD", cmd, ...] |
HTTP 형식을 쓰려면 컨테이너가 이름이 지정된 포트를 하나 이상 선언해야 합니다. 합성기는 알파벳순으로 첫 번째 포트 이름을 골라 그 번호로 curl URL을 만듭니다. 포트를 선언하지 않은 컨테이너는 HTTP 프로브를 사용할 수 없으며, 컴파일러는 문제가 되는 프로브를 명시하는 TRANSLATION_ERROR로 중단합니다.
프로브 시간 필드는 compose 스타일의 기간 문자열로 매핑됩니다.
| Workload 필드 | Compose healthcheck 필드 |
|---|---|
periodSeconds | interval: <n>s |
timeoutSeconds | timeout: <n>s |
failureThreshold | retries: <n> |
initialDelaySeconds | start_period: <n>s |
볼륨
Compose에는 자체 config 프리미티브가 있으며, configmap 볼륨은 이것으로 변환됩니다. Compose에는 Secret이나 레플리카별 볼륨 템플릿에 해당하는 Kubernetes 대응 요소가 없으므로, 해당 변형은 가장 가까운 compose 프리미티브로 격하됩니다.
| Workload 볼륨 변형 | Compose 변환 | 손실 사항 |
|---|---|---|
ephemeral | 서비스 수준 tmpfs: 목록 항목 | sizeLimit는 보존되지 않습니다(compose tmpfs 짧은 형식에는 크기가 없습니다). 작성된 sizeLimit는 컨테이너가 해당 볼륨을 마운트하는지와 관계없이, 작성된 좌표(volumes.<name>.ephemeral.sizeLimit)에서 그 필드를 지목하는 unsupported-field 경고를 발생시킵니다. 필드를 생략하면 아무것도 발생하지 않습니다 |
configmap | configmap을 지목하는 서비스 수준 configs: 참조로, 볼륨 마운트의 경로에 마운트됩니다 | 🔴 마운트 경로는 디렉터리가 아니라 단일 파일의 경로입니다. Compose는 config의 내용을 정확히 대상 경로에 기록하는 반면, Kubernetes 대상에서 ConfigMap을 경로에 마운트하면 키마다 파일 하나를 담은 디렉터리가 만들어집니다. 따라서 같은 작성된 path:가 여기서는 파일을, 저기서는 디렉터리를 가리킵니다. configmap 볼륨의 마운트는 이를 담을 디렉터리가 아니라 컨테이너가 읽어야 할 파일 이름(/seed/config.json)을 가리켜야 하며, 두 대상 모두를 위해 작성된 Recipe는 대상마다 다른 경로를 가집니다. 다른 대상의 형태에 맞춰 작성된 경로는 빌드의 어떤 단계에서도 잡아낼 수 없습니다. 경로는 컴파일러가 그대로 전달하는 불투명한 문자열이며, 생성된 출력은 어느 쪽이든 유효합니다. 참조는 Kubernetes 대상이 ConfigMap 리소스를 참조하는 것과 똑같이 이름으로 이루어지며, config의 내용은 아무것도 읽지 않습니다. 대응하는 최상위 configs: 항목은 Recipe의 artifacts: 입력에서 오며, 그 compose 프래그먼트가 인라인 content:로 이를 선언합니다. 그러한 항목이 없는 참조는 빌드를 중단시킵니다(Artifacts-emitted compose fragments 참조). configs: 참조는 config 이름과 마운트 경로만 담으므로, 마운트의 readOnly는 별도로 표현되지 않습니다 |
secret | volumes 긴 형식 바인드 마운트, 읽기 전용 | secret 볼륨은 의도적으로 configmap 변환을 따르지 않습니다. 인라인 configs: 항목은 secret의 값을 생성된 compose 파일에 평문으로 기록하게 되는데, 컴파일러는 secret을 평문으로 해석하지 않으며 secret은 빌드의 모든 단계에서 포인터로 유지됩니다. 바인드 소스는 secret의 source 이름이며, 운영자가 빌드와 무관하게 compose 호스트에서 접근할 수 있도록 만든 경로로 해석됩니다 |
persistent | 명명된 볼륨 + 최상위 volumes: { <volume-name>: {} } 선언으로, 볼륨 이름이 도출되는 방식에 따라 이름이 지정됩니다 | 스토리지 클래스, 액세스 모드, 크기는 보존되지 않습니다(compose에는 동등한 형태가 없습니다). 작성된 class 또는 accessModes는 작성된 좌표(volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes)에서 그것을 명시하는 unsupported-field 경고를 발생시키며, 둘 다 생략하면 아무것도 발생하지 않습니다. 필수인 size는 경고를 발생시키지 않습니다 — 아래 참조 |
persistentTemplate | 명명된 볼륨 + 최상위 선언으로, 같은 방식으로 이름이 지정됩니다(persistent와 동일) | form: stateful의 동반 요소입니다. compose에는 레플리카별 볼륨 템플릿 프리미티브가 없으므로 레플리카별 동작은 손실되며, unsupported-field 경고가 볼륨이 모든 레플리카가 공유하는 하나의 볼륨이 되었음을 알립니다. 스토리지 클래스, 액세스 모드, 크기는 persistent의 경우와 똑같이 보존되지 않습니다. 작성된 class 또는 accessModes는 volumes.<name>.persistentTemplate.class 또는 volumes.<name>.persistentTemplate.accessModes에서 unsupported-field 경고를 발생시키며, 필수인 size는 아무 경고도 발생시키지 않습니다 |
마운트의 subPath는 compose에 해당 형식이 있는 경우 볼륨의 일부를 마운트합니다. persistent 또는 persistentTemplate 볼륨을 지정하고 subPath를 가진 volumeMounts 항목은 volume.subpath를 가진 긴 형식 volumes 항목이 되므로, 마운트에는 볼륨의 루트가 아니라 볼륨 안의 지정된 디렉터리나 파일이 보이며, 한 볼륨을 서로 다른 두 subPath 값으로 마운트한 두 마운트에는 볼륨의 서로 다른 두 부분이 보입니다:
volumes: - type: volume source: store--data target: /var/lib/app/db volume: subpath: db - type: volume source: store--data target: /var/lib/app/uploads volume: subpath: uploadssubPath 없이 작성된 마운트는 volume: 블록을 갖지 않습니다. ephemeral, configmap 또는 secret 볼륨의 마운트에 있는 subPath는 TRANSLATION_ERROR로 빌드를 중단시키며, 컴포넌트, 컨테이너, 마운트의 작성된 경로(containers.<name>.volumeMounts[<i>]), 볼륨 및 subPath를 명시합니다. 이 변형들은 compose에서 각각 tmpfs 항목, configs: 참조, 바인드 마운트가 되며, 그중 어느 것도 전달하는 내용의 일부만 마운트하지 않으므로, 중단하지 않으면 마운트에 볼륨 전체가 보이게 됩니다. 그러한 마운트에서 subPath를 제거하거나 persistent 볼륨을 마운트하십시오. Docker Compose는 릴리스 2.26.0부터, Docker Engine 26.0 이상에서 volume.subpath를 읽습니다. 빌드는 파일을 실행할 호스트를 볼 수 없으므로, 이를 가진 파일은 어디에서 실행되든 같은 방식으로 조립됩니다.
볼륨은 자신이 어떤 변형인지만 나타냅니다. secret 볼륨의 변환은 위의 읽기 전용 바인드 마운트 하나뿐이며, 볼륨에는 다른 변환을 선택할 as: 필드가 없습니다. 슬롯이 게시한 것을 환경 변수로 전달하는 것은 볼륨이 아니라 컨테이너의 attachments 항목(as: env)이며, compose가 이를 어떻게 처리하는지는 What the compose provider does not deliver에서 설명합니다.
세 가지 변형이 스토리지 크기를 가지지만, 크기가 버려졌다고 경고하는 것은 그중 하나뿐입니다. 차이는 선택의 여지가 있었는지에 있습니다. ephemeral 볼륨의 sizeLimit는 선택 사항이므로 이를 작성한 것은 하나의 결정이었고, 경고는 그 값이 이 대상에서 아무것도 결정하지 않으며 제거해도 된다고 알려 줍니다. 이 경고는 권고성이며 출력과 별개로 전달되고, 생성된 파일은 경고가 없을 때와 바이트 단위로 동일하며, --no-unsupported-field-warnings는 같은 부류의 다른 경고와 함께 이를 끕니다. persistent 또는 persistentTemplate 볼륨의 size는 필수이므로 어떤 버전의 문서도 이를 생략하지 않습니다. 그런 경우 빌드마다 경고를 내면 바꿀 수 있는 것을 하나도 지목하지 못한 채 모든 stateful 워크로드에서 경고가 발생하므로, 이 차이는 빌드마다 보고하는 대신 여기서 설명합니다. compose를 대상으로 하면 persistent 볼륨의 size, class, accessModes는 생성된 파일에서 아무것도 결정하지 않습니다. 결과는 compose 호스트의 볼륨 드라이버가 기본으로 하는 방식대로 크기가 정해지고 뒷받침되는 평범한 명명된 볼륨입니다. class와 accessModes는 선택 사항이므로, 작성한 각 필드는 ephemeral의 sizeLimit와 같은 방식으로 보고됩니다. 필드마다 unsupported-field 경고가 하나씩 발생하며, 이 경고는 권고성이고 출력과 별개로 전달되며 같은 플래그로 끌 수 있습니다. 기반 스토리지의 크기는 호스트에서, 또는 이 필드가 실제로 출력에 반영되는 Kubernetes 대상에서 지정하십시오.
어떤 컨테이너도 마운트하지 않는 볼륨은 작성된 좌표(volumes.<name>)에서 그 볼륨을 지목하는 unsupported-field 경고를 발생시킵니다. 이 경우 생성된 파일에 반영되는 내용이 변형에 따라 크게 달라지기 때문입니다. persistent와 persistentTemplate은 여전히 최상위 선언을 생성하므로, 볼륨은 만들어지지만 아무것도 사용하지 않습니다. ephemeral, configmap, secret은 마운트 자체 외에는 표현이 없습니다. 각각 마운트 경로에 기록되는 무언가, 즉 tmpfs 항목, configs 참조, 바인드 마운트로 변환되므로, 마운트하는 것이 없으면 선언한 볼륨은 출력에 아무런 흔적도 남기지 않습니다. 이 두 번째 경우가 경고가 존재하는 이유입니다. 경고가 없다면 마운트를 잊은 configmap 볼륨은 생성된 파일에서 알아챌 단서 없이 그냥 빠져 있게 됩니다. 워크로드의 모든 컨테이너는 init 컨테이너를 포함해 마운트 주체로 간주되므로, init 컨테이너만 마운트하는 볼륨도 연결된 것이며 아무것도 발생시키지 않습니다. 이 경고는 권고성이며 출력과 별개로 전달됩니다. 생성된 파일은 경고가 없을 때와 바이트 단위로 동일하며, --no-unsupported-field-warnings는 이 부류의 경고를 끕니다.
볼륨 이름이 도출되는 방식
persistent 또는 persistentTemplate 볼륨은 compose 명명된 볼륨이 됩니다. 즉 최상위 volumes: 항목 하나가 되며, 이를 마운트하는 모든 컨테이너가 이 항목을 참조합니다. compose 볼륨은 공유 스토리지이고 최상위 volumes: 블록은 항목을 이름으로 합치므로, 같은 이름에 도달한 두 작성된 볼륨은 두 컨테이너가 모두 기록하는 하나의 볼륨이 되며, 생성된 파일에는 원래 둘이었다는 것을 보여 주는 단서가 없습니다. 따라서 이름은 그것이 어떤 볼륨인지를 함께 나타내는 두 식별자, 즉 볼륨이 속한 <component>와 Workload가 volumes: 아래에서 볼륨에 붙인 이름으로 구성됩니다.
compose 볼륨 이름이 허용하는 문자 집합은 두 식별자가 가질 수 있는 문자보다 좁습니다. 문자, 숫자, 점, 밑줄, 하이픈만 허용됩니다. 도출 과정은 compose가 허용하지 않는 문자를 다른 문자로 대체하는 대신 풀어서 기록하므로, 조금이라도 다른 두 볼륨은 서로 다른 두 이름에 도달하며, 조립된 이름을 다시 원래의 두 식별자로 읽어 낼 수 있습니다.
- 문자, 숫자, 점, 밑줄은 작성된 그대로 전달됩니다.
- 하이픈은 그 뒤의 문자가 그대로 전달되고 소문자
z가 아닌 경우 작성된 그대로 유지됩니다. 소문자z가 뒤따르는 하이픈은 이스케이프를 시작하므로, 그 위치에 작성된 하이픈은 그 자체가 풀어서 기록됩니다.api-zone은api-zhzone이 되며, 덕분에 어떤 이름이든 추측 없이 다시 읽어 낼 수 있습니다. 뒤에 아무것도 없는 하이픈도 같은 이유로 풀어서 기록되므로db-는db-zh가 됩니다. - 그 밖의 모든 문자는
-z뒤에 그 문자를 나타내는 글자를 붙여 기록합니다. 경로 구분자는s, 위 규칙이 유지하지 않는 하이픈은h입니다. 공백과 비ASCII 문자를 포함한 그 밖의 모든 것은x와 문자의 여섯 자리 16진수 코드 포인트로 기록하며, 어떤 문자도 시작하지 않는 바이트는b와 그 바이트의 두 자리 값으로 기록합니다. 따라서 유효한 텍스트가 아닌 이름도 뭉개지지 않고 구별되게 기록됩니다. - 빈 값은
-ze로 기록되며, 비어 있지 않은 값은 이를 만들어 낼 수 없습니다. - 두 식별자는
--로 연결됩니다. 인코딩된 단일 식별자는 이 쌍을 절대 포함하지 않으므로, 연결된 이름은 한 식별자가 어디서 끝나고 다른 식별자가 어디서 시작하는지를 모호함 없이 나타냅니다.
따라서 Workload가 data라고 부르는 볼륨을 가진 component store는 볼륨 이름 store--data를 만들고, db-server와 data는 db-server--data를 만듭니다. 동일한 입력은 항상 동일한 이름을 만듭니다.
쌍을 모호하지 않게 만드는 것은 두 글자 연결자이며, 한 글자 연결자로는 그렇게 할 수 없습니다. 두 식별자 모두 하이픈을 포함할 수 있으므로, 하이픈 하나로 연결하면 둘 이상의 위치에서 나뉠 수 있는 이름이 남습니다. data-cache라는 볼륨을 가진 db와 cache라는 볼륨을 가진 db-data는 모두 db-data-cache가 되며, 최상위 블록은 이름으로 합치므로 두 component는 생성된 파일에 아무런 표시도 없이 하나의 볼륨을 공유하게 됩니다. 인코딩된 식별자는 하이픈 쌍을 절대 포함하지 않으므로, 두 글자 연결자는 다른 해석의 여지를 남기지 않습니다. 두 경우는 각각 db--data-cache와 db-data--cache가 됩니다.
어느 한 식별자를 바꾸면 compose 볼륨의 이름이 바뀌며, compose는 볼륨의 이름을 제자리에서 바꾸지 않습니다. 새 이름으로 볼륨이 새로 만들어지고 기존 볼륨은 데이터를 담은 채 남으므로, 컨테이너는 빈 스토리지로 시작하고 내용은 아무것도 마운트하지 않는 볼륨에 남게 됩니다. 어느 식별자든 이름을 바꿀 때는 배포할 변경으로 다루지 말고 백업, 복사, 일정 수립 등 계획이 필요한 교체로 다루십시오.
컨트롤러 형식
Workload의 form은 추상적인 컨트롤러 형태를 선택합니다(entities/workload.md 참조). Compose는 stateless와 stateful(그리고 stateless로 취급되는 빈 기본값)을 장기 실행 서비스로 렌더링하며, stateful 형식은 persistentTemplate 동반 요소를 위한 명명된 볼륨을 추가합니다. daemon, scheduled, task 형식은 단일 호스트 compose에 깔끔하게 매핑되지 않으므로, compose 경계를 대상으로 이 중 하나를 선언한 Workload는 해당 형식과 지원되는 집합을 지목하는 TRANSLATION_ERROR로 중단됩니다. compose는 지원되지 않는 형식을 의도를 잘못 나타내는 평범한 서비스로 격하하지 않습니다. reference Workload는 외부 엔드포인트를 선언하고 컨테이너는 없으므로, compose는 이에 대한 서비스를 출력하지 않습니다.
reference Workload에 대해서는 서비스가 출력되지 않으므로, 그것이 실현하는 컴포넌트의 전달 파이프를 읽는 것이 없습니다. 그 컴포넌트에 어태치된 자격 증명(dotenv-secret 또는 어태치먼트 자체의 inject: 블록에 의해 그 파이프로 전달되는 것)은 출력되는 어떤 파일에도 도달하지 않습니다. 따라서 이런 방식으로 외부 서비스를 실현하고 그 Component가 자격 증명 슬롯을 선언하는 모든 표준 라이브러리 Compose Recipe는 그 슬롯을 채우는 자격 증명을 거부합니다. 빌드는 자격 증명이 없는 채로 성공하는 대신 슬롯과 컴포넌트를 명시하며 중단됩니다. compose에서 외부 서비스의 자격 증명은 그 서비스를 호출하는 컴포넌트에, 그 컴포넌트가 읽는 환경 변수 이름으로 어태치합니다. 이 거부는 각 Recipe 자체의 어설션이며, 이 provider가 무엇이든 렌더링하기 전에 실행됩니다. 이 provider는 Recipe가 어느 카탈로그에서 왔든 노드 자체에서도 거부합니다. reference 노드의 어태치먼트 중 그 자료가 민감한 것으로 선언된 것, 즉 그 Feature가 필드를 sensitive: true로 선언하거나 그것이 채우는 슬롯이 그렇게 선언한 것은 TRANSLATION_ERROR(E0288)로 빌드를 중단시키며, 노드와 그러한 모든 어태치먼트를 명시합니다. 이는 어태치에 쓰인 이름을 어떤 슬롯이 선언하는지 여부와 관계없습니다. 민감한 것으로 선언된 것을 아무것도 갖지 않는 어태치먼트는 여기서 거부되지 않습니다. 해당 Components는 자격 증명 슬롯을 선택 사항으로 선언하므로, compose에서는 비어 있는 슬롯 때문에 중단되는 일이 없습니다. Kubernetes 실현에 자격 증명이 필요한 경우, 즉 twilio, vonage, telnyx, bland, letta, retell, vapi의 helm Recipes에서는 그 Recipe가 대신 슬롯을 필수로 요구하며, 비어 있으면 슬롯을 명시하며 빌드를 중단합니다.
서비스 노출
Workload services 항목의 type 필드는 compose가 포트를 게시할지, 그리고 어떤 호스트 주소에 게시할지를 결정합니다.
| Workload 서비스 유형 | Compose 동작 |
|---|---|
ClusterIP | ports: 게시 없음 — 서비스는 compose 네트워크에서만 접근할 수 있습니다 |
NodePort | 모든 호스트 인터페이스에 ports: [<host>:<container>] 게시 |
LoadBalancer | 모든 호스트 인터페이스에 ports: [<host>:<container>] 게시(compose에는 관리형 로드밸런서에 해당하는 것이 없으며, 호스트 포트 게시가 가장 가까운 대응입니다) |
Loopback | ports: [127.0.0.1:<host>:<container>] 게시 — 호스트 자신에서만 접근할 수 있고 다른 곳에서는 접근할 수 없습니다 |
Headless | ports: 게시 없음 |
어느 번호가 어느 쪽에 오는가. 서비스 항목은 컨테이너 포트를 지정하고 거기에 번호를 부여합니다. Kubernetes Service가 port를 targetPort에 매핑하는 방식과 같습니다. 항목의 번호는 게시되는 쌍의 <host> 쪽이고, 이름이 해석되는 컨테이너 포트의 번호는 <container> 쪽입니다. 따라서 http: 8080을 선언한 컨테이너와 http: 8081을 작성한 NodePort 항목은 8081:8080을 게시합니다. 호스트의 포트 8081이 컨테이너가 서비스하는 포트에 도달합니다. 컨테이너 포트 자체의 번호를 지닌 항목은 그 번호를 양쪽에 게시하여 8080:8080이 됩니다. compose 네트워크의 피어는 게시된 포트가 아니라 컨테이너의 포트에서 서비스 이름으로 서비스에 도달합니다. 게시된 포트는 호스트에 속하기 때문입니다. 따라서 직접 선택한 포트를 게시하는 Recipe도 소비자에게는 여전히 컨테이너의 포트를 전달합니다.
Loopback 항목은 IPv4 루프백 주소에만 바인딩됩니다. IPv6 루프백 주소 ::1은 바인딩되지 않습니다. compose의 포트 구문은 항목당 호스트 주소 하나를 담으며, 루프백 인터페이스에 IPv6 주소가 없는 호스트는 이를 바인딩할 수 없어 그곳에서는 서비스가 시작되지 않기 때문입니다. 호스트의 클라이언트는 127.0.0.1에서 포트에 접근합니다.
단일 Workload의 여러 서비스가 같은 컨테이너 포트를 같은 번호로 게시하면 포트는 한 번만 게시되며, 가장 넓은 접근 범위가 우선합니다. NodePort 또는 LoadBalancer 참조가 하나라도 있으면 Loopback 항목도 그 포트를 지목하고 있더라도, 그리고 어느 항목이 먼저 선언되었든 관계없이 모든 호스트 인터페이스에 게시됩니다. Loopback 항목만 지목하는 포트는 127.0.0.1에 게시됩니다. 두 번호로 게시되는 하나의 컨테이너 포트는 각 번호마다 한 번씩, 두 번 게시됩니다. 게시된 포트는 컨테이너 포트 순서로 나열되며, 하나의 컨테이너 포트 안에서는 게시된 포트 순서로 나열됩니다.
포트 전송 프로토콜. 게시된 항목은 자신이 지목하는 컨테이너 포트에 선언된 전송 프로토콜을 compose의 /protocol 접미사로 담습니다. 예를 들어 53:53/udp, Loopback 항목이라면 127.0.0.1:53:53/udp입니다. 전송 프로토콜을 선언하지 않은 포트는 접미사 없이 <host>:<container>로 게시되며, compose 자체의 기본값이 적용됩니다. Compose는 게시된 포트의 전송 프로토콜을 tcp 또는 udp로 표기합니다. SCTP를 선언한 포트는 compose 표기가 없으므로, 다른 전송 프로토콜을 사용하는 포트를 게시하는 대신 TRANSLATION_ERROR로 중단됩니다. 어떤 서비스도 게시하지 않는 컨테이너 포트는 compose 파일의 어느 부분에도 반영되지 않으므로, 그러한 포트에 선언된 전송 프로토콜은 표기될 곳이 없으며 중단을 일으키지 않습니다.
다중 컨테이너 Workloads
컨테이너가 여러 개인 Workload는 하나의 메인 서비스와, 메인이 아닌 컨테이너마다 하나씩의 사이드카 서비스가 됩니다. 메인 컨테이너는 main이라는 이름의 컨테이너(있는 경우)이거나, 선언 순서상 첫 번째 컨테이너입니다. 사이드카는 network_mode: "service:<main>"을 통해 메인 서비스의 네트워크 네임스페이스를 공유합니다. 이는 Kubernetes 파드의 공유 네트워크 모델에 가장 가까운 compose 기본 요소입니다.
사이드카 또는 init 서비스의 이름 지정 방식
메인 서비스는 <component> 이름을 그대로 사용합니다. Workload가 생성하는 그 밖의 모든 서비스 — 사이드카마다 하나, init 컨테이너마다 하나 — 는 두 식별자를 함께 사용해 이름이 지정됩니다. 하나는 <component>이고 다른 하나는 컨테이너 이름이며, 컨테이너 이름은 사이드카의 경우 containers: 아래의 키, init 컨테이너의 경우 name, 또는 이름 없는 init 항목이 갖는 위치 기반 init-<index>입니다. 조립된 services: 블록은 이름마다 서비스 하나를 담으므로, 어느 한 식별자라도 다른 두 컨테이너는 항상 서로 다른 두 이름을 갖도록 이름이 구성됩니다.
각 식별자는 볼륨 이름의 두 부분과 정확히 같은 방식으로 기록됩니다 — 문자, 숫자, 점, 밑줄은 작성한 그대로, 하이픈은 그곳의 규칙이 유지하는 위치에서 유지되며, 그 밖의 모든 문자는 변환되어 기록됩니다 — 그리고 두 식별자는 변환된 어떤 식별자에도 포함되지 않는 --로 연결됩니다. 따라서 사이드카 logger가 있는 컴포넌트 api는 이를 api--logger로 실행하고, platform의 init 컨테이너 import-seed는 platform--import-seed로, api의 이름 없는 첫 번째 init 항목은 api--init-0으로 실행됩니다. 서비스 이름이 허용하지 않는 문자를 포함한 컨테이너 이름은 작성한 그대로 출력되지 않고 변환되어 기록됩니다. api의 warm cache/x라는 init 컨테이너는 api--warm-zx000020cache-zsx로 실행됩니다.
이중 연결은 두 컴포넌트의 컨테이너를 서로 구분합니다. 컨테이너 warm-cache가 있는 api와 컨테이너 cache가 있는 api-warm은 api--warm-cache와 api-warm--cache라는 두 서비스로 실행되며, 하이픈 하나로 연결하면 둘 다 api-warm-cache가 됩니다.
사이드카와 init 컨테이너는 이 하나의 명명 방식을 공유하므로, 같은 이름을 가진 containers 항목과 initContainers 항목은 같은 서비스 이름에 도달하며, 빌드는 한 컨테이너를 다른 컨테이너 대신 실행하지 않고 그 쌍에서 중단됩니다(Init 컨테이너 참조).
컴포넌트 자체의 서비스는 이러한 이름을 갖지 않습니다. 메인 서비스는 컴포넌트의 이름을 따르며, 컴포넌트 이름에 쓰인 이중 하이픈은 그곳에서 그 자체로 변환되어 기록되므로 — api--prep이라는 컴포넌트는 api-zh-prep으로 실행됩니다 — -- 연결을 포함하지 않습니다. 그럼에도 서로 다른 두 컴포넌트의 서비스가 하나의 compose 파일에서 같은 이름으로 만나는 경우 — 예를 들어 아티팩트가 스스로 이름을 붙인 서비스를 통해 — 빌드는 둘 다를 밝히며 중단됩니다. (path, provider)별 출력에서 설명하는 바와 같습니다.
컴포넌트 이름이나 컨테이너 이름을 변경하면 서비스 이름이 바뀝니다. Compose는 새 이름의 서비스를 새 서비스로 취급하므로, 그 컨테이너는 새 이름으로 새로 생성됩니다.
파드 수준 필드
파드 수준의 Workload 필드는 메인 서비스에만 적용됩니다. 사이드카는 메인 서비스의 네트워크 네임스페이스를 공유하며, init 서비스도 같은 규칙을 따릅니다. 유일한 예외는 파드의 사용자입니다. 파드는 모든 컨테이너를 podSecurityContext.runAsUser와 runAsGroup으로 실행하므로, 이 값들은 사이드카와 init 서비스를 포함해 Workload가 생성하는 모든 서비스에 적용됩니다.
그중 몇 가지는 compose 서비스 필드에 대응합니다.
| Workload 필드 | Compose 필드 |
|---|---|
podSecurityContext.runAsUser / runAsGroup | Workload의 모든 서비스에 대한 user("1000", 또는 그룹이 있으면 1000:3000). 자체 securityContext.runAsUser를 설정한 컨테이너는 대신 자신의 서비스에서 그 사용자로 실행되며, 자체 runAsGroup을 설정한 경우 그 그룹도 사용합니다 |
terminationGracePeriodSeconds | stop_grace_period: <n>s |
dnsConfig.nameservers / dnsConfig.searches | dns / dns_search |
hostAliases | 호스트 이름마다 하나의 extra_hosts 항목, 작성 순서대로 |
hostNetwork: true | network_mode: host |
노드의 네트워크에서 실행. hostNetwork: true를 선언한 워크로드는 자체 서비스에 network_mode: host를 받으며, 그 서비스는 경계 네트워크에 연결되지 않고 제외됩니다. compose는 networks:와 network_mode:를 모두 선언한 서비스를 거부하므로, 둘은 함께 쓰는 것이 아니라 택일하는 것입니다. 실질적인 결과는 호스트 네트워킹이 항상 수반하는 것과 같습니다. 서비스가 더 이상 그 네트워크에 있지 않으므로 피어는 그 네트워크에서 compose 서비스 이름으로 서비스에 접근하지 못하고, 호스트 자체의 주소로 접근합니다. 이것이 바로 선언이 요청한 바입니다. 경계의 다른 서비스는 영향을 받지 않습니다.
이와 함께 쓰이는 형태가 두 가지 있습니다. 사이드카는 계속 메인 서비스를 지정하므로(network_mode: "service:<main>"), 스스로 아무것도 선언하지 않아도 메인 서비스를 따라 호스트의 네트워크로 갑니다. Kubernetes 파드의 컨테이너들이 하나의 네임스페이스를 공유하는 것과 같은 방식입니다. init 서비스는 그렇지 않습니다. init 서비스는 독자적으로 경계 네트워크에 참여하는데, 메인 서비스의 네임스페이스를 공유하면 메인 서비스가 init 서비스를 기다리는 것이 순환이 되기 때문입니다. 따라서 hostNetwork와 initContainers를 모두 가진 워크로드는 자체 서비스를 호스트의 네트워크에서 실행하고 init 서비스는 경계 네트워크에 남으며, 이는 모델로 삼는 파드 형태보다 범위가 좁습니다. 이 차이를 실행 시점에 발견하도록 남겨 두지 않고 unsupported-field 경고가 이를 알려 줍니다.
나머지는 단일 호스트에 해당하는 것이 없습니다. 어느 것도 조용히 버려지지 않습니다. 작성된 각 필드는 해당 필드를 명시하는 unsupported-field 경고를 발생시키므로, 작성자는 실행 중인 스택에서 발견하는 대신 대상이 어떤 설정을 지원할 수 없었는지 알게 됩니다.
| Workload 필드 | compose가 지원할 수 없는 이유 |
|---|---|
scheduling | 배치 — nodeSelector, affinity, tolerations, topologySpreadConstraints — 는 노드 중에서 선택하는 스케줄러를 전제합니다. compose는 하나의 호스트에서 실행됩니다 |
replicas | compose 자체의 레플리카 수는 deploy: 아래에 있으며 swarm 모드 기능입니다 |
runtimeClassName | 다른 컨테이너 런타임(예: GPU 지원 런타임)을 선택하는 것은 compose로 표현할 방법이 없습니다 |
priorityClassName | 선점 순서는 스케줄러를 전제합니다 |
serviceAccount | Workload 아이덴티티는 클러스터 개념입니다 |
imagePullSecrets | compose 호스트의 레지스트리 자격 증명은 파일의 필드가 아니라 호스트 자체의 로그인 상태입니다 |
dnsPolicy, dnsConfig.options | compose는 dns와 dns_search만 제공하며 그보다 세밀한 것은 없습니다 |
podSecurityContext.fsGroup, podSecurityContext.supplementalGroups | user는 사용자 하나와 그룹 하나를 담습니다. 파드의 볼륨을 소유하는 그룹과 프로세스의 추가 그룹은 변환되지 않습니다 |
파드가 runAsUser를 설정하지 않은 경우, 또는 컨테이너(메인, 사이드카, init)가 자체 runAsUser를 설정하고 runAsGroup은 설정하지 않은 경우의 podSecurityContext.runAsGroup | user는 사용자와 함께일 때만 그룹을 지정하며, 컨테이너 자체 사용자가 파드의 사용자를 대신하므로, 그렇게 작성된 서비스에는 파드의 그룹이 적용되지 않습니다 |
컨테이너 수준의 securityContext는 부분적으로 변환됩니다. readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot와 allowPrivilegeEscalation은 compose로 표현할 방법이 없으며 같은 unsupported-field 경고를 발생시킵니다. 옆에 runAsUser 없이 작성된 컨테이너의 runAsGroup도 마찬가지입니다. 이 경우 파드가 사용자를 설정했다면 서비스는 그 그룹 없이 파드의 사용자로 실행됩니다.
이 절의 모든 경고는 권고 사항이며 대역 외로 전달됩니다. 빌드는 성공하고, 생성된 파일은 경고가 없을 때와 바이트 단위로 동일합니다. --no-unsupported-field-warnings로 이 유형의 경고를 끌 수 있습니다.
Init 컨테이너
Workload의 initContainers 항목은 compose의 완료까지 실행(run-to-completion) 관용 방식을 사용하여 각각 별도의 서비스가 됩니다. 각 항목은 서비스 하나를 추가하며, 이 서비스는 사이드카와 같은 명명 방식에 따라 <component>와 항목의 name으로부터 이름이 지어집니다. 일반적인 이름이면 <component>--<container-name>입니다. name을 생략한 항목은 Workload 레퍼런스에 설명된 위치 기반 이름 init-<index>를 사용하며, 그 이름으로부터 명명됩니다.
작성 계약이 약속하는 순서, 즉 init 컨테이너가 작성된 순서대로 완료까지 실행되고 다른 모든 컨테이너는 이들이 모두 끝난 뒤에야 시작된다는 순서는 depends_on의 긴 형식으로 표현됩니다.
- 첫 번째 이후의 각 init 서비스는
condition: service_completed_successfully로 직전 서비스를 기다립니다. - 메인 서비스와 모든 사이드카 서비스는 같은 조건으로 마지막 init 서비스를 기다립니다. init 서비스가 체인을 이루므로 마지막 서비스만 기다리면 충분합니다.
- 각 init 서비스에는
restart: "no"가 지정됩니다. init 서비스는 한 번만 실행됩니다. 다시 기동된 서비스는 의존하는 서비스들이 기다리는 완료 상태에 도달하지 못하므로, init 컨테이너에 작성된restartPolicy도 이를 바꾸지 않습니다.
services: platform: image: platform:1.0 depends_on: platform--verify-seed: condition: service_completed_successfully platform--import-seed: image: platform:1.0 restart: "no" platform--verify-seed: image: platform:1.0 depends_on: platform--import-seed: condition: service_completed_successfully restart: "no"init 컨테이너는 다른 컨테이너와 정확히 같은 방식으로 변환됩니다. image(aggrega.ai/image-registry 어노테이션이 적용하는 레지스트리 재작성 포함), command, args, variables, attachments, volumeMounts, securityContext가 모두 init 서비스에 반영됩니다. 이 덕분에 init 컨테이너가 지닌 구성, 대개는 마운트하여 메인 컨테이너도 마운트하는 볼륨에 기록하는 파일이 컨테이너와 함께 사라지지 않고 compose 대상에 그대로 유지됩니다. compose가 표현할 수 없는 형태는 일반 컨테이너와 마찬가지로 init 컨테이너에서도 실패합니다. 선언된 lifecycle 또는 envFrom은 해당 init 컨테이너를 명시하는 TRANSLATION_ERROR로 중단됩니다.
init 서비스가 메인이 아닌 서비스이기 때문에 메인 서비스와 두 가지 차이가 생깁니다.
- Pod 수준 Workload 필드는 적용되지 않습니다. 사이드카가 따르는 규칙과 같습니다. 단, 파드의 사용자는 예외이며 파드 수준 필드에서 설명하는 대로 모든 서비스에 적용됩니다.
- init 서비스는 사이드카처럼 메인 서비스의 네트워크 네임스페이스를 공유하지 않고 자신의 boundary 네트워크에 직접 참여합니다. 그래야만 합니다. 메인 서비스가 init 서비스를 기다리는데, 네임스페이스 공유 자체가 메인 서비스에 대한 의존이므로 대기가 순환이 되어 compose가 시작을 거부하기 때문입니다. 따라서 init 컨테이너는 boundary 네트워크의 다른 서비스에 서비스 이름으로 접근하지만, 메인 서비스의
localhost는 공유하지 않습니다.
init 서비스와 사이드카 서비스는 하나의 명명 방식이 둘 모두의 이름을 정하므로 하나의 이름 네임스페이스를 공유하며, 따라서 initContainers 항목과 containers 항목은 같은 이름을 가질 수 없습니다. 같은 이름이면 컴파일러는 한 서비스가 다른 서비스를 조용히 대체하도록 두지 않고, 노드, 컨테이너 이름, 둘 다 원한 서비스 이름을 명시하는 TRANSLATION_ERROR로 중단합니다.
완료 조건을 출력해도 최소 Compose 버전은 올라가지 않습니다. condition과 그 값은 기본 Compose Specification에 속합니다. 같은 긴 형식 블록에 함께 있는 restart와 required 필드는 사양이 특정 Compose 릴리스에 연결하는 것과 다릅니다. compose provider의 출력이 요구하는 각 최소 버전은 그것을 필요로 하는 구성 요소와 함께 나옵니다. 인라인 configs.content에는 ≥ 2.23.1, 마운트의 subPath에는 ≥ 2.26.0(볼륨 참조), 모델에는 2.38입니다. 첫 번째 버전은 인라인 content:를 가진 config를 포함하는 모든 compose 출력에 적용되며, configmap 볼륨 뒤의 파일과 브리지된 교차 네트워크 엣지 뒤의 config가 모두 이 방식으로 전달됩니다. 특정 작성 경로 하나에만 해당하는 것이 아닙니다.
서비스가 참여하는 네트워크
모든 서비스는 Docker 네트워크에 참여합니다. 사이드카는 메인 서비스를 가리키는 network_mode 참조를 통해 이를 상속합니다. 노드가 어느 네트워크에 놓이는지는 해당 노드의 aggrega.ai/namespace 어노테이션에서 읽으며, 노드에 그런 어노테이션이 없으면 compose 파일의 경로를 대신 사용합니다. 이는 빌드 출력 디렉터리 아래에서 파일이 기록되는 디렉터리로, 예를 들어 directory:가 bridge인 경계라면 bridge/compose입니다. 따라서 하나의 compose 파일에서 어노테이션이 없는 모든 노드는 어느 경계에 있든 파일 경로로 이름 붙은 하나의 네트워크에 참여합니다. compose 파일을 공유하는 어노테이션 없는 경계는 그 네트워크를 공유하며, 이들을 분리하는 것이 aggrega.ai/namespace입니다. 서로 다른 어노테이션을 가진 노드는 고유한 어노테이션마다 하나의 네트워크에 놓입니다. 네트워크 이름이 도출되는 방식은 그 식별자가 만들어 내는 이름입니다.
네트워크 이름이 도출되는 방식
compose 네트워크는 공유되는 L3 연결이며, 최상위 networks: 블록은 항목을 이름으로 합칩니다. 따라서 하나의 이름에 도달한 두 식별자는 양쪽 서비스 집합이 모두 놓이는 하나의 네트워크가 되어 서비스 이름으로 서로에게 도달하게 되고, 출력된 파일에는 두 개의 네트워크가 의도되었음을 보여 주는 것이 아무것도 남지 않습니다. 그래서 이름은 그것이 어떤 네트워크인지를 말해 주는 식별자, 즉 노드의 aggrega.ai/namespace 어노테이션 또는 노드에 어노테이션이 없을 때의 compose 파일 경로로부터 만들어집니다.
compose 네트워크 이름은 두 식별자 중 어느 쪽이 가질 수 있는 것보다 좁은 문자 집합, 즉 문자, 숫자, 점, 밑줄, 하이픈만 허용합니다. 도출 과정은 compose가 허용하지 않는 문자를 다른 문자로 대체하는 대신 풀어서 기록하므로, 조금이라도 다른 두 식별자는 두 개의 네트워크에 도달하며, 이름을 그것이 만들어진 식별자로 다시 읽어 낼 수 있습니다.
- 문자, 숫자, 점, 밑줄은 작성된 그대로, 작성된 대소문자 그대로 전달됩니다. 따라서
prod와Prod는 하나가 아니라 두 개의 네트워크입니다. - 하이픈은 그 뒤의 문자가 그대로 전달되고 소문자
z가 아닌 경우 작성된 그대로 유지됩니다. 소문자z가 뒤따르는 하이픈은 이스케이프를 시작하므로, 그 위치에 작성된 하이픈은 그 자체가 풀어서 기록됩니다.api-zone은api-zhzone이 되며, 덕분에 어떤 이름이든 추측 없이 다시 읽어 낼 수 있습니다. 뒤에 아무것도 없는 하이픈도 같은 이유로 풀어서 기록되므로db-는db-zh가 됩니다. - 그 밖의 모든 문자는
-z뒤에 그 문자를 나타내는 글자를 붙여 기록합니다. 경로 구분자는s, 위 규칙이 유지하지 않는 하이픈은h입니다. 그 밖의 것은 공백과 비 ASCII 문자를 포함하여x와 그 문자의 여섯 자리 16진수 코드 포인트로 기록하고, 어떤 문자도 시작하지 않는 바이트는b와 그 바이트 자체의 두 자리 값으로 기록합니다. 따라서 유효한 텍스트가 아닌 식별자도 뭉개지지 않고 구별되게 기록됩니다. - 식별자가 아예 없는 경우, 즉 경로가 없는 compose 파일 안에서
aggrega.ai/namespace어노테이션이 없는 노드는-ze로 기록되며, 이는 작성자가 작성한 어떤 식별자로도 만들어질 수 없습니다. 따라서 식별자가 없는 네트워크는 특정 방식으로 표기된 식별자를 가진 네트워크와 결코 연결을 공유하지 않습니다.
따라서 네임스페이스 prod는 네트워크 prod를, core-net은 core-net을, dist/app/compose에 있는 compose 파일은 dist-zsapp-zscompose를 만듭니다. 동일한 입력은 항상 동일한 이름을 만듭니다.
네임스페이스와 compose 파일의 경로는 같은 공간에 기록됩니다. 이 둘은 같은 것, 즉 노드가 어느 네트워크에 있는지를 명명하는 두 가지 방법입니다. 따라서 네임스페이스가 app/compose인 노드와, app/compose에 있는 compose 파일 안에서 네임스페이스가 없는 노드는 같은 aggrega.ai/namespace 어노테이션을 가진 두 경계와 똑같이 의도적으로 하나의 네트워크에 놓입니다. 두 노드를 분리하려면 서로 다른 식별자를 부여하십시오.
노드의 식별자를 변경하면 compose 네트워크의 이름이 바뀌며, compose는 네트워크 이름을 제자리에서 바꾸지 않습니다. 네트워크는 새 이름으로 새로 생성되고 그 위의 모든 서비스는 새 네트워크에 연결되도록 다시 생성되며, 이전 네트워크는 무언가가 제거할 때까지 남아 있습니다. 네트워크는 데이터를 담지 않으므로 잃는 것은 없지만, 그 위의 컨테이너는 재시작되며 변경 시점에 연결을 유지하던 것은 연결이 끊깁니다. 네임스페이스 어노테이션이나 compose 파일이 기록되는 디렉터리의 변경은 제자리에서 조정할 값이 아니라 계획해야 할 재배포로 다루십시오.
두 경계가 하나의 조립 경로로 합쳐지면(공유 directory:), 그중 aggrega.ai/namespace 어노테이션이 없는 노드는 파일의 단일 네트워크를 공유합니다. 각 경계에 고유한 aggrega.ai/namespace 어노테이션을 부여하면 병합된 docker-compose.yaml은 어노테이션마다 최상위 networks: 항목을 하나씩 선언합니다. 같은 compose 파일 안의 서로 다른 경계에 속한 서비스는 compose 자체의 네트워크 간 도달성 규칙에 따라 compose의 기본 DNS 해석 안에서 서비스 이름으로 통신할 수 있습니다. 단일 compose 파일 안의 네트워크 간 L4 라우팅은 표준 라이브러리의 compose-bridge Feature가 가능하게 하는 것으로, 이는 카탈로그 콘텐츠이며 이 provider는 그 로직을 전혀 갖고 있지 않습니다. 공통 조상 경계에 연결되면 그 FeatureRecipe는 양 끝이 경계 자신의 compose 파일로 조립되고 그 파일의 서로 다른 네트워크에 놓이는 경계의 uses 엣지로부터 게이트웨이를 도출합니다. 이는 nginx stream 구성이 브리지된 각 엣지를 프록시하는 aggrega-gw 서비스입니다(엣지마다 server 블록 하나, 대상의 포트를 사용하며 충돌 시 portBase로 대체). 그리고 FeatureRecipe 자신의 injectMapping은 각 소비자의 호스트 환경 변수를 aggrega-gw:<port>로 다시 쓰며, 같은 연결이 호스트와 포트를 모두 전달하는 경우에는 aggrega-gw로 다시 쓰고 포트 변수를 수신 포트로 다시 씁니다. 이 재작성은 소비자 자신의 연결이 전달한 값을 대체합니다. 소비자에 연결된 다른 Feature가 같은 변수를 전달했다면, 빌드는 값을 대체하지 않고 둘 다를 명시하며 중단됩니다. FeatureRecipe의 valuesMapping은 그 구성을 마운트된 compose config로 기록합니다. 이는 인라인 content:를 가진 최상위 configs: 항목으로, 게이트웨이에서 참조되어 /etc/nginx/nginx.conf에 마운트되며, 운영자가 마운트해야 하는 사항이 아닙니다. 또한 브리지된 모든 엔드포인트를 게이트웨이의 x-aggrega-networks-of 아래에 지정하며, 이 provider는 이를 해당 엔드포인트가 놓인 네트워크로 해석합니다(아래). 양 끝이 두 compose 파일로 조립되는 엣지는 브리지되지 않으며 대상 자신의 이름을 유지합니다. 브리지할 것이 없는 경계에도 유휴 게이트웨이가 남으며, 구성도 없고 자신의 네트워크 외의 네트워크도 없습니다. 그리고 compose 파일에 컴포넌트가 하나도 없는 경계에 연결된 브리지는 게이트웨이를 아무 데도 기록하지 않는 대신 빌드를 중단시킵니다. stream 구성은 resolver 지시어를 포함하고 엣지별 변수(set $uN <host>; proxy_pass $uN)를 통해 프록시하므로, 각 업스트림은 시작 시 한 번이 아니라 연결 시점에 해석됩니다. 그렇지 않으면 아직 실행되지 않은 대상으로의 단순 proxy_pass가 부팅 시 게이트웨이를 실패시킵니다. (이 변수들의 $는 configs.content 안에서 $$로 이스케이프되어, Docker Compose 자체의 $ 보간이 nginx에 리터럴 $를 남깁니다.) 인라인 configs.content에는 Docker Compose ≥ 2.23.1이 필요합니다. compose-bridge 패턴을 참조하십시오.
다른 컴포넌트의 네트워크에 참여하기 — x-aggrega-networks-of
프래그먼트가 작성하는 서비스, 즉 오버레이가 병합된 후의 소스 compose 파일 또는 artifacts: 본문은 확장 키 x-aggrega-networks-of 아래에 다른 컴포넌트를 지정하여 같은 compose 파일로 조립된 그 컴포넌트들의 네트워크에 참여할 수 있습니다. 이 키는 컴포넌트 ID의 목록으로, Aggregate가 자신의 컴포넌트에 부여하는 ID이며, boundary 범위 FeatureRecipe는 이를 .boundary.components의 키로, 그리고 .boundary 엣지 목록의 source와 target으로 읽습니다. provider는 모든 노드가 받는 것과 같은 배치에 따라 각 ID를 해당 컴포넌트가 이 파일에서 놓인 네트워크로 해석하고, 그 네트워크들을 각각 한 번씩 이름순으로 서비스에 추가합니다. 이들은 서비스 자신의 네트워크보다 앞에 오며, 서비스는 여전히 자신의 네트워크에도 참여합니다. 키 자체는 조립된 파일에서 제외됩니다. provider는 ID를 해석할 참조로만 읽고 서비스가 무엇을 하는지는 전혀 읽지 않으므로, 어떤 Recipe나 FeatureRecipe든 이 키를 사용할 수 있습니다. compose bridge의 게이트웨이는 이 방식으로 자신이 중계하는 엔드포인트의 네트워크에 참여합니다.
# written by a FeatureRecipe attached at the boundary `bridge`, whose file holds adminer (namespace frontend) and db (namespace backend)services: probe-svc: image: busybox x-aggrega-networks-of: ["adminer", "db"]# dist/bridge/compose/docker-compose.yaml (abridged)services: probe-svc: image: busybox networks: - backend - frontend - bridge-zscompose파일이 조립될 때 다음 세 가지는 TRANSLATION_ERROR로 빌드를 중단시키며, 각각 서비스를 명시합니다.
- 이 파일로 조립된 어떤 컴포넌트도 갖지 않는 ID, 예를 들어 다른 compose 파일로 조립된 컴포넌트의 ID. 네트워크는 하나의 파일에 속하므로, 메시지는 ID와 서비스가 속한 파일을 명시합니다. 같은 파일로 조립된 컴포넌트만 지정하거나 ID를 제거하십시오.
- 문자열 목록이 아닌 값. 이 키는 ID가 하나뿐이더라도 컴포넌트 ID의 목록을 받습니다.
network_mode를 작성한 서비스의 이 키. Compose는network_mode가 있는 서비스가 네트워크에 참여하는 것을 허용하지 않습니다. 둘 중 하나를 제거하십시오.
depends_on 추론
compose provider는 IR의 uses 엣지로부터 depends_on을 자동으로 도출합니다. 소스와 타깃이 모두 병합된 compose 파일에 서비스를 기여하는 각 엣지에 대해, provider는 소스 서비스에 depends_on: [<target>]를 추가합니다.
의존성은 소스 컴포넌트 자체의 서비스에만 추가되며, 그 컴포넌트가 기여하는 다른 서비스에는 추가되지 않습니다. init 컨테이너도 선언하는 컴포넌트는 항목마다 완료될 때까지 실행되는 서비스를 하나씩 기여하며, 그중 어느 것도 엣지에서 도출된 의존성을 받지 않습니다. 엣지는 컴포넌트를 지정하고, init 서비스는 자체 이름을 가지기 때문입니다. 따라서 컴포넌트가 uses하는 데이터베이스에 대한 스키마 마이그레이션처럼 엣지의 타깃에 접근해야 하는 init 컨테이너는 그 타깃에 대한 순서 지정이 없어 타깃에 접근할 수 있기 전에 실행될 수 있으며, 컴포넌트 자체의 서비스는 init 체인이 완료되기를 기다리는 동시에 타깃이 시작되기를 기다립니다.
엣지에서 도출된 항목은 게이트 없이 출력됩니다. 타깃이 healthcheck를 선언하는지와 관계없이 service_started 의미를 가집니다. 타깃의 상태로 게이트하는 것, 즉 타깃의 healthcheck가 healthy를 보고할 때까지 compose 런타임이 시작을 막도록 하는 것은 표현할 수 있지만, uses 엣지는 이를 요구하지 않습니다. 같은 쌍을 지정하는 웨이브만이 엣지에서 도출된 항목의 조건을 바꾸며, 이는 엣지가 아니라 웨이브가 그것을 요구하기 때문입니다.
엣지에서 도출된 항목은 출력 안정성을 위해 타깃의 알파벳 순서로 출력됩니다. 소스나 타깃이 다른 provider(helm 또는 helm-chart)에 의해 처리되는 엣지는 건너뜁니다. depends_on은 Release 중 compose가 처리하는 부분 집합 안에서만 적용됩니다.
서비스의 depends_on은 compose의 두 형식 중 하나로만 출력되며 섞이지 않습니다. compose는 긴 형식의 모든 항목에 조건을 요구하기 때문입니다.
- 짧은 형식 목록(
depends_on: [<service-name>]): 해당 서비스의 어떤 항목도 조건을 가지지 않을 때 사용됩니다. 의존성이 모두uses엣지에서만 오는 서비스가 모두 여기에 해당합니다. - 긴 형식 매핑: 어느 한 항목이라도 조건을 가질 때 사용됩니다. 이는 서비스가 init 컨테이너도 기다리거나 배포 웨이브가 순서를 지정할 때 발생합니다. 이 경우 엣지에서 도출된 항목은 명시적인
condition: service_started를 출력하며, Compose Specification은 이를 짧은 형식과 동등하다고 정의하므로 의미는 바뀌지 않습니다.
한 서비스 안에서 각 출처는 자체 순서를 유지하며 서로 섞이지 않습니다. 작성자가 목록을 작성한 순서를 따르는 init 체인 대기가 먼저 출력되고, 그다음 알파벳 순으로 정렬된 엣지 도출 항목, 그다음 알파벳 순으로 정렬된 웨이브 도출 항목이 출력됩니다.
배포 웨이브 순서
Release 경계의 syncWave: 값은 그 경계가 렌더링되는 compose 파일의 서비스 순서를 정합니다. 경계 안의 모든 컴포넌트는 경계의 웨이브를 상속하며, 여러 경계가 하나의 directory:를 공유하여 그 기여분이 단일 docker-compose.yaml로 합쳐지는 경우, 병합된 파일에는 둘 이상의 웨이브가 담기고 provider는 그 사이의 순서를 depends_on으로 표현합니다.
각 서비스는 서비스가 하나라도 있는 바로 이전 wave의 모든 서비스를 기다리며, 그보다 앞선 wave는 기다리지 않습니다. 나머지는 Compose가 전이적으로 해결합니다. wave 2의 서비스는 wave 1을 기다리고, 그 wave는 다시 wave 0을 기다리므로, 각 서비스의 목록은 파일 전체가 아니라 wave 하나 크기로 유지되면서도 전체 순서가 정해집니다. wave는 연속적일 필요가 없으며 음수 값도 일반적으로 사용됩니다. 다른 모든 것보다 먼저 실행되는 마이그레이션에는 흔히 -1을 선택합니다.
조건은 대상이 충족할 수 있는 것에 따라 달라집니다. 웨이브는 이전 그룹이 준비된 뒤에 다음 그룹이 시작된다는 뜻이며, 이는 프로세스 실행이 아니라 준비 상태를 의미합니다. 따라서:
- 대상 서비스가
healthcheck를 선언하면 대기 조건은condition: service_healthy입니다. - 선언하지 않으면 대기 조건은
condition: service_started입니다. healthcheck가 없는 서비스는 healthy를 보고할 수 없으므로, 그 서비스에 대한 상태 기반 대기는 결코 충족되지 않고 파일이 결코 기동되지 않기 때문입니다.
약한 조건은 출력된 파일에서 강한 조건과 나란히 보이며, 빌드는 그러한 서비스 각각을 경고로도 알려 줍니다. 따라서 준비 상태 순서를 기대한 작성자는 자신이 선언한 웨이브 중 어느 부분이 시작 순서로만 적용되는지 알 수 있습니다. 이 경고는 참고용입니다. 빌드는 성공하며 렌더링된 바이트는 경고가 없을 때와 정확히 같습니다. 해당 컨테이너에 health: 블록을 추가하면 대기 조건이 강화됩니다. --no-unsupported-field-warnings는 이 종류의 경고를 끕니다.
웨이브는 여전히 레이블로도 기록됩니다. 순서는 aggrega.ai/sync-wave 레이블을 대체하지 않고 그 옆에 추가됩니다. 출력된 파일을 살펴보는 사람은 이 레이블에서 서비스가 어느 웨이브에서 왔는지 알 수 있으며, 이는 depends_on 항목에는 나타나지 않습니다.
웨이브와 uses 에지가 같은 쌍을 가리키면 항목 하나가 둘 다를 담습니다. Compose는 의존성 하나에 항목 하나만 허용하므로, 대상을 uses하면서 그 대상보다 한 웨이브 뒤에 있는 서비스는 웨이브의 조건이 적용된 단일 항목을 출력합니다. 둘 중 더 강한 요구 사항은 웨이브의 것이며 그것이 표현됩니다.
모든 컴포넌트가 한 웨이브에 있는 경계는 이로부터 아무것도 출력하지 않습니다. syncWave를 전혀 선언하지 않은 Release도 마찬가지입니다. 모든 기여자는 이 필드의 기본값 0을 가지므로 병합된 파일에는 웨이브가 하나뿐이며, 출력은 provider가 웨이브 순서를 전혀 표현하지 않았을 때와 정확히 같습니다.
두 compose 파일 사이의 순서는 표현할 수 없으며, 근사하지도 않습니다. depends_on은 같은 파일 안의 서비스를 가리키며, 서로 다른 어셈블리 경로로 평가되는 경계들은 서로 다른 docker-compose.yaml 파일을 생성하고, compose 런타임은 이를 독립된 프로젝트로 취급합니다. 따라서 웨이브는 렌더링되는 파일 안의 모든 서비스의 순서를 정할 뿐 그 밖의 것은 정하지 않습니다. 두 compose 프로젝트의 순서를 정하는 것은 파일 간 라우팅과 마찬가지로 운영자의 몫입니다. 두 경계를 한 파일로 모으는 것은 공유 directory: 선언이며, 이는 순서를 얻기 위해서가 아니라 그 자체의 이유로 내려야 하는 출력 형태에 관한 결정입니다.
더 나중 웨이브를 가리키는 uses 엣지는 작성된 그대로 출력되고 보고됩니다. 출력된 depends_on은 선언된 내용, 즉 uses 엣지와 웨이브 모두를 반영합니다. 소비자가 자신이 사용하는 대상보다 더 이른 웨이브에 있는 엣지는 웨이브가 말하는 것과 반대를 말합니다. 엣지는 소비자가 대상을 기다리게 하는 반면, 웨이브는 둘 사이의 모든 웨이브를 거쳐 대상이 소비자를 기다리게 합니다. 병합된 파일은 둘 다 표현하며, 이는 Docker Compose가 시작을 거부하는 순환 의존성 집합입니다. 빌드는 이러한 각 엣지를 두 서비스와 두 웨이브를 모두 밝히는 경고로 명시하므로, 순환은 docker compose up 시점이 아니라 빌드할 때 드러납니다. 이 경고는 권고성입니다 — 빌드는 성공하고 렌더링된 바이트는 경고가 없을 때와 정확히 같습니다 — 그리고 --no-unsupported-field-warnings로는 끌 수 없습니다. 버려진 것이 없기 때문입니다. 두 선언은 각각 표현되었고, 함께 있으면 시작할 수 없을 뿐입니다. 이 경고는 직접적인 쌍만 다룹니다. 전체 순환을 추적하는 대신 하나의 엣지가 연결하는 두 서비스를 명시합니다. uses 엣지와 웨이브가 함께 만드는 순환은 그러한 엣지를 적어도 하나 지나므로 항상 보고됩니다. 반면 웨이브가 관여하지 않고 uses 엣지만으로 형성된 순환과, Recipe가 제공하는 compose 파일에 작성된 depends_on 항목으로 닫히는 순환은 작성된 그대로 출력되며 보고되지 않습니다. 엣지 방향과 웨이브 순서를 일관되게 유지하십시오. 소비자를 대상의 웨이브나 그 이후 웨이브에 두거나, 대상을 소비자의 웨이브나 그 이전 웨이브에 두십시오.
# release.yaml fragment — three boundaries collapsing onto one compose fileboundaries: data: directory: ./dist/cluster syncWave: -1 components: migrator: {} # no health: block core: directory: ./dist/cluster syncWave: 0 components: store: {} # declares health: edge: directory: ./dist/cluster syncWave: 1 components: frontend: {} # uses: store# dist/cluster/compose/docker-compose.yaml (abridged)services: frontend: labels: aggrega.ai/sync-wave: "1" depends_on: store: condition: service_healthy # store declares a healthcheck migrator: labels: aggrega.ai/sync-wave: "-1" # lowest wave: waits on nothing store: depends_on: migrator: condition: service_started # migrator declares no healthcheck healthcheck: test: [CMD-SHELL, "nc -z localhost 5432"]frontend는 migrator를 가리키지 않습니다. 순서는 바로 앞 웨이브까지만 미치며, 나머지는 compose가 store를 통해 연결합니다.
소스 모드
compose provider의 source:는 provider가 읽고 파싱할 수 있는 docker-compose YAML 파일을 지정하며, source: 필드가 취하는 두 가지 형태를 모두 허용합니다. 하나는 단순 파일 시스템 경로 문자열이고, 다른 하나는 url:에 위치를 담는 구조화된 객체입니다. 그 위치가 파일 시스템 경로인 경우, 경로는 빌드를 호출한 디렉터리가 아니라 해당 경로를 선언한 recipe.yaml이 있는 디렉터리를 기준으로 하며, 그 디렉터리 안에 머물러야 합니다. 디렉터리 밖으로 벗어나는 경로나 절대 경로는 거부됩니다. Recipe의 배포본이 담는 모든 파일은 그 디렉터리에서 가져오기 때문입니다. entities/recipe.md의 “Content paths stay inside the Recipe’s own directory”를 참조하십시오. 이렇게 지정된 파일은 Recipe와 함께 배포되지만, Recipe 옆에 있더라도 Recipe가 선언하는 어떤 항목도 지정하지 않는 파일은 배포되지 않습니다.
spec: capability: compose source: ./docker-compose.base.yaml # filesystem path to the base compose file valuesMapping: | services: api: image: "{{ .values.image }}"구조화된 형태에서는 url:에 담긴 내용에 따라 가져오기 여부가 결정됩니다. https://로 배포된 프래그먼트는 가져와서 kind: compose-https-fragment로 고정됩니다. aggrega pull이 이를 획득하고 빌드는 캐시에서 읽습니다. 파일 시스템 경로를 지정하는 url:은 가져오지 않고 디스크에서 읽으며, 위의 단순 문자열 형태와 똑같이 기준 디렉터리가 정해집니다. aggrega pin은 지정된 파일의 다이제스트를 Recipe 옆의 entity.lock에 기록하고, 빌드는 프래그먼트를 읽기 전에 이를 비교합니다. 원격 프래그먼트를 로컬에 벤더링하고 source:가 벤더링된 사본을 가리키게 하는 방식은 가져오기의 대안으로 지원되며, 필수는 아닙니다. 스키마는 개방형 구조화 객체를 허용합니다.
source: <path-to-compose-file>와 valuesMapping:을 가진 Recipe는 다음 파이프라인을 실행합니다.
<path>의 기본 compose 파일을 읽고 YAML로 파싱합니다.valuesMapping템플릿이 Recipe의 템플릿 컨텍스트에 대해 평가됩니다. 그 출력은 compose 오버레이 문서, 즉 기본 파일의 필드를 보강하거나 재정의하는 부분 compose 파일로 취급됩니다.- 기본 파일과 오버레이는 docker-compose 고유의 오버레이 의미 체계에 따라 깊은 병합됩니다.
깊은 병합 규칙은 다음과 같습니다.
- 스칼라: 오버레이가 우선합니다. 기본 파일과 오버레이가 같은 스칼라 필드를 설정하면 오버레이의 값이 기본 파일의 값을 대체합니다.
- 맵: 재귀적으로 병합합니다. 기본 파일과 오버레이가 같은 맵 필드를 설정하면 병합이 맵 안으로 재귀합니다. 양쪽에 모두 있는 키는 같은 규칙을 따르고, 한쪽에만 있는 키는 그대로 보존됩니다.
- 리스트: 대체합니다. 기본 파일과 오버레이가 같은 리스트 필드를 설정하면 오버레이의 리스트가 기본 파일의 리스트를 완전히 대체합니다(요소 단위 병합이나 추가는 없습니다). 이는
docker compose -f base.yaml -f overlay.yaml config의 동작과 일치합니다. null: 대체하며, 남습니다. 오버레이가 서비스에서null로 설정한 키, 즉user,command,healthcheck같은 서비스 자체의 키,environment항목, 레이블, 또는healthcheck나deploy바로 아래의 키는 다른 스칼라처럼 기본 파일의 값을 대체하고 compose 파일에key: null로 기록됩니다. 키를 제거하지는 않습니다. provider가 해당 키에 자체 값을 기록하는 경우, 파일에는 대신 provider의 값이 들어갑니다.labels: null이면 provider가 붙이는 출처 레이블이 남고,networks: null이면 provider가 연결하는 네트워크가 남습니다. 오버레이의 다른 곳에 작성된null은 이 규칙의 대상이 아닙니다. 그null이 무엇을 뜻하는지는 해당 속성에 대한 Compose의 해석에 따릅니다. 예를 들어 값이 없는environment항목은docker compose가 실행되는 환경에서 값을 가져옵니다.
서비스 작성자가 작성한 모든 레이블은 유지됩니다. 기본 파일 또는 오버레이에 있는 서비스의 labels:는 맵으로 작성하거나 Compose의 key=value 항목 목록으로 작성할 수 있으며, 각 레이블은 provider가 붙이는 출처 레이블과 함께 compose 파일에 들어갑니다. 목록 항목은 Compose가 읽는 방식대로 읽힙니다. 첫 번째 = 앞의 텍스트가 레이블 이름이고 뒤의 텍스트가 값이며, =가 없는 항목은 값이 비어 있는 레이블입니다. 숫자나 true/false 값은 그 텍스트로 작성되므로 replicas-hint: 2는 파일에 replicas-hint: "2"로 들어가고, null로 작성된 레이블은 null로 유지됩니다. 작성된 레이블과 출처 레이블이 같은 키를 가지면 파일에는 출처 값이 들어갑니다. 맵도 목록도 아닌 labels: 값과 텍스트가 아닌 목록 항목은 소스 파일과 서비스를 명시하며 빌드를 중단시킵니다. artifacts: 본문의 서비스 레이블은 맵 형식을 사용합니다. 그곳에서 목록을 사용하면 아티팩트와 서비스를 명시하며 빌드가 중단됩니다.
병합된 문서는 이후 합성 모드 기여분과 함께 Release 수준 병합으로 넘어가며, 동일한 경계별 네트워킹과 depends_on 추론이 적용됩니다.
서비스, 볼륨, 구성 제외하기. 오버레이는 기본 파일에서 아무것도 제거할 수 없습니다. 오버레이 값은 대체할 뿐 삭제하지 않습니다. 따라서 가져온 파일에 Release가 실행해서는 안 되는 서비스가 포함되어 있다면, 이를 위한 것이 Recipe 또는 FeatureRecipe의 omits: 항목입니다. 이 provider는 이 모드에서만 이를 따르며, 합성된 Workload와 artifacts: 본문은 이를 적용하지 않고 렌더링됩니다. 항목은 파일의 최상위 단위 하나를 kind(service, volume 또는 config)와 name(services:, volumes: 또는 configs: 아래의 단위 키)으로 지정하며, 정확히 일치하는지 비교합니다. compose 파일에는 네임스페이스가 없으므로, namespace를 가진 항목은 다른 kind를 지정하는 항목과 마찬가지로 컴포넌트가 렌더링될 때 빌드를 중지시키며, 해당 항목과 이 provider가 허용하는 kind를 표시합니다. 무엇이든 제외하기 전에 모든 항목을 검사합니다. 항목은 위의 오버레이가 병합된 뒤의 파일과 대조되므로 오버레이가 추가한 단위도 기본 파일이 선언한 단위와 똑같이 제외되며, provider가 자체적으로 무언가를 추가하기 전에 대조되므로 항목이 그것을 지정하는 일은 없습니다. 항목이 지정한 단위는 제거되며, 모든 단위가 제외된 섹션도 함께 제거됩니다. 그 밖의 모든 단위는 항목이 없을 때와 정확히 똑같이 기록됩니다. 항목은 그것을 선언한 Recipe 또는 FeatureRecipe의 파일에만 적용됩니다. 다른 component나 연결된 Feature가 같은 docker-compose.yaml에 기여한 내용은 같은 키를 가진 단위를 포함하여 영향을 받지 않습니다. provider는 각 항목이 제외한 단위 수를 보고하며, 아무것도 제외하지 않은 항목은 빌드를 중지시킵니다. An omits entry left out nothing the source rendered (omits 항목이 소스가 렌더링한 것 중 아무것도 제외하지 않음)을 참조하십시오.
제외된 단위는 남은 내용에서 계속 참조되어서는 안 됩니다. compose는 선언하지 않은 서비스, 볼륨 또는 구성을 지정하는 파일을 거부하기 때문입니다. 단위가 제거된 뒤 파일이 여전히 그중 하나를 참조하면 모든 참조가 빌드를 중지시키며, 메시지에는 참조하는 각 서비스 또는 작업, 지정된 단위, 참조가 있는 필드가 표시됩니다. 참조란 Compose Specification이 파일의 한 항목이 다른 항목을 지정하는 것으로 정의한 것입니다.
- 서비스: 두 형태 중 어느 쪽이든
depends_on,links(SERVICE또는SERVICE:ALIAS),volumes_from(SERVICE또는SERVICE:MODE),service:<name>으로 설정된network_mode,ipc,pid또는uts, 같은 파일의 서비스를 지정하는extends, 또는service:<name>값을 가진build.additional_contexts로 지정됩니다. - 볼륨:
volumes:항목의 소스로 지정됩니다. 소스가 경로가 아닌 이름인 짧은 형태SOURCE:TARGET와type: volume의 긴 형태가 해당합니다. - 구성: 두 형태 중 어느 쪽이든
configs:항목으로 지정됩니다.
서비스의 pre_start 훅과 각 최상위 jobs: 항목도 사양이 각각에 허용하는 참조에 대해 읽습니다. 일부 값은 참조처럼 보일 뿐 참조로 읽지 않습니다. container:로 시작하는 volumes_from 또는 network_mode 항목은 컨테이너를 지정하고, external_links는 이 파일이 선언하지 않은 컨테이너를 지정하며, file:이 있는 extends는 다른 파일의 서비스를 지정하고, credential_spec.config는 파일이 아닌 플랫폼이 보유한 구성을 지정할 수 있습니다. 모든 값은 작성된 그대로 비교되므로 ${VARIABLE}을 통해 작성된 참조는 이 검사가 감지하지 못하며, 파일이 선언한 적 없는 단위에 대한 참조는 그대로 남습니다.
검사는 선언한 Recipe 또는 FeatureRecipe 자체의 파일만 읽으므로, 같은 어셈블리 경로의 다른 기여자가 같은 이름의 서비스를 선언하더라도 제외된 서비스에 대한 참조는 빌드를 중지시킵니다. 참조를 유지하려면 단위를 유지하십시오. 참조를 없애려면 valuesMapping:을 통해 참조하는 항목을 변경하거나(그곳의 리스트는 기본 파일의 리스트를 대체하므로 depends_on: []으로 비울 수 있습니다), 참조하는 서비스도 함께 제외하십시오.
(path, provider)별 출력
각 compose 어셈블리 경로는 하나의 docker-compose.yaml을 생성합니다. 서로 다른 경로로 평가되는 경계는 서로 다른 compose 파일을 생성하고, 평가된 경로를 공유하는 경계는 그 경로의 모든 기여자를 담은 하나의 병합된 compose 파일을 생성합니다. 경로는 경계의 directory:에 컴포넌트별 subDirectory:를 이어 붙인 것입니다(이 값의 기본값은 {{ .capability }}이므로 compose 기여자는 기본적으로 compose/ 하위 폴더에 놓입니다).
단일 어셈블리 경로 안에서 서비스 이름이 충돌하면 빌드가 중단됩니다. 서로 다른 두 노드가 같은 (path, provider) 튜플에서 같은 인스턴스 ID를 가진 서비스를 기여하면 컴파일러는 중단되고, 진단은 기여하는 모든 (boundary, node) 튜플을 알파벳순으로 나열합니다. 작성자는 기여자 중 하나의 이름을 바꾸거나(일반적으로 노드의 식별자를 조정하여 신시사이저가 다른 서비스 이름을 생성하도록 함), 서로 다른 directory: 선언을 통해 기여자를 서로 다른 경로로 보내 충돌을 해결합니다.
최상위 볼륨은 어셈블리 경로 안에서 합집합으로 모이며, 두 기여자는 같은 이름에 대해 합의하는 한 하나의 이름을 선언할 수 있습니다. 기여자는 프래그먼트이므로, 한 컴포넌트의 두 프래그먼트, 즉 자체 compose 파일과 artifacts: 항목, 또는 두 artifacts: 항목은 두 컴포넌트와 똑같이 두 기여자입니다. 명명된 볼륨은 하나의 물리적 볼륨이므로, 동일한 두 선언은 모두 어셈블된 파일에 최종적으로 들어가는 항목을 정확히 기술하며, 그 이름 아래에 단일 항목이 유지됩니다. provider가 도출한 볼륨은 본문을 갖지 않으므로 그런 두 볼륨은 자명하게 합의하며, 어떤 경우에도 서로 만날 수 없습니다(볼륨 이름이 도출되는 방식 참조).
주의해야 할 것은 작성된 volumes: 항목입니다. 이 항목은 driver, driver_opts, labels 같은 자체 본문을 가질 수 있기 때문입니다. 두 기여자가 하나의 이름을 서로 다른 본문으로 선언하면 빌드는 TRANSLATION_ERROR로 중단되며, 볼륨과 기여하는 모든 (boundary, node, fragment) 튜플을 명시합니다. 하나의 볼륨에 대해 두 작성자가 의견이 다르면 어셈블러가 선택할 수 있는 답이 없습니다. 어느 본문을 유지하든 그렇지 않았다면 성공했을 빌드에서 다른 작성자가 쓴 내용을 버리게 됩니다. 두 작성자가 같은 볼륨을 의도했다면 두 선언을 동일하게 만들고, 두 개를 의도했다면 하나의 이름을 바꿔 해결합니다. 최상위 네트워크는 고유한 aggrega.ai/namespace 어노테이션마다 하나씩이고, 여기에 어노테이션이 없는 노드를 위해 compose 파일 경로로 이름 붙은 네트워크 하나가 더해지며, 네트워크 이름이 도출되는 방식에 따라 이름이 지정됩니다. 같은 aggrega.ai/namespace 어노테이션을 가진 두 기여 경계는 둘이 공유하는 단일 네트워크로 병합되며, 파일을 공유하는 어노테이션 없는 두 경계도 마찬가지입니다.
프래그먼트가 작성하는 모든 키는 전달되거나 거부됩니다
프래그먼트, 즉 오버레이가 병합된 후의 소스 compose 파일 또는 compose YAML로 평가되는 artifacts: 본문은 provider가 전달하는 키를 통해서만 조립된 docker-compose.yaml에 도달하며, 그 키 집합은 고정되어 있습니다. 프래그먼트가 작성하는 각 키는 작성된 그대로 조립된 파일에 전달되거나 이름이 명시되어 거부됩니다. 아무 말 없이 빠지는 키는 없습니다. 프래그먼트는 하나의 compose 파일이므로 하나의 YAML 문서입니다.
- 전달되는 것. 최상위에서는
services,volumes,configs,models. 서비스에서는image,pull_policy,command,entrypoint,environment,env_file,ports,labels,volumes,tmpfs,networks,network_mode,depends_on,healthcheck,restart,user,working_dir,privileged,read_only,cap_add,cap_drop,configs,models,deploy,stop_grace_period,dns,dns_search,extra_hosts,profiles. provider가 기술하는 블록 안에서는deploy.resources와 그limits(cpus,memory) 및reservations(cpus,memory,devices, 각 장치 항목의driver,count,device_ids,capabilities,options),healthcheck의test,interval,timeout,retries,start_period, 긴 형식volumes:항목의type,source,target,read_only,volume.subpath, 긴 형식configs:항목의source와target, 긴 형식depends_on:항목의condition, 최상위 볼륨의driver,driver_opts,labels, 최상위 config의content. 모델의 본문과 서비스의 긴 형식models:항목은 모델에서 설명하는 대로 모든 멤버를 전달합니다. 확장 멤버, 즉x-로 시작하는 키는 확장 멤버에서 설명하는 대로 최상위와 서비스에서 전달됩니다. - 거부되는 것. 그 밖의 모든 키, 즉 서비스의
stdin_open, 최상위secrets:또는name:,deploy.replicas, 긴 형식depends_on:항목 안의restart:또는required:, 최상위 볼륨 본문이나healthcheck안의x-키는TRANSLATION_ERROR로 빌드를 중단시키며, 그러한 모든 키와 프래그먼트 안의 경로(services.migrate.stdin_open), 프래그먼트, 컴포넌트를 명시하고, 그러한 키가 나오는 두 곳을 알려 줍니다. 하나는 프래그먼트 자체이며, 해결 방법은 거기서 키를 제거하는 것입니다. 다른 하나는valuesMapping:을 선언하지 않은 소스 Recipe입니다. 이 경우 노드의 값이 그대로 compose 파일 위에 놓이므로 각 값 키가 프래그먼트의 최상위 키로 도착하며, 해결 방법은 각 값을 provider가 전달하는 키 아래에 두는valuesMapping:을 선언하는 것입니다. YAML 병합 키(<<: *anchor)가 블록에 가져오는 키는 거기에 작성된 것처럼 놓이는 위치에서 판단됩니다. 소스에서 렌더링된 프래그먼트의 이름은<component>.compose-fragment.yaml이며,artifacts:프래그먼트는 Recipe가 붙인 이름으로 표시됩니다. - 전체가 거부되는 것: 프래그먼트 자체의 네트워크. 프래그먼트의 최상위
networks:아래 항목은 본문에 무엇이 있든, 즉 빈 항목이든driver든 그 밖의 무엇이든TRANSLATION_ERROR로 빌드를 중단시키며, 항목(networks.back), 프래그먼트, 컴포넌트를 명시합니다. 조립된 파일에는 provider가 도출하는 네트워크만 들어가기 때문입니다(서비스가 참여하는 네트워크 참조). 항목을 제거하십시오. 서비스는 아무것도 선언하지 않아도 자신의 컴포넌트 네트워크에 참여하고, 컴포넌트가 어느 네트워크에 참여할지는aggrega.ai/namespace어노테이션이 선택하며, 서비스는 추가로 참여할 네트워크의 컴포넌트를x-aggrega-networks-of아래에 지정하고, 서로 다른 네트워크에 있는 서비스 간의 라우팅은compose-bridgeFeature가 담당합니다. 빈networks: {}는 아무것도 선언하지 않으므로 거부되지 않으며, 서비스 자체의networks:목록은 위와 같이 전달됩니다. - 전체가 거부되는 것: 둘 이상의 문서로 된 프래그먼트.
---로 구분된 두 개 이상의 YAML 문서를 담은artifacts:본문은TRANSLATION_ERROR로 빌드를 중단시키며, 프래그먼트, 컴포넌트, 담긴 문서 수를 명시합니다. 병합은 프래그먼트를 하나의 compose 파일로 읽으므로, 그렇지 않으면 첫 번째 이후의 모든 문서가 조립된 파일에서 빠지게 되기 때문입니다. 프래그먼트를 하나의 문서로 작성하거나 각 문서에 자체artifacts:항목을 부여하십시오. 아무것도 담지 않은 문서, 즉 끝에 붙은---가 여는 빈 문서는 세지 않습니다. 여러 문서로 된 소스 compose 파일은 결코 그러한 프래그먼트가 되지 않으며, 파일을 읽을 때 거부됩니다.
provider는 어떤 키의 의미도 읽지 않습니다. 키는 위의 집합에 있기 때문에 전달되고, 없기 때문에 거부됩니다.
확장 멤버는 작성된 그대로 전달됩니다
Compose Specification은 x-로 시작하는 키를 확장용으로 예약합니다. 이는 파일을 읽는 도구가 사용할 수 있고 Compose 자체는 무시하는 데이터입니다. 프래그먼트의 최상위와 서비스에 있는 확장 멤버는 provider가 해당 수준에서 모델링하는 모든 키 뒤에, 프래그먼트가 담고 있는 순서대로, 작성된 그대로 어셈블된 파일에 도달합니다. provider는 그 안의 어떤 것도 읽지 않으며, 예외는 서비스의 x-aggrega-networks-of뿐입니다. provider는 이를 서비스가 참여하는 네트워크로 해석하고 어셈블된 파일에서는 제외합니다(다른 컴포넌트의 네트워크에 참여하기 참조). artifacts: 본문은 작성한 순서대로 이를 담습니다. 소스로 지정된 compose 파일의 키는 오버레이가 병합된 뒤 이름 순서로 프래그먼트에 도달하므로, 그 확장 멤버는 이름 순서로 기록됩니다.
# an artifacts: bodyx-owner: team-bservices: migrate: image: example/migrate:1 x-schedule: manualYAML 별칭을 통해 도달한 멤버는 전체가 풀어서 기록되며 앵커는 전달되지 않으므로, 어셈블된 파일에는 앵커가 없는 별칭이 결코 남지 않습니다. 이 덕분에 최상위 멤버가 서비스의 병합 키(<<: *base)가 가져오는 앵커를 담을 수 있습니다. 서비스의 멤버는 해당 서비스와 함께 이동합니다. 최상위 멤버는 볼륨과 같은 규칙에 따라 어셈블리 경로 안에서 합집합으로 모입니다. 두 프래그먼트가 같은 내용으로 하나의 멤버를 작성하면 블록 스타일이든 플로 스타일이든 단일 항목이 남고, 서로 다른 내용으로 작성하면 빌드가 TRANSLATION_ERROR로 중단되며 해당 멤버와 기여하는 모든 (boundary, node, fragment) 튜플을 명시합니다. 한 컴포넌트의 두 프래그먼트도 포함됩니다. 두 선언을 동일하게 만들거나 그중 하나에 다른 이름을 지정하십시오.
profiles는 서비스를 Compose 프로필 뒤에 둡니다. profiles:를 나열하는 서비스는 프로필 중 하나가 활성화되지 않는 한 docker compose up이 시작하지 않으며, docker compose run --rm <service>가 요청 시 시작합니다. 이는 필요할 때 실행하는 작업의 compose 형태입니다. 목록은 프래그먼트가 작성한 그대로, 그 순서대로 전달됩니다.
# a sourced compose fileservices: migrate: image: example/migrate:1 profiles: [manual]모델
compose 파일의 최상위 models: 섹션은 파일의 서비스가 사용하는 AI 모델을 선언하며, 서비스는 자체 models: 항목을 통해 모델을 부여받습니다. provider는 프래그먼트가 소스 compose 파일이든 compose YAML로 평가되는 artifacts: 본문이든, 두 가지 모두를 Compose 고유의 표기 그대로 프래그먼트에서 어셈블된 docker-compose.yaml로 옮깁니다. Workload는 모델을 선언하지 않으므로 Workload 모드 Recipe는 모델을 기여하지 않습니다.
- 모델의 본문은 프래그먼트가 작성한 그대로 기록됩니다.
model(모델의 OCI 아티팩트 식별자),context_size,runtime_flags는 이름을 유지하며,x-확장을 포함한 그 밖의 모든 멤버는 그 옆에 함께 옮겨집니다. 모델 안에서는 이 세 명명된 멤버가 먼저 오고 나머지는 키 순서로 이어지며, 모델들은 이름 순서로 기록되므로 동일한 입력은 바이트 단위로 동일한 파일을 생성합니다. provider는 본문을 전혀 읽지 않습니다. 식별자를 검사하지 않으며, 무엇이 모델을 서빙할지에 대해서도 알지 못합니다. - 서비스의 참조는 형식을 유지합니다. 짧은 형식은 모델 이름을 나열하고(
models: [llm]), 긴 형식은 각 모델을endpoint_var와model_var에 매핑합니다. 이들은 모델 러너의 주소와 모델의 식별자를 받는 변수의 이름입니다. 어느 형식이든 프래그먼트가 사용한 형식과 순서대로 기록되며, 해당 서비스와 함께 이동합니다. 긴 형식에서 변수 이름을 지정하지 않으면 Compose가 파일을 실행할 때 이름을 지정합니다. - 모델은 볼륨과 같은 규칙에 따라 어셈블리 경로 안에서 합집합으로 모입니다. 두 기여자가 하나의 모델 이름을 동일하게 출력되는 본문으로 선언하면 그 이름 아래에 단일 항목이 남습니다. 서로 다른 본문으로 선언하면 빌드는
TRANSLATION_ERROR로 중단되며, 모델과 기여하는 모든(boundary, node, fragment)튜플을 명시합니다. 한 컴포넌트의 두 프래그먼트도 여기서는 두 기여자입니다. 두 기여자가 하나의 모델을 의도했다면 선언을 동일하게 만들고, 그렇지 않다면 하나에 다른 이름을 지정합니다. - 모든 참조는 선언된 모델을 가리킵니다. 어셈블리 경로의 프래그먼트가 합집합으로 모인 뒤, 해당 경로의 어떤 기여자도 선언하지 않은 모델을 부여받은 서비스가 있으면 빌드는
TRANSLATION_ERROR로 중단되며, 서비스와 모델을 명시합니다. 검사는 완성된 합집합을 대상으로 실행되므로, 한 컴포넌트가 같은 어셈블리 경로의 다른 컴포넌트가 선언한 모델을 자신의 서비스에 부여할 수 있습니다. omits:항목으로는 모델을 제외할 수 없습니다. 이 provider가 허용하는 종류는service,volume,config이며, 모델을 지정하는 항목은 다른 종류를 지정하는 항목과 마찬가지로 빌드를 중단시킵니다.
모델은 파일이 빌드될 때가 아니라 실행될 때 서빙됩니다. Docker Model Runner처럼 Compose 모델을 지원하는 플랫폼에서 Docker Compose 2.38 이상은 서비스가 부여받은 각 모델을 풀하고 실행하며, --all-resources로 시작하지 않는 한 그 밖의 모델은 제외합니다. 또한 모델을 부여받은 각 서비스에서 해당 참조가 지정한 변수를 모델 러너의 주소와 모델의 식별자로 설정합니다. 빌드는 파일을 실행할 호스트를 볼 수 없으므로 Compose 버전도 플랫폼도 검사하지 않습니다. 모델을 담은 파일은 무엇이 실행하든 같은 방식으로 어셈블됩니다.
컴포넌트에 연결된 Feature는 같은 파일에 기여합니다
컴포넌트에 연결된 Feature는 호스트 컴포넌트가 어셈블되는 docker-compose.yaml에 호스트 자체의 Recipe와 같은 조건으로 자신의 서비스를 기여합니다. 그 옆에 두 번째 파일은 없습니다. 하나의 어셈블리 경로는 하나의 문서를 생성하므로, 연결된 Feature의 서비스는 그 문서 안에 있거나 아예 배포되지 않습니다. Feature를 분리하면 정확히 그 서비스들만 제거되고 호스트 컴포넌트 자체의 서비스는 그대로 유지됩니다.
이 서비스들은 다른 기여자와 마찬가지로 해당 어셈블리 경로의 기여자이므로, 위의 모든 내용이 변경 없이 적용됩니다. 서비스 이름 규칙, 그리고 하나의 최상위 볼륨 또는 config 이름을 선언하는 두 기여자가 그것이 무엇인지에 대해 합의해야 한다는 요구 사항이 그렇습니다. 또한 경계의 나머지와 같은 네트워크에 참여하므로, 컴포넌트와 그에 연결된 Feature는 추가로 선언할 것 없이 서비스 이름으로 서로에게 도달합니다.
Feature가 기여하는 각 서비스는 호스트 컴포넌트의 아이덴티티가 아니라 해당 연결을 위해 구성된 아이덴티티를 가지므로, 둘이 함께 기여한 문서 안에서도 서로 구별됩니다. 그 아이덴티티가 구성되는 방식은 레이블과 어노테이션에서 다룹니다.
이는 Workload의 컨테이너 수준 attachments: 블록과는 다른 메커니즘이며, 같은 단어를 공유하기 때문에 둘을 하나로 오해하기 쉽습니다. Feature를 컴포넌트에 연결하면 어셈블된 문서에 서비스가 추가됩니다. 컨테이너의 attachments: 항목은 슬롯이 해당 컨테이너 하나에 게시한 자격 증명을 읽으며, 컨테이너 필드에서 다룹니다.
Artifacts가 생성한 compose 프래그먼트
Recipe의 artifacts: 블록이 compose YAML로 평가될 때, 즉 자체 services:, volumes:, configs:, models: 또는 networks: 블록(각 항목은 인라인이거나 항목별로 $import:로 로드됨)을 가진 프래그먼트일 때, (path, provider)별 어셈블리로의 병합은 형태별 규칙을 따릅니다.
- artifacts의
services:는 컴포넌트별 서비스와 함께 어셈블된 compose 파일에 병합됩니다. 같은 어셈블리 경로에서 서로 다른 두 컴포넌트가 기여한 서비스 이름은 빌드를 중단시키며, 진단은 모든 기여자를 명시합니다. 단일 컴포넌트 내부의 충돌, 즉 해당 컴포넌트 자체의 artifact 프래그먼트와 그 컴포넌트를 위해 합성된 서비스 사이의 충돌은 감지되지 않고 나중의 기여가 앞의 기여를 대체합니다. 따라서 artifact에서 작성한 서비스 이름은 합성기가 생성하는<component>및<component>--<container-name>이름과 구별되게 유지하십시오(사이드카 또는 init 서비스의 이름이 정해지는 방식 참조). - artifacts의
volumes:는 최상위volumes:블록에 병합됩니다. 하나의 이름에 도달한 두 항목은 동일하게 선언한 경우 그 이름 아래 단일 항목을 남기며, 이는 컴포넌트별 볼륨과 같은 규칙입니다. 다르게 선언한 두 항목은 빌드를 중단시키며, 이는 두 항목이 두 컴포넌트에서 왔든 한 컴포넌트의 두 프래그먼트(그 컴포넌트의artifacts:항목 두 개, 또는 그중 하나와 컴포넌트 자체의 compose 파일)에서 왔든 마찬가지입니다. artifact 프래그먼트는 자체 본문을 작성하므로, 이 경로에서 두 기여자가 일치하지 않을 가능성이 가장 높습니다. artifact에서 작성한 볼륨 이름은 해당 어셈블리 경로의 다른 이름들과, 파생 과정이 생성하는<component>--<volume-name>형태와도 구별되게 유지하십시오. 단, 두 기여자가 하나의 공유 볼륨을 기술하려는 경우에는 선언이 일치해야 합니다. - artifacts의
configs:는 최상위configs:블록에 병합됩니다.configmap볼륨 뒤의 파일은 이 방식으로 어셈블리에 도달합니다. 볼륨은 configmap을 명시하는 서비스 수준configs:참조가 되고, artifact 프래그먼트는 인라인content:와 함께 그 이름의 항목을 선언합니다. 어셈블리 경로의 프래그먼트가 합쳐지면 모든 서비스 수준 참조는 선언된 항목으로 해석되어야 하며, 그렇지 않으면 빌드는 해석되지 않은 각 참조(서비스, config 이름, 마운트 경로)를 명시하는TRANSLATION_ERROR와 함께 중단됩니다. 이 검사는 컴포넌트별이 아니라 완성된 합집합에 대해 실행되므로, 한 컴포넌트는 같은 어셈블리 경로의 다른 컴포넌트가 선언한 config를 참조할 수 있습니다. 합집합은 기여자가 일치하는 경우 이름으로 조정됩니다. 동일한content:로 하나의 config 이름을 선언한 두 기여자는 둘 다 기술한 단일 항목을 남깁니다. 서로 다른content:로 하나의 이름을 선언한 두 기여자는 config와 기여한 모든(boundary, node, fragment)튜플(한 컴포넌트의 두 프래그먼트 포함)을 명시하며TRANSLATION_ERROR로 빌드를 중단시킵니다. config 항목은 항상 내용을 가지므로 어느 한 선언을 유지하면 작성자가 작성한 파일이 버려지기 때문입니다. config 이름은 해당 어셈블리 경로의 모든 기여자에 걸쳐 구별되게 유지하거나, 두 기여자가 하나의 공유 파일을 전달하려는 경우 선언을 동일하게 만드십시오. - artifacts의
models:는 최상위models:블록에 병합되며, 서비스의models:참조는 Models의 규칙에 따라 해당 서비스와 함께 이동합니다. 하나의 모델 이름을 선언하는 두 기여자는 동일하게 선언해야 하며, 모든 참조는 어셈블리 경로의 어떤 기여자가 선언한 모델을 명시해야 합니다. - artifacts의
networks:는 거부됩니다. compose provider는 경계 어노테이션에서 네트워크를 파생합니다(서로 다른aggrega.ai/namespace어노테이션마다 네트워크 하나, 그리고 어노테이션이 없는 모든 노드가 참여하는, compose 파일의 경로를 따라 이름 붙인 네트워크 하나이며, 각각 네트워크 이름이 파생되는 방식에 따라 이름이 지어집니다). 따라서 artifact가 제공하는 네트워크 선언은 어셈블된 파일에 자리가 없습니다. 어떤 항목이든 프래그먼트가 작성하는 모든 키는 전달되거나 거부됩니다의 규칙에 따라 항목과 프래그먼트를 명시하며 빌드를 중단시킵니다. 항목을 제거하고aggrega.ai/namespace어노테이션으로 네트워크를 구성하거나,x-aggrega-networks-of를 통해 서비스가 지정한 컴포넌트의 네트워크에 참여하도록 하십시오. 단일 compose 파일 안에서 네트워크 간 라우팅이 필요한 작성자는compose-bridgeFeature를 사용합니다. - artifacts의 확장 멤버는 전달됩니다. 최상위
x-키는 확장 멤버는 작성된 그대로 전달됩니다의 규칙에 따라 어셈블된 파일의 다른 섹션 뒤에 작성된 순서대로 기록됩니다. - artifacts의 다른 모든 최상위 키는 빌드를 중단시킵니다.
services:,volumes:,configs:,models:와 확장 멤버가 어셈블러가 프래그먼트에서 가져가는 전부입니다.secrets:블록과 최상위name:은 프래그먼트가 작성하는 모든 키는 전달되거나 거부됩니다의 규칙에 따라 각각 키와 프래그먼트를 명시하며 빌드를 중단시킵니다. artifacts:본문은 하나의 문서입니다. 여러 YAML 문서를 담은 본문은 프래그먼트와 그 안의 문서 수를 명시하며 빌드를 중단시킵니다. 각 문서에 별도의artifacts:항목을 지정하십시오.
앞의 네 블록과 networks: 사이의 비대칭은 구조적입니다. services:, volumes:, configs:, models:는 어셈블러가 어셈블된 파일에 누적하는 Recipe별 내용을 담고, networks:는 어셈블러가 경계 상태에서 파생하는 경계별 인프라입니다. Artifacts는 전자를 확장할 수 있지만 후자는 경계 어노테이션만 형성할 수 있으며, 그래서 artifact 자체의 네트워크 항목은 거부됩니다. 확장 멤버는 Compose Specification이 다른 도구를 위해 정의한 데이터이므로 작성된 그대로 전달됩니다. 그 밖의 모든 것은 어셈블된 문서에 자리가 없는 형태이며, 그래서 병합되지 않고 거부됩니다.
compose provider가 제공하지 않는 것
- 하나의 compose 파일 내 네트워크 간 L4 라우팅. provider는 각 노드를 해당 네트워크에 배치하고 서비스를
x-aggrega-networks-of가 지정하는 네트워크에 참여시키지만, 네트워크 사이의 라우팅은 직접 전혀 수행하지 않습니다. 네트워크 A의 서비스가 docker-compose의 기본 DNS 이외의 방법으로 네트워크 B의 서비스에 도달하려면compose-bridgeFeature가 필요하며, 그 FeatureRecipe가 게이트웨이와 재작성을 작성합니다. - compose 파일 간 라우팅. 서로 다른 어셈블리 경로로 평가되는 경계는 서로 다른
docker-compose.yaml파일을 생성하며, compose 런타임은 이를 독립된 프로젝트로 취급하고,compose-bridgeFeature도 두 파일 사이의 연결을 작성된 그대로 둡니다. 파일 간 통신은 운영자가 담당합니다(호스트 포트 공개, 외부 네트워크 공유, 또는 공유directory:를 통해 경계를 하나의 경로로 합치기). - attachment에서 환경 변수 가져오기. Compose에는 이를 위한 기본 요소가 없으므로,
as: env인 Workloadattachments항목은 런타임에 해석되는 참조 대신 빈 값을 가진 변수 이름을 출력합니다. 이 자리 표시자는 의도된 것입니다. 존재하지만 비어 있는 변수는 컨테이너를 디버깅하는 사람에게 보이지만, 없는 변수는 살펴볼 것을 아무것도 남기지 않습니다. 또한 빌드는 이를 나중에 발견하도록 두지 않고 직접 알립니다. 이러한 각 항목은 작성된 좌표(containers.<name>.attachments.<KEY>또는initContainers[<i>].attachments.<KEY>)로 항목을 지목하는unsupported-field경고를 발생시키므로, 작성자는 어떤 변수가 비어 있는 채로 도착하고 그것이 어느 컨테이너에 속하는지 알 수 있습니다. 이 경고는 권고 사항입니다. 빌드는 성공하며, 렌더링된 파일은 경고가 없을 때와 바이트 단위로 동일합니다.--no-unsupported-field-warnings는 이 경고 부류를 억제합니다.as: file인attachments항목은 영향을 받지 않습니다. compose가 이를 바인드 마운트하며 경고는 발생하지 않습니다. - Swarm 모드
deploy:내용.deploy:아래의 레플리카, 배치 제약 조건, 업데이트 전략은 swarm 모드 기능이며, compose provider는 단일 호스트 compose만 대상으로 하므로 이들 중 어느 것도 출력하지 않습니다. 단,deploy.resources는 출력합니다. 이는 컨테이너의resources가 매핑되는 예약 및 제한으로, docker compose가 non-swarm 모드에서도 준수합니다(컨테이너 리소스 참조). uses엣지에서 비롯된 상태 조건 기반depends_on.uses엣지에서 파생된 의존성은service_started의미론으로, 조건 없이 출력됩니다. 대상의 healthcheck가 정상으로 보고되는 것을 조건으로 하지 않습니다. 이는uses엣지가 무엇을 의미하는가의 문제이지, provider가 생성할 수 없는 형태의 문제가 아닙니다. 긴 형식은 init 컨테이너 대기에 대해 출력되며, 배포 웨이브는 대상이 healthcheck를 선언한 경우 대상의 상태를 조건으로 삼습니다.
작성 예시
uses에서 도출된 depends_on 엣지가 있는 두 서비스 compose 배포:
# release.yaml fragmentspec: boundaries: production: annotations: aggrega.ai/namespace: prod components: api: {} db: {}# api RecipeapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api version: 1.0.0spec: capability: compose implements: example/compute/api:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: api:1.0 ports: http: 8080 health: live: http: /healthz services: public: type: NodePort ports: http: 8080# Aggregate fragment — api uses db, on a socket api's Component declaresapiVersion: aggrega.ai/v1beta1kind: Aggregatespec: components: api: type: example/compute/api:1.0.0 uses: backend: db: target: db db: type: example/datastore/db:1.0.0compose provider는 경계의 평가된 경로(경계의 directory: 기본값이 dist/boundaries/<name>이고 subDirectory:의 기본값이 {{ .capability }}이므로 기본값은 dist/boundaries/production/compose/docker-compose.yaml)에 다음을 포함하는 docker-compose.yaml 하나를 생성합니다:
services.api(메인 api 서비스, 네트워크prod, 포트8080:8080,curl을 통한 healthcheck,depends_on: [db])services.db(메인 db 서비스, 네트워크prod)networks.prod(경계의 docker 네트워크)
관련 참조 문서
- Workload 엔터티 — compose 프로바이더가 변환하는, 플랫폼이 소유하는 Workload 종류입니다.
- Provider 아키텍처 — 프로바이더가 컴파일 파이프라인에 어떻게 들어맞는지 설명합니다.
- 잘 알려진 어노테이션 — compose 프로바이더가 사용하는
aggrega.ai/*어노테이션입니다. - Provider 참조 색인 — 각 표준 라이브러리 프로바이더가 무엇을 생성하는지, 그리고 어떤 페이지가 어떤 질문에 답하는지 설명합니다.
- Recipe 입력 구성 — 정식 Provider 기능 매트릭스입니다.