Конфігурація dockup.yaml як код: безпечне планування та застосування

dockup.yaml перетворює конфігурацію сервісу на артефакт репозиторію, який можна переглядати й перевіряти. Замість того щоб покладатися на стан dashboard, який хтось пам’ятає, команда може оголосити в одному файлі гілку, порт, команди build і start, 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, кешується та копіюється, як і інші source-файли. Для облікових даних використовуйте dockup env set --secret або схвалений процес ін’єкції секретів.

Використання CPU, RAM і диска залишається usage-based: воно вимірюється щохвилини відповідно до балансу плану. Manifest має описувати конфігурацію сервісу, а не припущення щодо billing.

Як dockup plan показує drift конфігурації?

Перед кожним apply виконуйте порівняння лише для читання:

dockup plan production/api --json

Результат містить зміни з аспектами, полями, старими та новими значеннями, а також діями. План може показати, що гілку змінено, health path відрізняється, домен буде додано або звичайне значення environment зазнало drift.

План особливо корисний у таких ситуаціях:

Ситуація	Що показує план
Pull request змінює manifest	Очікуваний вплив на production до merge
Dashboard відредаговано вручну	Drift від джерела в репозиторії
Agent пропонує оновлення	Точні поля, які agent планує змінити
Відновлення після інциденту	Чи відрізняється поточний стан від відомої конфігурації
Налаштування кількох середовищ	Відмінності між manifest для production і staging

Планування не блокує сервіс. Поточний стан може змінитися між plan і apply, тому в workflows із високим ризиком варто проводити review і up майже послідовно та перевіряти результат apply.

Coding agent має повертати JSON плану або стислий опис кожного поля. Фраза «Конфігурація виглядає добре» не є достатнім артефактом 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 показує, які зміни було застосовано або пропущено, і може містити deployment ID, якщо використано --deploy. Сам deployment усе одно має передбачати перевірку terminal state, коли це доречно: mutation конфігурації та успішний healthy production release — це різні результати.

Значення секретів залишаються за межами manifest. Установіть їх через workflow secret environment до застосування конфігурації, потім виконайте deploy і перевірте отриманий container, не виводячи збережене значення.

Чому конфігурація як код за замовчуванням є адитивною?

Найбезпечніше трактувати неповний manifest як «керувати оголошеними значеннями», а не як «видалити все інше». Тому Dockup не змінює environment variables і домени, відсутні у файлі.

Це важливо під час поступового впровадження. У сервісі вже можуть бути secret variables, operational domains або тимчасова конфігурація, які ще не описані в manifest. Перший up не має їх видаляти.

Гарантії безпеки є конкретними:

• dockup up не видаляє сервіси, бази даних або volumes.
• Наявні secret variables не перезаписуються звичайними значеннями з manifest.
• Secret variables не видаляються через prune.
• Автоматичне застосування manifest під час deploy є адитивним.
• Некоректний manifest не перетворюється непомітно на destructive cleanup.

Адитивна поведінка робить dockup.yaml придатним для поступового GitOps workflow. Водночас це означає, що manifest не є повним inventory автоматично, якщо команда свідомо не застосовує pruning для підтримуваних полів.

Як слід перевіряти --prune?

--prune видаляє підтримувані звичайні environment values і домени, відсутні в manifest:

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

Сприймайте цей flag як destructive request. Перевірте план, чітко вкажіть target і отримайте human approval, якщо agent працює з production.

Ця операція не поширюється на secrets, services, databases або volumes. Для цих ресурсів передбачено власний lifecycle і шляхи підтвердження. Такий поділ не дає невеликій зміні manifest перетворитися на широке видалення інфраструктури.

Корисний запис про approval має виглядати так: «Застосувати dockup.yaml до production/api і видалити через prune дві звичайні змінні та один домен, показані в плані X». Це не має бути багаторазовим blanket permission для майбутніх планів.

Ширшу модель підтверджень описано в матеріалі production guardrails for AI agents.

Як команди організовують GitOps workflow із dockup.yaml?

Підтримуйте workflow простим:

1. Developer або agent редагує dockup.yaml.
2. CI перевіряє синтаксис YAML і application tests.
3. Read-only dockup plan запускається для потрібного target.
4. Pull request містить і source diff, і план поточного стану.
5. Reviewer схвалює зміну.
6. dockup up --deploy застосовує її.
7. Deploy очікує на 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 залишається окремим target для review. У проєктах із private networking preview може під’єднуватися до project network і отримувати read-only доступ до database, не змінюючи production manifest.

Для роботи з обліковими даними дивіться guide щодо environment variables і secrets, а для readiness gate — матеріал zero-downtime deployments.

Playbook реагування на drift

Коли dockup plan повідомляє про неочікувані зміни в поточному стані, не перезаписуйте їх автоматично. Визначте, чи була зміна в dashboard екстреним виправленням, несанкціонованою зміною або потрібним налаштуванням, яке ніколи не закомітили.

Потім виберіть одне джерело істини:

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

dockup audit --writes --json

Цей процес зберігає dockup.yaml як authoritative source, не стираючи контекст інциденту.

Dockup CLI reference є джерелом актуальних полів manifest і параметрів plan/up.

Проєктуйте зміни manifest, зручні для review

Робіть кожну зміну достатньо малою, щоб план мав одну чітку мету. Поєднання зміни гілки, збільшення ресурсів, нового домену, переписування health check і очищення environment в одному pull request ускладнює і review, і rollback.

Використовуйте comments, щоб пояснювати нетипові значення, але не дублюйте operational documentation у файлі. Додайте посилання з repository runbook на target сервісу, semantics health check і policy approval. Manifest має залишатися валідним YAML, який можна розібрати без custom preprocessor.

Корисний template для pull request має запитувати output dockup plan --json, очікуваний вплив deployment, чи запитується --prune, а також ID попереднього deployment. Це дає AI agent або human reviewer однаковий набір evidence.

Впроваджуйте manifest без порушення поточного стану

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

Оскільки apply є адитивним, unmanaged plain values і домени зберігаються під час впровадження. Коли manifest точно описуватиме потрібну non-secret configuration, вирішіть, чи використовуватиме команда pruning взагалі. Деякі команди залишають cleanup ручним, інші дозволяють --prune лише в захищеному pipeline після approval плану.

Мета конфігурації як коду — не максимізувати кількість рядків у Git. Мета — зробити production intent зрозумілим, придатним для review і відновлення.

Не допускайте потрапляння секретних даних у плани

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

Тримайте source і target разом

Вказуйте потрібний project/service у pull request і deployment job. Валідний dockup.yaml, застосований не до того target, усе одно є operational failure. Discovery target і review manifest — це дві окремі обов’язкові перевірки.

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

Розбирайте manifest у CI до виклику Dockup, щоб помилки відступів або типів виявлялися безпосередньо біля source change. Перевірка синтаксису не замінює dockup plan; вона запобігає зайвим requests із файлом, який неможливо прочитати.

Віддавайте перевагу одному source

Перевірений dockup.yaml має пояснювати production intent.

Почніть із deployment, який можна перевірити

Додайте мінімальний manifest до одного сервісу, запустіть plan лише для читання та перевірте кожне повідомлене поле перед першим apply.

Почніть безкоштовно на app.dockup.ai. План Free коштує $0 на місяць, містить стартовий кредит $10 і підтримує один workspace, три databases та три deployments.

FAQ

Що таке dockup.yaml?

Це config-as-code manifest Dockup для оголошення гілки сервісу, порту, параметрів build і start, health checks, звичайних environment values та доменів.

Чи змінює dockup plan production?

Ні. dockup plan працює лише для читання та показує різницю між manifest і поточним сервісом.

Чи видаляє dockup up конфігурацію, якої немає у файлі?

За замовчуванням — ні. Apply є адитивним. Підтримувані звичайні environment values і домени видаляються лише за явного використання --prune.

Чи можна зберігати секрети в dockup.yaml?

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

Чи може dockup up виконати deploy після застосування конфігурації?

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