Конфигурация как код с dockup.yaml: безопасные plan и apply

dockup.yaml превращает конфигурацию сервиса в артефакт репозитория, который можно просматривать и обсуждать. Вместо того чтобы полагаться на состояние dashboard, которое кто-то помнит, команда может задать в одном файле branch, port, команды сборки и запуска, health checks, обычные значения environment и домены.

Dockup разделяет проверку и изменение состояния. dockup plan показывает разницу между manifest и работающим сервисом, ничего не изменяя. dockup up применяет объявленные изменения. Удаление остаётся opt-in и выполняется через --prune.

Что можно объявить в dockup.yaml?

Manifest сервиса может содержать production-настройки, которые полезно подвергать code review:

service:
  branch: main
  port: 3000
  dockerfile: Dockerfile
  build: npm run build
  start: npm start
  healthcheck:
    path: /health
    interval: 5
    timeout: 3
    retries: 5
  env:
    NODE_ENV: production
    API_URL: https://api.example.com
  domains:
    - api.example.com
    - { domain: admin.example.com, port: 4000 }

По умолчанию файл размещается в корне репозитория. Другой путь можно выбрать с помощью --file.

Не размещайте секреты в mapping env. Manifest коммитится, проходит review, кэшируется и копируется так же, как другие исходные файлы. Для credentials используйте dockup env set --secret или утверждённый процесс injection секретов.

Потребление CPU, RAM и диска по-прежнему зависит от использования и рассчитывается поминутно в рамках баланса плана; manifest должен описывать конфигурацию сервиса, а не предположения о billing.

Как dockup plan показывает drift конфигурации?

Перед каждым apply выполняйте read-only сравнение:

dockup plan production/api --json

Результат содержит изменения с аспектами, полями, старыми и новыми значениями, а также действиями. В plan может быть указано, что изменился branch, отличается health path, будет добавлен домен или изменилось обычное значение environment.

Plan особенно полезен в пяти ситуациях:

Ситуация	Что показывает plan
Pull request изменяет manifest	Планируемый эффект для production до merge
Dashboard изменён вручную	Drift относительно исходного кода в репозитории
Agent предлагает обновление	Точные поля, которые agent собирается изменить
Восстановление после инцидента	Отличается ли текущее состояние от известной конфигурации
Настройка нескольких окружений	Различия между manifest для production и staging

Plan не блокирует сервис. Состояние может измениться между plan и apply, поэтому в workflows с высоким риском следует проводить review и up с минимальным интервалом и проверять результат apply.

Coding agent должен возвращать JSON plan или краткое резюме по каждому полю. Формулировка «Конфигурация выглядит хорошо» не является достаточным артефактом review.

Как dockup up применяет конфигурацию как код?

Примените manifest по умолчанию:

dockup up production/api --json

Примените изменения и затем запустите deployment:

dockup up production/api --deploy --json

Используйте другой файл для staging:

dockup plan production/api \
  --file dockup.production.yaml \
  --json

dockup up production/api \
  --file dockup.production.yaml \
  --deploy \
  --json

Результат apply сообщает, какие изменения были применены или пропущены, и может содержать ID deployment, если используется --deploy. При этом сам deployment следует проверять по terminal state, когда это уместно: изменение конфигурации и успешный production release — разные результаты.

Значения секретов остаются за пределами manifest. Перед применением конфигурации задайте их через workflow для secret environment, затем выполните deployment и проверьте получившийся container, не выводя сохранённое значение.

Почему config as code по умолчанию работает в additive-режиме?

Самая безопасная интерпретация неполного manifest — «управлять объявленными значениями», а не «удалить всё остальное». Поэтому Dockup оставляет без изменений environment variables и домены, отсутствующие в файле.

Это важно при постепенном внедрении. В сервисе уже могут быть secret variables, operational domains или временная конфигурация, которые ещё не были описаны в manifest. Первый up не должен их удалять.

Гарантии безопасности конкретны:

• dockup up не удаляет services, databases или volumes.
• Существующие secret variables не перезаписываются обычными значениями из manifest.
• Secret variables не подвергаются prune.
• Автоматическое применение manifest во время deploy работает в additive-режиме.
• Некорректный manifest не превращается незаметно в destructive cleanup.

Additive-поведение делает dockup.yaml подходящим для постепенного GitOps workflow. Но это также означает, что manifest не считается автоматически полным inventory, если команда специально не включила pruning для поддерживаемых полей.

Как следует проверять --prune?

--prune удаляет поддерживаемые обычные значения environment и домены, отсутствующие в manifest:

dockup plan production/api --json
dockup up production/api --prune --json

Считайте этот flag destructive-запросом. Проверьте plan, укажите точную цель и получите human approval, если agent работает с production.

Операция не распространяется на secrets, services, databases или volumes. У этих ресурсов собственный lifecycle и отдельные пути подтверждения. Такое разделение не позволяет небольшому изменению manifest привести к масштабному удалению infrastructure.

Полезная запись об approval выглядит так: «Применить dockup.yaml к production/api и удалить два обычных variable и один домен, указанные в plan X». Это не должно быть общим разрешением, которое можно повторно использовать для будущих plan.

Более подробно модель подтверждений описана в статье production guardrails для AI agents.

Как командам выстроить GitOps workflow с dockup.yaml?

Сохраняйте workflow простым:

1. Developer или agent изменяет dockup.yaml.
2. CI проверяет синтаксис YAML и application tests.
3. Для нужной target-среды запускается read-only dockup plan.
4. В pull request отображаются и diff исходного файла, и plan live state.
5. Reviewer одобряет изменение.
6. dockup up --deploy применяет его.
7. Deployment ожидает terminal success.
8. Сохраняются status, logs и audit evidence.

Manifest не должен превращаться в свалку настроек. Когда это уместно, храните business configuration приложения в самом приложении. Используйте dockup.yaml для deployment- и runtime-настроек, которыми управляет граница ответственности сервиса.

Для разных окружений может быть понятнее использовать отдельные файлы, чем один файл с недокументированным templating layer. Например, используйте dockup.staging.yaml и dockup.production.yaml, явно передавая нужный файл.

Branch preview — это изолированный deployment, а production config остаётся отдельной целью для review. В проектах с private networking preview могут подключаться к project network и получать read-only доступ к database, не изменяя production manifest.

Для работы с credentials используйте руководство по environment variables и secrets, а описание readiness gate — в статье zero-downtime deployments.

Playbook при drift

Если dockup plan сообщает о неожиданных изменениях live state, не перезаписывайте их автоматически. Определите, была ли правка в dashboard экстренным исправлением, несанкционированным изменением или нужной настройкой, которую просто не закоммитили.

Затем выберите один source of truth:

• Обновите manifest, чтобы сохранить нужное live-значение.
• Примените manifest, чтобы восстановить значение, прошедшее review.
• Задокументируйте временное исключение, назначив владельца и срок действия.
• Изучите audit log, если происхождение изменения неизвестно.

dockup audit --writes --json

Так dockup.yaml остаётся authoritative source, а контекст инцидента не теряется.

Справочник Dockup CLI содержит актуальные поля manifest и параметры plan/up.

Проектируйте изменения manifest так, чтобы их было удобно проверять

Делайте каждое изменение достаточно небольшим, чтобы у plan была одна понятная цель. Если объединить в одном pull request изменение branch, увеличение ресурсов, добавление домена, переписывание health check и очистку environment, review и rollback становятся сложнее.

Используйте comments для объяснения необычных значений, но не дублируйте operational documentation внутри файла. Добавьте ссылку на repository runbook с описанием target сервиса, health semantics и approval policy. Manifest должен оставаться корректным YAML, который можно разобрать без custom preprocessor.

В полезном шаблоне pull request стоит запросить вывод dockup plan --json, ожидаемый эффект deployment, указание на необходимость --prune и ID предыдущего deployment. Это даёт AI agent или human reviewer одинаковый набор evidence.

Внедряйте manifest без нарушения текущего live state

Для существующего сервиса начните с полей, которые можно проверить. Выполните dockup info production/api --json, создайте минимальный dockup.yaml и сравните его с dockup plan. Добавляйте настройки поэтапно, а не пытайтесь сразу восстановить все исторические значения из dashboard.

Поскольку apply работает в additive-режиме, неуправляемые обычные значения и домены сохраняются в процессе внедрения. Когда manifest точно описывает нужную non-secret configuration, решите, будет ли команда использовать pruning. Некоторые команды выполняют cleanup вручную, другие разрешают --prune только в защищённом pipeline после approval plan.

Цель config as code — не увеличить число строк в Git. Она заключается в том, чтобы production intent был понятным, проверяемым и пригодным для восстановления.

Исключайте секретные данные из plan

Plan должен быть безопасным для добавления в pull request или incident record. Поскольку dockup.yaml содержит только обычные значения, а существующие secret values остаются защищёнными, reviewers могут проверять планируемую конфигурацию, не получая production credentials. Тем не менее проверяйте обычные значения на наличие internal hostnames, customer identifiers и других данных, которые не должны быть публичными.

Храните source и target вместе

Указывайте целевой project/service в pull request и deployment job. Корректный dockup.yaml, применённый не к тому target, всё равно является operational failure. Проверка target и review manifest — две отдельные обязательные проверки.

Проверяйте YAML до plan

Разбирайте manifest в CI до вызова Dockup, чтобы ошибки отступов или типов обнаруживались рядом с изменением исходного файла. Проверка syntax не заменяет dockup plan, но предотвращает ненужные запросы с нечитаемым файлом.

Предпочитайте один source of truth

Проверенный dockup.yaml должен объяснять production intent.

Начните с deployment, который можно проверить

Добавьте минимальный manifest для одного сервиса, выполните read-only plan и проверьте каждое обнаруженное поле перед первым apply.

Начните бесплатно на app.dockup.ai. План Free стоит $0 в месяц, включает стартовый кредит $10 и поддерживает один workspace, три databases и три deployments.

FAQ

Что такое dockup.yaml?

Это manifest Dockup в формате config as code, предназначенный для объявления branch сервиса, port, настроек build и start, health checks, обычных environment values и доменов.

Меняет ли dockup plan production?

Нет. dockup plan работает в read-only режиме и показывает разницу между manifest и работающим сервисом.

Удаляет ли dockup up конфигурацию, которой нет в файле?

По умолчанию нет. Apply работает в additive-режиме. Поддерживаемые обычные environment values и домены удаляются только при явном использовании --prune.

Можно ли хранить secrets в dockup.yaml?

Не следует. Коммитьте только обычные значения, а secrets задавайте через команду для secret environment или runtime secret injection. Существующие secrets защищены от pruning.

Может ли dockup up запустить deployment после применения конфигурации?

Да. Документированная опция --deploy применяет manifest и запускает deployment, terminal result которого затем следует проверить.