Konfiguracja jako kod w dockup.yaml: bezpieczne planowanie i wdrażanie

dockup.yaml zamienia konfigurację usługi w artefakt repozytorium, który można przejrzeć. Zamiast polegać na zapamiętanym stanie dashboardu zespół może zadeklarować w jednym pliku branch, port, polecenia build i start, health checki, zwykłe wartości zmiennych środowiskowych oraz domeny.

Dockup oddziela inspekcję od modyfikacji. dockup plan pokazuje różnicę między manifestem a działającą usługą bez wprowadzania zmian. dockup up stosuje zadeklarowane zmiany. Usuwanie pozostaje opcjonalne i wymaga użycia --prune.

Co można zadeklarować w dockup.yaml?

Manifest usługi może zawierać ustawienia produkcyjne, które warto poddawać 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 }

Plik jest domyślnie umieszczany w katalogu głównym repozytorium. Inną ścieżkę można wybrać za pomocą --file.

Nie umieszczaj sekretów w mapowaniu env. Manifest jest commitowany, przeglądany, cache’owany i kopiowany tak jak inne pliki źródłowe. W przypadku danych uwierzytelniających użyj dockup env set --secret albo zatwierdzonego procesu wstrzykiwania sekretów.

Zużycie CPU, RAM-u i miejsca na dysku nadal jest rozliczane według użycia i mierzone co minutę względem salda planu; manifest powinien opisywać konfigurację usługi, a nie założenia dotyczące rozliczeń.

Jak dockup plan pokazuje drift konfiguracji?

Przed każdym zastosowaniem zmian uruchom porównanie tylko do odczytu:

dockup plan production/api --json

Wynik zawiera zmiany wraz z aspektami, polami, starymi i nowymi wartościami oraz akcjami. Plan może pokazać, że zmienił się branch, ścieżka health checka jest inna, zostanie dodana domena albo zwykła wartość zmiennej środowiskowej uległa rozbieżności.

Plan jest szczególnie przydatny w pięciu sytuacjach:

Sytuacja	Co pokazuje plan
Pull request zmienia manifest	Zamierzony wpływ na produkcję przed scaleniem
Dashboard został ręcznie zmodyfikowany	Drift względem źródła w repozytorium
Agent proponuje aktualizację	Dokładne pola, które agent zamierza zmodyfikować
Odtwarzanie po incydencie	Czy bieżący stan już różni się od znanej konfiguracji
Konfiguracja wielu środowisk	Różnice między manifestami produkcji i stagingu

Plan nie blokuje usługi. Bieżący stan może zmienić się między wykonaniem planu a zastosowaniem zmian, dlatego w workflow wysokiego ryzyka warto przeprowadzać review i up bezpośrednio po sobie oraz sprawdzać wynik zastosowania zmian.

Agent kodujący powinien zwrócić JSON planu albo zwięzłe podsumowanie pole po polu. „Konfiguracja wygląda dobrze” nie jest wystarczającym artefaktem review.

Jak dockup up stosuje konfigurację jako kod?

Zastosuj domyślny manifest:

dockup up production/api --json

Zastosuj zmiany, a następnie uruchom deployment:

dockup up production/api --deploy --json

Użyj innego pliku dla stagingu:

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

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

Wynik zastosowania zmian informuje, które zmiany zostały zastosowane lub pominięte. Jeśli użyto --deploy, może również zawierać ID deploymentu. W razie potrzeby sam deployment powinien nadal być weryfikowany na podstawie stanu końcowego; modyfikacja konfiguracji i zdrowe wydanie produkcyjne to dwa odrębne rezultaty.

Wartości sekretów pozostają poza manifestem. Ustaw je za pomocą workflow sekretów środowiskowych przed zastosowaniem konfiguracji, a następnie wykonaj deployment i zweryfikuj wynikowy kontener bez wyświetlania zapisanej wartości.

Dlaczego konfiguracja jako kod jest domyślnie addytywna?

Najbezpieczniejsza interpretacja niekompletnego manifestu brzmi: „zarządzaj zadeklarowanymi wartościami”, a nie: „usuń wszystko inne”. Dlatego Dockup pozostawia bez zmian zmienne środowiskowe i domeny, których nie ma w pliku.

Ma to znaczenie podczas stopniowego wdrażania. Usługa może już zawierać zmienne z sekretami, domeny operacyjne albo tymczasową konfigurację, która nie została jeszcze opisana w manifeście. Pierwsze up nie powinno ich usuwać.

Gwarancje bezpieczeństwa są konkretne:

• dockup up nie usuwa usług, baz danych ani wolumenów.
• Istniejące zmienne z sekretami nie są nadpisywane zwykłymi wartościami z manifestu.
• Zmienne z sekretami nie są usuwane przez prune.
• Automatyczne stosowanie manifestu podczas deploymentu ma charakter addytywny.
• Nieprawidłowy manifest nie zamienia się po cichu w destrukcyjne czyszczenie.

Zachowanie addytywne sprawia, że dockup.yaml nadaje się do stopniowego workflow GitOps. Oznacza to również, że manifest nie jest automatycznie kompletną inwentaryzacją, chyba że zespół świadomie zdecyduje się na prune obsługiwanych pól.

Jak należy przeglądać opcję --prune?

--prune usuwa obsługiwane zwykłe wartości zmiennych środowiskowych i domeny, których nie ma w manifeście:

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

Traktuj tę flagę jako żądanie destrukcyjnej operacji. Przejrzyj plan, wskaż dokładny cel i uzyskaj zgodę człowieka, gdy agent działa na produkcji.

Operacja nie obejmuje sekretów, usług, baz danych ani wolumenów. Te zasoby mają własny cykl życia i osobne ścieżki potwierdzania. Takie rozdzielenie zapobiega sytuacji, w której niewielka zmiana manifestu prowadzi do szerokiego usunięcia infrastruktury.

Przydatny zapis akceptacji brzmi: „Zastosuj dockup.yaml do production/api i usuń przez prune dwie zwykłe zmienne oraz jedną domenę pokazane w planie X”. Nie powinien być uniwersalną zgodą na przyszłe plany.

Szerszy model potwierdzania omówiono w artykule production guardrails for AI agents.

Jak zespoły korzystają z workflow GitOps z dockup.yaml?

Zachowaj prosty workflow:

1. Developer lub agent edytuje dockup.yaml.
2. CI sprawdza składnię YAML i testy aplikacji.
3. Dla wybranego celu uruchamiany jest dockup plan tylko do odczytu.
4. Pull request pokazuje zarówno diff źródłowy, jak i plan bieżącego stanu.
5. Reviewer zatwierdza zmianę.
6. dockup up --deploy stosuje zmianę.
7. Deployment czeka na pomyślne zakończenie.
8. Zachowywane są status, logi i dowody w audit trail.

Manifest nie powinien stać się miejscem na wszystko. Odpowiednią konfigurację biznesową aplikacji pozostaw w samej aplikacji. Używaj dockup.yaml do ustawień deploymentu i runtime należących do granicy odpowiedzialności usługi.

Pliki zależne od środowiska mogą być czytelniejsze niż jeden plik z nieudokumentowaną warstwą templatingu. Możesz na przykład użyć dockup.staging.yaml i dockup.production.yaml, a następnie jawnie przekazać właściwy plik.

Preview brancha to odizolowany deployment, natomiast konfiguracja produkcji pozostaje osobnym celem review. W projektach z prywatną siecią preview może dołączyć do sieci projektu i otrzymać dostęp tylko do odczytu do bazy danych bez zmieniania manifestu produkcyjnego.

Skorzystaj z przewodnika po zmiennych środowiskowych i sekretach, aby poznać zasady obsługi danych uwierzytelniających, oraz z artykułu deploymenty bez przestoju, aby skonfigurować readiness gate.

Playbook reagowania na drift

Gdy dockup plan zgłasza nieoczekiwane zmiany w bieżącym stanie, nie nadpisuj ich automatycznie. Ustal, czy zmiana na dashboardzie była awaryjną poprawką, nieautoryzowaną modyfikacją, czy zamierzonym ustawieniem, którego nigdy nie zapisano w repozytorium.

Następnie wybierz jedno źródło prawdy:

• Zaktualizuj manifest, aby zachować zamierzoną wartość bieżącego stanu.
• Zastosuj manifest, aby przywrócić wartość zatwierdzoną w review.
• Udokumentuj tymczasowy wyjątek, wskazując właściciela i termin wygaśnięcia.
• Jeśli źródło jest nieznane, przeanalizuj audit log.

dockup audit --writes --json

Ten proces utrzymuje dockup.yaml jako źródło prawdy bez zacierania kontekstu incydentu.

Dokumentacja Dockup CLI jest źródłem aktualnych pól manifestu oraz opcji plan/up.

Projektuj zmiany manifestu tak, aby można je było łatwo przeglądać

Każda zmiana powinna być na tyle mała, aby plan miał jeden jasno określony cel. Połączenie zmiany brancha, zwiększenia zasobów, dodania nowej domeny, przepisania health checka i czyszczenia środowiska w jednym pull requeście utrudnia zarówno review, jak i rollback.

Używaj komentarzy do wyjaśniania nietypowych wartości, ale nie powielaj dokumentacji operacyjnej w pliku. Dodaj link do runbooka repozytorium opisującego target usługi, znaczenie health checków i zasady akceptacji. Manifest powinien pozostać poprawnym YAML-em, który można sparsować bez custom preprocessora.

Przydatny template pull requesta powinien wymagać wyniku dockup plan --json, oczekiwanego efektu deploymentu, informacji, czy żądano --prune, oraz ID poprzedniego deploymentu. Dzięki temu agent AI i reviewer mają te same dowody.

Wprowadź manifest bez zakłócania bieżącego stanu

W przypadku istniejącej usługi zacznij od pól, które możesz zweryfikować. Uruchom dockup info production/api --json, utwórz minimalny dockup.yaml i porównaj go za pomocą dockup plan. Dodawaj ustawienia etapami, zamiast od razu próbować odtworzyć wszystkie historyczne wybory z dashboardu.

Ponieważ zastosowanie zmian ma charakter addytywny, niezarządzane zwykłe wartości i domeny pozostają na miejscu podczas wdrażania manifestu. Gdy manifest będzie już dokładnie odzwierciedlał zamierzoną konfigurację niezawierającą sekretów, zdecyduj, czy zespół kiedykolwiek będzie korzystał z prune. Niektóre zespoły pozostawiają czyszczenie jako operację ręczną, a inne zezwalają na --prune wyłącznie w chronionym pipeline po akceptacji planu.

Celem konfiguracji jako kodu nie jest maksymalizowanie liczby linii w Git. Chodzi o to, aby intencja dotycząca produkcji była zrozumiała, możliwa do przejrzenia i możliwa do odtworzenia.

Nie umieszczaj sekretów w planach

Plan powinien nadawać się do dołączenia do pull requesta lub dokumentacji incydentu. Ponieważ dockup.yaml zawiera wyłącznie zwykłe wartości, a istniejące wartości sekretów pozostają chronione, reviewerzy mogą sprawdzić zamierzoną konfigurację bez otrzymywania poświadczeń produkcyjnych. Nadal należy jednak sprawdzać zwykłe wartości pod kątem wewnętrznych hostname’ów, identyfikatorów klientów i innych danych, które nie powinny być publiczne.

Przechowuj źródło i cel razem

W pull requeście i jobie deploymentu podaj docelowy project/service. Poprawny dockup.yaml zastosowany do niewłaściwego celu nadal oznacza awarię operacyjną. Wykrycie celu i review manifestu to dwie wymagane, odrębne kontrole.

Sprawdzaj YAML przed planem

Przeparsuj manifest w CI przed wywołaniem Dockup, aby błędy wcięć lub typów kończyły się blisko źródła zmiany. Walidacja składni nie zastępuje dockup plan; zapobiega jedynie zbędnym żądaniom z nieczytelnym plikiem.

Preferuj jedno źródło

Przejrzany w review dockup.yaml powinien wyjaśniać intencję dotyczącą produkcji.

Zacznij od deploymentu, który można zweryfikować

Dodaj minimalny manifest do jednej usługi, uruchom plan tylko do odczytu i przejrzyj każde zgłoszone pole przed pierwszym zastosowaniem zmian.

Zacznij bezpłatnie na app.dockup.ai. Plan Free kosztuje 0 USD miesięcznie, obejmuje 10 USD początkowego kredytu oraz obsługuje jeden workspace, trzy bazy danych i trzy deploymenty.

FAQ

Czym jest dockup.yaml?

To manifest Dockup w modelu konfiguracji jako kodu, służący do deklarowania brancha usługi, portu, ustawień build i start, health checków, zwykłych wartości środowiskowych oraz domen.

Czy dockup plan zmienia produkcję?

Nie. dockup plan działa tylko do odczytu i pokazuje różnicę między manifestem a działającą usługą.

Czy dockup up usuwa konfigurację, której nie ma w pliku?

Nie domyślnie. Zastosowanie zmian ma charakter addytywny. Obsługiwane zwykłe wartości zmiennych środowiskowych i domeny są usuwane dopiero po jawnym użyciu --prune.

Czy sekrety można przechowywać w dockup.yaml?

Nie należy tego robić. Commituj wyłącznie zwykłe wartości, a sekrety ustawiaj za pomocą polecenia dotyczącego środowiska sekretów albo wstrzykiwania sekretów w runtime. Istniejące sekrety są chronione przed prune.

Czy dockup up może wykonać deployment po zastosowaniu konfiguracji?

Tak. Udokumentowana opcja --deploy stosuje manifest i uruchamia deployment, którego wynik końcowy należy następnie zweryfikować.