VPS Üzerinde Nginx ile Canary Dağıtımı
Canary dağıtımı, yeni uygulama sürümünü sınırlı trafikle gözlemleyip kademeli açmayı amaçlar. Hata etkisini azaltabilir; staging testlerinin, veri uyumluluğunun ve kurtarma planının yerini tutmaz. Tek VPS üzerinde iki sürüm çalıştırmak ayrıca CPU, RAM, bağlantı ve disk kapasitesi gerektirir; aynı makinedeki sürümler ortak arıza alanını paylaşır.
Bu rehber VPS üzerinde Nginx ağırlıklı yönlendirme, canary’ye özel sağlık kontrolü ve trafik geri dönüşünü birlikte kurar. Örneklerde stable v1, canary v2’dir; HTTP uygulamaları yalnız 127.0.0.1:8080 ve 127.0.0.1:9080 üzerinde dinler. Mevcut TLS/sanal host yapınıza ve uygulama servislerinize uyarlayıp önce yalıtılmış ortamda deneyin.
Canary Dağıtımının Kapsamı ve Sınırları
Stable sürümü çalışır durumda tutarken yeni sürüme az sayıda gerçek istek gönderirsiniz. Her adımda sürüm bazında hata, gecikme ve kritik kullanıcı işlemlerini gözlemler; önceden belirlediğiniz durdurma ölçütleri aşılırsa trafik açılımını durdurursunuz. Yönlendirmeyi geri almak, tamamlanmış ödeme, kuyruk işi veya veritabanı yazımını geri almaz.
Ağırlıklı havuzdaki canary sunucusunu kapatmak tek başına yeterli değildir: cookie veya ayrı bir hash kuralı da canary’ye gidebilir. Aşağıdaki düzen, havuz ve yönlendirme kapısını aynı state dosyasında değiştirir. Cookie bir erişim yetkisi değildir; kullanıcı kendisi gönderebilir. Ekip testlerini kısıtlamak için ayrıca kimlik doğrulama veya ayrı, korumalı test erişimi gerekir.
Nginx ile Ağırlıklı Yönlendirme Kurulumu
İki sabit hedef havuzu ve normal trafik için bir ağırlıklı havuz kullanıyoruz. Stable ve canary ağırlıkları istek seçiminin göreli payını belirler; kullanıcıları kalıcı olarak bir sürüme bağlamaz. Nginx upstream belgeleri ağırlıkları ve kullanılabilirlik koşullarını tanımlar.
Örnek cookie oluşturmaz ve herkese açık ?canary=1 anahtarı kurmaz. Test istemcisi doğrudan Cookie: canary=1 başlığı gönderebilir; yönlendirme ancak ortak kapı açıkken çalışır. Gerçek tarayıcı cookie’sini uygulamada oluşturuyorsanız HTTPS, Secure, SameSite, Domain/Path ve gerekiyorsa HttpOnly ayarlarını akışınıza göre belirleyin.
Ortak Kapı ile Cookie ve Ağırlıklı Havuzu Yönetme
Aşağıdaki parçayı mevcut http bağlamına bir kez ekleyin; aynı upstream veya log_format adını ikinci kez tanımlamayın. Bir sonraki örnekteki state dosyasını da oluşturmadan yapılandırmayı yüklemeyin. Başlangıçta normal ve cookie’li istekler stable’a gider. Uygulamalar yanıtta güvenilir X-Release: v1 veya X-Release: v2 üretmelidir. Loopback 18089 portunun boş olduğunu doğrulayın; bu uç nokta yalnız yapılandırma neslini gösterir.
# Merge once into the existing http context; do not duplicate upstream names.
upstream app_stable { server 127.0.0.1:8080; }
upstream app_canary { server 127.0.0.1:9080; }
include /etc/nginx/canary-state.conf;
map "$canary_enabled:$cookie_canary" $backend_upstream {
default app_pool;
"1:1" app_canary;
}
log_format canary_json escape=json
'{"time":"$time_iso8601","status":$status,'
'"route":"$backend_upstream","upstream":"$upstream_addr",'
'"upstream_status":"$upstream_status","release":"$upstream_http_x_release",'
'"request_time":$request_time,"upstream_time":"$upstream_response_time"}';
server {
listen 80;
server_name example.com;
access_log /var/log/nginx/canary.json canary_json;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_connect_timeout 2s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_pass http://$backend_upstream;
}
}
# Local configuration-generation probe, not application readiness.
server {
listen 127.0.0.1:18089;
server_name localhost;
access_log off;
location = /__canary_generation { return 200 "$canary_generation\n"; }
location / { return 404; }
}
Cookie testi için canary kapısını açmanız normal ağırlıklı trafiğe de seçtiğiniz küçük payı açar; bu örnek “yalnız ekip açık, genel trafik sıfır” modu sağlamaz. İlk kontrolleri doğrudan canary uygulama portunda veya ayrı korumalı staging erişiminde yapın. Ardından düşük ağırlıkla açıp yanıttaki sürüm ve gerçek upstream kayıtlarını doğrulayın.
Geçerli Ağırlıklar ve Başlangıçta Kapalı Canary
State dosyası ana örnekte gerçek bir include ile yüklenir. Nginx sunucu ağırlığı pozitif olmalıdır; canary’yi kapatırken weight=0 yerine down kullanılır. Aynı dosyadaki map, cookie yolunu da kapatır. Nginx map belgeleri değişkenlerden hedef seçiminin nasıl kurulduğunu açıklar.
# generation: initial
upstream app_pool {
zone app_pool 64k;
keepalive 16;
server 127.0.0.1:8080 weight=100 max_fails=3 fail_timeout=10s;
server 127.0.0.1:9080 down;
}
map $host $canary_enabled { default 0; }
map $host $canary_generation { default "initial"; }
Canary’nin hedef payı, iki peer kullanılabilirken canary / (stable + canary) oranıdır. 9:1 yaklaşık %10, 7:3 yaklaşık %30, 100:50 yaklaşık %33,3; 100:100 yaklaşık %50 eder. Kısa örneklem, başarısız peer, tekrar denemeler ve zorunlu cookie trafiği gözlenen oranı değiştirir. Bu sayılar kesin kullanıcı yüzdesi değildir.
Sağlık Kontrolü ve Gerçek Sürümün İzlenmesi
Ağırlıklı havuzda max_fails ve fail_timeout, ilgili hata koşullarında peer’ı geçici olarak dışlayabilir. Hangi hataların sayıldığı proxy_next_upstream ile ilişkilidir. Tek peer içeren app_stable/app_canary havuzlarında bu pasif dışlama parametreleri etkili değildir; cookie ile doğrudan canary’ye giden bir 503 otomatik stable geçişi garantilemez. Bu nedenle ayrı aktif kontrol ve ortak kapı kullanıyoruz.
Ana yapılandırma en fazla iki upstream denemesine izin verir. Yalnız tanımlı koşullarda, uygun başka peer varsa ve istemciye yanıt gönderilmediyse yeniden deneme yapılabilir. Upstream’e gönderilmiş POST gibi idempotent olmayan istekler normalde tekrar edilmez. İş mantığının idempotency kuralları yine gereklidir; timeout değerlerini uygulamanın gerçek çalışma süresine göre seçin.
Canary’ye Ait Açık Bir Sağlık Sözleşmesi
Canary uygulamasının /healthz yanıtı tam HTTP 200 ve gövdede aşağıdaki tek satır olsun; satır sonunda LF bulunmalıdır. Guard, durum kodunu ve gövdeyi birlikte doğrular. Sabit bir Nginx 200 yanıtı uygulama sağlığını göstermez. Uygulama bu yanıtı ancak tanımladığınız hizmete hazır olma kontrolleri geçince vermeli; ayrıntılı sır veya kişisel veri döndürmemelidir.
HTTP/1.1 200 OK
Content-Type: text/plain
ok version=v2
Önce state değiştiriciyi /usr/local/bin/canaryctl olarak kaydedin. Bash, curl, util-linux flock, GNU coreutils, sed ve guard’ın kullandığı cmp (GNU sistemlerde diffutils) gerekir. Örnek, systemd ile yönetilen bir Nginx servisi varsayar. Script yalnız yetkili yönetici tarafından yazılabilir ve çalıştırılabilir olmalıdır. State dosyası, kilit dizini ve Nginx komutları bu hesaba uygun olmalıdır. Script pozitif tamsayıları doğrular; ikinci argümandaki 0, Nginx’e sıfır ağırlık yazmak yerine ortak kapıyı ve canary peer’ını kapatır.
#!/usr/bin/env bash
set -euo pipefail
umask 077
STATE="/etc/nginx/canary-state.conf"
LOCK="/run/lock/dchost-canary.lock"
PROBE="http://127.0.0.1:18089/__canary_generation"
positive_weight() {
[[ "$1" =~ ^[1-9][0-9]{0,4}$ ]] && (( 10#$1 <= 10000 ))
}
[[ $# == 2 ]] || { echo "Usage: canaryctl STABLE_WEIGHT CANARY_WEIGHT_OR_0" >&2; exit 64; }
positive_weight "$1" || { echo "Stable must be an integer 1..10000 without leading zeros" >&2; exit 64; }
[[ "$2" == 0 ]] || positive_weight "$2" || { echo "Canary must be 0 or an integer 1..10000" >&2; exit 64; }
stable=$1; canary=$2
exec 9>"$LOCK"
flock -x -w 10 9 || { echo "Another canary update holds the lock" >&2; exit 1; }
[[ -f "$STATE" && ! -L "$STATE" ]] || { echo "Expected a regular state file" >&2; exit 1; }
old_generation=$(sed -n 's/^# generation: //p' "$STATE")
[[ "$old_generation" =~ ^[A-Za-z0-9-]+$ ]] || { echo "Invalid old generation" >&2; exit 1; }
backup=""; candidate=""; probe_body=""; dirty=0
wait_generation() {
local wanted=$1 code attempt
for attempt in {1..10}; do
if code=$(curl --noproxy '*' -sS --connect-timeout 1 --max-time 1 \
-H 'Connection: close' -o "$probe_body" -w '%{http_code}' "$PROBE") &&
[[ "$code" == 200 && "$(cat "$probe_body")" == "$wanted" ]]; then
return 0
fi
sleep 0.2
done
return 1
}
cleanup() {
local rc=$? restore
trap - EXIT HUP INT TERM
if (( dirty )); then
echo "Restoring previous state from $backup" >&2
if restore=$(mktemp "${STATE}.restore.XXXXXX") &&
cp -p -- "$backup" "$restore" && mv -fT -- "$restore" "$STATE" &&
nginx -t && timeout 30 systemctl reload nginx && wait_generation "$old_generation"; then
dirty=0
else
echo "RESTORE NOT CONFIRMED. Preserve $backup and reconcile disk/runtime manually." >&2
rc=2
fi
fi
[[ -z "$candidate" ]] || rm -f -- "$candidate"
[[ -z "$probe_body" ]] || rm -f -- "$probe_body"
if (( ! dirty )) && [[ -n "$backup" ]]; then rm -f -- "$backup"; fi
exit "$rc"
}
trap cleanup EXIT
trap 'exit 129' HUP
trap 'exit 130' INT
trap 'exit 143' TERM
backup=$(mktemp "${STATE}.backup.XXXXXX")
cp -p -- "$STATE" "$backup"
candidate=$(mktemp "${STATE}.new.XXXXXX")
probe_body=$(mktemp)
generation="$(date +%s%N)-$$"
enabled=0
canary_line="server 127.0.0.1:9080 down;"
if (( canary > 0 )); then
enabled=1
canary_line="server 127.0.0.1:9080 weight=${canary} max_fails=3 fail_timeout=10s;"
fi
cat >"$candidate" <<EOF
# generation: $generation
upstream app_pool {
zone app_pool 64k;
keepalive 16;
server 127.0.0.1:8080 weight=${stable} max_fails=3 fail_timeout=10s;
$canary_line
}
map \$host \$canary_enabled { default $enabled; }
map \$host \$canary_generation { default "$generation"; }
EOF
chmod --reference="$STATE" "$candidate"
chown --reference="$STATE" "$candidate"
# Every config writer/reloader must obey the same lock during this transaction.
# Mark dirty before rename so a catchable signal cannot skip restoration.
dirty=1
mv -fT -- "$candidate" "$STATE"
if ! nginx -t; then echo "Candidate validation failed" >&2; exit 1; fi
if ! timeout 30 systemctl reload nginx; then echo "Reload command failed" >&2; exit 1; fi
if ! wait_generation "$generation"; then echo "New generation not observed" >&2; exit 1; fi
dirty=0
echo "Accepted generation=$generation stable=$stable canary=$canary; verify traffic and draining workers."
Helper aynı kilidi kullanan değişiklikleri sıraya alır, aynı dizinde aday dosya üretip atomik ad değişimi yapar, yapılandırmayı test eder ve reload sonrasında yeni nesli yoklar. Hata olursa önceki dosyayı geri koyup eski nesli yeniden doğrulamaya çalışır. Çıkış 1 değişikliğin başarısız olduğunu, 2 ise geri yüklemenin doğrulanamadığını belirtir; 2 durumunda yedek korunur ve disk/çalışan yapılandırma elle uzlaştırılmalıdır. Ardından aşağıdaki guard’ı /usr/local/bin/canary-health-guard olarak kaydedin; tek çalışmada üç ardışık başarısız deneme kapatma girişimi başlatır.
#!/usr/bin/env bash
set -euo pipefail
umask 077
body=$(mktemp)
trap 'rm -f -- "$body"' EXIT
for attempt in 1 2 3; do
if code=$(curl --noproxy '*' -sS --connect-timeout 1 --max-time 2 \
-H 'Host: example.com' -o "$body" -w '%{http_code}' \
'http://127.0.0.1:9080/healthz') &&
[[ "$code" == 200 ]] && cmp -s "$body" <(printf 'ok version=v2\n'); then
exit 0
fi
if (( attempt < 3 )); then sleep 1; fi
done
echo "Three failed readiness probes; attempting canary disable" >&2
/usr/local/bin/canaryctl 100 0
İki unit’i aşağıdaki ayrı dosyalara kaydedin. Helper ve guard kurulduktan sonra yetkili yönetici olarak chmod 0750 /usr/local/bin/canaryctl /usr/local/bin/canary-health-guard, systemctl daemon-reload ve systemctl enable --now canary-healthcheck.timer çalıştırın. systemctl status canary-healthcheck.timer ve journalctl -u canary-healthcheck.service ile tetikleme ve hataları doğrulayın. Timer yaklaşık olarak bir çalışma bittikten 10 saniye sonra yeniden tetikler; 1 saniyelik AccuracySec ve çalışma süresi nedeniyle “her 10 saniyede kesin geri dönüş” garantisi yoktur. Guard bir sağlıklı yanıt alınca çıkar; kapatma/reload hatasını gizlemez.
# Save as /etc/systemd/system/canary-healthcheck.service
[Unit]
Description=Canary readiness check and traffic-disable attempt
[Service]
Type=oneshot
ExecStart=/usr/local/bin/canary-health-guard
TimeoutStartSec=180s
# Save separately as /etc/systemd/system/canary-healthcheck.timer
[Unit]
Description=Run canary readiness check after each completed run
[Timer]
OnBootSec=30s
OnUnitInactiveSec=10s
AccuracySec=1s
[Install]
WantedBy=timers.target
Yönlendirme Yolu ile Gerçek Backend’i Ayırma
Ana örnekteki JSON log formatını tekrar eklemeyin. route seçilen havuzdur; upstream gerçekte denenen adresleri, upstream_status aynı sıradaki yanıtları, release son upstream yanıtındaki X-Release değerini gösterir. Aşağıdaki temsili kayıtta canary 503 verdikten sonra stable 200 dönmüştür. Son istemci durumunu saymak bu ilk hatayı gizleyebilir.
{"time":"2026-11-04T12:00:00+03:00","status":200,"route":"app_pool","upstream":"127.0.0.1:9080, 127.0.0.1:8080","upstream_status":"503, 200","release":"v1","request_time":0.025,"upstream_time":"0.010, 0.015"}
Aynı zaman penceresinde stable ve canary için gerçek örnek sayısını, deneme hatalarını ve gecikmeyi karşılaştırın; boş canary örneklemi başarı kanıtı değildir. Ham upstream adres/deneme listeleri log alanı olarak kalsın. Prometheus’a her değişken listeyi, IP’yi veya request ID’yi label yapmayın; gerekiyorsa stable/canary/unknown gibi sınırlı değerlerle ve kontrollü durum sınıflarıyla metrik üretin. Örnek erişim logu yol, sorgu, cookie, IP veya User-Agent kaydetmez; diğer uygulama/error loglarının erişim, saklama ve içerik politikasını ayrıca belirleyin.
Trafik Geri Dönüşünü Önceden Sınama
Stable ve canary’yi ayrı, sürümü belli süreçler olarak çalıştırın. Bir current sembolik bağlantısını çevirmek çalışan uygulama sürecini veya bellekteki kodu kendiliğinden değiştirmez. Yeni sürümün yayına alınması, readiness kontrolü ve eski sürümün durdurulması servis yöneticinizin uygulama özelindeki adımlarıdır. Eski sürümü, veri ve oturum uyumluluğu izin verdiği sürece geri dönüş için hazır tutun.
Rollback komutu state dosyasındaki canary peer’ını down yapar ve cookie kapısını kapatır. Bu, yeni yapılandırmayı kullanan isteklerin canary’ye gitmesini önler. Yeni nesli bir uç noktada görmek bütün eski worker’ların dinleme soketlerini kapattığını veya devam eden işleri bitirdiğini kanıtlamaz. Geçişi gerçek istek ve loglarla izleyin; canary sürecini hemen öldürmeyin.
Kurulumun tüm config yazıcıları ve reload işlemleri aynı kilide uymalıdır. Helper’ın dosya geri alma düzeni harici eşzamanlı yönetici değişikliklerine, SIGKILL’e veya güç kesintisine karşı işlem garantisi vermez. Yetkili dizinleri koruyun, yedek dosyasının yerini bilin ve kasıtlı validation/reload hatalarıyla kurtarma akışını staging’de sınayın. İlk kurulum ve v2’yi yeni stable yapma işlemi ayrı kontrollü değişikliklerdir. GNU timeout burada 30 saniye sonunda varsayılan TERM sinyalini gönderir; -k kullanılmadığından kesin bir 30 saniyelik bitiş sınırı değildir. systemctl istemcisinin sonlanması, servis yöneticisindeki reload işinin iptal edildiğini kanıtlamaz. Bash bir ön plan komutunu beklerken sinyal trap’i gecikebilir. Oneshot servisin 180 saniyelik başlangıç sınırı aşılırsa systemd varsayılan olarak kontrol grubunu sonlandırır ve daha sonra zorla öldürebilir; bu sırada geri yükleme tamamlanamayabilir. Servis durumunu, yedeği ve çalışan nesli kontrol ederek elle kurtarma yapabilecek bir işletim planı hazırlayın.
Canary Ağırlığını Artırma ve Kapatma
# Approximately 10% of eligible weighted requests
/usr/local/bin/canaryctl 9 1
# Approximately 30%
/usr/local/bin/canaryctl 7 3
# Disable weighted and forced-cookie canary routes
/usr/local/bin/canaryctl 100 0
Her artış için gözlem süresini trafik, risk ve yeterli canary örneği belirlesin. Hata oranının paydasını ve minimum örnek sayısını önceden tanımlayın; az trafikte birkaç dakikalık hatasız görünüm yeterli değildir. Uygulama işlemlerini, kaynak tüketimini, kuyrukları ve stable karşılaştırmasını değerlendirin. Helper başarısı yalnız yapılandırma neslinin görüldüğünü bildirir.
Kademeli Yayın İçin Uygulama Planı
Önce iki sürümün portlarını, X-Release başlıklarını ve canary sağlık sözleşmesini doğrudan doğrulayın. Ortak oturum deposu kullanmak tek başına yeterli değildir: oturum serileştirme biçimi, cookie adı/kapsamı, imzalama veya şifreleme anahtarları, CSRF ve kullanıcı doğrulama davranışı da birlikte çalışmalıdır. Cookie’li hedefli testin genel trafik payını da açacağını hesaba katın.
Düşük ağırlıkla başlayın; giriş, arama, form gönderimi ve işinize uygun kritik akışları kontrollü test verileriyle deneyin. Gerçek ödeme veya e-posta yan etkisi üretmeden kabul ölçütlerini doğrulayın. Hata, gecikme veya veri uyumsuzluğu görülürse kapatmayı deneyin, dönüş kodunu ve yeni trafiğin stable’a geçtiğini kontrol edin; düzeltmeden yeniden artırmayın.
Çalışma zamanı değişikliği de sürüm uyumluluğunun parçasıdır. PHP yükseltme kontrol listesini kullanırken iki sürümün desteklenen runtime, eklenti, sürücü ve bağımlılık koşullarını ayrı sınayın. Veritabanında eklemeli değişiklikler tercih edilebilir; yeni kısıtlar, varsayılanlar, kilitlenme ve yazma biçimleri yine eski sürümü bozabilir. Cache biçimlerini uyumlu tutun veya sürüm anahtarlarıyla ayırın.
50/50 veya daha yüksek canary payı başarıyla gözlemlendikten sonra tam terfi için v2’yi stable hedefi yapan ayrı bir yapılandırma/süreç planı gerekir. İki pozitif ağırlığı büyütmek eski sürümü trafikten tamamen çıkarmaz. Terfiden önce sağlık kontrolü timer’ını durdurun; başlamış guard/helper çalışmasının tamamlanmasını bekleyip sonucunu ve çalışan yapılandırmayı doğrulayın. Mevcut helper eski portları yeniden yazar; terfi sonrasında değişmeden çalışırsa trafiği yeniden v1’e yönlendirebilir. Uygun test, kilit ve reload düzeniyle hedefleri değiştirin; eski worker ve işler boşaldıktan sonra v1’i durdurun. Timer’ı yeniden açmadan önce helper hedeflerini, guard’ın sürüm/port sözleşmesini ve başlangıç state dosyasını sonraki dağıtımın stable/canary düzenine uyarlayıp kapatma ve kurtarma akışlarını sınayın. Veritabanı geri yükleme, o andan sonraki yazımları kaybettirebileceği için trafik rollback’i yerine kullanılamaz.
TLS, Reload ve Hash Tabanlı Alternatifler
HTTP örneği mevcut HTTPS sanal hostunuza uyarlanmalıdır. TLS sertifikası, yenileme ve varsa CDN/origin erişimini ayrı test edin. Nginx reload belgeleri yeni worker’ların başlatılması ve eskilerinin mevcut istemcilere hizmet vermeyi sürdürmesini açıklar. Bundan kesintisizlik, bağlantı havuzunun sıcak kalması veya anlık boşalma garantisi çıkarılamaz. ACME otomasyonu da izleme ve hata kontrolü gerektirir.
İsteğe bağlı split_clients kullanırsanız hash yolunu da aynı canary_enabled kapısına bağlayın. Hash uzayının %5’i, gerçek kullanıcıların veya istek hacminin tam %5’i değildir. IP paylaşılabilir/değişebilir; User-Agent da değişebilir. Kalıcı uygulama kimliği daha uygun olabilir, ancak kimlik doğrulama, gizlilik ve oturum uyumluluğunu sağlamaz. Ağırlık helper’ı hash yüzdesini değiştirmez; ayrı kuralı değiştirmek kontrollü yapılandırma işlemidir.
Yayın Öncesi Son Kontroller
İki sürümün aynı anda çalışması için kapasite, hazır olma ve veri/oturum/cache uyumluluğunu doğrulayın. Başlangıçta canary kapalı olsun; geçerli ağırlıkları, hedefli test yolunu, gerçek upstream loglarını, zamanlayıcı kurulumunu ve hata dönüş kodlarını sınayın. Açılımı yeterli gerçek canary örneğine göre yönetin.
Canary, hataların etkisini sınırlamaya yardımcı olan bir yayın yöntemidir. Trafik dönüşü, uygulama geri alma ve veri kurtarmayı ayrı planlayın. Ağırlık, cookie ve varsa hash yollarını birlikte kapatabildiğinizi doğrularken geçişteki eski işlemleri de izleyin; yalnız bir başarılı reload veya sağlık yanıtıyla yayını tamamlanmış saymayın.
Ek kaynak: Nginx upstream ve ağırlıklar için resmi doküman, koşullu yönlendirme için map modülü, güvenli yeniden yükleme için kontrol komutları.
