dockup.yaml ile Config as Code: Güvenli Planlama ve Uygulama

dockup.yaml, servis yapılandırmasını incelenebilir bir repository artifact'ına dönüştürür. Bir ekip, dashboard'da hatırlanan ayar durumuna güvenmek yerine branch, port, build ve start komutlarını, health check'leri, normal environment değerlerini ve domain'leri tek bir dosyada tanımlayabilir.

Dockup, incelemeyi değişiklik uygulamadan ayırır. dockup plan, hiçbir şeyi değiştirmeden manifest ile çalışan servis arasındaki farkı gösterir. dockup up, tanımlanan değişiklikleri uygular. Silme işlemi ise --prune aracılığıyla açıkça etkinleştirilmelidir.

dockup.yaml neleri tanımlayabilir?

Bir servis manifest'i, code review'dan fayda sağlayan production ayarlarını içerebilir:

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 }

Dosya, varsayılan olarak repository root'una yerleştirilir. --file ile farklı bir path seçilebilir.

env mapping'ine secret eklemeyin. Manifest; diğer source file'lar gibi commit edilir, incelenir, cache'lenir ve kopyalanır. Credential'lar için dockup env set --secret veya onaylanmış bir secret injection süreci kullanın.

CPU, RAM ve disk tüketimi kullanıma göre hesaplanmaya ve plan bakiyesine karşı dakika bazında ölçülmeye devam eder; manifest, billing varsayımlarını değil servis yapılandırmasını tanımlamalıdır.

dockup plan configuration drift'i nasıl gösterir?

Her apply işleminden önce salt okunur bir karşılaştırma çalıştırın:

dockup plan production/api --json

Sonuç; aspect'leri, field'ları, eski değerleri, yeni değerleri ve action'ları içeren değişiklikleri kapsar. Bir plan, branch'in değiştiğini, bir health path'inin farklı olduğunu, bir domain'in ekleneceğini veya normal bir environment değerinin drift ettiğini gösterebilir.

Plan şu üç durumda özellikle değerlidir:

Durum	Planın gösterdiği
Pull request manifest'i değiştiriyor	Merge öncesinde production üzerindeki amaçlanan etki
Dashboard manuel olarak düzenlendi	Repository'deki source'tan sapma
Agent bir güncelleme öneriyor	Agent'ın değiştirmeyi amaçladığı tam field'lar
Incident recovery	Çalışan durumun bilinen yapılandırmadan zaten farklı olup olmadığı
Multi-environment kurulumu	Production ve staging manifest'leri arasındaki farklar

Planlama servisi kilitlemez. Plan ile apply arasında çalışan durum değişebilir. Bu nedenle yüksek riskli iş akışlarında review ile up adımları birbirine yakın tutulmalı ve apply sonucu incelenmelidir.

Bir coding agent, plan JSON'unu veya field bazında kısa bir özeti döndürmelidir. “Configuration looks good” yeterli bir review artifact'ı değildir.

dockup up config as code'u nasıl uygular?

Varsayılan manifest'i uygulayın:

dockup up production/api --json

Uygulayıp ardından deployment başlatın:

dockup up production/api --deploy --json

Staging için farklı bir dosya kullanın:

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

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

Apply sonucu, hangi değişikliklerin uygulandığını veya atlandığını bildirir ve --deploy kullanıldığında deployment ID'sini içerebilir. Uygun durumlarda çevreleyen deployment sürecinde yine terminal-state verification kullanılmalıdır; bir yapılandırma değişikliği ile sağlıklı bir production release'i birbirinden ayrı sonuçlardır.

Secret değerleri manifest'in dışında kalır. Yapılandırmayı uygulamadan önce secret environment workflow üzerinden bunları ayarlayın; ardından deploy edin ve kayıtlı değeri yazdırmadan ortaya çıkan container'ı doğrulayın.

Config as code neden varsayılan olarak eklemelidir?

Eksik bir manifest'in en güvenli yorumu “tanımlanan bu değerleri yönet” olmalıdır; “diğer her şeyi sil” değil. Bu nedenle Dockup, dosyada yer almayan environment variable'ları ve domain'leri olduğu gibi bırakır.

Bu yaklaşım, kademeli geçiş sırasında önemlidir. Bir serviste henüz modellenmemiş secret variable'lar, operasyonel domain'ler veya geçici yapılandırmalar bulunabilir. İlk up işlemi bunları silmemelidir.

Güvenlik garantileri şunlardır:

• dockup up, servisleri, database'leri veya volume'leri silmez.
• Mevcut secret variable'ların üzerine normal manifest değerleri yazılmaz.
• Secret variable'lar prune edilmez.
• Deployment sırasında otomatik manifest uygulaması eklemelidir.
• Geçersiz bir manifest sessizce destructive cleanup işlemine dönüşmez.

Eklemeli davranış, dockup.yaml dosyasını incremental bir GitOps workflow'u için uygun hale getirir. Bununla birlikte ekip, desteklenen field'lar için bilinçli olarak pruning yaklaşımını benimsemedikçe manifest otomatik olarak eksiksiz bir inventory değildir.

--prune nasıl incelenmelidir?

--prune, manifest'te bulunmayan desteklenen normal environment değerlerini ve domain'leri kaldırır:

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

Bu flag'i destructive bir istek olarak değerlendirin. Planı inceleyin, kesin hedefi belirtin ve production üzerinde bir agent çalışıyorsa human approval alın.

Bu işlem secret'ları, servisleri, database'leri veya volume'leri kapsamaz. Bu kaynakların kendi lifecycle'ları ve confirmation path'leri vardır. Bu ayrım, küçük bir manifest düzenlemesinin geniş kapsamlı infrastructure deletion işlemine dönüşmesini önler.

Faydalı bir approval kaydı şöyle olmalıdır: “production/api için dockup.yaml dosyasını uygula ve plan X'te gösterilen iki normal variable ile bir domain'i prune et.” Bu kayıt, gelecekteki planlar için yeniden kullanılabilecek genel bir izin olmamalıdır.

Daha kapsamlı confirmation modeli, AI agent'ları için production guardrail'leri başlıklı yazıda ele alınır.

Ekipler dockup.yaml ile GitOps workflow'unu nasıl yürütür?

Workflow'u basit tutun:

1. Bir developer veya agent dockup.yaml dosyasını düzenler.
2. CI, YAML syntax'ını ve application test'lerini doğrular.
3. Amaçlanan target üzerinde salt okunur bir dockup plan çalıştırılır.
4. Pull request hem source diff'ini hem de live-state plan'ını gösterir.
5. Bir reviewer değişikliği onaylar.
6. dockup up --deploy değişikliği uygular.
7. Deploy, terminal success durumunu bekler.
8. Status, log'lar ve audit kanıtları saklanır.

Manifest bir dumping ground'a dönüşmemelidir. Uygun olduğunda application business configuration'ını application içinde tutun. dockup.yaml dosyasını, servis sınırının sahip olduğu deployment ve runtime ayarları için kullanın.

Environment'a özel dosyalar, belgelenmemiş bir templating layer içeren tek bir dosyadan daha anlaşılır olabilir. Örneğin dockup.staging.yaml ve dockup.production.yaml kullanın ve amaçlanan dosyayı açıkça geçin.

Bir branch preview izole bir deployment'tır; production config ise ayrı bir review target'ı olarak kalır. Private networking projelerinde preview'lar project network'e katılabilir ve production manifest'ini değiştirmeden read-only database access alabilir.

Credential yönetimi için environment variable'ları ve secret'lar rehberini, readiness gate için zero-downtime deployment'ları kullanın.

Drift response playbook'u

dockup plan beklenmeyen live değişiklikler bildirdiğinde bunların üzerine otomatik olarak yazmayın. Dashboard düzenlemesinin acil bir düzeltme mi, yetkisiz bir değişiklik mi yoksa hiç commit edilmemiş amaçlanan bir ayar mı olduğunu belirleyin.

Ardından tek bir source of truth seçin:

• Amaçlanan live değerini korumak için manifest'i güncelleyin.
• Review edilmiş değeri geri yüklemek için manifest'i uygulayın.
• Owner ve expiry içeren geçici bir istisnayı belgeleyin.
• Kaynak bilinmiyorsa audit log'u inceleyin.

dockup audit --writes --json

Bu süreç, incident bağlamını silmeden dockup.yaml dosyasını authoritative tutar.

Güncel manifest field'ları ve plan/up seçenekleri için Dockup CLI reference temel kaynaktır.

İncelenebilir manifest değişiklikleri tasarlayın

Her değişikliği, planın tek bir net amaca sahip olacağı kadar küçük tutun. Branch değişikliğini, resource artışını, yeni domain'i, health-check düzenlemesini ve environment cleanup işlemini tek bir pull request'te birleştirmek hem review'u hem de rollback'i zorlaştırır.

Sıra dışı değerleri açıklamak için comment kullanın; ancak operasyonel dokümantasyonu dosyanın içinde tekrarlamayın. Repository runbook'unu service target'ına, health semantics'e ve approval policy'ye bağlayın. Manifest, custom preprocessor olmadan parse edilebilen geçerli bir YAML olarak kalmalıdır.

Faydalı bir pull request template'i dockup plan --json çıktısını, beklenen deployment etkisini, --prune istenip istenmediğini ve önceki deployment ID'sini sorar. Böylece bir AI agent veya human reviewer aynı kanıta sahip olur.

Manifest'i live state'i bozmadan kullanıma alın

Mevcut bir servis için doğrulayabildiğiniz field'larla başlayın. dockup info production/api --json çalıştırın, minimal bir dockup.yaml yazın ve bunu dockup plan ile karşılaştırın. Geçmişteki tüm dashboard seçimlerini tek seferde yeniden oluşturmaya çalışmak yerine ayarları aşamalı olarak ekleyin.

Apply eklemeli olduğu için yönetilmeyen normal değerler ve domain'ler, adoption süreci devam ederken korunur. Manifest amaçlanan non-secret configuration'ı doğru şekilde temsil etmeye başladığında ekibin pruning kullanıp kullanmayacağına karar verin. Bazı ekipler cleanup işlemini manuel tutar; bazıları ise --prune kullanımına yalnızca plan approval sonrasında korumalı bir pipeline'da izin verir.

Config as code'un amacı Git'teki satır sayısını artırmak değildir. Amaç, production niyetini anlaşılır, incelenebilir ve kurtarılabilir hale getirmektir.

Planları secret materyalinden arındırın

Bir plan, pull request'e veya incident kaydına güvenle eklenebilmelidir. dockup.yaml yalnızca normal değerler içerdiği ve mevcut secret değerleri korunduğu için reviewer'lar production credential'larını almadan amaçlanan yapılandırmayı inceleyebilir. Yine de normal değerleri; internal hostname'ler, customer identifier'ları veya public olmaması gereken diğer veriler açısından inceleyin.

Source ile target'ı birlikte tutun

Pull request'te ve deployment job'ında amaçlanan project/service değerini belirtin. Geçerli bir dockup.yaml dosyasının yanlış target'a uygulanması da operasyonel bir hatadır. Target discovery ve manifest review ayrı ve zorunlu kontrollerdir.

Plan'dan önce YAML'ı doğrulayın

Indentation veya type hatalarının source değişikliğine yakın bir noktada başarısız olması için Dockup'ı çağırmadan önce manifest'i CI'da parse edin. Syntax validation, dockup plan'in yerini tutmaz; okunamayan bir dosyayla gereksiz request'leri önler.

Tek bir source'u tercih edin

İncelenmiş bir dockup.yaml, production niyetini açıklamalıdır.

Doğrulanabilir bir deployment ile başlayın

Bir servise minimal bir manifest ekleyin, salt okunur bir plan çalıştırın ve ilk apply işleminden önce raporlanan her field'ı inceleyin.

app.dockup.ai'da ücretsiz başlayın. Free plan aylık $0'dır, başlangıç kredisi olarak $10 içerir ve bir workspace, üç database ve üç deployment desteği sunar.

SSS

dockup.yaml nedir?

Servis branch'ini, port'unu, build ve start ayarlarını, health check'lerini, normal environment değerlerini ve domain'leri tanımlamak için kullanılan Dockup config-as-code manifest'idir.

dockup plan production'ı değiştirir mi?

Hayır. dockup plan salt okunurdur ve manifest ile çalışan servis arasındaki farkı gösterir.

dockup up dosyada bulunmayan yapılandırmaları siler mi?

Varsayılan olarak hayır. Apply eklemelidir. Desteklenen normal environment değerleri ve domain'ler yalnızca --prune açıkça kullanıldığında kaldırılır.

Secret'lar dockup.yaml içinde saklanabilir mi?

Saklanmamalıdır. Yalnızca normal değerleri commit edin; secret'ları secret environment komutu veya runtime secret injection üzerinden ayarlayın. Mevcut secret'lar pruning işlemine karşı korunur.

dockup up yapılandırmayı uyguladıktan sonra deploy edebilir mi?

Evet. Belgelenen --deploy seçeneği manifest'i uygular ve ardından terminal sonucu doğrulanması gereken bir deployment başlatır.