Compose Provider
Провайдер compose преобразует сущности Aggrega Recipes в файл Docker Compose. Провайдер выполняет сборку по (path, provider): участники compose каждой границы направляются в сборщик, ключом которого служит вычисленное значение directory: границы, объединённое со значением subDirectory: для каждого компонента, и этот сборщик выдаёт один файл docker-compose.yaml, содержащий всех участников по этому пути. Две соседние границы, которые вычисляются в один и тот же путь, сводятся в один объединённый файл compose; канонический пример — родительская граница и две дочерние границы с directory: "{{ .parent_boundary.directory }}" (шаблон compose-bridge).
Поддерживаемые виды входных данных
Провайдер compose принимает все три вида входных данных Recipe:
- Режим с источником. Recipe с
source:, указывающим на существующий файл compose, иvaluesMapping:, создающим документ наложения. Базовый файл compose загружается, наложение вычисляется, и оба документа глубоко сливаются по собственной семантике наложения docker-compose. - Режим Workload. Recipe с
workload:(встроенным или загруженным через$import:) объявляет документWorkload. Провайдер синтезирует один или несколько сервисов compose из спецификации Workload. - Режим артефактов. Записи
artifacts:сущности Recipe вычисляются во фрагменты compose, которые сливаются в собранный файл по правилам из раздела Фрагменты compose, создаваемые артефактами. Артефакты могут сопровождать источник или Workload, а могут составлять и весь вывод Recipe: Recipe, объявляющийartifacts:и не объявляющий ниsource:, ниworkload:, рендерится здесь и вносит всё, что объявляют его фрагменты. Так компонент, состоящий только из ресурсов — общего набора сетей и томов, начальной конфигурации, — попадает в развёртывание compose без Workload-заглушки, изображающей вычислительную часть, которой у него нет.
Три вида сочетаются путём сложения, а Recipe, не объявляющий ни одного из них, отклоняется при загрузке. valuesMapping: без source: рядом с ним тоже отклоняется при загрузке Recipe, какой бы провайдер он ни называл: наложение не к чему применить, и диагностика предлагает вам объявить указатель source: или удалить valuesMapping:.
Сопоставление возможностей Workload
Когда Recipe объявляет workload:, провайдер переводит принадлежащую платформе форму 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 (в форме списка): оно задаёт аргументы, которые получает точка входа, а именно их переопределяет command в compose |
variables | environment (в форме словаря) |
attachments[as: env] | запись environment с пустым значением и предупреждение с именем записи (см. Что провайдер compose не обеспечивает) |
attachments[as: file] | длинная форма bind-монтирования в volumes, только для чтения |
volumeMounts | примитив compose, в который отображается вариант указанного тома: запись длинной формы в volumes, запись tmpfs: уровня сервиса или ссылка configs: уровня сервиса (см. Тома) |
ports | неявно (контейнеры compose открывают порты, которые слушает образ) |
restartPolicy: Always | restart: unless-stopped |
restartPolicy: OnFailure | restart: on-failure |
restartPolicy: Never | restart: "no" |
variables и attachments[as: env] попадают в один словарь environment: сначала записи вложений, затем variables, каждые в порядке написания — в том же порядке, в каком пишет провайдер helm, так что один Workload даёт одну последовательность переменных окружения на любой цели. Compose не раскрывает ссылки $(NAME) между записями окружения сервиса, поэтому в compose этот порядок не имеет значения во время выполнения. Поскольку словарь содержит каждое имя один раз, контейнер, задающий одно имя и как запись variables, и как запись attachments, доставляемую as: env, останавливает сборку, а не сохраняет одно из двух значений (см. A container gives one environment variable two values (Контейнер задаёт одной переменной окружения два значения)).
Ресурсы контейнера
resources контейнера попадают в блок deploy.resources в compose, который docker compose учитывает в режиме без swarm. requests в Kubernetes выражают гарантированный минимум, поэтому становятся reservations в compose; limits выражают жёсткий предел, поэтому остаются limits.
| Поле Workload | Поле Compose | Преобразование |
|---|---|---|
resources.requests.cpu | deploy.resources.reservations.cpus | Десятичное число ядер. Число ядер, записанное просто числом (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 | То же преобразование |
nvidia.com/gpu в resources.limits, resources.requests или в обоих | deploy.resources.reservations.devices | Одна запись устройства NVIDIA в сервисе контейнера: driver: nvidia, count: — число GPU, capabilities: [gpu]. Число берётся из лимита, если лимит задан (это число Kubernetes планирует для расширенного ресурса), иначе из запроса. Число 0 не запрашивает GPU и не создаёт записи |
любой другой ключ расширенного ресурса: amd.com/gpu и любой другой <domain>/<name> | — | Аналога в однохостовом compose нет. Ключ отбрасывается, и сборка выдаёт предупреждение unsupported-field с его именем — одно на каждый отдельный ключ, сколько бы requests и limits его ни содержали. Его значение не выводится, поэтому и не проверяется |
Каждое значение cpu, memory и nvidia.com/gpu читается как количество в форме, описанной в Workload → Количества ресурсов, из Workload в том виде, в каком его вычислили шаблоны Recipe. Сборку с TRANSLATION_ERROR останавливают два случая, и ошибка сообщает, какой из них встретился, называя путь контейнера, является ли значение запросом или лимитом, ресурс и значение:
- значение, не являющееся количеством:
lots,1.5 coresилиm, которое пустой шаблон оставляет в"{{ .infra.cpu }}m"; - количество, которое compose не может представить точно: отрицательная величина; объём памяти, не равный целому числу байтов (
1500m,4u) или превышающий 9223372036854775807 байтов (8Ei); объём cpu точнее девяти знаков после запятой в долях ядра (самая высокая точность, которую хранит само количество Kubernetes) или больше 9223372036.854775807 ядер; число GPU, не равное целому числу устройств (0.5,500m).
Контейнер, у которого запрос и лимит nvidia.com/gpu задают разные числа, останавливается так же, с указанием обоих путей: compose резервирует для сервиса одно число, и иначе преобразованию пришлось бы выбирать одно из них. Укажите одинаковое число в обоих или только лимит.
Ничего не округляется, и не выводится никакое значение, означающее что-то другое.
Запрос GPU резервирует GPU NVIDIA. Контейнер Workload, запрашивающий nvidia.com/gpu: "1", даёт сервис с таким резервированием наряду с любыми cpus и memory, которые резервируют его запросы:
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpuDocker Compose передаёт зарезервированные GPU контейнеру, если на хосте Docker есть столько GPU NVIDIA и он настроен отдавать их контейнерам; сборка не видит хост, поэтому файл с резервированием GPU собирается одинаково, где бы он ни запускался. Запись всегда указывает число, потому что Compose читает запись устройства без числа как все GPU на хосте. Преобразуется только ключ NVIDIA: amd.com/gpu и ключи всех других производителей сохраняют предупреждение из строки об отбрасываемых ключах. Строка runtimeClassName в Поля уровня пода не меняется: в compose нет аналога runtime class, поэтому Workload, указывающему среду выполнения с поддержкой GPU, сообщается, что среда выполнения опущена, а число GPU резервируется.
Пробы
Три слота проб сущности Workload (live, ready, startup) сводятся к единственному healthcheck на сервис в compose с приоритетом live > ready > startup (побеждает наиболее канонический сигнал живости). Если при этом отбрасывается слот, объявленный автором, сборка выдаёт предупреждение unsupported-field с именем преобразованного слота и отброшенных слотов, так что намерение, не попавшее в вывод, сообщается, а не теряется. Блок health с одним слотом преобразуется без потерь и ничего не выдаёт, если только слот не задаёт successThreshold: у healthcheck в compose нет для него поля, поэтому заданное автором значение — включая 1 — опускается с предупреждением unsupported-field, называющим его (containers.<name>.health.<slot>.successThreshold), а остальная часть слота преобразуется так, как показано в таблице ниже.
| Форма пробы Workload | healthcheck.test в Compose |
|---|---|
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-форма требует, чтобы контейнер объявлял хотя бы один именованный порт; синтезатор выбирает первое по алфавиту имя порта и использует его номер для построения URL curl. Контейнеры без объявленных портов не могут использовать HTTP-пробы: компилятор останавливается с TRANSLATION_ERROR, называя проблемную пробу.
Поля таймаутов проб отображаются в строки длительности в стиле compose:
| Поле Workload | Поле healthcheck в Compose |
|---|---|
periodSeconds | interval: <n>s |
timeoutSeconds | timeout: <n>s |
failureThreshold | retries: <n> |
initialDelaySeconds | start_period: <n>s |
Тома
В Compose есть собственный примитив конфигурации, в который и транслируется том configmap. Эквивалента Kubernetes для Secret или шаблонов томов на реплику в нём нет, поэтому эти варианты деградируют до ближайшего примитива compose:
| Вариант тома Workload | Трансляция в Compose | Что теряется |
|---|---|---|
ephemeral | запись списка tmpfs: на уровне сервиса | sizeLimit не сохраняется (в краткой форме tmpfs в compose нет размера). Заданный sizeLimit вызывает предупреждение unsupported-field, называющее его по координате, где он задан (volumes.<name>.ephemeral.sizeLimit), независимо от того, монтирует ли том какой-либо контейнер; если поле не задано, ничего не выводится |
configmap | ссылка configs: на уровне сервиса, называющая configmap и смонтированная по пути монтирования тома | 🔴 Путь монтирования — это путь к одному файлу, а не к каталогу. Compose записывает содержимое конфигурации ровно по целевому пути, тогда как цель Kubernetes, монтирующая ConfigMap по пути, создаёт каталог с одним файлом на каждый ключ. Поэтому один и тот же заданный path: здесь обозначает файл, а там — каталог: направляйте монтирование тома configmap на имя файла, которое должен читать контейнер (/seed/config.json), а не на содержащий его каталог; Recipe, написанный для обеих целей, содержит разный путь для каждой цели. Ничто в сборке не может обнаружить путь, написанный под форму другой цели: путь — непрозрачная строка, которую компилятор передаёт без изменений, а выходные данные корректны в любом случае. Ссылка выполняется по имени, точно так же, как цель Kubernetes ссылается на ресурс ConfigMap, — содержимое конфигурации никто не читает. Соответствующая запись configs: верхнего уровня берётся из входных данных artifacts: сущности Recipe, фрагмент compose которых объявляет её со встроенным content:; ссылка без такой записи останавливает сборку (см. Фрагменты compose, создаваемые артефактами). Ссылка configs: содержит имя конфигурации и путь монтирования и больше ничего, поэтому у readOnly монтирования нет отдельного выражения |
secret | длинная форма bind-монтирования в volumes, только для чтения | Том секрета намеренно не следует трансляции configmap: встроенная запись configs: записала бы значение секрета в создаваемый файл compose открытым текстом, а компилятор никогда не разрешает секрет в открытый текст — секрет остаётся указателем на всех этапах сборки. Источником bind-монтирования служит имя source секрета, разрешаемое как путь, который оператор делает доступным на хосте compose независимо от сборки |
persistent | именованный том + объявление volumes: { <volume-name>: {} } верхнего уровня, имя которого строится согласно разделу Как строится имя тома | Класс хранилища, режимы доступа и размер не сохраняются (в compose нет эквивалентной структуры). Указанный class или accessModes вызывает предупреждение unsupported-field, называющее его по координате, где он указан (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes); если опустить любое из них, ничего не возникает. Обязательный size не вызывает предупреждения — см. ниже |
persistentTemplate | именованный том + объявление верхнего уровня, имя строится так же (как для persistent) | Дополнение к form: stateful; в compose нет примитива шаблонов томов на реплику, поэтому поведение на уровне реплик теряется, и предупреждение unsupported-field сообщает, что том стал одним томом, общим для всех реплик. Класс хранилища, режимы доступа и размер не сохраняются — точно так же, как для persistent: указанный class или accessModes вызывает предупреждение unsupported-field в volumes.<name>.persistentTemplate.class или volumes.<name>.persistentTemplate.accessModes, а обязательный size никакого предупреждения не вызывает |
Параметр subPath монтирования монтирует часть тома там, где у compose есть для этого форма. Запись volumeMounts, указывающая том persistent или persistentTemplate с subPath, становится записью volumes в полной форме с volume.subpath, поэтому монтирование видит указанный каталог или файл внутри тома, а не его корень, а два монтирования одного тома с двумя разными значениями 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: uploadsМонтирование, записанное без subPath, не содержит блока volume:. subPath на монтировании тома ephemeral, configmap или secret останавливает сборку с TRANSLATION_ERROR с указанием компонента, контейнера, заданного автором пути монтирования (containers.<name>.volumeMounts[<i>]), тома и subPath: эти варианты попадают в compose соответственно как запись tmpfs, ссылка configs: и bind-монтирование, ни одно из которых не монтирует часть того, что доставляет, поэтому иначе монтирование видело бы весь том. Удалите subPath из такого монтирования или смонтируйте том persistent. Docker Compose читает volume.subpath начиная с выпуска 2.26.0, на Docker Engine 26.0 или новее; сборка не видит хост, который будет запускать файл, поэтому файл, содержащий его, собирается одинаково, где бы он ни запускался.
Том указывает, какой это вариант, и ничего больше. У тома secret ровно одна трансляция — описанное выше bind-монтирование только для чтения, — и у тома нет поля as: для выбора другой. Передача того, что слот опубликовал, в виде переменной окружения — это запись attachments контейнера (as: env), а не том; что compose делает с такой записью, описано в разделе Что не предоставляет провайдер compose.
Размер хранилища содержат три варианта, и только один из них предупреждает, что размер отброшен. Разница в том, был ли у вас выбор. sizeLimit тома ephemeral необязателен, так что его указание было решением, и предупреждение сообщает, что на этой цели значение ни на что не влияет и его можно удалить: оно носит рекомендательный характер и выводится отдельно от результата, создаваемый файл побайтово такой же, каким был бы без него, а --no-unsupported-field-warnings отключает его вместе с остальным классом. size тома persistent или persistentTemplate обязателен, поэтому ни одна версия документа его не опускает: предупреждение при каждой сборке срабатывало бы на каждой stateful-нагрузке, не называя ничего, что вы могли бы изменить, поэтому разница объясняется здесь, а не сообщается при каждой сборке. При цели compose size, class и accessModes постоянного тома ни на что не влияют в создаваемом файле: вы получаете обычный именованный том, размер и хранилище которого определяются поведением драйвера томов хоста compose по умолчанию. class и accessModes необязательны, поэтому о каждом указанном вами поле сообщается так же, как о sizeLimit тома ephemeral: одно предупреждение unsupported-field на поле, рекомендательное и выводимое отдельно от результата, отключаемое тем же флагом. Задавайте размер нижележащего хранилища на хосте или на цели Kubernetes, где эти поля действительно попадают в результат.
Том, который не монтирует ни один контейнер, вызывает предупреждение unsupported-field, называющее его по координате, где он задан (volumes.<name>), потому что то, что попадает в создаваемый файл, в этом случае сильно зависит от варианта. persistent и persistentTemplate по-прежнему создают своё объявление верхнего уровня, поэтому том создаётся, но ничем не используется. У ephemeral, configmap и secret нет выражения вне самого монтирования — каждый транслируется во что-то, записываемое по пути монтирования: соответственно запись tmpfs, ссылку configs или bind-монтирование, — поэтому, если их ничто не монтирует, объявленный вами том вообще не оставляет следа в результате. Именно этот второй случай — причина существования предупреждения: без него том 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и шестизначная шестнадцатеричная кодовая точка символа, а байт, с которого не начинается ни один символ, — какbи его собственное двузначное значение, так что имя, не являющееся допустимым текстом, всё равно записывается различимо, а не схлопывается. - Пустое значение записывается как
-ze, чего не может дать ни одно непустое значение. - Две идентичности соединяются через
--. Отдельная закодированная идентичность никогда не содержит такой пары, поэтому соединённое имя однозначно показывает, где заканчивается одна идентичность и начинается другая.
Так, компонент store с томом, который Workload называет data, даёт имя тома store--data, а db-server с data даёт db-server--data. Одинаковые входные данные всегда дают одинаковое имя.
Однозначность пары обеспечивает именно двойной соединитель, а односимвольный соединитель её обеспечить не может. Любая идентичность сама может содержать дефис, поэтому соединение одним дефисом даёт имя, которое делится более чем в одном месте: db с томом data-cache и db-data с томом cache оба дали бы db-data-cache, а поскольку блок верхнего уровня объединяет записи по имени, два компонента разделили бы один том, и в итоговом файле ничто бы этого не показало. Закодированная идентичность никогда не содержит пары дефисов, поэтому двойной соединитель не допускает второго прочтения: они получают db--data-cache и db-data--cache.
Изменение любой из идентичностей переименовывает том compose, а compose не переименовывает том на месте. Том создаётся заново под новым именем, а старый остаётся вместе с данными, поэтому контейнер запускается с пустым хранилищем, а содержимое лежит в томе, который никто не монтирует. Переименовывайте любую из идентичностей только как планируемую замену — с резервной копией, переносом данных или по расписанию, — а не как изменение для развёртывания.
Форма контроллера
Поле form сущности Workload выбирает абстрактную форму контроллера (см. entities/workload.md). Compose отображает stateless и stateful (а также пустое значение по умолчанию, трактуемое как stateless) как долгоживущие сервисы; форма stateful добавляет именованный том для сопутствующего persistentTemplate. Формы daemon, scheduled и task не имеют чистого однохостового отображения в compose, поэтому Workload, объявляющий одну из них и нацеленный на границу compose, останавливается с TRANSLATION_ERROR, где указаны форма и поддерживаемый набор: compose не превращает неподдерживаемую форму в обычный сервис, искажающий замысел. Сущность Workload формы reference объявляет внешнюю конечную точку и не имеет контейнеров, поэтому compose не создаёт для неё сервиса.
Поскольку для сущности Workload типа reference не выводится ни один сервис, ничто не читает канал доставки компонента, который она реализует: учётные данные, присоединённые к этому компоненту, — доставляемые в его канал через dotenv-secret или собственным блоком inject: присоединения — не попали бы ни в один выводимый файл. Поэтому каждая сущность Recipe стандартной библиотеки для Compose, которая реализует внешний сервис таким образом и чья сущность Component объявляет слот учётных данных, отклоняет учётные данные, заполняющие этот слот: сборка останавливается с указанием слота и компонента, а не завершается успешно без учётных данных. В compose учётные данные для внешнего сервиса присоединяются к компоненту, который его вызывает, под переменной окружения, которую читает этот компонент. Это отклонение — собственное утверждение каждой сущности Recipe, и оно выполняется до того, как этот провайдер что-либо отрендерит. Этот провайдер также отклоняет на уровне самого узла, из какого бы каталога ни происходила сущность Recipe: присоединение на узле reference, материал которого объявлен чувствительным, — его сущность Feature объявляет поле как sensitive: true или так объявляет заполняемый им слот, — останавливает сборку с TRANSLATION_ERROR (E0288) с указанием узла и каждого такого присоединения, независимо от того, объявляет ли какой-либо слот имя, под которым оно присоединено. Присоединение, не содержащее ничего объявленного чувствительным, здесь не отклоняется. Эти сущности Components объявляют свои слоты учётных данных необязательными, поэтому в compose пустой слот ничего не останавливает. Там, где реализации в Kubernetes нужны учётные данные, — в сущностях Recipes helm для twilio, vonage, telnyx, bland, letta, retell и vapi — эта сущность Recipe, напротив, требует слот и останавливает сборку с его указанием, когда он пуст.
Публикация сервисов
Поле type записи services сущности Workload определяет, публикует ли 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, и запись NodePort, задающая http: 8081, публикуют 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 или 127.0.0.1:53:53/udp для записи Loopback. Порт, не объявляющий транспорт, публикуется как <host>:<container> без суффикса, и действует собственное значение compose по умолчанию. Compose записывает транспорт опубликованного порта как tcp или udp; у порта, объявляющего SCTP, нет записи в compose, поэтому он останавливается с TRANSLATION_ERROR, а не публикует порт с другим транспортом. Порт контейнера, который не публикует ни один сервис, вообще не попадает в файл compose, поэтому транспорту, объявленному на таком порту, не к чему применяться, и остановки не происходит.
Многоконтейнерные Workloads
Сущность Workload с несколькими контейнерами превращается в один основной сервис плюс по одному sidecar-сервису на каждый неосновной контейнер. Основной контейнер — это контейнер с именем main (если он есть) или первый контейнер в порядке объявления. Sidecar-сервисы разделяют сетевое пространство имён основного сервиса через network_mode: "service:<main>" — ближайший примитив compose к модели общей сети пода Kubernetes.
Как именуется sidecar-сервис или init-сервис
Основной сервис носит имя <component> без изменений. Каждый другой сервис, который создаёт Workload, — по одному на каждый sidecar и по одному на каждый init-контейнер — получает имя из двух идентификаторов вместе: <component> и имени контейнера, которым для sidecar является его ключ в containers:, а для init-контейнера — его name или позиционное init-<index>, которое получает безымянная запись init. Собранный блок services: содержит по одному сервису на имя, поэтому имя строится так, что два контейнера, различающиеся любым из идентификаторов, всегда получают два разных имени.
Каждый идентификатор записывается точно так же, как две части имени тома, — буква, цифра, точка и подчёркивание как написаны, дефис сохраняется там, где его сохраняют тамошние правила, а каждый другой символ кодируется, — и оба соединяются через --, которого не содержит ни один закодированный идентификатор. Так, компонент api с sidecar logger запускает его как api--logger, init-контейнер import-seed компонента platform запускается как platform--import-seed, а безымянная первая запись init компонента api — как api--init-0. Имя контейнера с символом, который не допускает имя сервиса, кодируется, а не выводится как написано: init-контейнер warm cache/x компонента api запускается как api--warm-zx000020cache-zsx.
Двойное соединение разделяет контейнеры двух компонентов. api с контейнером warm-cache и api-warm с контейнером cache запускаются как api--warm-cache и api-warm--cache, два сервиса, тогда как соединение одним дефисом дало бы для обоих api-warm-cache.
Sidecar-контейнеры и init-контейнеры используют одно и то же именование, поэтому запись containers и запись initContainers с одинаковым именем получают одно имя сервиса, и сборка останавливается на этой паре, а не запускает один контейнер вместо другого (см. Init-контейнеры).
Собственный сервис компонента не получает ни одного из этих имён. Основной сервис называется по компоненту, а двойной дефис, написанный в имени компонента, там сам кодируется — компонент api--prep запускается как api-zh-prep, — поэтому он никогда не содержит соединения --. Если сервисы двух разных компонентов всё же совпадают по имени в одном файле compose — скажем, через сервис, который артефакт называет для себя, — сборка останавливается, называя оба, как описано в разделе Вывод для каждой пары (path, provider).
Изменение имени компонента или имени контейнера переименовывает сервис. Compose считает сервис под новым именем новым сервисом, поэтому его контейнер создаётся заново под новым именем.
Поля уровня пода
Поля сущности Workload уровня пода применяются только к основному сервису — sidecar-сервисы разделяют сетевое пространство имён основного сервиса, — и init-сервис следует тому же правилу. Единственное исключение — пользователь пода: под запускает все свои контейнеры от podSecurityContext.runAsUser и runAsGroup, поэтому они распространяются на каждый сервис, создаваемый сущностью Workload, включая sidecar- и init-сервисы.
Некоторые из них отображаются на поле сервиса compose:
| Поле Workload | Поле Compose |
|---|---|
podSecurityContext.runAsUser / runAsGroup | user ("1000" или 1000:3000 с группой) на каждом сервисе сущности Workload. Контейнер, задающий собственный 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 через эту сеть, поскольку он в ней больше не находится; они достигают его по собственным адресам хоста, чего и требовало объявление. Остальные сервисы на границе не затрагиваются.
С этим сочетаются две формы. Sidecar-сервис продолжает ссылаться на основной сервис (network_mode: "service:<main>"), поэтому он следует за основным сервисом в сеть хоста, ничего не объявляя сам, — так же, как контейнеры пода Kubernetes разделяют одно пространство имён. 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 несёт одного пользователя и одну группу; группа, которой принадлежат тома пода, и дополнительные группы его процессов не транслируются |
podSecurityContext.runAsGroup, если под не задаёт runAsUser или если контейнер — основной, sidecar или init — задаёт собственный runAsUser и не задаёт runAsGroup | user указывает группу только рядом с пользователем, а собственный пользователь контейнера заменяет пользователя пода, поэтому группа пода не попадает ни в один сервис, записанный таким образом |
securityContext уровня контейнера транслируется частично: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot и allowPrivilegeEscalation не имеют выражения в compose и вызывают то же предупреждение unsupported-field; то же относится к runAsGroup контейнера, записанному без runAsUser рядом с ним: тогда сервис запускается от пользователя пода, если под его задаёт, без этой группы.
Каждое предупреждение в этом разделе носит рекомендательный характер и выдаётся вне основного вывода: сборка завершается успешно, а сгенерированный файл побайтно совпадает с тем, каким он был бы без него. --no-unsupported-field-warnings отключает этот класс предупреждений.
Init-контейнеры
Записи initContainers сущности Workload становятся отдельными сервисами по идиоме compose «выполнить до завершения». Каждая запись добавляет один сервис, имя которого образуется из <component> и name записи по той же схеме именования, что и у sidecar-сервисов, — <component>--<container-name> для обычного имени; запись без name получает позиционное имя init-<index>, описанное в справочнике по Workload, и имя сервиса образуется из него.
Порядок, который обещает контракт авторинга, — init-контейнеры выполняются до завершения в том порядке, в каком они записаны, а все остальные контейнеры запускаются только после завершения всех init-контейнеров, — выражается длинной формой depends_on:
- Каждый init-сервис, кроме первого, ожидает своего предшественника с
condition: service_completed_successfully. - Основной сервис и каждый sidecar-сервис ожидают последний init-сервис с тем же условием. Ожидать последний достаточно, потому что init-сервисы образуют цепочку.
- Каждый init-сервис получает
restart: "no". Init-сервис выполняется один раз; сервис, поднявшийся снова, никогда не достиг бы завершённого состояния, которого ждут зависящие от него сервисы, поэтомуrestartPolicy, заданный для init-контейнера, этого не меняет.
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 останавливает сборку с TRANSLATION_ERROR, в которой указан init-контейнер, где он встретился.
Из того, что init-сервис не является основным, следуют два отличия от основного сервиса:
- Поля уровня пода сущности Workload не применяются — то же правило действует для sidecar-сервисов; исключение составляет пользователь пода, который распространяется на каждый сервис, как описано в разделе Поля уровня пода.
- Init-сервис подключается к сети своей границы напрямую, а не разделяет сетевое пространство имён основного сервиса, как это делает sidecar. Иначе нельзя: основной сервис ожидает init-сервис, а разделение пространства имён само по себе является зависимостью от основного сервиса, что замкнуло бы ожидание в цикл, который compose отказывается запускать. Поэтому init-контейнер обращается к другим сервисам в сети границы по имени сервиса, но не разделяет
localhostосновного сервиса.
Init-сервисы и sidecar-сервисы используют одно пространство имён, потому что и те и другие называет одна схема именования, поэтому запись initContainers и запись containers не могут иметь одинаковое имя. Если это происходит, компилятор останавливается с TRANSLATION_ERROR, в которой указаны узел, имя контейнера и имя сервиса, на которое претендовали оба, вместо того чтобы позволить одному сервису незаметно заменить другой.
Вывод условия завершения не повышает минимальную версию Compose. condition и его значения относятся к базовой спецификации Compose Specification — в отличие от полей restart и required рядом с ними в том же блоке длинной формы, которые спецификация связывает с определёнными выпусками Compose. Каждая минимальная версия, которую требует вывод provider compose, появляется вместе с конструкцией, которой она нужна: ≥ 2.23.1 для встроенного configs.content, ≥ 2.26.0 для subPath монтирования (см. Тома) и 2.38 для моделей. Первая из них распространяется на любой вывод compose, содержащий конфигурацию со встроенным content:, — именно так поступают и файл за томом configmap, и конфигурация за мостовым межсетевым ребром, — а не на один путь авторинга.
К какой сети подключается сервис
Каждый сервис подключается к сети Docker; sidecar-контейнеры наследуют её через ссылку network_mode на основной сервис. В какую сеть попадает узел, определяется по аннотации aggrega.ai/namespace на этом узле, а если у узла такой аннотации нет — по пути файла compose, то есть по каталогу, в который файл записывается внутри выходного каталога сборки, например bridge/compose для границы, у которой directory: равно bridge. Поэтому все узлы без аннотации в одном файле 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и шестизначная шестнадцатеричная кодовая точка символа, а байт, с которого не начинается ни один символ, — какbи его собственное двузначное значение, так что идентичность, не являющаяся допустимым текстом, всё равно записывается различимо, а не схлопывается. - Полностью отсутствующая идентичность — узел без аннотации
aggrega.ai/namespaceв файле compose без пути — записывается как-ze, что не может получиться ни из одной идентичности, написанной автором. Поэтому сеть без идентичности никогда не разделяет связность с сетью, идентичность которой записана каким-либо конкретным образом.
Так, пространство имён prod даёт сеть prod, core-net даёт core-net, а файл compose по пути dist/app/compose даёт dist-zsapp-zscompose. Одинаковые входные данные всегда дают одинаковое имя.
Пространство имён и путь файла compose записываются в одно и то же пространство. Это два способа назвать одно и то же — сеть, в которой находится узел, — поэтому узел с пространством имён app/compose и узел без пространства имён в файле compose по пути app/compose намеренно попадают в одну сеть, точно так же, как две границы с одинаковой аннотацией aggrega.ai/namespace. Если нужно разделить два узла, задайте им различающиеся идентичности.
Изменение идентичности узла переименовывает сеть compose, а compose не переименовывает сеть на месте. Сеть создаётся заново под новым именем, и каждый сервис в ней пересоздаётся, чтобы подключиться к ней, а старая сеть остаётся, пока что-нибудь её не удалит. Сеть не хранит данных, поэтому ничего не теряется, но контейнеры в ней перезапускаются, и всё, что держит соединение во время изменения, видит его разрыв. Рассматривайте изменение аннотации пространства имён или каталога, в который записывается файл compose, как повторное развёртывание, которое нужно планировать, а не как значение, которое можно поправить на месте.
Когда две границы сводятся к одному пути сборки (общий directory:), их узлы без аннотации aggrega.ai/namespace разделяют единственную сеть файла; задайте каждой границе собственную аннотацию aggrega.ai/namespace, и объединённый docker-compose.yaml объявит по одной записи верхнего уровня networks: на каждую аннотацию. Сервисы из разных границ в одном файле compose могут обращаться друг к другу по именам сервисов через DNS-разрешение compose по умолчанию, с учётом собственных правил compose о достижимости между сетями. Маршрутизацию L4 между сетями внутри одного файла compose обеспечивает сущность Feature compose-bridge из стандартной библиотеки — как содержимое каталога, логики которого в этом провайдере нет: при подключении к общей границе-предку её сущность FeatureRecipe строит шлюз из рёбер uses границы, оба конца которых собираются в собственный файл compose границы и находятся в разных сетях этого файла, — сервис aggrega-gw, конфигурация nginx stream которого проксирует каждое связанное ребро (по одному блоку server на ребро, на порту цели с запасным вариантом portBase при коллизии), — а её собственный injectMapping переписывает переменную окружения хоста каждого потребителя на aggrega-gw:<port> или, если одно и то же соединение доставляет и хост, и порт, на aggrega-gw, переписывая переменную порта на порт прослушивания. Эта перезапись заменяет значение, которое доставило собственное соединение потребителя; если ту же переменную доставила другая сущность Feature, подключённая к потребителю, сборка останавливается с указанием обеих, а не заменяет её. valuesMapping сущности FeatureRecipe записывает эту конфигурацию как монтируемую конфигурацию compose — запись верхнего уровня configs: со встроенным content:, на которую ссылается шлюз и которая монтируется в /etc/nginx/nginx.conf; оператору не нужно её монтировать, — и перечисляет каждую связанную конечную точку в x-aggrega-networks-of шлюза, которое этот провайдер разрешает в сети, где размещены эти конечные точки (ниже). Ребро, концы которого собираются в два разных файла compose, не связывается и сохраняет собственное имя цели; граница, которой нечего связывать, всё равно несёт простаивающий шлюз без конфигурации и без сетей, кроме собственной; а мост, подключённый к границе, в файле compose которой нет ни одного компонента, останавливает сборку, а не записывает шлюз в никуда. Конфигурация stream содержит директиву resolver и проксирует через переменную для каждого ребра (set $uN <host>; proxy_pass $uN), чтобы каждый upstream разрешался в момент соединения, а не один раз при запуске, — иначе голый proxy_pass к ещё не запущенной цели привёл бы к сбою шлюза при старте. (Символ $ в этих переменных экранируется как $$ внутри configs.content, чтобы собственная $-интерполяция Docker Compose оставляла для nginx буквальный $.) Встроенный configs.content требует Docker Compose ≥ 2.23.1. См. шаблон compose-bridge.
Подключение к сетям других компонентов — x-aggrega-networks-of
Сервис, который пишет фрагмент, — исходный файл compose после слияния с его наложением или тело artifacts:, — может подключиться к сетям других компонентов, собранных в тот же файл compose, перечислив их под ключом расширения x-aggrega-networks-of: это список идентификаторов компонентов, тех, что сущность Aggregate даёт своим компонентам, и сущность FeatureRecipe с областью границы читает их как ключи .boundary.components и как source и target своих списков рёбер .boundary. Провайдер разрешает каждый идентификатор в сеть, в которой размещён этот компонент в данном файле, по тому же правилу размещения, что и для каждого узла, и добавляет эти сети к сервису, каждую по одному разу и в порядке имён, перед собственной сетью сервиса, к которой тот по-прежнему подключается. Сам ключ в собранный файл не попадает. Провайдер читает идентификаторы как ссылки для разрешения и ничего не знает о том, что делает сервис, поэтому ключ может использовать любая сущность 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 при сборке файла, и каждая указывает сервис:
- Идентификатор, который не несёт ни один компонент, собранный в этот файл, — например, идентификатор компонента, собранного в другой файл compose. Сеть принадлежит одному файлу, поэтому сообщение указывает идентификатор и файл, в котором находится сервис. Указывайте только компоненты, собранные в тот же файл, или удалите идентификатор.
- Значение, не являющееся списком строк. Ключ принимает список идентификаторов компонентов, даже если идентификатор один.
- Ключ на сервисе, который задаёт
network_mode. Compose не позволяет сервису сnetwork_modeподключаться к сетям; удалите одно из двух.
Вывод depends_on
Провайдер compose автоматически выводит depends_on из рёбер uses в IR. Для каждого ребра, у которого и источник, и цель вносят сервисы в объединённый файл compose, провайдер добавляет depends_on: [<target>] к сервису-источнику.
Зависимость добавляется к собственному сервису компонента-источника и ни к какому другому сервису, который вносит этот компонент. Компонент, который также объявляет init-контейнеры, вносит по одному сервису, выполняющемуся до завершения, на каждую запись, и ни один из них не получает зависимость, выведенную из ребра: ребро называет компонент, а у init-сервиса собственное имя. Поэтому init-контейнер, которому нужно обращаться к цели ребра, например миграция схемы для базы данных, которую компонент использует через uses, не упорядочен относительно этой цели и может запуститься раньше, чем она станет доступна, тогда как собственный сервис компонента ждёт и завершения цепочки init, и запуска цели.
Записи, выведенные из рёбер, выводятся без ограничения по готовности: они имеют семантику service_started независимо от того, объявляет ли цель healthcheck. Ограничение по состоянию цели, при котором среда выполнения compose блокировала бы запуск, пока healthcheck цели не сообщит о работоспособности, выразимо, но ребро uses этого не требует. Волна, называющая ту же пару, — единственное, что меняет условие у записи, выведенной из ребра, и меняет его потому, что этого требует волна, а не ребро.
Записи, выведенные из рёбер, выводятся в алфавитном порядке целей для стабильности вывода. Рёбра, источник или цель которых обслуживаются другим провайдером (helm или helm-chart), пропускаются: depends_on применяется только в пределах обслуживаемого compose подмножества Release.
depends_on сервиса выводится в одной из двух форм compose, никогда не в смешанной, потому что compose требует условие у каждой записи длинной формы:
- Список в короткой форме (
depends_on: [<service-name>]), когда ни одна запись этого сервиса не содержит условия. Это любой сервис, все зависимости которого получены из рёберuses. - Отображение в длинной форме, когда условие есть хотя бы у одной записи: это происходит, когда сервис также ждёт init-контейнер или когда его упорядочивает волна развёртывания. В этом случае записи, выведенные из рёбер, получают явное
condition: service_started, которое Compose Specification определяет как эквивалент короткой формы, поэтому их смысл не меняется.
Внутри сервиса источники сохраняют собственный порядок и не перемешиваются: сначала выводится ожидание цепочки init в том порядке, в котором автор записал список, затем упорядоченные по алфавиту записи из рёбер, затем упорядоченные по алфавиту записи из волн.
Упорядочивание по волнам развёртывания
Значение syncWave: границы Release упорядочивает сервисы compose-файла, в который рендерится эта граница. Каждый компонент границы наследует её волну, а там, где несколько границ используют один directory: — так что их вклады сводятся в единый docker-compose.yaml, — объединённый файл содержит более одной волны, и провайдер выражает порядок между ними через depends_on.
Каждый сервис ожидает все сервисы непосредственно предшествующей волны, в которой есть хотя бы один сервис, и не ожидает более ранних волн. Остальное compose разрешает транзитивно: сервис в волне 2 ожидает волну 1, которая ожидает волну 0, так что вся последовательность упорядочена, а собственный список каждого сервиса остаётся размером с одну волну, а не со весь файл. Волны не обязаны идти подряд, а отрицательные значения вполне обычны — -1 часто выбирают для миграции, которая выполняется раньше всего остального.
Условие зависит от того, что может обеспечить цель. Волна означает, что более ранняя группа готова до запуска более поздней, то есть речь о готовности, а не о запуске процесса, поэтому:
- если целевой сервис объявляет
healthcheck, ожидание задаётся какcondition: service_healthy; - если не объявляет, ожидание задаётся как
condition: service_started, поскольку сервис без healthcheck никогда не сообщит о работоспособности и ожидание по состоянию здоровья никогда не было бы удовлетворено — файл никогда бы не запустился.
Более слабое условие видно в сгенерированном файле рядом с более сильным, и сборка дополнительно называет каждый такой сервис в предупреждении, чтобы автор, ожидавший упорядочивания по готовности, узнал, какая часть объявленной им волны обеспечивает лишь порядок запуска. Предупреждение носит рекомендательный характер: сборка завершается успешно, а сгенерированные байты в точности те же, что и без него. Усилить ожидание позволяет добавление блока health: в этот контейнер. --no-unsupported-field-warnings отключает этот класс предупреждений.
Волна по-прежнему записывается как метка. Упорядочивание добавляется рядом с меткой aggrega.ai/sync-wave, а не вместо неё: именно по метке читатель, изучающий сгенерированный файл, видит, из какой волны пришёл сервис, — записи depends_on этого не указывают.
Если волна и ребро uses указывают одну и ту же пару, обе зависимости несёт одна запись. Compose допускает одну запись на зависимость, поэтому сервис, который и uses цель, и находится на волну позже неё, генерирует одну запись с условием волны — требование волны сильнее из двух, и выражается именно оно.
Граница, все компоненты которой находятся в одной волне, ничего из этого не генерирует. Так же ведёт себя сущность Release, которая вообще не объявляет syncWave: каждый участник получает значение поля по умолчанию 0, объединённый файл содержит одну волну, и результат в точности такой, как если бы провайдер не выражал упорядочивание по волнам.
Упорядочивание между двумя compose-файлами невыразимо и не аппроксимируется. depends_on указывает сервис внутри того же файла, а границы, которые вычисляются в разные пути сборки, создают разные файлы docker-compose.yaml, которые среда выполнения compose рассматривает как независимые проекты. Поэтому волна упорядочивает каждый сервис в файле, в который она рендерится, и ничего за его пределами. Последовательность двух compose-проектов — забота оператора, так же как и маршрутизация между файлами; объединяет две границы в один файл объявление общего directory:, и это решение о форме вывода, которое следует принимать по собственным причинам, а не ради упорядочивания.
Ребро uses, указывающее на более позднюю волну, выводится так, как записано, и о нём сообщается. Выводимый depends_on отражает то, что объявлено, — и рёбра uses, и волны. Ребро, потребитель которого находится в более ранней волне, чем используемая им цель, утверждает противоположное тому, что утверждают волны: ребро заставляет потребителя ждать цель, тогда как волны заставляют цель ждать — через каждую волну между ними — потребителя. Объединённый файл выражает и то, и другое, а это набор циклических зависимостей, который Docker Compose отказывается запускать. Сборка называет каждое такое ребро в предупреждении, указывающем оба сервиса и обе волны, поэтому цикл обнаруживается при сборке, а не при docker compose up. Предупреждение носит рекомендательный характер — сборка завершается успешно, а отрендеренные байты в точности такие же, какими были бы без него, — и --no-unsupported-field-warnings его не отключает, потому что ничего не было отброшено: оба объявления выражены, и вместе они не могут запуститься. Оно охватывает только прямую пару: называет два сервиса, которые соединяет одно ребро, а не прослеживает весь цикл. Любой цикл, образованный рёбрами uses и волнами вместе, проходит как минимум через одно такое ребро, поэтому о нём всегда сообщается; цикл, образованный только рёбрами uses без участия волн, и цикл, замкнутый записью depends_on в файле compose, который предоставляет сущность Recipe, выводятся так, как записаны, и о них не сообщается. Согласуйте направление рёбер и порядок волн: помещайте потребителя в волну цели или более позднюю либо цель — в волну потребителя или более раннюю.
# 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.
Режим с источником
Поле source: провайдера compose указывает файл docker-compose YAML, который провайдер может прочитать и разобрать, и принимает обе формы, которые принимает поле source:: простую строку с путём в файловой системе и структурированный объект, в котором url: содержит расположение. Если это расположение — путь в файловой системе, он отсчитывается от каталога, содержащего объявляющий его recipe.yaml, а не от каталога, из которого запущена сборка, и должен оставаться внутри этого каталога: путь, выходящий за его пределы, или абсолютный путь отклоняется, поскольку каждый файл, входящий в публикацию сущности Recipe, берётся из её каталога — см. entities/recipe.md, «Content paths stay inside the Recipe’s own directory». Указанный так файл публикуется вместе с сущностью 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 записывает дайджест указанного файла в entity.lock рядом с сущностью Recipe, и сборка сверяет его перед чтением фрагмента. Копирование удалённого фрагмента в локальный репозиторий и указание source: на эту копию поддерживается как альтернатива загрузке, но не обязательно. Схема принимает открытый структурированный объект.
Сущность Recipe с source: <path-to-compose-file> и valuesMapping: выполняет следующий конвейер:
- Базовый файл compose по пути
<path>читается и разбирается как 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; ключ при этом не удаляется. Если провайдер записывает в этот ключ собственное значение, файл вместо этого содержит значение провайдера: приlabels: nullостаются метки происхождения, которые ставит провайдер, а приnetworks: null— сеть, которую он подключает.null, записанный в любом другом месте наложения, под это правило не подпадает. Что затем означаетnull, определяет то, как Compose трактует этот атрибут: например, записьenvironmentбез значения берёт значение из окружения, в котором запущенdocker compose.
Каждая метка, написанная автором сервиса, сохраняется. labels: сервиса в базовом файле или в оверлее можно записать как отображение или как список записей key=value в стиле Compose, и каждая метка попадает в файл compose рядом с метками происхождения, которые проставляет провайдер. Запись списка читается так, как её читает Compose: текст до первого = называет метку, а текст после него является значением, и запись без = — это метка с пустым значением. Число или значение true/false записывается как его текст, поэтому replicas-hint: 2 попадает в файл как replicas-hint: "2", а метка, записанная как null, остаётся null. Если авторская метка и метка происхождения имеют один и тот же ключ, файл содержит значение происхождения. Значение labels:, не являющееся ни отображением, ни списком, и запись списка, не являющаяся текстом, останавливают сборку с указанием исходного файла и сервиса. Метки сервиса в теле artifacts: принимают форму отображения: список там останавливает сборку с указанием артефакта и сервиса.
Затем слитый документ поступает в слияние на уровне сущности Release вместе со вкладами синтезированного режима, с той же сетью на каждую границу и тем же выводом depends_on.
Исключение сервисов, томов и конфигураций. Наложение не может ничего удалить из базового файла — значение наложения заменяет, но никогда не удаляет, — поэтому для загруженного файла, включающего сервис, который сущность Release запускать не должна, предназначены записи omits: сущности Recipe или FeatureRecipe. Этот провайдер учитывает их только в этом режиме: синтезированная сущность Workload и тело artifacts: отрисовываются без них. Запись указывает одну единицу верхнего уровня файла по её kind — service, volume или config — и её name, то есть ключу единицы в services:, volumes: или configs:, сравниваемому точно. В файле compose нет пространств имён, поэтому запись с namespace, как и запись с любым другим видом, останавливает сборку при отрисовке компонента с указанием записи и видов, которые принимает провайдер; все записи проверяются до того, как что-либо исключается. Записи сопоставляются с файлом после слияния с ним описанного выше наложения, так что единица, добавленная наложением, исключается так же, как объявленная в базовом файле, и до того, как провайдер добавит что-либо своё, поэтому запись никогда не указывает на добавленное им. Указанная записью единица удаляется, а раздел, все единицы которого исключены, удаляется вместе с ними; все остальные единицы записываются в точности так, как без записей. Записи действуют только на файл объявившей их сущности Recipe или FeatureRecipe: то, что другой компонент или подключённая сущность Feature вносит в тот же docker-compose.yaml, не затрагивается, включая единицу с тем же ключом. Провайдер сообщает, сколько единиц исключила каждая запись, а запись, не исключившая ни одной, останавливает сборку; см. An omits entry left out nothing the source rendered (Запись omits не исключила ничего из отрисованного источником).
На исключённую единицу не должно ссылаться то, что осталось, поскольку compose отклоняет файл, ссылающийся на сервис, том или конфигурацию, которых он не объявляет. После удаления единиц каждая оставшаяся в файле ссылка на одну из них останавливает сборку, и сообщение называет каждый ссылающийся сервис или задание, единицу, на которую указывает ссылка, и поле, в котором она находится. Ссылка — это то, что Compose Specification определяет как запись файла, указывающую на другую:
- сервис, указанный через
depends_onв любой форме, черезlinks(SERVICEилиSERVICE:ALIAS), черезvolumes_from(SERVICEилиSERVICE:MODE), черезnetwork_mode,ipc,pidилиutsсо значениемservice:<name>, черезextends, указывающий сервис того же файла, или через значениеbuild.additional_contextsвидаservice:<name>; - том, указанный как источник записи
volumes:— в краткой формеSOURCE:TARGET, где источник является именем, а не путём, и в полной форме сtype: volume; - конфигурация, указанная записью
configs:в любой форме.
Хуки pre_start сервиса и каждая запись верхнего уровня jobs: тоже читаются — ради ссылок, которые спецификация допускает в каждой из них. Некоторые значения лишь похожи на ссылки и не читаются как ссылки: запись volumes_from или network_mode, начинающаяся с container:, указывает контейнер, external_links указывает контейнер, не объявленный в этом файле, extends с file: указывает сервис другого файла, а credential_spec.config может указывать конфигурацию, хранящуюся на платформе, а не в файле. Каждое значение сравнивается в записанном виде, поэтому ссылку, записанную через ${VARIABLE}, эта проверка не видит, а ссылка на единицу, которую файл никогда не объявлял, остаётся как есть.
Проверка читает только собственный файл объявившей сущности Recipe или FeatureRecipe, поэтому ссылка на исключённый сервис останавливает сборку, даже если другой участник по тому же пути сборки объявляет сервис с таким именем. Чтобы сохранить ссылку, сохраните единицу. Чтобы убрать её, измените ссылающуюся запись через valuesMapping: — список там заменяет список базового файла, так что depends_on: [] очищает его, — или исключите также и ссылающийся сервис.
Вывод для каждой пары (path, provider)
Каждый путь сборки compose создаёт один docker-compose.yaml. Границы, которые вычисляются в разные пути, создают разные compose-файлы; границы с общим вычисленным путём создают один объединённый compose-файл, содержащий всех участников по этому пути. Путь — это directory: границы, соединённый с subDirectory: каждого компонента (по умолчанию {{ .capability }}, поэтому участники compose по умолчанию попадают в подпапку compose/).
Конфликты имён сервисов в пределах одного пути сборки останавливают сборку. Если два разных узла вносят сервисы с одинаковым идентификатором экземпляра в одном кортеже (path, provider), компилятор останавливается, а диагностика перечисляет все участвующие кортежи (boundary, node) в алфавитном порядке. Автор устраняет конфликт, переименовав одного из участников (обычно изменив идентификатор узла, чтобы синтезатор создал другое имя сервиса), или направив участников в разные пути с помощью разных объявлений directory:.
Тома верхнего уровня объединяются в пределах пути сборки, и два участника могут объявить одно имя при условии, что их объявления согласованы. Участник — это фрагмент, поэтому два фрагмента одного компонента — его собственный файл compose и запись artifacts: или две записи artifacts: — являются двумя участниками точно так же, как два компонента. Именованный том — это один физический том, поэтому два идентичных объявления описывают ровно ту запись, которая окажется в собранном файле, и под этим именем остаётся одна запись. Том, выведенный провайдером, не имеет тела, поэтому два таких тома согласованы тривиально, и в любом случае они не могут встретиться (см. Как выводится имя тома).
Особого внимания требует авторская запись volumes:, поскольку у неё может быть собственное тело — driver, driver_opts или labels. Если два участника объявляют одно имя с разными телами, сборка останавливается с TRANSLATION_ERROR, указывая том и все участвующие кортежи (boundary, node, fragment). У двух авторов, расходящихся во мнении об одном томе, нет ответа, между которыми сборщик мог бы выбрать: сохранение любого из тел отбросило бы написанное другим автором в сборке, которая иначе завершилась бы успешно. Устраните это, сделав оба объявления идентичными, если оба автора имели в виду один том, или переименовав одно из них, если имелись в виду два. Сетей верхнего уровня по одной на каждую различную аннотацию aggrega.ai/namespace плюс одна, названная по пути файла compose, для узлов без аннотации; они именуются согласно Как выводится имя сети; две участвующие границы с одинаковой аннотацией aggrega.ai/namespace объединяются в одну сеть, общую для обеих, как и две неаннотированные границы, разделяющие файл.
Каждый ключ, который пишет фрагмент, переносится или отклоняется
Фрагмент — исходный файл compose после слияния с его наложением или тело artifacts:, вычисляемое в YAML compose, — попадает в собранный 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. Внутри блоков, которые описывает провайдер: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; у конфигурации верхнего уровня —content. Тело модели и записьmodels:сервиса в полной форме переносят каждый член, как описано в разделе Модели. Член-расширение — ключ, начинающийся сx-, — переносится на верхнем уровне и на сервисе, как описано в разделе Члены-расширения. - Отклоняются. Любой другой ключ —
stdin_openна сервисе,secrets:илиname:верхнего уровня,deploy.replicas,restart:илиrequired:внутри записиdepends_on:в полной форме, ключx-внутри тела тома верхнего уровня илиhealthcheck— останавливает сборку сTRANSLATION_ERROR, указывая каждый такой ключ, его путь во фрагменте (services.migrate.stdin_open), фрагмент и компонент, а также два места, откуда такой ключ может взяться. Первое — сам фрагмент, и исправление состоит в том, чтобы удалить из него ключ. Второе — исходная сущность Recipe, не объявляющаяvaluesMapping:: тогда значения узла накладываются на файл compose как есть, так что каждый ключ значения оказывается ключом верхнего уровня фрагмента, и исправление состоит в том, чтобы объявитьvaluesMapping:, размещающий каждое значение под ключом, который переносит провайдер. Ключ, который ключ слияния YAML (<<: *anchor) вносит в блок, оценивается там, где он оказывается, как если бы был записан там. Фрагмент, отрисованный из источника, называется<component>.compose-fragment.yaml; фрагментartifacts:— по имени, которое даёт ему его сущность Recipe. - Отклоняется целиком: собственная сеть фрагмента. Запись под
networks:верхнего уровня фрагмента останавливает сборку сTRANSLATION_ERROR, что бы ни содержало её тело — пустая запись,driverили что-либо ещё, — с указанием записи (networks.back), фрагмента и компонента, потому что собранный файл содержит только сети, которые выводит провайдер (см. К какой сети подключается сервис). Удалите запись: сервис подключается к сети своего компонента без каких-либо объявлений, аннотацияaggrega.ai/namespaceвыбирает, к какой сети подключается компонент, сервис перечисляет компоненты, к сетям которых он также подключается, вx-aggrega-networks-of, а сущность Featurecompose-bridgeмаршрутизирует трафик между сервисами в разных сетях. Пустойnetworks: {}ничего не объявляет и не отклоняется, а собственный списокnetworks:сервиса переносится, как описано выше. - Отклоняется целиком: фрагмент из нескольких документов. Тело
artifacts:, содержащее два или более документов YAML, разделённых---, останавливает сборку сTRANSLATION_ERROR, указывая фрагмент, компонент и количество содержащихся в нём документов, потому что слияние читает фрагмент как один файл compose, и иначе каждый документ после первого отсутствовал бы в собранном файле. Запишите фрагмент как один документ или дайте каждому документу собственную записьartifacts:. Документ, не содержащий ничего, — пустой документ, который открывает завершающий---, — не учитывается. Исходный файл compose из нескольких документов никогда не становится таким фрагментом: он отклоняется при чтении файла.
Провайдер не читает смысла ни одного ключа: ключ переносится потому, что он входит в приведённый выше набор, и отклоняется потому, что не входит.
Члены-расширения переносятся в том виде, в каком написаны
Compose Specification резервирует ключи, начинающиеся с x-, для расширений: данных, которые может использовать инструмент, читающий файл, и которые сам Compose игнорирует. Члены-расширения фрагмента на верхнем уровне и в сервисе попадают в собранный файл в том виде, в каком написаны, после всех ключей, которые провайдер моделирует на этом уровне, в том порядке, в каком их содержит фрагмент; провайдер ничего внутри них не читает, за исключением x-aggrega-networks-of сервиса, который он разрешает в сети, к которым присоединяется сервис, и не включает в собранный файл (см. Присоединение к сетям других компонентов). Тело artifacts: содержит их в том порядке, в каком они в нём записаны. Ключи подключаемого файла compose попадают в его фрагмент в порядке имён после слияния его наложения, поэтому его члены-расширения записываются в порядке имён.
# an artifacts: bodyx-owner: team-bservices: migrate: image: example/migrate:1 x-schedule: manualЧлен, достигнутый через псевдоним YAML, записывается полностью, а якоря не переносятся, поэтому собранный файл никогда не содержит псевдоним без соответствующего якоря; именно это позволяет члену верхнего уровня содержать якорь, который подтягивает ключ слияния сервиса (<<: *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]Модели
Раздел models: верхнего уровня в compose-файле объявляет модели ИИ, которые используют сервисы файла, а сервис получает модель через собственную запись models:. Провайдер переносит и то и другое из фрагмента в собранный docker-compose.yaml в написании самого Compose, независимо от того, является ли фрагмент исходным compose-файлом или телом artifacts:, которое вычисляется в compose YAML. Сущность Workload не объявляет моделей, поэтому Recipe в режиме Workload их не вносит.
- Тело модели записывается так, как его записал фрагмент.
model— идентификатор артефакта OCI для модели, —context_sizeиruntime_flagsсохраняют свои имена, а все остальные члены, в том числе расширениеx-, переносятся рядом с ними. Внутри модели три названных члена идут первыми, остальные следуют в порядке ключей, а модели записываются в порядке имён, поэтому одинаковые входные данные дают побайтно идентичный файл. Провайдер ничего не читает в теле: он не проверяет идентификатор и ничего не знает о том, что будет обслуживать модель. - Ссылка сервиса сохраняет свою форму. Краткая форма перечисляет имена моделей (
models: [llm]); полная форма сопоставляет каждой моделиendpoint_varиmodel_var— имена переменных, которые получают адрес исполнителя моделей и идентификатор модели. Любая из них записывается в той форме и в том порядке, которые использовал фрагмент, и переносится вместе со своим сервисом. Если полная форма оставляет переменную без имени, Compose присваивает ей имя при запуске файла. - Модели объединяются в пределах пути сборки по тому же правилу, что и тома. Если два участника объявляют одно имя модели с телами, которые выводятся идентично, под ним остаётся одна запись; если два объявляют его с разными телами, сборка останавливается с
TRANSLATION_ERROR, указывая модель и все участвующие кортежи(boundary, node, fragment). Два фрагмента одного компонента здесь тоже считаются двумя участниками. Сделайте объявления идентичными, если оба участника имеют в виду одну модель, или дайте одному из них другое имя. - Каждая ссылка называет объявленную модель. После объединения фрагментов пути сборки сервис, получивший модель, которую не объявляет ни один участник по этому пути, останавливает сборку с
TRANSLATION_ERROR, указывая сервис и модель. Проверка выполняется по завершённому объединению, поэтому один компонент может предоставить своему сервису модель, объявленную другим компонентом по тому же пути сборки. - Запись
omits:не может исключить модель.service,volumeиconfig— виды, которые принимает этот провайдер, и запись, называющая модель, останавливает сборку так же, как запись, называющая любой другой вид.
Модели обслуживаются при запуске файла, а не при его сборке. Docker Compose 2.38 или новее на платформе, поддерживающей модели Compose, например Docker Model Runner, загружает и запускает каждую модель, предоставленную сервису, пропуская остальные, если запуск выполнен без --all-resources, и в каждом сервисе, получившем модель, задаёт переменным, названным в его ссылке, адрес исполнителя моделей и идентификатор модели. Сборка не видит хост, который будет запускать файл, поэтому не проверяет ни версию Compose, ни платформу: файл с моделями собирается одинаково, что бы его ни запускало.
Feature, присоединённая к компоненту, вносит вклад в тот же файл
Сущность Feature, присоединённая к компоненту, вносит свои сервисы в тот docker-compose.yaml, в который собирается её компонент-хост, на тех же условиях, что и собственный Recipe хоста. Второго файла рядом нет: один путь сборки создаёт один документ, поэтому сервисы присоединённой Feature либо находятся в этом документе, либо не развёртываются вовсе. Отсоединение Feature удаляет ровно эти сервисы и не затрагивает собственные сервисы компонента-хоста.
Они являются участниками по этому пути сборки, как и любые другие, поэтому всё сказанное выше применяется к ним без изменений — правило имён сервисов и требование, чтобы два участника, объявляющие одно имя тома или конфигурации верхнего уровня, были согласны в том, что это такое. Они также подключаются к той же сети, что и остальная часть границы, поэтому компонент и присоединённая к нему Feature обращаются друг к другу по имени сервиса без каких-либо дополнительных объявлений.
Каждый сервис, вносимый Feature, несёт идентичность, составленную для этого присоединения, а не идентичность компонента-хоста, поэтому они остаются различимыми внутри документа, в который внесли вклад оба. Как строится эта идентичность, описано в разделе Метки и аннотации.
Это механизм, отличный от блока attachments: уровня контейнера в Workload, и их легко принять за одно, поскольку у них общее слово. Присоединение Feature к компоненту добавляет сервисы в собранный документ; запись attachments: контейнера считывает учётные данные, которые слот опубликовал в этот конкретный контейнер, и описана в разделе Поля контейнера.
Фрагменты compose, создаваемые через artifacts
Когда блок artifacts: сущности Recipe вычисляется в YAML compose — фрагмент с собственными блоками services:, volumes:, configs:, models: или networks: (каждая запись задаётся inline или загружается по отдельности через $import:), — слияние в сборку для каждого (path, provider) подчиняется правилам, зависящим от формы:
services:из artifacts сливаются в собранный файл compose наряду с сервисами отдельных компонентов. Имя сервиса, внесённое двумя разными компонентами по одному пути сборки, останавливает сборку, и диагностика называет каждого участника. Коллизия внутри одного компонента — между собственным фрагментом artifact этого компонента и сервисами, синтезированными для него, — не обнаруживается, и более поздний вклад заменяет более ранний, поэтому имя сервиса, заданное в artifact, должно отличаться от имён<component>и<component>--<container-name>, которые создаёт синтезатор (см. Как называется sidecar- или init-сервис).volumes:из artifacts сливаются в блокvolumes:верхнего уровня. Две записи с одним именем оставляют под ним одну запись, если объявляют его одинаково, — по тому же правилу, что и тома отдельных компонентов; две записи, объявляющие его по-разному, останавливают сборку независимо от того, пришли ли они из двух компонентов или из двух фрагментов одного — двух его записейartifacts:или одной из них и собственного файла compose компонента. Поскольку фрагмент artifact пишет собственные тела, именно на этом пути два участника вероятнее всего разойдутся. Имя тома, заданное в artifact, должно отличаться от других имён по его пути сборки, в том числе от формы<component>--<volume-name>, которую создаёт вывод имён, — если только два участника не должны описывать один общий том; в этом случае их объявления должны совпадать.configs:из artifacts сливаются в блокconfigs:верхнего уровня. Так файл, стоящий за томомconfigmap, попадает в сборку: том становится ссылкойconfigs:уровня сервиса, указывающей на configmap, а фрагмент artifact объявляет запись с этим именем и inline-содержимымcontent:. После объединения фрагментов пути сборки каждая ссылка уровня сервиса должна разрешаться в объявленную запись, иначе сборка останавливается сTRANSLATION_ERROR, называя каждую неразрешённую ссылку — сервис, имя config и путь монтирования. Проверка выполняется по завершённому объединению, а не по каждому компоненту, поэтому один компонент может ссылаться на config, объявленный другим компонентом по тому же пути сборки. Объединение согласует записи по имени, если участники согласны: два участника, объявляющие одно имя config с одинаковымcontent:, оставляют одну запись, которую оба описали. Два участника, объявляющие одно имя с разнымcontent:, останавливают сборку сTRANSLATION_ERROR, называя config и каждый участвующий кортеж(boundary, node, fragment), включая два фрагмента одного компонента: запись config всегда несёт содержимое, поэтому сохранение любого из объявлений отбросило бы файл, написанный автором. Имя config должно быть уникальным среди всех участников по его пути сборки, либо объявления должны быть одинаковыми, если два участника должны поставлять один общий файл.models:из artifacts сливаются в блокmodels:верхнего уровня, а ссылкаmodels:сервиса переносится вместе с сервисом по правилам из раздела Модели: два участника, объявляющие одно имя модели, должны объявлять его одинаково, и каждая ссылка должна называть модель, объявленную каким-либо участником по этому пути сборки.networks:из artifacts отклоняются. Провайдер compose выводит сети из аннотаций границ (одна сеть на каждую отдельную аннотациюaggrega.ai/namespace, плюс одна, названная по пути файла compose, к которой присоединяется каждый узел без такой аннотации; каждая именуется согласно разделу Как выводится имя сети), поэтому объявлению сети, предоставленному artifact, нет места в собранном файле: любая запись останавливает сборку с указанием записи и фрагмента по правилам раздела Каждый ключ, который пишет фрагмент, переносится или отклоняется. Удалите запись и формируйте сети через аннотациюaggrega.ai/namespaceили присоедините сервис к сетям указанных компонентов черезx-aggrega-networks-of; авторы, которым нужна маршрутизация между сетями в пределах одного файла compose, используют Featurecompose-bridge.- Члены-расширения из artifacts переносятся. Ключ
x-верхнего уровня записывается после остальных разделов собранного файла, в порядке записи, по правилам раздела Члены-расширения переносятся в том виде, в каком написаны. - Любой другой ключ верхнего уровня из artifacts останавливает сборку.
services:,volumes:,configs:,models:и члены-расширения — это всё, что сборщик переносит из фрагмента. Блокsecrets:и ключname:верхнего уровня каждый останавливают сборку с указанием ключа и фрагмента по правилам раздела Каждый ключ, который пишет фрагмент, переносится или отклоняется. - Тело
artifacts:— это один документ. Тело, содержащее несколько документов YAML, останавливает сборку с указанием фрагмента и количества документов в нём; дайте каждому документу собственную записьartifacts:.
Асимметрия между первыми четырьмя блоками и networks: структурна: services:, volumes:, configs: и models: несут содержимое отдельных Recipe, которое сборщик накапливает в собранном файле; networks: — это инфраструктура уровня границы, которую сборщик выводит из состояния границы. Artifacts могут расширять первое; формировать второе могут только аннотации границ, поэтому собственная сетевая запись artifact отклоняется. Члены-расширения — это данные, которые Compose Specification определяет для других инструментов, поэтому они переносятся в том виде, в каком написаны. Всё остальное — форма, для которой в собранном документе нет места, поэтому оно отклоняется, а не сливается.
Чего не обеспечивает провайдер compose
- Межсетевая маршрутизация L4 в пределах одного файла compose. Провайдер размещает каждый узел в его сети и присоединяет сервис к сетям, которые называет
x-aggrega-networks-of, но сам ничего между сетями не маршрутизирует. Чтобы сервис в сети A обращался к сервису в сети B иначе, чем через DNS по умолчанию docker-compose, требуется Featurecompose-bridge, чей FeatureRecipe записывает шлюз и перезапись. - Маршрутизация между файлами compose. Границы, которые вычисляются в разные пути сборки, порождают разные файлы
docker-compose.yaml; среда выполнения compose рассматривает их как независимые проекты, а Featurecompose-bridgeоставляет соединение между двумя файлами таким, как оно записано. Взаимодействие между файлами — забота оператора (публикация портов хоста, совместное использование внешних сетей или объединение границ в один путь через общийdirectory:). - Получение переменной окружения из вложения. В Compose нет для этого примитива, поэтому запись
attachmentsсущности Workload сas: envвыводит имя переменной с пустым значением, а не ссылку, разрешаемую во время выполнения. Заполнитель намеренный — присутствующая, но пустая переменная видна тому, кто отлаживает контейнер, тогда как отсутствующая не оставляет ничего, на что можно посмотреть, — и сборка сообщает об этом, а не оставляет это на обнаружение: каждая такая запись вызывает предупреждениеunsupported-field, указывающее запись по её координате в исходном описании (containers.<name>.attachments.<KEY>илиinitContainers[<i>].attachments.<KEY>), чтобы автор знал, какая переменная приходит пустой и к какому контейнеру она относится. Предупреждение носит рекомендательный характер: сборка завершается успешно, а сгенерированный файл побайтно совпадает с тем, каким он был бы без него.--no-unsupported-field-warningsотключает этот класс предупреждений. Записьattachmentsсas: fileне затрагивается — compose монтирует её через bind mount, и предупреждение не выдаётся. - Содержимое
deploy:режима swarm. Реплики, ограничения размещения и стратегия обновления вdeploy:— возможности режима swarm, а провайдер compose нацелен только на compose на одном хосте, поэтому не выводит ничего из этого. Однако он выводитdeploy.resources— резервирования и лимиты, в которые отображаютсяresourcesконтейнера и которые docker compose учитывает вне режима swarm (см. Ресурсы контейнера). depends_onс условием по состоянию здоровья из ребраuses. Зависимость, выведенная из ребраuses, выводится без условия, с семантикойservice_started; она не ожидает, пока healthcheck цели сообщит о работоспособности. Дело в значении ребраuses, а не в форме, которую провайдер не может создать: длинная форма выводится для ожидания init-контейнера, а волна развёртывания действительно ожидает работоспособности цели, если цель объявляет healthcheck.
Пример написания
Развёртывание compose из двух сервисов с ребром depends_on, выведенным из uses:
# 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.0Провайдер compose создаёт один файл docker-compose.yaml по вычисленному пути границы (по умолчанию dist/boundaries/production/compose/docker-compose.yaml, поскольку directory: границы по умолчанию равен dist/boundaries/<name>, а subDirectory: — {{ .capability }}), который содержит:
services.api(основной сервис api, сетьprod, порты8080:8080, проверка работоспособности черезcurl,depends_on: [db])services.db(основной сервис db, сетьprod)networks.prod(сеть docker для границы)
Связанные справочные материалы
- Сущность Workload — принадлежащий платформе вид Workload, который транслирует провайдер compose.
- Архитектура сущностей Provider — как провайдеры встраиваются в конвейер компиляции.
- Общеизвестные аннотации — аннотации
aggrega.ai/*, которые использует провайдер compose. - Указатель справочника по сущностям Provider — что создаёт каждый провайдер стандартной библиотеки и какая страница отвечает на какой вопрос.
- Композиция входных данных сущности Recipe — каноническая матрица возможностей сущностей Provider (Provider Capability Matrix).