Compose Provider
Compose provider рендерить сутності Aggrega Recipes у файл Docker Compose. Provider виконує збирання окремо для кожної пари (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, у який відображається відповідний варіант Volume: запис 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 у Полях рівня pod не змінюється: compose не має аналога класу середовища виконання, тож 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. Для Secret або шаблонів томів для кожної репліки в Compose немає еквівалента Kubernetes, тож ці варіанти деградують до найближчого примітива 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, згенеровані з artifacts). Посилання configs: містить ім’я конфігурації та шлях монтування й нічого більше, тому readOnly монтування не має окремого вираження |
secret | bind-монтування volumes у довгій формі, лише для читання | Том секрету навмисно не слідує трансляції configmap: вбудований запис configs: записав би значення секрету у згенерований файл compose відкритим текстом, а компілятор ніколи не розкриває секрет у відкритий текст — секрет залишається вказівником на кожному етапі збирання. Джерелом прив’язки є ім’я 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 має рівно одну трансляцію — монтування прив’язки лише для читання, наведене вище, — і том не має поля 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 або монтування прив’язки відповідно, — тож якщо жоден контейнер їх не монтує, оголошений вами том не залишає у виході жодного сліду. Саме через цей другий випадок і існує попередження: без нього том 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 прив’язується лише до loopback-адреси IPv4. Loopback-адреса IPv6 ::1 не прив’язується: синтаксис портів compose містить одну адресу хоста на запис, а хост, loopback-інтерфейс якого не має адреси 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-сервіс так не робить: він приєднується до мережі межі самостійно, бо спільний простір імен з основним сервісом зробив би очікування основного сервісу на нього циклічним. Отже, робоче навантаження з 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-контейнери виконуються до завершення в тому порядку, в якому їх записано, а кожен інший контейнер запускається лише після завершення всіх них, — виражається довгою формою 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 рівня pod не застосовуються — те саме правило, якого дотримуються sidecar-сервіси, за винятком користувача пода, який поширюється на кожен сервіс, як описано в розділі Поля рівня пода.
- Init-сервіс приєднується до мережі своєї межі безпосередньо, а не спільно використовує мережевий простір імен основного сервісу, як це робить sidecar. Інакше не можна: основний сервіс чекає на init-сервіс, а спільний простір імен сам по собі є залежністю від основного сервісу, що замкнуло б очікування в цикл, який compose відмовляється запускати. Тому init-контейнер звертається до інших сервісів у мережі межі за іменем сервісу, але не має спільного з основним сервісом
localhost.
Init-сервіси й sidecar-сервіси мають спільний простір імен, бо і ті, і інші називає одна схема іменування, тому запис initContainers і запис containers не можуть мати однакове ім’я. Якщо так стається, компілятор зупиняється з TRANSLATION_ERROR, що називає вузол, ім’я контейнера та ім’я сервісу, на яке претендували обидва, замість того щоб дозволити одному сервісу непомітно замінити інший.
Виведення умови завершення не підвищує мінімальну версію Compose. condition та її значення належать до базової Compose Specification — на відміну від полів restart і required поряд із ними в тому самому блоці довгої форми, які специфікація пов’язує з певними випусками Compose. Кожна мінімальна версія, якої вимагає вивід compose-провайдера, з’являється разом із конструкцією, що її потребує: ≥ 2.23.1 для вбудованого configs.content, ≥ 2.26.0 для subPath монтування (див. Томи) і 2.38 для моделей. Перша з них стосується будь-якого виводу compose, що містить config із вбудованим content:, — саме так надходять і файл за томом configmap, і config за мостовим міжмережевим ребром, — а не одного шляху авторингу.
До якої мережі приєднується сервіс
Кожен сервіс приєднується до мережі 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 застосовується лише в межах підмножини Release, яку обслуговує compose.
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-провайдера вказує на YAML-файл docker-compose, який провайдер може прочитати й розібрати, і приймає обидві форми, яких набуває поле source:: простий рядок шляху у файловій системі та структурований об’єкт, чиє поле url: містить розташування. Якщо це розташування є шляхом у файловій системі, воно відраховується від каталогу, що містить recipe.yaml, який його оголошує, а не від каталогу, з якого запущено збірку, і має залишатися всередині цього каталогу: шлях, що виходить за його межі, або абсолютний шлях відхиляється, оскільки кожен файл, який містить публікація сутності Recipe, береться з її каталогу — див. entities/recipe.md «Шляхи до вмісту залишаються всередині власного каталогу 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_contextsservice:<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:, яке обчислюється в YAML compose. Сутність 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 обчислюється в compose YAML — фрагмент із власними блоками services:, volumes:, configs:, models: або networks: (кожен запис вбудований або завантажений окремо через $import:), — злиття в збірку для кожного (path, provider) відбувається за правилами, що залежать від форми:
services:з artifacts зливаються у зібраний файл compose поряд із сервісами окремих компонентів. Ім’я сервісу, яке надають два різні компоненти за одним шляхом збірки, зупиняє збірку, а діагностика називає кожного учасника. Колізія в межах одного компонента — між власним фрагментом артефакту цього компонента та сервісами, синтезованими для нього, — не виявляється, і пізніший внесок замінює раніший, тож ім’я сервісу, написане в артефакті, має відрізнятися від імен<component>і<component>--<container-name>, які створює синтезатор (див. Як називається sidecar- або init-сервіс).volumes:з artifacts зливаються у блокvolumes:верхнього рівня. Два записи з одним ім’ям залишають під ним один запис, якщо оголошують його однаково, — за тим самим правилом, що й томи окремих компонентів; два, що оголошують його по-різному, зупиняють збірку незалежно від того, чи походять вони з двох компонентів, чи з двох фрагментів одного — двох його записівartifacts:або одного з них і власного файлу compose компонента. Оскільки фрагмент артефакту пише власні тіла, саме на цьому шляху два учасники найімовірніше розійдуться. Ім’я тому, написане в артефакті, має відрізнятися від інших за його шляхом збірки, зокрема від форми<component>--<volume-name>, яку створює виведення, — хіба що два учасники мають описувати один спільний том, і тоді їхні оголошення мусять збігатися.configs:з artifacts зливаються у блокconfigs:верхнього рівня. Саме так файл, що стоїть за томомconfigmap, потрапляє у збірку: том стає посиланнямconfigs:на рівні сервісу, що називає configmap, а фрагмент артефакту оголошує запис із цим ім’ям і вбудованимcontent:. Після об’єднання фрагментів шляху збірки кожне посилання на рівні сервісу мусить вказувати на оголошений запис, інакше збірка зупиняється зTRANSLATION_ERROR, називаючи кожне нерозв’язане посилання — сервіс, ім’я конфігурації та шлях монтування. Перевірка виконується над завершеним об’єднанням, а не для кожного компонента окремо, тож один компонент може посилатися на конфігурацію, яку оголошує інший компонент за тим самим шляхом збірки. Об’єднання узгоджує записи за іменем, коли учасники згодні: два, що оголошують одне ім’я конфігурації з ідентичнимcontent:, залишають єдиний запис, який обидва описали. Два, що оголошують одне ім’я з різнимcontent:, зупиняють збірку зTRANSLATION_ERROR, називаючи конфігурацію та кожен кортеж(boundary, node, fragment)учасників, зокрема й два фрагменти одного компонента, — запис конфігурації завжди має вміст, тож збереження будь-якого з оголошень відкинуло б файл, написаний автором. Тримайте ім’я конфігурації унікальним серед усіх учасників за її шляхом збірки або робіть оголошення ідентичними, коли два учасники мають постачати один спільний файл.models:з artifacts зливаються у блокmodels:верхнього рівня, а посиланняmodels:сервісу переміщується разом із сервісом за правилами з розділу Моделі: два учасники, що оголошують одне ім’я моделі, мусять оголошувати її однаково, а кожне посилання мусить називати модель, яку оголошує якийсь учасник за цим шляхом збірки.networks:з artifacts відхиляються. Провайдер compose виводить мережі з анотацій меж (одна мережа на кожну окрему анотаціюaggrega.ai/namespace, а також одна, названа за шляхом файлу compose, до якої приєднується кожен вузол без такої анотації; кожну названо згідно з розділом Як виводиться ім’я мережі), тож оголошенню мережі, наданому артефактом, немає місця в зібраному файлі: будь-який запис зупиняє збірку, називаючи запис і фрагмент, за правилами розділу Кожен ключ, який пише фрагмент, переноситься або відхиляється. Видаліть запис і формуйте мережі через анотацію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 можуть розширювати перше; формувати друге можуть лише анотації меж, і саме тому власний мережевий запис артефакту відхиляється. Члени-розширення — це дані, які 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; вона не чекає, доки перевірка здоров’я цілі повідомить про справний стан. Це стосується значення ребраuses, а не форми, яку провайдер не може створити: довга форма виводиться для очікування init-контейнера, а хвиля розгортання таки чекає на здоров’я цілі, якщо ціль оголошує перевірку здоров’я.
Приклад створення
Розгортання 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.