Διαχείριση ρυθμίσεων με κώδικα με το dockup.yaml: Ασφαλές plan και apply

Το dockup.yaml μετατρέπει τις ρυθμίσεις μιας υπηρεσίας σε ένα artifact του repository που μπορεί να ελεγχθεί και να αξιολογηθεί. Αντί να βασίζεται η ομάδα σε μια κατάσταση dashboard που πρέπει να θυμάται, μπορεί να δηλώσει σε ένα αρχείο το branch, το port, τις εντολές build και start, τα health checks, τις απλές τιμές environment και τα domains.

Το Dockup διαχωρίζει την επιθεώρηση από τις μεταβολές. Το dockup plan εμφανίζει τη διαφορά μεταξύ του manifest και της ενεργής υπηρεσίας χωρίς να αλλάζει τίποτα. Το dockup up εφαρμόζει τις δηλωμένες αλλαγές. Η διαγραφή παραμένει προαιρετική και απαιτεί ρητά το --prune.

Τι μπορεί να δηλώσει το dockup.yaml;

Ένα service 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 }

Από προεπιλογή, το αρχείο τοποθετείται στη ρίζα του repository. Μπορείτε να επιλέξετε διαφορετικό path με το --file.

Μην τοποθετείτε secrets στο mapping env. Το manifest γίνεται commit, αξιολογείται, αποθηκεύεται σε cache και αντιγράφεται όπως και τα υπόλοιπα source files. Για credentials, χρησιμοποιήστε dockup env set --secret ή μια εγκεκριμένη διαδικασία secret injection.

Η κατανάλωση CPU, RAM και disk εξακολουθεί να βασίζεται στη χρήση και μετριέται ανά λεπτό σε σχέση με το υπόλοιπο του plan· το manifest πρέπει να περιγράφει τις ρυθμίσεις της υπηρεσίας και όχι παραδοχές χρέωσης.

Πώς εμφανίζει το dockup plan το configuration drift;

Εκτελέστε μια read-only σύγκριση πριν από κάθε apply:

dockup plan production/api --json

Το αποτέλεσμα περιέχει changes με aspects, fields, old values, new values και actions. Ένα plan μπορεί να δείξει ότι άλλαξε το branch, ότι διαφέρει ένα health path, ότι θα προστεθεί ένα domain ή ότι drift-αρε μια απλή τιμή environment.

Ένα plan είναι χρήσιμο σε πέντε περιπτώσεις:

Περίπτωση	Τι αποκαλύπτει το plan
Ένα pull request αλλάζει το manifest	Την αναμενόμενη επίδραση στην production πριν από το merge
Έγινε χειροκίνητη αλλαγή στο dashboard	Το drift από την πηγή του repository
Ένας agent προτείνει update	Τα ακριβή fields που σκοπεύει να μεταβάλει ο agent
Ανάκτηση από incident	Αν η ενεργή κατάσταση διαφέρει ήδη από τη γνωστή ρύθμιση
Ρύθμιση πολλών environments	Τις διαφορές μεταξύ των production και staging manifests

Το planning δεν κλειδώνει την υπηρεσία. Η ενεργή κατάσταση μπορεί να αλλάξει μεταξύ plan και apply, επομένως τα workflows υψηλού ρίσκου πρέπει να κρατούν το review και το up κοντά χρονικά και να ελέγχουν το αποτέλεσμα του apply.

Ένας coding agent πρέπει να επιστρέφει το plan JSON ή μια σύντομη σύνοψη ανά field. Το «Η ρύθμιση φαίνεται σωστή» δεν αποτελεί επαρκές review artifact.

Πώς εφαρμόζει config as code το dockup up;

Εφαρμόστε το προεπιλεγμένο manifest:

dockup up production/api --json

Κάντε apply και στη συνέχεια ξεκινήστε ένα 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 που ακολουθεί πρέπει και πάλι, όπου απαιτείται, να χρησιμοποιεί verification terminal state· μια μεταβολή ρύθμισης και ένα υγιές production release είναι διαφορετικά αποτελέσματα.

Οι secret values παραμένουν εκτός manifest. Ορίστε τις μέσω του secret environment workflow πριν εφαρμόσετε τις ρυθμίσεις, στη συνέχεια κάντε deploy και επαληθεύστε το container που προέκυψε χωρίς να εμφανίσετε την αποθηκευμένη τιμή.

Γιατί το config as code είναι additive από προεπιλογή;

Η ασφαλέστερη ερμηνεία ενός ελλιπούς manifest είναι «διαχειρίσου αυτές τις δηλωμένες τιμές» και όχι «διέγραψε οτιδήποτε άλλο». Επομένως, το Dockup αφήνει αμετάβλητα τα environment variables και τα domains που απουσιάζουν από το αρχείο.

Αυτό είναι σημαντικό κατά τη σταδιακή υιοθέτηση. Μια υπηρεσία μπορεί ήδη να διαθέτει secret variables, operational domains ή προσωρινές ρυθμίσεις που δεν έχουν ακόμη μοντελοποιηθεί. Το πρώτο up δεν πρέπει να τα διαγράψει.

Οι εγγυήσεις ασφάλειας είναι συγκεκριμένες:

• Το dockup up δεν διαγράφει services, databases ή volumes.
• Τα υπάρχοντα secret variables δεν αντικαθίστανται από απλές τιμές του manifest.
• Τα secret variables δεν γίνονται prune.
• Η αυτόματη εφαρμογή του manifest κατά το deploy είναι additive.
• Ένα μη έγκυρο manifest δεν μετατρέπεται σιωπηρά σε καταστροφικό cleanup.

Η additive συμπεριφορά καθιστά το dockup.yaml κατάλληλο για ένα incremental GitOps workflow. Σημαίνει επίσης ότι το manifest δεν αποτελεί αυτόματα πλήρη inventory, εκτός αν η ομάδα υιοθετήσει σκόπιμα το pruning για τα υποστηριζόμενα fields.

Πώς πρέπει να αξιολογείται το --prune;

Το --prune αφαιρεί τις υποστηριζόμενες απλές τιμές environment και τα domains που απουσιάζουν από το manifest:

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

Αντιμετωπίστε το flag ως destructive request. Αξιολογήστε το plan, δηλώστε με ακρίβεια τον στόχο και ζητήστε ανθρώπινη έγκριση όταν ένας agent λειτουργεί σε production.

Η ενέργεια δεν επεκτείνεται σε secrets, services, databases ή volumes. Αυτοί οι resources έχουν δικό τους lifecycle και δικές τους διαδικασίες επιβεβαίωσης. Ο διαχωρισμός αυτός αποτρέπει τη μετατροπή μιας μικρής αλλαγής στο manifest σε ευρεία διαγραφή υποδομής.

Μια χρήσιμη καταγραφή έγκρισης αναφέρει: «Εφαρμογή του dockup.yaml στο production/api και prune των δύο απλών variables και του ενός domain που εμφανίζονται στο plan X». Δεν πρέπει να αποτελεί επαναχρησιμοποιήσιμη γενική άδεια για μελλοντικά plans.

Το ευρύτερο μοντέλο επιβεβαίωσης περιγράφεται στο 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 στον προβλεπόμενο στόχο.
4. Το pull request εμφανίζει τόσο το source diff όσο και το live-state plan.
5. Ένας reviewer εγκρίνει την αλλαγή.
6. Το dockup up --deploy την εφαρμόζει.
7. Το deploy περιμένει terminal success.
8. Διατηρούνται τα status, logs και audit evidence.

Το manifest δεν πρέπει να μετατραπεί σε dumping ground. Κρατήστε την επιχειρησιακή ρύθμιση της εφαρμογής μέσα στην εφαρμογή, όπου αυτό είναι κατάλληλο. Χρησιμοποιήστε το dockup.yaml για deployment και runtime settings που ανήκουν στο όριο ευθύνης της υπηρεσίας.

Τα environment-specific αρχεία μπορεί να είναι πιο ξεκάθαρα από ένα αρχείο με ένα μη τεκμηριωμένο templating layer. Για παράδειγμα, χρησιμοποιήστε τα dockup.staging.yaml και dockup.production.yaml και περάστε ρητά το κατάλληλο αρχείο.

Ένα branch preview είναι ένα isolated deployment, ενώ το production config παραμένει ξεχωριστός στόχος review. Σε projects με private networking, τα previews μπορούν να συνδεθούν στο project network και να λάβουν read-only πρόσβαση στη database χωρίς να αλλάξει το production manifest.

Χρησιμοποιήστε τον οδηγό για environment variables και secrets για τη διαχείριση credentials και το zero-downtime deployments για το readiness gate.

Playbook αντιμετώπισης drift

Όταν το dockup plan αναφέρει μη αναμενόμενες αλλαγές στην ενεργή κατάσταση, μην τις αντικαθιστάτε αυτόματα. Εξετάστε αν η αλλαγή στο dashboard ήταν emergency fix, μη εξουσιοδοτημένη αλλαγή ή επιθυμητή ρύθμιση που δεν έγινε ποτέ commit.

Στη συνέχεια, επιλέξτε μία πηγή αλήθειας:

• Ενημερώστε το manifest ώστε να διατηρηθεί η επιθυμητή ενεργή τιμή.
• Εφαρμόστε το manifest για να επαναφέρετε την τιμή που έχει αξιολογηθεί.
• Καταγράψτε μια προσωρινή εξαίρεση με owner και ημερομηνία λήξης.
• Ερευνήστε το audit log όταν η προέλευση είναι άγνωστη.

dockup audit --writes --json

Έτσι, το dockup.yaml παραμένει authoritative χωρίς να διαγράφεται το context του incident.

Το Dockup CLI reference αποτελεί την πηγή για τα τρέχοντα manifest fields και τις επιλογές των plan/up.

Σχεδιάστε αλλαγές manifest που μπορούν να αξιολογηθούν

Κρατήστε κάθε αλλαγή αρκετά μικρή, ώστε το plan να έχει έναν ξεκάθαρο σκοπό. Ο συνδυασμός αλλαγής branch, αύξησης resources, προσθήκης domain, επανεγγραφής health check και cleanup environment σε ένα pull request δυσκολεύει τόσο το review όσο και το rollback.

Χρησιμοποιήστε comments για να εξηγείτε ασυνήθιστες τιμές, αλλά μην αντιγράφετε operational documentation μέσα στο αρχείο. Συνδέστε το repository runbook με το service target, τα health semantics και την approval policy. Το manifest πρέπει να παραμένει έγκυρο YAML που μπορεί να γίνει parse χωρίς custom preprocessor.

Ένα χρήσιμο pull-request template ζητά το output του dockup plan --json, το αναμενόμενο deployment effect, αν ζητείται --prune και το προηγούμενο deployment ID. Έτσι, ένας AI agent ή human reviewer διαθέτει τα ίδια evidence.

Εισαγάγετε το manifest χωρίς να διαταράξετε την ενεργή κατάσταση

Για μια υπάρχουσα υπηρεσία, ξεκινήστε με τα fields που μπορείτε να επαληθεύσετε. Εκτελέστε dockup info production/api --json, γράψτε ένα minimal dockup.yaml και συγκρίνετέ το με το dockup plan. Προσθέστε ρυθμίσεις σταδιακά αντί να προσπαθήσετε να ανακατασκευάσετε ταυτόχρονα κάθε ιστορική επιλογή του dashboard.

Επειδή το apply είναι additive, οι unmanaged απλές τιμές και τα domains παραμένουν όσο προχωρά η υιοθέτηση. Όταν το manifest αναπαριστά με ακρίβεια την επιθυμητή non-secret configuration, αποφασίστε αν η ομάδα θα χρησιμοποιεί ποτέ pruning. Ορισμένες ομάδες διατηρούν το cleanup ως χειροκίνητη διαδικασία, ενώ άλλες επιτρέπουν το --prune μόνο σε protected pipeline μετά από έγκριση plan.

Ο στόχος του config as code δεν είναι να μεγιστοποιήσει τον αριθμό των γραμμών στο Git. Είναι να κάνει το production intent κατανοητό, αξιολογήσιμο και ανακτήσιμο.

Κρατήστε τα plans απαλλαγμένα από secret material

Ένα plan πρέπει να είναι ασφαλές για επισύναψη σε pull request ή incident record. Εφόσον το dockup.yaml περιέχει μόνο απλές τιμές και οι υπάρχουσες secret values παραμένουν προστατευμένες, οι reviewers μπορούν να ελέγξουν την επιθυμητή ρύθμιση χωρίς να λάβουν production credentials. Ελέγχετε, ωστόσο, τις απλές τιμές για internal hostnames, customer identifiers ή άλλα δεδομένα που δεν πρέπει να είναι δημόσια.

Κρατήστε μαζί την πηγή και τον στόχο

Δηλώστε το προβλεπόμενο project/service στο pull request και στο deployment job. Ένα έγκυρο dockup.yaml που εφαρμόζεται στον λάθος στόχο παραμένει operational failure. Το target discovery και το manifest review είναι δύο ξεχωριστοί, υποχρεωτικοί έλεγχοι.

Επικυρώστε το YAML πριν από το plan

Κάντε parse το manifest στο CI πριν καλέσετε το Dockup, ώστε τα σφάλματα indentation ή type να αποτυγχάνουν κοντά στην αλλαγή του source. Η syntax validation δεν αντικαθιστά το dockup plan· αποτρέπει avoidable requests με μη αναγνώσιμο αρχείο.

Προτιμήστε μία πηγή

Ένα dockup.yaml που έχει αξιολογηθεί πρέπει να εξηγεί το production intent.

Ξεκινήστε με ένα deployment που μπορεί να επαληθευτεί

Προσθέστε ένα minimal manifest σε μία υπηρεσία, εκτελέστε ένα read-only plan και αξιολογήστε κάθε reported field πριν από το πρώτο apply.

Ξεκινήστε δωρεάν στο app.dockup.ai. Το Free plan κοστίζει $0 τον μήνα, περιλαμβάνει αρχικό credit $10 και υποστηρίζει ένα workspace, τρεις databases και τρία deployments.

FAQ

Τι είναι το dockup.yaml;

Είναι το config-as-code manifest του Dockup για τη δήλωση του branch, του port, των ρυθμίσεων build και start, των health checks, των απλών τιμών environment και των domains μιας υπηρεσίας.

Αλλάζει το dockup plan την production;

Όχι. Το dockup plan είναι read-only και εμφανίζει τη διαφορά μεταξύ του manifest και της ενεργής υπηρεσίας.

Διαγράφει το dockup up ρυθμίσεις που δεν υπάρχουν στο αρχείο;

Όχι από προεπιλογή. Το apply είναι additive. Οι υποστηριζόμενες απλές τιμές environment και τα domains αφαιρούνται μόνο όταν χρησιμοποιείται ρητά το --prune.

Μπορούν να αποθηκευτούν secrets στο dockup.yaml;

Δεν πρέπει. Κάντε commit μόνο απλές τιμές· ορίστε τα secrets μέσω της secret environment command ή μέσω runtime secret injection. Τα υπάρχοντα secrets προστατεύονται από το pruning.

Μπορεί το dockup up να κάνει deploy μετά την εφαρμογή των ρυθμίσεων;

Ναι. Η τεκμηριωμένη επιλογή --deploy εφαρμόζει το manifest και ξεκινά ένα deployment, το terminal result του οποίου πρέπει στη συνέχεια να επαληθεύεται.