dockup.yaml: konfiguraatio koodina – turvallinen suunnittelu ja käyttöönotto

dockup.yaml muuttaa palvelun konfiguraation repositoryssä tarkasteltavaksi artefaktiksi. Dashboardin muistissa pidetyn tilan sijaan tiimi voi määrittää branchin, portin, build- ja start-komennot, health checkit, tavalliset environment-arvot ja domainit yhdessä tiedostossa.

Dockup erottaa tarkastelun ja muutokset toisistaan. dockup plan näyttää manifestin ja käynnissä olevan palvelun välisen eron muuttamatta mitään. dockup up ottaa määritetyt muutokset käyttöön. Poistaminen edellyttää erikseen --prune-valintaa.

Mitä dockup.yaml-tiedostolla voi määrittää?

Palvelumanifesti voi sisältää tuotantoasetukset, joiden tarkastelusta koodikatselmoinnissa on hyötyä:

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 }

Tiedosto sijoitetaan oletuksena repositoryn juureen. Toisen polun voi valita --file-valinnalla.

Älä sijoita salaisuuksia env-määritykseen. Manifesti commitoidaan, katselmoidaan, välimuistitetaan ja kopioidaan muiden lähdetiedostojen tavoin. Käytä tunnistetietojen kanssa dockup env set --secret -komentoa tai hyväksyttyä secretien injektointiprosessia.

CPU:n, RAM-muistin ja levyn käyttö perustuu edelleen käyttöön, ja kulutus mitataan minuutti kerrallaan planin saldon perusteella. Manifestin tulisi kuvata palvelun konfiguraatiota laskutukseen liittyvien oletusten sijaan.

Miten dockup plan näyttää konfiguraation driftin?

Suorita vain luku -tilassa toimiva vertailu ennen jokaista käyttöönottoa:

dockup plan production/api --json

Tulos sisältää muutokset, niiden osa-alueet, kentät, vanhat ja uudet arvot sekä toimenpiteet. Plan voi osoittaa, että branch on vaihtunut, health path poikkeaa nykyisestä, domain lisätään tai tavallinen environment-arvo on ajautunut pois määritetystä tilasta.

Planista on hyötyä erityisesti seuraavissa tilanteissa:

Tilanne	Mitä plan paljastaa
Pull request muuttaa manifestia	Suunnitellun vaikutuksen tuotantoon ennen yhdistämistä
Dashboardia on muokattu manuaalisesti	Driftin repositoryn lähteeseen verrattuna
Agentti ehdottaa päivitystä	Tarkat kentät, joita agentti aikoo muuttaa
Häiriöstä palautuminen	Poikkeaako aktiivinen tila jo tunnetusta konfiguraatiosta
Usean ympäristön käyttöönotto	Tuotanto- ja staging-manifestien väliset erot

Plan ei lukitse palvelua. Aktiivinen tila voi muuttua planin ja applyn välillä, joten riskialttiissa työnkuluissa katselmointi ja up kannattaa pitää ajallisesti lähellä toisiaan, ja applyn tulos tulee tarkastaa.

Koodausagentin tulisi palauttaa planin JSON tai tiivis kenttäkohtainen yhteenveto. ”Konfiguraatio näyttää hyvältä” ei ole riittävä katselmointiaineisto.

Miten dockup up ottaa config as coden käyttöön?

Ota oletusmanifesti käyttöön:

dockup up production/api --json

Ota muutokset käyttöön ja käynnistä sen jälkeen deployment:

dockup up production/api --deploy --json

Käytä stagingissa toista tiedostoa:

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

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

Apply-tulos ilmoittaa, mitkä muutokset otettiin käyttöön ja mitkä ohitettiin. Kun --deploy on käytössä, tulos voi sisältää myös deployment ID:n. Varsinaisessa deploymentissa tulisi silti tarvittaessa käyttää lopputilan varmistusta: konfiguraation muuttaminen ja terveen production-releasen saavuttaminen ovat eri lopputuloksia.

Secret-arvot säilyvät manifestin ulkopuolella. Aseta ne secret-ympäristön työnkulun kautta ennen konfiguraation käyttöönottoa, käynnistä sitten deployment ja varmista syntyvä container tulostamatta tallennettua arvoa.

Miksi config as code on oletusarvoisesti lisäävä?

Turvallisin tulkinta puutteelliselle manifestille on ”hallinnoi näitä määritettyjä arvoja”, ei ”poista kaikki muu”. Siksi Dockup jättää tiedostosta puuttuvat environment-muuttujat ja domainit ennalleen.

Tällä on merkitystä vaiheittain käyttöönotettaessa. Palvelussa voi jo olla secret-muuttujia, toiminnallisia domaineja tai väliaikaista konfiguraatiota, jota ei ole vielä mallinnettu. Ensimmäisen up-komennon ei pitäisi poistaa niitä.

Turvallisuustakuut ovat seuraavat:

• dockup up ei poista palveluita, tietokantoja tai volumeja.
• Olemassa olevia secret-muuttujia ei korvata tavallisilla manifestiarvoilla.
• Secret-muuttujia ei poisteta prunella.
• Manifestin automaattinen käyttöönotto deploymentin yhteydessä on lisäävä.
• Virheellinen manifesti ei muutu huomaamatta tuhoisaksi siivoukseksi.

Lisäävä toimintatapa tekee dockup.yaml-tiedostosta sopivan vaiheittain käyttöönotettavaan GitOps-työnkulkuun. Se tarkoittaa myös, ettei manifesti ole automaattisesti täydellinen inventaario, ellei tiimi päätä käyttää tuettujen kenttien prune-toimintoa.

Miten --prune tulee katselmoida?

--prune poistaa tuetut tavalliset environment-arvot ja domainit, jotka puuttuvat manifestista:

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

Käsittele valintaa tuhoisana pyyntönä. Tarkasta plan, määritä täsmällinen kohde ja hanki ihmisen hyväksyntä, kun agentti toimii production-ympäristössä.

Toiminto ei koske secret-arvoja, palveluita, tietokantoja tai volumeja. Näillä resursseilla on oma elinkaarensa ja omat vahvistuspolkunsa. Tämä erottelu estää pientä manifestimuutosta muuttumasta laajaksi infrastruktuurin poistoksi.

Hyödyllisessä hyväksyntämerkinnässä sanotaan: ”Ota dockup.yaml käyttöön kohteessa production/api ja poista planissa X näkyvät kaksi tavallista muuttujaa ja yksi domain.” Sen ei pidä olla tulevia planeja koskeva yleinen lupa.

Laajempaa vahvistusmallia käsitellään oppaassa AI-agenttien tuotantoympäristön suojakaiteet.

Miten tiimit toteuttavat GitOps-työnkulun dockup.yaml-tiedostolla?

Pidä työnkulku yksinkertaisena:

1. Kehittäjä tai agentti muokkaa dockup.yaml-tiedostoa.
2. CI tarkistaa YAML-syntaksin ja sovellustestit.
3. Vain luku -tilassa toimiva dockup plan suoritetaan aiottua kohdetta vasten.
4. Pull request näyttää sekä lähdekoodin diff-taulun että aktiivisen tilan planin.
5. Katselmoija hyväksyy muutoksen.
6. dockup up --deploy ottaa muutoksen käyttöön.
7. Deployment odottaa lopullista onnistumistilaa.
8. Status, logit ja auditointiaineisto säilytetään.

Manifestista ei pidä tehdä kaatopaikkaa. Pidä sovelluksen liiketoimintakonfiguraatio tarvittaessa sovelluksessa. Käytä dockup.yaml-tiedostoa deployment- ja runtime-asetuksiin, jotka kuuluvat palvelun rajapintaan.

Ympäristökohtaiset tiedostot voivat olla selkeämpi ratkaisu kuin yksi tiedosto, jonka ympärillä on dokumentoimaton templatointi. Käytä esimerkiksi tiedostoja dockup.staging.yaml ja dockup.production.yaml ja välitä aiottu tiedosto eksplisiittisesti.

Branch preview on eristetty deployment, kun taas production-konfiguraatio säilyy erillisenä katselmointikohteena. Private networking -projekteissa previewt voivat liittyä projektin verkkoon ja saada vain luku -oikeuden tietokantaan muuttamatta production-manifestia.

Katso tunnistetietojen käsittelyä varten opas environment-muuttujat ja secretit ja readiness gatea varten opas zero-downtime deploymentit.

Driftin käsittelyn pelikirja

Kun dockup plan ilmoittaa odottamattomista aktiivisen tilan muutoksista, älä korvaa niitä automaattisesti. Selvitä, oliko dashboardissa tehty muutos hätäkorjaus, luvaton muutos vai tarkoituksellinen asetus, jota ei koskaan commitattu.

Valitse sen jälkeen yksi totuuden lähde:

• Päivitä manifesti säilyttääksesi aktiivisen tilan tarkoitetun arvon.
• Ota manifesti käyttöön palauttaaksesi katselmoidun arvon.
• Dokumentoi väliaikainen poikkeus ja määritä sille omistaja ja vanhenemispäivä.
• Tutki audit-loki, jos alkuperä ei ole tiedossa.

dockup audit --writes --json

Näin dockup.yaml pysyy auktoritatiivisena ilman, että häiriötilanteen kontekstia hävitetään.

Dockup CLI -referenssi on ajantasainen lähde manifestin kentille sekä plan- ja up-valinnoille.

Suunnittele helposti katselmoitavat manifestimuutokset

Pidä jokainen muutos riittävän pienenä, jotta planilla on yksi selkeä tarkoitus. Branchin vaihtamisen, resurssien kasvattamisen, uuden domainin lisäämisen, health checkin uudelleenkirjoittamisen ja environment-siivouksen yhdistäminen samaan pull requestiin vaikeuttaa sekä katselmointia että palautusta.

Käytä kommentteja poikkeavien arvojen selittämiseen, mutta älä kopioi operatiivista dokumentaatiota tiedostoon. Linkitä repositoryn runbook palvelukohteeseen, health checkin merkitykseen ja hyväksyntäkäytäntöön. Manifestin tulee säilyä kelvollisena YAML-tiedostona, jonka voi jäsentää ilman mukautettua esikäsittelijää.

Hyödyllisessä pull request -mallissa pyydetään dockup plan --json -tulostetta, odotettua vaikutusta deploymentiin, tietoa siitä pyydetäänkö --prune-valintaa sekä edellisen deploymentin ID:tä. Näin AI-agentilla tai ihmiskatselmoijalla on käytettävissään sama aineisto.

Ota manifesti käyttöön häiritsemättä aktiivista tilaa

Aloita olemassa olevan palvelun kanssa kentistä, jotka pystyt varmistamaan. Suorita dockup info production/api --json, kirjoita minimaalinen dockup.yaml ja vertaa sitä komennolla dockup plan. Lisää asetuksia vaiheittain sen sijaan, että yrittäisit palauttaa kaikki dashboardissa aiemmin tehdyt valinnat kerralla.

Koska apply on lisäävä, hallitsemattomat tavalliset arvot ja domainit säilyvät käyttöönoton aikana. Kun manifesti kuvaa tarkoitettua ei-secret-konfiguraatiota tarkasti, päättäkää, käytättekö jatkossa prune-toimintoa. Jotkin tiimit pitävät siivouksen manuaalisena, kun taas toiset sallivat --prune-valinnan vain suojatussa putkessa planin hyväksynnän jälkeen.

Config as coden tavoitteena ei ole kasvattaa Gitissä olevien rivien määrää mahdollisimman suureksi. Tavoitteena on tehdä productionin intentiosta ymmärrettävä, katselmoitava ja palautettava.

Pidä planet vapaina secret-materiaalista

Planin tulee olla turvallinen liitettäväksi pull requestiin tai häiriötilanteen tietueeseen. Koska dockup.yaml sisältää vain tavallisia arvoja ja olemassa olevat secret-arvot pysyvät suojattuina, katselmoijat voivat tarkastaa aiotun konfiguraation ilman production-tunnistetietoja. Tarkasta silti tavalliset arvot sisäisten hostnamejen, asiakastunnisteiden ja muiden mahdollisesti julkisuuteen kuulumattomien tietojen varalta.

Pidä lähde ja kohde yhdessä

Nimeä aiottu project/service pull requestissa ja deployment-työssä. Oikeaan muotoon laadittu dockup.yaml, joka otetaan käyttöön väärässä kohteessa, on silti operatiivinen virhe. Kohteen tunnistaminen ja manifestin katselmointi ovat erillisiä, pakollisia tarkistuksia.

Vahvista YAML ennen plania

Jäsennä manifesti CI:ssä ennen Dockup-kutsua, jotta sisennys- tai tyyppivirheet havaitaan lähellä lähdemuutosta. Syntaksin tarkistus ei korvaa dockup plan -komentoa, mutta se estää turhat pyynnöt lukukelvottomalla tiedostolla.

Suosi yhtä lähdettä

Katselmoidun dockup.yaml-tiedoston pitäisi selittää productionin intentio.

Aloita varmennettavasta deploymentista

Lisää yhteen palveluun minimaalinen manifesti, suorita vain luku -tilassa toimiva plan ja tarkasta jokainen ilmoitettu kenttä ennen ensimmäistä applya.

Aloita maksutta osoitteessa app.dockup.ai. Free-plan maksaa 0 dollaria kuukaudessa, sisältää 10 dollarin aloitussaldon ja tukee yhtä workspacea, kolmea tietokantaa ja kolmea deploymentia.

Usein kysyttyä

Mikä on dockup.yaml?

Se on Dockupin config-as-code-manifesti, jolla määritetään palvelun branch, portti, build- ja start-asetukset, health checkit, tavalliset environment-arvot ja domainit.

Muuttaako dockup plan productionia?

Ei. dockup plan toimii vain luku -tilassa ja näyttää manifestin ja aktiivisen palvelun välisen eron.

Poistaako dockup up tiedostosta puuttuvan konfiguraation?

Ei oletusarvoisesti. Apply on lisäävä. Tuetut tavalliset environment-arvot ja domainit poistetaan vain, kun --prune-valintaa käytetään eksplisiittisesti.

Voiko secret-arvoja tallentaa dockup.yaml-tiedostoon?

Ei pitäisi. Committaa vain tavalliset arvot; aseta secret-arvot secret environment -komennolla tai runtime-secrets-injektiolla. Olemassa olevat secret-arvot on suojattu prunelta.

Voiko dockup up käynnistää deploymentin konfiguraation käyttöönoton jälkeen?

Kyllä. Dokumentoitu --deploy-valinta ottaa manifestin käyttöön ja käynnistää deploymentin, jonka lopullinen tulos tulee sen jälkeen varmistaa.