Compose Projects

Opfield обнаруживает внешние приложения Docker Compose и может управлять одновузловыми Compose Project как долговременными ресурсами. Проект объединяет службы, конфигурацию, неизменяемые ревизии, операции жизненного цикла, журналы, Routes и привязки баз данных под одной стабильной идентичностью.

Внешнее обнаружение доступно на любом тарифе. Для создания или принятия под управление одновузлового проекта требуется Personal или выше. Для сборки Compose из Git нужны Business или Enterprise и подключённый выделенный Build Worker.

Выбор между видимостью и владением

Обнаружение даёт команде общий обзор существующего приложения Compose, не меняя его владельца. Принятие под управление меняет модель владения: после него ревизии конфигурации и действия жизненного цикла выполняются в Opfield. Зафиксируйте передачу ответственности с владельцем приложения. Если после принятия продолжать независимый процесс docker compose, возникнут конкурирующие желаемые состояния.

Выбирайте управляемый Compose Project, если несколько служб на одной ноде Docker нужно проверять, применять, останавливать, восстанавливать и аудировать как одно приложение. Владелец проекта должен определить зависимости служб, ответственность за данные, источники секретов, допустимое время простоя и условия отката конфигурации. Для подходящих проектов без монтирований Business и Enterprise позволяют включить Workload Availability (HA): реплицировать проект целиком или заменить обслуживающий экземпляр при потере узла. Службы каждого экземпляра остаются на одном узле; Opfield не распределяет отдельные службы Compose по кластеру.

Успешный проект имеет одного понятного владельца конфигурации, воспроизводимую активную ревизию, работоспособные обязательные службы, известные постоянные тома, работающие Routes и приватные привязки и не содержит необъяснимых расхождений состояния.

Внешние и управляемые проекты

External-проект обнаруживается по каноническим меткам Docker Compose на его контейнерах, томах и сетях. Opfield показывает инвентарь, общее состояние, состояние служб, мониторинг и объединённые журналы, а пользователи с нужными правами могут открыть консоль или файловый браузер контейнера службы. Внешние проекты доступны только для чтения: Opfield не читает Compose-файл с хоста и не предлагает запуск, остановку, перезапуск, ревизии, секреты или удаление, пока оператор явно не примет проект под управление. Продолжайте управлять внешним проектом через исходный процесс docker compose или примите его под управление. Модель доступа описана в разделе Операции без принятия под управление.

Managed-проект хранит в Opfield исходный Compose YAML, переменные, защищённые ключи секретов и неизменяемые ревизии. Docker-демон применяет выбранную ревизию через зафиксированную среду выполнения Compose в Opfield. Одноузловой жизненный цикл доступен с Personal. Многоузловая Workload Availability доступна на Business и Enterprise; автомасштабирование по метрикам и несколько реплик на одном узле остаются In development.

Дочерние Containers проекта, именованные тома и сети, не отмеченные как external, управляются через Compose Project. Они скрыты или защищены от конфликтующих автономных операций жизненного цикла: отдельный контейнер Compose нельзя запустить, остановить, перезапустить, изменить, пересоздать или удалить сам по себе — ни во внешнем, ни в управляемом проекте. Действия жизненного цикла применяются ко всему проекту. Образы и явно внешние или общие ресурсы остаются глобальными ресурсами Docker.

Создайте управляемый проект

1. Откройте Docker > Compose и выберите New Project.
2. Выберите подключённую ноду Docker с поддержкой Compose.
3. Введите полную конфигурацию Compose в одном файле.
4. Укажите несекретные переменные и отдельно перечислите защищённые ключи секретов.
5. Запустите валидацию и устраните неподдерживаемые параметры, отсутствующие переменные, конфликты портов и нарушения политики.
6. Создайте проект и проследите первую операцию применения до завершения.
7. Проверьте все ожидаемые службы, их состояние, сеть, тома и объединённый поток журналов.

Проекты, созданные вручную, используют только готовые образы: целевая нода должна иметь возможность их загрузить. На тарифах Business и Enterprise можно подключить разрешённый источник Git. Тогда ограниченные секции Compose build выполняются изолированными Build Workers, результат проверяется политикой уязвимостей, а одобренные дайджесты образов фиксируются в неизменяемой ревизии до развёртывания.

Примите внешний проект во владение

Принятие под управление — явная передача ответственности. Для него нужны тариф Personal или выше и права docker:compose:create и docker:compose:manage на проект. Откройте обнаруженный проект, выберите Adopt into Opfield и вставьте полную конфигурацию, за которую должен отвечать Opfield. Opfield не читает Compose-файл с хоста, поэтому редактор открывается пустым. Opfield проверяет YAML, сохраняет его как первую неизменяемую ревизию и применяет её по кнопке Adopt & Apply.

Убедитесь, что переданный YAML соответствует работающим службам приложения, томам, сетям, переменным и секретам. Opfield не считает путь на хосте, полученный из метки, доверенным источником конфигурации. После принятия все изменения должны проходить через новые ревизии, а не через прямое изменение дочернего Container.

Что сохраняется и что меняется при принятии

• Имя проекта. Принятый проект сохраняет имя, которое уже сообщает Docker, и Opfield выполняет все операции с этим именем проекта Compose. Opfield не переименовывает проект, его службы и тома и не добавляет к ним префиксы. Ключ верхнего уровня name: в YAML необязателен, но если он указан, то должен совпадать с именем проекта.
• Именованные тома. Поскольку имя проекта не меняется, Docker Compose вычисляет те же имена томов, что и раньше, — по умолчанию <project>_<volume> или явное name: тома — и повторно использует существующие тома вместе с данными. Тома с external: true подключаются, а не создаются. До первого применения сравните тома, показанные у обнаруженного проекта, с томами, которые получаются из переданного YAML: переименованный ключ тома создаст новый пустой том.
• Контейнеры. Opfield добавляет к каждой службе собственные метки управления, поэтому при первом применении контейнеры служб, скорее всего, будут пересозданы. Запланируйте короткое окно обслуживания.
• Переменные окружения и секреты. env_file и файл .env проекта не используются. Объявляйте переменные в environment: каждой службы и подставляйте значения через ${NAME}. При применении ревизии Opfield передаёт для подстановки несекретные переменные и зашифрованные секреты проекта. Вкладки Variables и Secrets в Console становятся доступны после принятия; для значений, которые вы добавите туда, используйте заполнители ${NAME}.
• Привязки каталогов хоста. Bind mounts отклоняются, включая относительные пути вроде ./config:/etc/app, пути с ~ и источники, собранные из переменных. До принятия перенесите файлы конфигурации в образ или именованный том.
• Разовые задачи. В Opfield нет аналога docker compose run и нет хуков перед развёртыванием или релизом. Для шага миграции выполните команду в контейнере службы через консоль (нужно право docker:containers:console) или оформите её как службу с restart: "no", завершения которой другие службы ждут через depends_on. Используйте condition: service_completed_successfully, если другие службы должны дождаться завершения задачи. Разовая служба, завершившаяся с кодом 0, считается выполненной и не переводит проект в статус degraded.

Поддерживаемая конфигурация Compose

Ручные и принятые ревизии принимают однофайловый документ Compose размером до 1 МиБ без якорей и псевдонимов YAML. На верхнем уровне допустимы только name, version, services, volumes и networks, поэтому include, secrets и configs верхнего уровня и расширения x- отклоняются.

Каждая служба должна использовать image и может содержать только ключи image, command, entrypoint, working_dir, user, hostname, environment, labels, ports, volumes, networks, depends_on, healthcheck, restart, extra_hosts, cpus, cpu_shares, mem_limit, mem_reservation, memswap_limit, pids_limit и logging. Всё остальное отклоняется, в том числе build, env_file, container_name, privileged, cap_add, devices, network_mode, pid, ipc, security_opt, tmpfs, ulimits, deploy, profiles, extends, secrets и configs на уровне службы, а также links.

Другие правила:

• restart может принимать только значения no, always, on-failure или unless-stopped;
• порты не могут задаваться диапазонами и должны использовать TCP или UDP;
• для сети службы можно указать только aliases, а каждая сеть, которую использует служба, кроме неявной сети default, должна быть объявлена на верхнем уровне;
• каждый именованный том, который монтирует служба, должен быть объявлен на верхнем уровне;
• в длинном синтаксисе монтирования тома допустимы только type, source, target и read_only; type обязателен (иначе VOLUME_TYPE_REQUIRED) и должен быть type: volume, а источником должен быть именованный том;
• depends_on принимает список служб или развёрнутую форму; в развёрнутой форме для каждой записи допустим только condition, он обязателен и должен быть service_started, service_healthy или service_completed_successfully; каждая зависимость должна быть службой из того же файла;
• для томов и сетей верхнего уровня допустимы только external, name, driver и labels, поэтому driver_opts отклоняется;
• в logging допустимы только driver и options; драйвер должен быть json-file, local или none, а среди опций допустимы только max-size, max-file и compress (у none опций нет);
• метки с префиксами com.docker.compose., wiolett.gateway., net.wiolett.gateway. и com.wiolett.gateway., а также метка gateway.sandbox зарезервированы, а ключ метки, собранный из переменной, отклоняется;
• сеть не может быть сетью хоста (host или none) или одной из внутренних сетей Opfield (gateway-secure-links, gateway-db-*, gateway-storage-*), а имя сети, собранное из переменной, отклоняется;
• переменные и секреты не могут называться так, как переменные, которые читает сам клиент Compose: PATH, DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY, DOCKER_TLS, DOCKER_API_VERSION, DOCKER_DEFAULT_PLATFORM, DOCKER_BUILDKIT, а также любые имена с префиксом BUILDKIT_ или COMPOSE_; остальные имена DOCKER_* остаются обычными переменными;
• каждой ссылке ${NAME} нужна заданная переменная или секрет.

Проект, сохранённый до появления этих правил для сетей, меток и переменных, продолжает работать, и его по-прежнему можно остановить и опустить, но создание ревизии, применение, запуск и перезапуск отклоняются, пока его конфигурация не будет им соответствовать. Это касается и первого применения после обновления Docker-демона.

На ноде, где драйвер журналов по умолчанию — json-file, Docker-демон даёт каждой службе без logging ротацию json-file 50 МБ × 3, такую же, как у одиночных контейнеров. Чтобы хранить журналы службы дольше, задайте свои max-size и max-file; driver: json-file без опций оставляет безлимитный режим Docker по умолчанию. Docker не умеет менять настройки журналов у существующего контейнера. Поэтому после обновления до 2.11 первое применение один раз пересоздаёт каждую службу, даже если ревизия не менялась: каждая служба получает новые настройки журналов и метку с дайджестом собственной конфигурации. После этого применение пересоздаёт только службы, конфигурация которых изменилась. Нода, Docker-демон которой ещё не обновлён, применяет ревизии без разделов logging и оставляет параметры Docker по умолчанию.

Opfield и Docker-демон применяют одни и те же правила, поэтому ревизия, прошедшая проверку, не будет отклонена позже при применении. Проекты Business и Enterprise с источником Git могут дополнительно использовать ограниченную секцию build; см. Создайте управляемый проект. Те же правила действуют для ревизий, созданных через API, MCP или AI Workspace. Переписывание Compose-файла под эти правила — часть планирования принятия, поэтому сначала выполните его в тестовой среде.

Ревизии и жизненный цикл

Изменение конфигурации создаёт новую неизменяемую ревизию. Используйте Pull & Apply, чтобы загрузить нужные образы и применить активную ревизию, Start и Stop — для управления жизненным циклом проекта, а Change revision — для повторного применения прежней корректной ревизии. Неактивную ревизию можно удалить, если её не использует ни одна операция; активную удалять нельзя.

Применение ревизии пересоздаёт только службы, собственное описание которых изменилось — образ, окружение, команда, порты, тома, сети, ограничения, метки, журналы или другое поле службы, — либо изменились подставляемые в них переменные или секреты; остальные службы продолжают работать. Pull & Apply также пересоздаёт службу, тег образа которой теперь указывает на более новый образ. Размещения проекта под Workload Availability по-прежнему помечены дайджестом всей ревизии, поэтому новая ревизия пересоздаёт все их службы. Применение без загрузки образов скачивает только те образы, которых нет на ноде. Ревизия, опубликованный TCP-порт которой на ноде уже занимает Deployment, реплика Availability, управляемая база данных или управляемое хранилище, отклоняется при создании с кодом 409 COMPOSE_HOST_PORT_IN_USE; для проекта, собираемого из Git, сборка завершается ошибкой с этим сообщением, а ревизия не создаётся. Проект получает статус degraded, если одна из его служб остановилась вне Opfield, и страница состояния это показывает. Если у проекта включена Workload Availability, запуск, остановка или перезапуск, запрошенные во время предыдущей операции Availability, ставятся в очередь и выполняются после неё.

Операции жизненного цикла сохраняются долговременно и представлены Tasks. Перезагрузка страницы не отменяет операцию. Пока сборка из Git развёртывается в проект, действия с ревизиями, жизненным циклом, секретами и удалением возвращают BUILD_ROLLOUT_IN_PROGRESS до завершения развёртывания; отменить операцию по-прежнему можно. Во время обновления Opfield новые операции Compose отклоняются с GATEWAY_UPDATING. Если доступна отмена, до запуска заменяющего действия обновите страницу проекта и состояние, сообщённое демоном.

Routes и привязки баз данных

Routes и Secure Links могут обращаться к управляемой службе Compose по стабильным идентичностям проекта и службы, а не по временному имени Container. Управляемая привязка базы данных обновляет ревизию проекта, сохраняя исходную конфигурацию и защищённые секреты. Удаление службы или привязки должно проходить через новую ревизию, чтобы Opfield мог безопасно согласовать зависимые связи. Применение более старой ревизии сохраняет текущие привязки; ревизия, в которой нет привязанной службы, отклоняется, пока эта привязка не удалена. Через API, MCP или ассистента службу можно привязать ещё до первой ревизии проекта; см. Рабочая нагрузка не запущена.

Новая ревизия несёт привязку к базе данных целиком — её сеть, переменные и имя хоста приватного адреса привязки, — поэтому её применение за одну операцию запускает службу, которая сразу находит базу данных. Добавление, удаление или восстановление привязки у работающего проекта применяет проект один раз, без загрузки его образов и без пересоздания остальных служб. Проект, собираемый из источника Git, тоже может получать и снимать привязки: Opfield применяет копию собранной ревизии, в которой сохраняются Compose-файл репозитория и его происхождение из Git, а следующий push сохраняет привязку и её секреты. Обзор проекта показывает состояние каждой привязки: открытые соединения относительно её ёмкости в 64 соединения и отклонённые соединения; см. Ёмкость привязки.

Привязки доступны только для управляемых баз данных. Чтобы подключиться к внешней базе, передайте параметры подключения через переменные и секреты; см. Управляемые и внешние базы данных: сравнение. Привязки управляемых хранилищ для служб Compose недоступны; вместо этого передайте службе учётные данные S3 ключа доступа через переменные и секреты.

Служба Compose может обращаться к одному порту другой рабочей нагрузки или принимать такие обращения через связь контейнеров: добавьте её в блоке Container Links на вкладке Variables проекта и выберите службу-потребителя.

Расхождения и диагностика

Opfield сообщает о расхождении, если наблюдаемое состояние среды выполнения больше не соответствует активной ревизии. До повторной попытки откройте текущую операцию и проверьте соединение ноды Docker, поддержку Compose, доступ к загрузке образа, журналы служб, переменные, секреты и диагностику демона. По этапу и сообщению Task определите ответственный уровень, исправьте предварительное условие и снова запустите поддерживаемое действие.

Не исправляйте управляемый проект ручным удалением его дочерних Containers, сетей или метаданных ревизии. Для внешнего проекта до завершения принятия вносите изменения через исходный процесс Compose.

Удалите проект

Остановите управляемый проект и удалите зависимые Routes или привязки до удаления самого проекта. Удаление проекта, на который ещё указывает Route, Additional Route или Additional Secure Link, отклоняется с 409 PROXY_UPSTREAM_IN_USE до того, как что-либо будет удалено, а удаление проекта с привязками баз данных — с 409 COMPOSE_DATABASE_BINDINGS_EXIST. Удаление управляемого проекта удаляет его контейнеры, сети без пометки external, ревизии, секреты и все тома с метками Docker Compose этого проекта — то есть и именованные тома, которые Compose создал для проекта. Ресурсы, не принадлежащие проекту, например отдельно созданные тома, объявленные как external: true, не удаляются. До удаления создайте резервную копию постоянных данных. Внешние проекты удалить из Opfield нельзя.

Операторские детали: восстановление ревизии

До применения ревизии сравните её службы, образы, переменные, секреты, тома, сети и открытые порты с активной ревизией. Зафиксируйте порядок миграции и запуска приложения, если службы нельзя безопасно перезапустить одновременно. Pull & Apply может заменить среды выполнения служб и не гарантирует непрерывность существующих соединений.

Если операция прервалась, дождитесь подключения ноды Docker и обновите наблюдаемое состояние проекта до нового применения. В списке последних операций определите этап сбоя: загрузка образа, подготовка конфигурации, создание службы, проверка состояния или итоговое подтверждение. Если активная ревизия заведомо исправна, а новая непригодна, выберите прежнюю через Change revision и проверьте полный путь приложения.

Откат меняет конфигурацию Compose и среды выполнения, но не отменяет записи во внешние системы или постоянные тома. Для обратно несовместимых миграций базы данных нужен отдельный план восстановления. Не удаляйте дочерние Containers или сети проекта ради принудительного согласования: это уничтожает диагностические данные и может помешать управляемой очистке.