Sürüm Yükseltme ve Değişiklik Yönetimi

Knowentra'da bir sürüm yükseltmesi yalnız yeni container image'ı çalıştırmak değildir. Uygulama ve workflow motoru kodu, veritabanı şemaları, model artefact'ları, connector operation'ları, agent/workflow sürümleri ve güvenlik politikaları birlikte davranışı belirler.

Bu rehber değişikliği şu yaşam döngüsüyle yönetir:

Talep → Etki analizi → Risk → Staging → Migration provası
      → Onay → Kademeli yayın → Doğrulama → İzleme → Kapatma / Geri alma

Değişiklik türleri

Bir release bu türlerden birkaçını içeriyorsa riski ayrı ayrı değerlendirip tek değişiklik paketinde bağımlılık sırasını belirtin.

Değişiklik sınıflandırması

Acil değişiklik kontrolsüz değişiklik değildir. Onay daha hızlı olabilir; minimum kanıt, rollback ve işlem sonrası inceleme yine gerekir.

Değişiklik kaydı

Her kayıt şunları içermelidir:

Değişiklik ID:
İş gerekçesi:
Kapsam ve etkilenen servisler:
Mevcut sürümler:
Hedef sürümler ve digest/revision:
Veri/migration etkisi:
Kimlik ve yetki etkisi:
Model/egress etkisi:
Agent/workflow etkisi:
Kesinti ve kullanıcı etkisi:
Test ve kabul kriterleri:
Yayın adımları:
Rollback veya roll-forward planı:
Sahipler ve onaylayanlar:
Bakım penceresi:
İletişim planı:
İzleme süresi:

“Bug fixleri ve iyileştirmeler” etki analizi değildir. Değişen API, şema, varsayılan, güvenlik kontrolü ve kullanıcı davranışını açıkça yazın.

Sürüm envanteri ve release manifest'i

Üretimde çalışan birleşimi tek manifest'te izleyin:

knowentra_app_image_digest
workflow_app_image_digest
workflow_migrations_digest
database_schema_revision(s)
realtime_service_version
llm_secure_gateway_version
guardrail_policy_revision
model_id + provider_revision
embedding_model_revision
connector_catalog_revision
agent/workflow published revisions
configuration_revision

UI footer'ındaki tek uygulama versiyonu bütün sistemi açıklamaz. Incident sırasında bu manifest'in belirli zamandaki kopyasına ulaşılabilmelidir.

Adım 1 — Release notlarını ve diff'i inceleyin

• Kırıcı değişiklik ve kaldırılan özellik
• Yeni/değişen environment variable
• Varsayılan değer değişikliği
• Veritabanı migration ve lock riski
• API, webhook ve tool schema değişikliği
• Kimlik/SSO/session davranışı
• Credential encryption veya secret gereksinimi
• Model provider ve routing değişikliği
• Connector permission/scope değişikliği
• Workflow execution ve retry davranışı
• Deprecation ve desteklenen göç yolu
• Güvenlik düzeltmesi ve uygulanma önceliği

Yalnız release notuna güvenmeyin; mevcut özelleştirmelerle upstream değişikliklerinin diff'ini inceleyin. Knowentra katmanları ve vendored workflow motorunun değişikliklerini ayrı değerlendirin.

Adım 2 — Bağımlılık ve uyumluluk matrisi

Rolling deployment planlıyorsanız eski ve yeni uygulama aynı DB şemasıyla geçici olarak çalışabilmelidir. Bu uyumluluk yoksa bakım penceresi veya expand–migrate–contract yaklaşımı gerekir.

Adım 3 — Veri ve güvenlik etkisi

Değişiklik için şu soruları yanıtlayın:

• Yeni veri alanı veya yeni kalıcı kopya oluşuyor mu?
• Veri başka bölgeye, modele veya alt işleyene çıkıyor mu?
• Prompt, log veya trace içeriği genişliyor mu?
• Yeni role, scope veya servis hesabına ihtiyaç var mı?
• Varsayılan fail-open/fail-closed davranışı değişiyor mu?
• Credential yeniden şifreleme veya key rotasyonu gerekiyor mu?
• Saklama ve silme davranışı değişiyor mu?
• Connector daha geniş kaynak izni istiyor mu?
• Workflow dış etkisi veya onay eşiği değişiyor mu?

Güvenlik değişikliği “teknik konfigürasyon” adı altında standart değişiklik olarak geçirilmemelidir.

Adım 4 — Yedek ve geri dönüş noktası

Yayın öncesinde:

• Son başarılı backup ve restore testini doğrulayın.
• Değişiklik öncesi tutarlı backup set'i oluşturun.
• Uygulama ve workflow DB consistency point'ini kaydedin.
• Konfigürasyon/release manifest'ini arşivleyin.
• Aktif/paused workflow ve connector checkpoint envanteri alın.
• Dış sistemde açık kritik işlemleri belirleyin.
• Rollback için eski image/model/policy artefact'larını hazır tutun.

Backup alınmış olması migration downgrade'ın güvenli olduğu anlamına gelmez. Veri geri dönüşü gerekiyorsa yayın sonrası oluşan kayıtların nasıl uzlaştırılacağını planlayın.

Adım 5 — Migration analizi

Her migration için:

Üretime benzeyen veri boyutunda prova yapın. Boş staging DB'de 2 saniye süren indeks, üretimde uzun lock oluşturabilir.

Expand–migrate–contract

Kırıcı değişikliği üç release'e bölün:

1. Expand: Yeni nullable kolon/tablo ekle; eski yol çalışmaya devam eder.
2. Migrate: Veriyi batch backfill et; dual-read/write veya adapter kullan.
3. Contract: Tüm okuyucular geçtikten sonra eski kolon/yolu kaldır.

Bu yöntem rolling deployment ve rollback penceresini korur.

Migration tekilliği

Birden fazla uygulama instance'ının aynı migration'ı paralel başlatmasını önleyin. Ayrı singleton migration job veya açık kilit mekanizması kullanın. Migration tamamlanmadan yeni uygulama trafiğini açmayın.

Adım 6 — Staging provası

Staging mümkün olduğunca üretime benzemelidir:

• Aynı servis topolojisi ve DB major sürümü
• Anonimleştirilmiş ama gerçekçi veri hacmi
• Aynı migration başlangıç revision'ı
• Sandbox model/connector hedefleri
• Üretime benzer network ve identity akışı
• Dış yazmaları engelleyen güvenlik sınırı

Prova sırası

1. Üretim-benzeri yedeği staging'e restore edin.
2. Hedef release manifest'ini kurun.
3. Migration süresi, lock ve disk kullanımını ölçün.
4. Uygulama ve workflow servislerini başlatın.
5. Smoke, negatif yetki ve kritik iş senaryolarını çalıştırın.
6. Eski sürüme uygulama rollback'ini test edin.
7. Gerekliyse backup restore ile veri rollback'ini test edin.
8. Sonuçları bakım penceresi ve RTO ile karşılaştırın.

Adım 7 — Kontrat ve regresyon testleri

Platform

• Login, logout, SSO ve session iptali
• Organizasyon/departman/Space izolasyonu
• Dosya yükleme, indirme ve RAG
• Model/gateway/guardrail davranışı
• Audit, metrics ve trace export

Agent

• Yayınlanan sürümün model, prompt, bilgi ve araçları
• Kaynak doğruluğu ve kaynak yokluğu
• Yetkisiz bilgi/araç negatif testleri
• Tool schema ve argument validasyonu
• Model değişiminde evaluation set'i

Workflow

• Editör/Knowentra workspace binding
• Yayınlanan grafik ve trigger
• Execution, retry, child workflow ve AI Feed callback
• Pause/resume/reject semantiği
• Credential ve idempotency
• Eski execution'ın sabitlenmiş sürümde bitmesi

Connector

• OAuth/credential decrypt
• Discovery, checkpoint ve artımlı sync
• Parser/chunk/index revision
• ACL ve silme semantiği
• Operation input/output şeması

Adım 8 — Model ve embedding değişikliği

Üretken model

Model alias'ını sessizce yeni sürüme taşımayın:

1. Yeni revision'ı ayrı ID ile kaydedin.
2. Veri egress ve provider koşullarını onaylayın.
3. Agent evaluation set'lerini çalıştırın.
4. Tool call şema uyumunu test edin.
5. Küçük pilot/canary kullanıcı grubuna açın.
6. Kalite, hata, latency ve maliyeti karşılaştırın.
7. Agent sürümlerini kontrollü biçimde güncelleyin.

Embedding modeli

Farklı embedding modellerini aynı index revision içinde karıştırmayın:

1. Yeni koleksiyon/index revision oluşturun.
2. Kaynakları aynı chunk/parser revision'ıyla yeniden embed edin.
3. Retrieval kalite ve ACL testlerini çalıştırın.
4. Reconciliation tamamlanınca alias'ı atomik değiştirin.
5. Eski indeksi rollback süresince salt-okunur tutun.

Adım 9 — Politika ve konfigürasyon değişikliği

Konfigürasyonu kod gibi yönetin:

• Sürümlü, review edilmiş ve ortam farkları görünür
• Secret değerleri dışarıda, referansları manifest'te
• Schema validation ve bilinmeyen alan reddi
• Varsayılan değerler açıkça sabit
• Değişiklik öncesi/sonrası diff
• Uygulayan, onaylayan ve zaman audit'i

LLM Secure Gateway, guardrail veya RBAC değişikliklerinde yalnız pozitif test yapmayın. Maskeleme zayıflatma, üst politika mirası, fail-closed ve çapraz tenant negatif testlerini çalıştırın.

Feature flag:

• Sahibine ve sona erme tarihine sahip olmalı.
• Tenant/kullanıcı hedefi açık olmalı.
• Varsayılan ve rollback davranışı belli olmalı.
• Audit edilmelidir.
• Kalıcı hâle gelince kod ve konfigürasyondan temizlenmelidir.

Adım 10 — Connector ve tool değişikliği

Bir connector/tool katalog güncellemesinde:

• Operation ekleme/silme/yeniden adlandırma
• Input/output JSON schema
• OAuth scope ve consent
• Pagination, rate limit ve retry
• Webhook imza formatı
• Source ID, cursor ve silme davranışı
• Yazma etkisi ve idempotency

kontrol edilir.

Kırılan operation'ı kullanan agent ve workflow'ları envanterden bulun. Yeni sürümü önce shadow veya sandbox hedefte çalıştırın. Scope genişlemesi gerekiyorsa mevcut consent'i otomatik varsaymayın; veri/iş sahibi onayı alın.

Adım 11 — Agent ve workflow değişikliği

Platform upgrade'i agent/workflow tanımlarını otomatik olarak “uyumlu” yapmaz.

• Bağlı model/tool/block ID'leri hâlâ mevcut mu?
• Kaldırılan parametre veya varsayılan değişti mi?
• Yayınlanmış revision ve taslak ayrımı korundu mu?
• Çalışan execution eski deployment version'a bağlı mı?
• Version restore yalnız grafı mı, credential/permission'ı da mı etkiliyor?
• Prompt veya tool şeması yeni modelde aynı davranıyor mu?

Workflow sürümünü geri almak, platform DB migration'ını geri almaz. Bu iki rollback türünü ayrı planlayın.

Adım 12 — Yayın stratejisi

Bakım penceresi

Kırıcı migration veya mixed-version uyumsuzluğunda en güvenli seçenek olabilir. Trigger ve yazmaları kontrollü durdurun.

Rolling

Eski/yeni uygulama ve şema geriye/ileriye uyumluysa instance'ları kademeli değiştirin.

Blue/green

Yeni stack'i ayrı kurun, smoke/canary sonrası trafik değiştirin. Stateful veri ve tekil trigger'larda çift yazmayı önleyin.

Canary

Belirli kullanıcı/tenant/trafik yüzdesini yeni sürüme yönlendirin. Kimlik, cache veya sticky session davranışını göz önünde bulundurun.

Adım 13 — Yayın günü

Başlamadan

• Değişiklik onayını ve sorumluları doğrulayın.
• Backup/restore kanıtını ve rollback artefact'ını kontrol edin.
• Aktif kritik workflow ve connector işlerini inceleyin.
• Kullanıcı/bakım iletişimini gönderin.
• Dashboard ve alarm baseline'ını kaydedin.

Uygulama

1. Gerekliyse trigger, schedule ve yazmaları durdurun.
2. Tutarlı backup/restore point alın.
3. Migration job'ını tekil çalıştırın.
4. Şema revision ve migration logunu doğrulayın.
5. Stateful bağımlılıkları, sonra uygulama/worker'ları güncelleyin.
6. Smoke ve negatif güvenlik testlerini çalıştırın.
7. Canary/rolling trafiği kademeli açın.
8. En son yazma etkili workflow ve connector'ları açın.

Gözlem

• Error rate ve P95/P99 latency
• DB lock, connection, disk ve migration sonrası sorgular
• Model/gateway hata ve politika kararı
• Retrieval/citation ve index revision
• Workflow queue, retry, paused ve dış etki
• Connector checkpoint ve hacim anomalisi
• Audit/OTLP exporter kaybı

Go / no-go ve abort kriterleri

Yayın öncesi sayısal eşikler belirleyin:

• Migration beklenen sürenin veya lock bütçesinin üzerinde
• Login/SSO veya tenant izolasyonu testi başarısız
• Error rate baseline'ın belirlenen katı üzerinde
• Harici model egress koruması çalışmıyor
• Kritik agent evaluation başarısız
• Workflow duplicate dış etki oluşturuyor
• Connector beklenmeyen toplu silme planlıyor
• Audit olay zincirinde boşluk var

Bu eşiklerden biri oluştuğunda kim karar verecek ve rollback/roll-forward hangi sürede başlayacak önceden belli olmalıdır.

Rollback mi, roll-forward mı?

Rollback kararıyla:

1. Yeni trafiği ve trigger'ları fence edin.
2. Yeni sürümdeki dış etkileri ve yazılan veriyi belirleyin.
3. Şema uyumluluğunu doğrulayın.
4. Uygulama veya konfigürasyonu geri alın.
5. Gerekliyse backup restore ve yeni kayıt reconciliation yapın.
6. Smoke/negatif testten sonra kontrollü açın.

“Eski image'ı çalıştır” tek başına güvenli rollback değildir.

Değişiklik sonrası

• En az tanımlı observation window boyunca izleyin.
• Release manifest ve gerçek çalışan revision'ları karşılaştırın.
• Kullanıcı ve destek bildirimlerini inceleyin.
• Koşullu kabul risklerini kapatın.
• Geçici feature flag, geniş izin ve debug loglarını kaldırın.
• Eski artefact'ı rollback süresi sonunda policy'ye göre arşivleyin.
• Başarı, sapma, rollback ve öğrenimleri değişiklik kaydına yazın.

Post-implementation review

Şunları sorun:

• Beklenen ve gerçek süre/etki neydi?
• Hangi test üretim sorununu yakalamadı?
• Runbook'ta hangi adım belirsizdi?
• Hangi alarm erken/geç geldi?
• Manuel adım otomasyona alınmalı mı?
• Risk ve kapasite varsayımları doğru muydu?

Acil değişikliklerde review zorunlu ve kısa süre içinde yapılmalıdır.

Upstream ve vendored bileşen yönetimi

Knowentra özelleştirmeleri ile upstream taban ve vendored workflow motoru ayrı değişiklik akışlarına sahip olabilir:

• Upstream commit/release tabanını kaydedin.
• Yerel patch ve davranış farklarını envanterleyin.
• Rebase/merge sırasında güvenlik ve auth yollarını özel inceleyin.
• Vendored bileşen ile bridge API/JWT purpose kontratlarını test edin.
• Upstream varsayılanının Knowentra güvenlik politikasını zayıflatmadığını doğrulayın.
• Kaldırılan legacy yolu yeni desteklenen yola migrate edin.

Upstream release notundaki bir özellik, Knowentra dağıtımında otomatik etkin veya destekli olmayabilir.

Air-gapped yükseltme

1. Image, migration, model ve SBOM paketini dış hazırlık ortamında alın.
2. Digest, imza, checksum, lisans ve zafiyet taramasını doğrulayın.
3. Onaylı transfer kapısından iç registry'ye taşıyın.
4. Staging'de tam migration ve rollback provası yapın.
5. Eksik runtime/model bağımlılığı olmadığını offline test edin.
6. Üretim bakım penceresinde aynı immutable paketi kullanın.
7. Sonucu ve kullanılan medya/artefact zincirini audit edin.

İçeride düzeltme yapıp dış manifest'ten farklı “özel paket” üretmeyin; gerekiyorsa yeni, imzalı revision oluşturun.

Değişiklik yönetimi metrikleri

• Değişiklik başarı ve rollback oranı
• Change failure rate
• Ortalama yayın ve kurtarma süresi
• Planlanan/gerçek kesinti
• Acil değişiklik oranı
• Migration süre sapması
• Değişiklik kaynaklı incident
• Otomatik test ve canary kapsamı
• Eski/deprecated sürüm sayısı
• Süresi geçmiş feature flag ve risk istisnası

Metrikleri ekipleri cezalandırmak için değil süreç darboğazı ve kalite iyileştirmesi için kullanın.

Kontrol listesi

• Değişiklik türü, risk sınıfı ve sahipleri belli.
• Hedef bileşenler digest/revision ile sabitlendi.
• Release notu, diff ve deprecation'lar incelendi.
• Bağımlılık/mixed-version uyumluluk matrisi hazır.
• Veri, kimlik, egress ve dış etki analizi yapıldı.
• Tutarlı backup ve doğrulanmış restore yolu var.
• Migration lock, hacim, disk ve downgrade analizi tamam.
• Üretim benzeri veride migration ve rollback provası geçti.
• Platform, agent, workflow ve connector kontrat testleri geçti.
• Model değişikliği evaluation ve canary içeriyor.
• Embedding değişimi yeni index revision kullanıyor.
• Feature flag sahibi ve sona erme tarihi var.
• Yayın stratejisi ve çift yazma/fencing kontrolü belli.
• Go/no-go ve abort eşikleri sayısal.
• Rollback ile veri/dış etki reconciliation birlikte planlandı.
• Dashboard, alarm, iletişim ve observation window hazır.
• Gerçek release manifest'i ve audit kaydı güncellendi.
• Post-implementation review aksiyonları sahipli.

Sonraki adımlar

• Kurtarma planı için Yedekleme, Geri Yükleme ve Felaket Kurtarma
• İzleme için Audit Logları ve Gözlemlenebilirlik
• Agent değişimleri için Agent Oluşturma ve Yayınlama
• Workflow sürümleri için Workflow Tasarım Rehberi
• Operasyon sırasında destek için Sorun Giderme