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

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

Dockup разделя проверката от промяната. dockup plan показва разликата между manifest файла и активната услуга, без да променя нищо. dockup up прилага декларираните промени. Изтриването остава изрично действие чрез --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 }

По подразбиране файлът се поставя в root директорията на repository-то. Можете да изберете друг път чрез --file.

Не поставяйте secret стойности в mapping-а env. Manifest файлът се commit-ва, преглежда, кешира и копира като всеки друг source файл. Използвайте dockup env set --secret или одобрен процес за инжектиране на secret стойности.

Консумацията на CPU, RAM и disk остава базирана на използването и се измерва на минута спрямо наличния баланс по плана; manifest файлът трябва да описва конфигурацията на услугата, а не предположенията за таксуване.

Как dockup plan показва configuration drift?

Изпълнявайте read-only сравнение преди всяко прилагане:

dockup plan production/api --json

Резултатът съдържа промените, включително aspects, fields, стари и нови стойности и actions. Планът може да покаже, че branch-ът е променен, health path-ът е различен, ще бъде добавен домейн или обикновена environment стойност се е отклонила от очакваната.

Планът е ценен в пет ситуации:

Ситуация	Какво показва планът
Pull request променя manifest файла	Очакваният ефект върху production преди merge
Dashboard е редактиран ръчно	Отклонението от source файла в repository-то
Agent предлага промяна	Точните полета, които agent-ът възнамерява да промени
Възстановяване след incident	Дали активното състояние вече се различава от познатата конфигурация
Multi-environment setup	Разликите между manifest файловете за production и staging

Планирането не заключва услугата. Активното състояние може да се промени между plan и apply, затова високорисковите workflow-и трябва да държат review и up възможно най-близо един до друг и да проверяват резултата от apply.

Coding agent-ът трябва да върне JSON-а на плана или кратко обобщение поле по поле. „Конфигурацията изглежда добре“ не е достатъчен артефакт за review.

Как dockup up прилага config as code?

Приложете 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, когато е уместно; промяната на конфигурацията и успешният production release са отделни резултати.

Secret стойностите остават извън manifest файла. Задайте ги чрез workflow-а за secret environment преди прилагане на конфигурацията, след което deploy-нете и проверете получения container, без да отпечатвате съхранената стойност.

Защо config as code е additive по подразбиране?

Най-безопасното тълкуване на непълен manifest файл е „управлявай декларираните стойности“, а не „изтрий всичко останало“. Затова Dockup оставя непроменени environment променливите и домейните, които отсъстват от файла.

Това е важно при постепенно внедряване. В дадена услуга може вече да има secret променливи, operational домейни или временна конфигурация, която все още не е описана. Първият up не трябва да ги изтрива.

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

• dockup up не изтрива услуги, бази данни или volumes.
• Съществуващите secret променливи не се презаписват с обикновени стойности от manifest файла.
• Secret променливите не се премахват чрез prune.
• Автоматичното прилагане на manifest файла по време на deploy е additive.
• Невалиден manifest файл не се превръща безшумно в разрушително почистване.

Additive поведението прави dockup.yaml подходящ за incremental GitOps workflow. Това също означава, че manifest файлът не е автоматично пълен inventory, освен ако екипът съзнателно не приеме pruning за поддържаните полета.

Как трябва да се преглежда --prune?

--prune премахва поддържаните обикновени environment стойности и домейни, които отсъстват от manifest файла:

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

Третирайте флага като destructive заявка. Прегледайте плана, посочете точния target и получете човешко одобрение, когато agent управлява production.

Операцията не обхваща secrets, услуги, бази данни или volumes. Тези ресурси имат собствен lifecycle и отделни пътища за потвърждение. Това разделяне предотвратява превръщането на малка промяна в manifest файла в широко инфраструктурно изтриване.

Полезен запис за одобрение гласи: „Приложете dockup.yaml към production/api и премахнете двете обикновени променливи и единия домейн, показани в план X.“ Той не трябва да бъде общо разрешение за бъдещи планове.

По-широкият модел за потвърждение е разгледан в production guardrails за AI агенти.

Как екипите изграждат GitOps workflow с dockup.yaml?

Поддържайте workflow-а прост:

1. Developer или agent редактира dockup.yaml.
2. CI валидира YAML синтаксиса и application тестовете.
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 доказателствата се запазват.

Manifest файлът не трябва да се превръща в място за всичко. Когато е подходящо, съхранявайте business конфигурацията на приложението в самото приложение. Използвайте dockup.yaml за deployment и runtime настройки, които принадлежат на границата на услугата.

Файловете за отделните среди може да са по-ясни от един файл с недокументиран templating layer. Например използвайте dockup.staging.yaml и dockup.production.yaml и подавайте изрично желания файл.

Branch preview е изолиран deployment, докато production конфигурацията остава отделна цел за review. При проекти с private networking preview-ите могат да се включат в project network-а и да получат read-only достъп до database, без да променят production manifest файла.

Използвайте ръководството за environment променливи и secrets за работа с credentials и deployment-и без прекъсване за readiness gate.

Playbook за реакция при drift

Когато dockup plan отчете неочаквани промени в активното състояние, не ги презаписвайте автоматично. Установете дали редакцията в dashboard е била emergency fix, неоторизирана промяна или желана настройка, която никога не е била commit-ната.

След това изберете един source of truth:

• Обновете manifest файла, за да запазите желаната активна стойност.
• Приложете manifest файла, за да възстановите прегледаната стойност.
• Документирайте временно изключение с отговорник и срок на валидност.
• Проучете audit log-а, когато произходът е неизвестен.

dockup audit --writes --json

Този процес запазва dockup.yaml като authoritative source, без да заличава контекста на incident-а.

Справочникът за Dockup CLI е източникът за актуалните полета на manifest файла и опциите на plan/up.

Проектирайте промени в manifest файла, които са лесни за review

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

Използвайте коментари, за да обясните необичайните стойности, но не дублирайте operational документацията във файла. Добавете link към repository runbook-а за service target-а, semantics на health check-а и policy-то за одобрение. Manifest файлът трябва да остане валиден YAML, който може да се parse-не без custom preprocessor.

Полезен pull-request template пита за изхода от dockup plan --json, очаквания ефект върху deployment-а, дали е заявен --prune и ID на предишния deployment. Така AI agent или human reviewer разполагат с едни и същи доказателства.

Въведете manifest файла, без да нарушавате активното състояние

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

Тъй като apply е additive, неуправляваните обикновени стойности и домейни остават, докато внедряването продължава. След като manifest файлът точно описва желаната non-secret конфигурация, решете дали екипът изобщо ще използва pruning. Някои екипи извършват почистването ръчно; други разрешават --prune само в защитен pipeline след одобрение на плана.

Целта на config as code не е да увеличи максимално броя редове в Git. Тя е да направи production намеренията разбираеми, преглеждаеми и възстановими.

Поддържайте плановете без secret материал

Планът трябва да е безопасен за добавяне към pull request или incident запис. Тъй като dockup.yaml съдържа само обикновени стойности, а съществуващите secret стойности остават защитени, reviewers могат да проверят желаната конфигурация, без да получават production credentials. Все пак проверявайте обикновените стойности за internal hostnames, customer идентификатори или други данни, които не трябва да бъдат публични.

Дръжте source файла и target-а заедно

Посочвайте целевия project/service в pull request-а и deployment job-а. Валиден dockup.yaml, приложен към грешния target, все пак е operational failure. Откриването на target-а и review-то на manifest файла са две отделни задължителни проверки.

Валидирайте YAML преди plan

Parse-вайте manifest файла в CI, преди да извикате Dockup, така че грешки в indentation или type да прекъсват процеса близо до source промяната. Syntax validation не заменя dockup plan; тя предотвратява ненужни заявки с файл, който не може да бъде прочетен.

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

Прегледаният dockup.yaml трябва да обяснява production намеренията.

Започнете с deployment, който може да бъде проверен

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

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

Често задавани въпроси

Какво е dockup.yaml?

Това е Dockup manifest файлът за config as code, чрез който се декларират branch-ът на услугата, port, build и start настройките, health checks, обикновените environment стойности и домейните.

Променя ли dockup plan production?

Не. dockup plan е read-only и показва разликата между manifest файла и активната услуга.

Изтрива ли dockup up конфигурацията, която не присъства във файла?

Не по подразбиране. Apply е additive. Поддържаните обикновени environment стойности и домейни се премахват само когато изрично се използва --prune.

Могат ли secrets да се съхраняват в dockup.yaml?

Не трябва. Commit-вайте само обикновени стойности; задавайте secrets чрез командата за secret environment или чрез runtime secret injection. Съществуващите secrets са защитени от pruning.

Може ли dockup up да deploy-не след прилагане на конфигурацията?

Да. Документираната опция --deploy прилага manifest файла и стартира deployment, чийто terminal резултат след това трябва да бъде проверен.