Tarayıcıda WebGPU ile Yapay Zeka Modellerini Hızlandırma: ONNX Runtime Web ile Adım Adım Rehber

WebGPU ile Tarayıcıda Yapay Zeka Neden Önemli?

WebGPU, tarayıcıda GPU’ya neredeyse yerel erişim sağlayan modern bir web standardıdır. WebGL’in grafik odaklı doğasını aşarak hesaplama iş yüklerini de hızlandırır ve makine öğrenmesi modellerini doğrudan Chrome, Edge veya Safari gibi tarayıcılarda çalıştırırken belirgin performans kazancı sunar. Bu yazıda, ONNX Runtime Web kullanarak WebGPU üzerinden nasıl hızlandırma yapabileceğinizi, gerçek dünya ipuçları ve sorun giderme önerileriyle adım adım anlatıyorum.

Ön Koşullar ve Uyumluluk

WebGPU, Chrome 113+, Edge 113+ sürümlerinde yaygın olarak desteklenir. macOS’te Metal, Windows’ta Direct3D 12, Linux’ta ise Vulkan üzerinden çalışır. Güncel bir tarayıcı kullandığınızdan emin olun. Kurumsal cihazlarda GPU sürücüleri eskiyse veya politika kısıtları varsa WebGPU adaptörü bulunamayabilir; bu durumda ONNX Runtime Web otomatik olarak WASM (WebAssembly) yedek yoluna düşebilir. Eğer eski bir tarayıcı kullanıyorsanız, chrome://flags alanında WebGPU ile ilgili ayarları gözden geçirmeniz gerekebilir; ancak çoğu güncel sürümde ekstra bir işlem yapmadan çalışır.

Ne Kuracağız? Kısa Yol Haritası

Bu rehberde bir web sayfasına ONNX Runtime Web’i entegre edip, bir görüntü sınıflandırma modelini WebGPU üzerinde çalıştıracağız. Adımlar özetle şöyle: ONNX Runtime Web’i projeye eklemek, uygun bir ONNX modeli seçmek, girdi verisini hazırlamak, executionProviders: ["webgpu"] ile oturum açmak ve sonuçları yorumlamak.

Adım 1: Projeye ONNX Runtime Web Eklemek

İki yaygın yöntem var. NPM ile kurulum için modern bir paketleyici (Vite, Webpack, Parcel) kullanabilirsiniz. Komut satırında npm i onnxruntime-web diyerek kurduktan sonra uygulamanızda import * as ort from "onnxruntime-web" ifadesini kullanın. Hızlı denemeler için CDN ile de ilerleyebilirsiniz: HTML dosyanıza ONNX Runtime Web’in CDN bağlantısını eklemek yeterli olur. Her iki yöntemde de tarayıcınızda WebGPU destekliyse arka planda otomatik olarak GPU hızlandırma devreye alınabilir.

Adım 2: Model Seçimi ve Hazırlık

Başlangıç için ONNX Model Zoo’da bulunan hafif bir model tercih edin. Örneğin MobileNet veya SqueezeNet düşük bellek tüketimiyle iyi bir başlangıç sunar. İndirdiğiniz model dosyasını (örnek: model.onnx) sunucunuzdan statik olarak servis edin. Model boyutunu mümkün olduğunca düşük tutmak hem ilk yükleme süresini hem de bellek kullanımını azaltır. FP16 dönüştürülmüş modeller, GPU bellek ayak izini düşürerek performansa katkı sağlar.

Adım 3: WebGPU ile Oturum Oluşturma

ONNX Runtime Web ile bir oturum oluştururken executionProviders: ["webgpu"] parametresini geçerek GPU hızlandırmayı istersiniz. WebGPU uygun değilse kütüphane WASM’a otomatik geçebilir. Bu aşamada önemli nokta, oturumu yalnızca bir kez oluşturmanızdır; inference işlemleri sırasında aynı oturumu tekrar tekrar kullanmak, modelin yeniden yüklenmesini ve derlenmesini önleyerek ciddi zaman kazandırır.

Adım 4: Girdi Hazırlama ve İnference

Görüntü tabanlı bir model için girdiyi modele uygun boyuta ölçekleyip normalleştirmeniz gerekir. Bu işlem genellikle şu adımlardan oluşur: görseli kanallara ayırma (RGB), piksel değerlerini 0-1 aralığına ölçekleme, ortalama/standart sapma ile normalizasyon ve tensörü NCHW biçiminde düzenleme. ONNX Runtime Web için tensör oluştururken new ort.Tensor("float32", data, [1, 3, H, W]) biçimini kullanabilirsiniz. Çıktı yüzlerce sınıf ve olasılık içeriyorsa en yüksek olasılıklı birkaç etiketi seçip kullanıcıya sunmak idealdir.

Adım 5: Performans İyileştirme İpuçları

Performansı artırmak için birkaç pratik öneri: Oturum nesnesini yeniden kullanın ve model dosyasını önbelleğe alarak ilk yükleme süresini kısaltın. Girdi verisini oluştururken gereksiz kopyalardan kaçının; aynı Float32Array tamponunu yeniden kullanmak GC yükünü azaltır. Mümkünse daha küçük çözünürlükte girişler deneyin; bazı modeller 224x224 ile tatmin edici sonuç verir. Ağır iş yüklerini Web Worker içine taşıyarak ana iş parçacığını bloklamayın; UI donmalarını önlemek için hesaplama dilimlerini requestIdleCallback veya küçük partisyonlarla planlayın. Ölçüm için performance.now() ile yükleme, ön işleme, inference ve son işlem sürelerini ayrı ayrı izleyin; darboğazı nokta atışı bularak iyileştirin.

Güvenlik, Gizlilik ve Dağıtım

Tarayıcı içinde yerel inference çalıştırmak, verilerin sunucuya gitmeden işlenmesini sağlar; bu da gizlilik ve gecikme (latency) açısından avantajdır. WASM yedek yolunda iş parçacıkları ve SIMD kullanmayı planlıyorsanız COOP/COEP başlıklarıyla cross-origin isolated bir yapılandırma gerekir. İç ağda veya kurumsal ortamlarda dağıtım yaparken GPU sürücü sürümlerini ve tarayıcı versiyonlarını standardize etmek, destek çağrılarını ciddi ölçüde azaltır.

Yaygın Hatalar ve Çözümler

“Adapter is null” veya “No WebGPU device found” hataları alıyorsanız tarayıcınızı ve ekran kartı sürücünüzü güncelleyin; sanal makinelerde WebGPU kısıtlı olabilir. “Out of memory” uyarılarında giriş boyutunu küçültün, modelin FP16 sürümüne geçin veya daha hafif bir mimari deneyin. “Invalid model input shape” hatası, tensör boyutlarıyla modelin beklediği şeklin uyuşmadığını gösterir; modelin giriş ismini ve beklenen boyutları kontrol edin. WASM’a düşüşte performans çok geriliyorsa, WebGPU’nun gerçekten etkinleştiğini doğrulamak için oturum seçeneklerini ve tarayıcı destek sayfalarını inceleyin.

Gerçek Dünya Senaryoları

Perakende uygulamalarında raf denetimi veya barkod dışı ürün tanıma gibi görevler, mağaza içi tabletlerle çevrimdışı çalıştırılabilir. Eğitim teknolojilerinde çizim veya laboratuvar deneylerinde görüntü analizi, öğrenci cihazlarında gecikme olmadan yapılabilir. Yayıncılıkta canlı metin filtreleme veya basit duygu analizi, kullanıcı tarayıcısında gerçekleşerek sunucu maliyetlerini düşürür.

Sonuç ve Öneriler

WebGPU, tarayıcıda yapay zeka deneyimini yeni bir seviyeye taşıyor. ONNX Runtime Web ile birlikte kullanıldığında, çeşitli cihaz ve tarayıcı kombinasyonlarında tatmin edici performans ve düşük gecikme elde etmek mümkün. Küçük ve optimize edilmiş bir model, doğru ön işleme adımları ve tek seferde başlatılan bir oturum mimarisi, projelerinize stabilite ve hız kazandırır. İlk prototipinizi basit bir görüntü sınıflandırma modeliyle kurup, ardından model boyutu, giriş çözünürlüğü ve iş parçacığı stratejileri üzerinde iterasyon yaparak prodüksiyon seviyesine güvenle geçebilirsiniz.

Rust ve WebAssembly ile Tarayıcıda Görüntü İşleme: Adım Adım Rehber

Giriş

WebAssembly (WASM), tarayıcıda neredeyse yerlisi kadar hızlı çalışan kodlar yazmayı mümkün kılıyor. Eğer piksel piksel görüntü işleme, gerçek zamanlı filtreler veya CPU yoğun işlemlerle uğraşıyorsanız, JavaScript tek başına her zaman yeterli olmayabilir. Bu rehberde, Rust + WebAssembly ikilisini kullanarak tarayıcıda basit bir görüntü işleme modülü oluşturmayı ve performansı artırmanın pratik yollarını adım adım anlatıyorum.

Neden Rust + WebAssembly?

Performans: Rust derlenmiş kodu WebAssembly’ye taşıdığınızda, piksel manipülasyonu gibi yoğun işlemlerde belirgin bir hız kazanırsınız. Özellikle büyük görsellerde JavaScript döngülerinin sınırlamalarını aştığınızı hissedeceksiniz.

Bellek güvenliği: Rust’ın sahiplik modeli ve derleyici kontrolleri, tipik bellek hatalarını en başında engeller. Tarayıcı gibi hassas bir ortamda bu oldukça kritiktir.

Taşınabilirlik: WASM çıktısı, modern tüm tarayıcılarda çalışır. Rust tarafında yazdığınız çekirdek algoritmaları, Node.js veya Wasmtime gibi ortamlarda da kullanabilirsiniz.

Gereken Araçlar ve Kurulum

Rust kurulumu için resmi yönlendiriciyi tercih edin: rustup. Ardından WASM hedefini ekleyin: rustup target add wasm32-unknown-unknown. Paketleme ve bağlayıcılar için wasm-pack aracını kurun: cargo install wasm-pack. Tarayıcı tarafında modülü kullanmak için npm veya yarn da işinizi kolaylaştırır.

Yeni bir kütüphane projesi oluşturun: cargo new goruntu-wasm --lib. Proje klasörüne geçin ve Cargo.toml dosyasına wasm-bindgen bağımlılığını ekleyin.

Proje İskeleti ve Yapılandırma

Cargo.toml içine aşağıdakine benzer satırlar ekleyin: [dependencies] wasm-bindgen = "0.2". Derleme hedefi için [lib] bölümüne crate-type = ["cdylib", "rlib"] yazmayı unutmayın. Bu, Rust kütüphanesinin WASM olarak bağlanabilmesini sağlar.

Kaynak dosyası src/lib.rs içinde, JavaScript ile köprü kurmak için wasm_bindgen makrolarını kullanacağız. Temel bir dışa aktarma şöyle görünür: use wasm_bindgen::prelude::*; #[wasm_bindgen] pub fn versiyon() -> String { "0.1.0".into() }. Bu, tarayıcıda modül yüklendiğinde çağrılabilir bir fonksiyon üretir.

Tarayıcı Entegrasyonu

Derlemek için wasm-pack build --target web komutunu çalıştırın. Bu, pkg klasöründe ES modül uyumlu bir çıktı üretir. Ön yüzde bir modül dosyasında şu şekilde içe aktarabilirsiniz: import init, { versiyon } from "./pkg/goruntu_wasm.js"; await init(); console.log(versiyon());. Basit bir HTML sayfasında <script type="module"> kullanarak bu modülü kolayca yükleyebilirsiniz.

Paket yöneticisi ile entegre çalışmak isterseniz wasm-pack çıktısını bir NPM paketi gibi tüketebilirsiniz. Bu sayede Vite, Webpack veya Parcel ile ağaç sarsma ve önbellekleme gibi optimizasyonlardan faydalanırsınız.

Basit Bir Gri Tonlama (Grayscale) Örneği

Tarayıcıdan aldığınız ImageData nesnesi, RGBA kanal sıralı bir Uint8ClampedArray içerir. Bu diziyi WASM tarafına aktarıp geri almak için iki pratik yol var: kopyalamak veya paylaşılan bir tampon üzerinden erişmek. Başlangıç için, güvenli ve net olduğu için kopyalama yaklaşımı işinizi görecektir.

Rust tarafında bir fonksiyon düşünün: #[wasm_bindgen] pub fn grayscale(input: Vec<u8>) -> Vec<u8> { ... }. Algoritma basit: Her piksel için r, g, b değerlerinin ağırlıklı ortalamasını alın ve geri yazın. Yaygın bir yaklaşım: gray = 0.299*r + 0.587*g + 0.114*b. Rust’ta tamsayı işlemlerinde küçük bir yuvarlama eklemek renk doğruluğunu iyileştirir.

Ön yüzde, CanvasRenderingContext2D ile bir görüntüyü çizip getImageData ile pikselleri alın. Daha sonra const out = grayscale(new Uint8Array(imageData.data)); gibi bir çağrıyla sonuç dizisini alın ve putImageData ile tekrar tuvale yazın. Bu döngüde veriyi fazla kopyalamamak için işlemi toplu yapın; birden fazla filtre uygulayacaksanız tek bir WASM çağrısında zincirlemek daha etkilidir.

Performans İpuçları

SIMD desteği: Modern tarayıcılar WASM SIMD’i destekliyor. Rust’ta std::arch veya uygun crate’lerle vektörleştirme yaparak yaklaşık 2-4 kat hız artışı görebilirsiniz. Varsa RUSTFLAGS="-C target-feature=+simd128" deneyin.

Veri kopyalarını azaltın: Çok büyük görüntülerde her karede kopyalama pahalıdır. Orta vadede wasm-bindgen ile Uint8Array tamponunu paylaşmak veya WebAssembly.Memory üzerinden doğrudan yazmak daha iyi sonuç verir.

Web Workers: Ana iş parçacığını kilitlememek için görüntü işlemeyi bir Worker içine taşıyın. OffscreenCanvas kullanabiliyorsanız, çizim ve filtrelemeyi tamamen worker içine izole ederek UI akıcılığını korursunuz.

Ön ısıtma: Modülü sayfa yüklenir yüklenmez başlatıp küçük bir “ısındırma” çağrısı yapmak, JIT/optimizasyon basamaklarını kullanıcı etkileşimi öncesinde tamamlamaya yardımcı olur.

Hata Ayıklama ve Ölçüm

WASM kodunu debug modunda derlediğinizde boyut artar ve performans düşer; bu normaldir. Geliştirmede console.time/console.timeEnd ile uçtan uca süreleri ölçün, Performance.now() ile kare bazlı gecikmeyi takip edin. Rust tarafında log ve console_error_panic_hook kullanarak panik ve logları tarayıcı konsoluna yönlendirebilirsiniz.

Boyut optimizasyonu için üretim derlemesinde wasm-opt -O3 (Binaryen) deneyin. Ayrıca wasm-pack build --release kullanarak sembol isimlerini küçültür ve gereksiz debug bilgilerini atarsınız.

Sonuç

Rust ve WebAssembly, tarayıcıda görüntü işleme gibi CPU ağırlıklı görevlerde güvenli, hızlı ve öngörülebilir bir çalışma zemini sunuyor. Basit bir gri tonlama filtresiyle başladık; aynı yaklaşımı kenar algılama, bulanıklaştırma, renk düzeltme veya gerçek zamanlı kamera filtrelerine kolayca genişletebilirsiniz. Doğru veri aktarım stratejisi, SIMD ve Web Workers ile birleştiğinde, modern web uygulamalarında yerel uygulama hissi veren bir performans elde etmek mümkün. Bir kez kurduktan sonra, bu altyapıyı pek çok projede tekrar tekrar kullanabileceğinizi göreceksiniz.

WebGPU ile Tarayıcıda Nesne Tespiti: ONNX Runtime Web ile Adım Adım Kurulum

Giriş

Tarayıcıda makine öğrenmesi artık bir demodan öte; üretim senaryolarına hazır. WebGPU sayesinde GPU hızlandırmalı hesaplama, Chrome ve Edge gibi modern tarayıcılarda varsayılan olarak açıldı. Bu rehberde, ONNX Runtime Web (ORT Web) kullanarak tarayıcı içinde nesne tespiti (YOLO ailesi gibi) modelini çalıştırmayı ve WebGPU yürütme sağlayıcısı ile performansı nasıl artırabileceğinizi anlatıyorum. Kurulum adımlarını, küçük kod parçacıklarıyla ve pratik ipuçlarıyla beraber bulacaksınız.

Neden WebGPU?

WebGPU, WebGL’in ötesine geçerek daha modern bir grafik ve hesaplama API’si sunar. ML tarafında en kritik fark, tensör hesaplamalarını verimli çalıştırabilmesi ve veri kopyalamayı azaltmasıdır. Sonuç olarak, aynı model WebAssembly (WASM) ile 200-400 ms sürerken, WebGPU ile 60-120 ms aralığına inebilir; bu özellikle canlı kamera akışında kare kaçırmamak için belirleyici bir fark yaratır.

Ön Koşullar ve Tarayıcı Desteği

- Chrome 113+ ve Edge 113+ sürümlerinde WebGPU masaüstünde varsayılan olarak açık. Mac’te Apple Silicon ile daha istikrarlı sonuçlar alırsınız. Firefox’ta Nightly ile about:config altında dom.webgpu.enabled bayrağını etkinleştirmeniz gerekebilir. Safari’de ise Technology Preview önerilir.
- Geliştirme için basit bir statik sunucu kullanın: npx serve, python -m http.server veya VS Code Live Server eklentisi işinizi görür. Dosyaları doğrudan diskten açmak (file://) CORS hatalarına yol açar.

Proje Yapısı

Minimum örnek için şu dosyaları oluşturun: index.html, app.js ve model dosyanız (ör. yolov8n.onnx). Test için bir görüntü dosyası veya webcam akışı kullanabilirsiniz. Kamera ile test edecekseniz, HTTPS üzerinde yayınlamayı unutmayın; tarayıcılar güvenlik nedeniyle kamera erişimini HTTP’de kısıtlar.

ONNX Runtime Web’i Ekleme

CDN ile hızlı başlamak için index.html içine ORT Web’i ekleyebilirsiniz: <script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/ort-web.min.js"></script>. Alternatif olarak modüler kullanım için paket yöneticileriyle onnxruntime-web kurabilir, bundler ile projeye dahil edebilirsiniz. WebGPU hızlandırma için çalışma zamanı seçeneklerinde executionProviders: ['webgpu'] belirtmeniz yeterli.

Oturum Oluşturma ve WebGPU’yu Açma

Temel başlatma adımı şöyledir: const session = await ort.InferenceSession.create('yolov8n.onnx', { executionProviders: ['webgpu'], graphOptimizationLevel: 'all' });. Eğer cihazda WebGPU yoksa otomatik olarak WASM’a düşmek isteyebilirsiniz; o durumda önce WebGPU ile dene, başarısız olursa executionProviders: ['wasm'] ile yeniden oluştur şeklinde bir sarmalayıcı yazın.

Girdi Hazırlama

Nesne tespiti modelleri tipik olarak BxCxHxW float32 tensörü bekler. Tarayıcı tarafında Canvas üzerinden resmi alıp 640x640 gibi modele uygun boyuta yeniden örnekleyin, ardından ImageData piksellerinden Float32Array oluşturun. Kanal sıralaması (NCHW vs NHWC) ve normalizasyon (0-1 arası ölçek, ortalama-standart sapma) modelinize göre değişir; ONNX ihracını yaparken hangi düzen kullanıldıysa ona sadık kalın. Örnek: const input = new ort.Tensor('float32', floatArray, [1,3,640,640]);

Çıktıların İşlenmesi

YOLO tarzı modeller, her kutu için [x, y, w, h, score, class] veya benzeri bir yapı üretir. Post-processing adımları: skor eşiği uygulama (örn. 0.25), Non-Maximum Suppression ile çakışan kutuları eleme ve sınıf etiketleri ile renklendirme. ORT WebGPU bazı durumlarda çıktı tensörünü GPU belleğinde tutabilir; tarayıcı tarafında çizmek için CPU’ya kopyalamanız gerekir. Performans için tek bir canvas üzerinde hem görüntü hem de kutuları çizmek, her karede gereksiz tahsislerden kaçınmak önemlidir.

Performans İpuçları

- Model boyutu: YOLOv8n gibi küçük varyantlarla başlayın; tarayıcıda latency dramatik şekilde düşer.
- Precision: FP16 desteği olan cihazlarda otomatik kazanç sağlanır. ORT Web, WebGPU arka ucunda uygunsa bunu kullanır.
- İşletim birleştirme: graphOptimizationLevel: 'all' genellikle faydalı. Bazı modellerde ek kazanımlar için ONNX’ı optimize edin (Fusion/Constant folding).
- Batch=1: Akış senaryolarında tekli batch en düşük gecikmeyi verir.
- Sıcak çalışma: İlk çalıştırmadan önce bir kez “ısındırma” inference’ı yapın; shader derlemeleri ve önbellekler sonrası kare süreleri iyileşir.

Güvenlik ve Barındırma

Model dosyanız büyükse (ör. 20-50 MB), ilk yükleme süresi kullanıcı deneyimini etkiler. HTTP istemci önbelleği için uzun Cache-Control süreleri ayarlayın ve sürümleme yapın. Kamera kullanan sayfalar için HTTPS zorunlu. Cross-origin model yüklerken CORS başlıklarını doğru verin (Access-Control-Allow-Origin). Ayrıca, kullanıcı donanımlarında GPU kaynakları sınırlı olabilir; bir hata durumunda kibarca WASM’a düşmek, uygulamanın kırılmasını engeller.

Hata Ayıklama

- navigator.gpu yoksa tarayıcı sürümünüzü ve bayrakları kontrol edin.
- ValidationError görüyorsanız tensör şekilleri/hizalamaları uyuşmuyor olabilir. Girdiyi ve modelin beklediği düzeni tekrar gözden geçirin.
- Performance sekmesiyle CPU/GPU zamanlarını izleyin; çoğu darboğaz, görüntü ön-işlemede ortaya çıkar. Web Workers ile ön-işlemeyi ana iş parçacığından ayırmak sayfa akıcılığını artırır.

Sonuç

WebGPU ve ONNX Runtime Web birleşimi, tarayıcıda ML uygulamaları için yeni bir performans eşiği sunuyor. Sunucuya görüntü yüklemeden, gizlilik dostu ve düşük gecikmeli nesne tespiti mümkün. Bu rehberdeki yapı ile kısa sürede çalışan bir prototip çıkarabilir, ardından model optimizasyonu, önbellekleme ve UI cilasıyla üretim seviyesine taşıyabilirsiniz. Bir kez kurduktan sonra, segmentasyon, yüz mesh’i ya da metin tespiti gibi diğer ONNX modellerini de aynı altyapı üzerinde hızla deneyebilirsiniz.

OpenTelemetry ile Mikroservislerde Dağıtık İzleme: Grafana Tempo ve OTEL Collector ile Hızlı Kurulum Rehberi

Giriş

Mikroservis mimarisine geçişle birlikte klasik log takibi, bir isteğin sistem içindeki yolculuğunu uçtan uca anlamak için yetersiz kalıyor. OpenTelemetry (OTel), uygulama metrikleri, loglar ve izleri (traces) için standartlaştırılmış bir yaklaşım sunarak bu boşluğu kapatıyor. Bu yazıda, Grafana Tempo ve OpenTelemetry Collector kullanarak 30 dakikada çalışır bir dağıtık izleme hattı kurmayı, uygulamaları enstrümante etmeyi ve üretime hazır ipuçlarını paylaşacağım.

Mimari ve Gereksinimler

Basit bir akış ile başlıyoruz: Uygulamalarınız OpenTelemetry SDK ile izleri üretir ve OTLP üzerinden OTel Collector’a gönderir. Collector, veriyi işleyip Tempo’ya aktarır. Görselleştirme için Grafana kullanırız. Aynı Collector hattına logları da bağlayabilir, korelasyon için traceID’yi loglara ekleyebilirsiniz.

Gereksinimler: Docker veya Kubernetes bilgisi, temel ağ/TLS kavrayışı ve uygulamalarınızda enstrümantasyon için Node.js/Java/Python’dan biri.

Adım 1: Uygulamanızda OpenTelemetry SDK’yı Etkinleştirin

Amaç, her servisin bir service.name etiketiyle izlerini göndermesi. Örnek olarak Node.js verelim. Kurulum:
npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-otlp-grpc
Basit bootstrap (otel.js) içinde şunları ayarlayın: hizmet adı, OTLP gRPC endpoint’i (collector:4317), Resource etiketleri (deployment.environment, service.version) ve BatchSpanProcessor. Uygulamayı bu bootstrap ile başlatın: node -r ./otel.js server.js.

Java (Spring Boot) tarafında opentelemetry-javaagent.jar ile kod değişikliği olmadan başlamak mümkün: java -javaagent:opentelemetry-javaagent.jar -Dotel.service.name=orders -Dotel.exporter.otlp.endpoint=http://collector:4318 -jar app.jar

Python (FastAPI) için benzer şekilde opentelemetry-distro ve otlp exporter kurup OTEL_EXPORTER_OTLP_ENDPOINT ve OTEL_SERVICE_NAME çevre değişkenlerini tanımlayabilirsiniz.

Adım 2: OpenTelemetry Collector Konfigürasyonu

Collector, veriyi merkezi olarak alır, zenginleştirir ve hedeflere yollar. Minimal bir topology şöyle olabilir:
- Receivers: otlp (grpc ve http),
- Processors: batch, attributes (ör. ortam bilgisi ekleme), tailsampling (isteğe bağlı),
- Exporters: otlp veya http tempo exporter (Grafana Tempo’ya),
- Extensions: health_check (durum kontrolü).

Basit bir YAML iskeleti (satır sonları korunarak kullanın):
receivers:
  otlp:
    protocols:
      grpc:
      http:
processors:
  batch:
exporters:
  otlp:
    endpoint: http://tempo:4317
    tls:
      insecure: true
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

Adım 3: Tempo ve Grafana’yı Hızlıca Ayağa Kaldırın

Docker Compose ile tek makinede deneme yapmak kolaydır. Örnek içerik:
version: "3.9"
services:
  tempo:
    image: grafana/tempo:latest
    ports: ["3200:3200", "4317:4317"]
  otel-collector:
    image: otel/opentelemetry-collector:latest
    ports: ["4317:4317", "4318:4318"]
    volumes: ["./otel-collector.yaml:/etc/otelcol/config.yaml"]
    command: ["--config=/etc/otelcol/config.yaml"]
  grafana:
    image: grafana/grafana:latest
    ports: ["3000:3000"]

Grafana arayüzüne (http://localhost:3000) girip Tempo’yu veri kaynağı olarak ekleyin. Sonrasında Explorations bölümünden trace araması yapabilir, service.name, http.target veya status.code gibi etiketlerle filtreleyebilirsiniz.

Adım 4: Örnek İşlem ve Trace Korelasyonu

Bir müşteri sipariş akışı düşünelim: api-gateway → orders → payments → notifications. Gateway, gelen isteğe traceparent üretir. Orders servisi DB işlemini bir span olarak işaretler; payments servisi harici ödeme sağlayıcısına giden HTTP çağrısını ayrı bir span olarak ekler. Bildirim servisi e-posta/SMS entegrasyonunu başka bir span’a yazar. Grafana Tempo üzerinde tek bir TraceID ile tüm zinciri adım adım görebilirsiniz.

Log korelasyonu için, uygulamanızın log satırlarına trace_id ve span_id ekleyin. Böylece bir hata logundan direkt ilgili trace’e atlayarak kök neden analizi (RCA) yapabilirsiniz.

Adım 5: Örnekleme (Sampling) ve Maliyet Kontrolü

Üretimde her isteği izlemek pahalı olabilir. Başlangıç için ParentBased + TraceIdRatio sampling uygundur: giriş isteklerinin %5’i örneklenir, bu karar alt çağrılara taşınır. Trafiğiniz zirvede arttığında Collector’ın tail sampling özelliğini kullanarak hatalı veya yavaş istekleri önceliklendirebilirsiniz (ör. duration > 500ms veya status.code != OK olanlar).

Güvenlik ve Uyum

OTLP trafiğini TLS ile koruyun. gRPC için 4317, HTTP için 4318 portlarını güvenlik gruplarıyla sınırlandırın. İzlerde kişisel veriyi (PII) tutmaktan kaçının; attributes processor ile maskeleme yapabilir veya whitelisting uygulayabilirsiniz. Harici servislere giden isteklerde başlıkları (headers) kayda geçirmeden önce ayıklayın.

Kubernetes’te Çalıştırma İpuçları

Collector’ı DaemonSet (node başına agent) veya Deployment (merkezi gateway) olarak çalıştırabilirsiniz. Latensi duyarlı servisler için aynı node’daki agent’a göndermek, gecikmeyi düşürür. resource etiketlerine kubernetes.namespace.name ve pod.name ekleyerek grafana panellerinde anlamlı filtreler elde edin.

Hata Ayıklama ve Ölçüm

Collector’ın health endpoint’ini izleyin, span queue doluluklarını kontrol edin. Uygulama tarafında enstrümantasyonun devreye girip girmediğini anlamak için başlangıçta console exporter ile kısa süreli test yapabilirsiniz. Grafana’da Exemplars kullanarak metrikteki bir anomaliyi doğrudan ilgili trace’e bağlamak, teşhisi hızlandırır.

Sonuç

OpenTelemetry + Tempo + Collector üçlüsü, mikroservislerde uçtan uca görünürlük sağlamak için güçlü ve esnek bir temel sunuyor. İlk kurulum basittir; ilerleyen aşamalarda örnekleme, maskeleme ve korelasyon stratejileri ile hattınızı olgunlaştırabilirsiniz. Bugün küçük başlayın: bir servisi enstrümante edin, Collector ve Tempo’yu çalıştırın, ardından en çok sorun yaşadığınız akışa odaklanarak görünürlüğü sistem geneline genişletin.

Docker Compose’tan Kubernetes’e Geçiş: Helm Chart ile Adım Adım Dağıtım Rehberi

Giriş

Docker Compose, tek makinede çok konteynerli uygulamaları hızla ayağa kaldırmak için harika. Ancak ölçek, güvenlik ve gözlemlenebilirlik ihtiyaçları arttığında, Kubernetes’e geçiş kaçınılmaz oluyor. Bu yazıda, mevcut Compose tanımınızı Helm Chart’a dönüştürerek Kubernetes üzerinde modern, sürdürülebilir ve otomasyona uygun bir dağıtım yapmayı adım adım ele alacağız. Rehber, pratik örnekler, en iyi uygulamalar ve sık yapılan hatalara karşı öneriler içerir.

Neden Helm?

Helm, Kubernetes manifestlerini paketleyip versiyonlayarak tekrar kullanılabilir hale getirir. values.yaml ile çevreye göre yapılandırma yönetimi kolaylaşır, helm upgrade --install ile idempotent dağıtımlar yapılır, rollback ile hızlı geri dönüş sağlanır. Çeviklik, izlenebilirlik ve CI/CD uyumluluğu açısından Compose’a kıyasla çok daha güçlü bir yönetim modeli sunar.

Ön Koşullar

- Kubernetes kümesi (minikube, kind, AKS, EKS veya GKE)
- kubectl ve helm kurulu (Helm v3 önerilir)
- Mevcut Docker Compose dosyası (docker-compose.yml)
- Bir container registry erişimi (Docker Hub, GHCR, ECR vs.)

Compose’tan Helm’e Modelleme

Compose servislerini tek tek Deployment ve Service kaynaklarına bölün. Her servis için bir Deployment (replica sayısı, image, env, volume mount) ve bir Service (ClusterIP veya LoadBalancer) oluşturun. Ağ politikaları, health check, kaynak limitleri gibi Kubernetes yerleşik yeteneklerle güvenilirlik ve ölçeklenebilirlik kazanın.

Helm Chart İskeleti Oluşturma

Proje dizininde helm create uyg-app komutunu çalıştırın. Oluşan yapı:
charts/
templates/
values.yaml
Chart.yaml
Yararlı şablonlar gelse de, gereksiz varsayılanları sadeleştirmek iyi bir başlangıçtır.

values.yaml Tasarımı

Uygulamanın farklı ortamları için değişecek alanları values.yaml içine alın. Örnek bir iskelet:
image.repository: ghcr.io/org/uyg-app
image.tag: 1.2.3
replicaCount: 3
resources.limits.cpu: "500m"
resources.limits.memory: "512Mi"
env: { APP_ENV: "prod", LOG_LEVEL: "info" }
service.type: ClusterIP
service.port: 8080
ingress.enabled: true
ingress.hosts: ["api.ornek.com"]

Deployment ve Service Şablonları

Deployment için şunları ihmal etmeyin:
- resources: request ve limit belirleyin (örn. cpu: 200m, memory: 256Mi).
- livenessProbe ve readinessProbe: HTTP endpoint veya TCP check ile hızlı hata tespiti.
- securityContext: root dışı kullanıcı, readOnlyRootFilesystem, capabilities kısıtlaması.
- envFrom: ConfigMap ve Secret’lardan çevresel değişken yönetimi.
Service için uygun type (ClusterIP, NodePort, LoadBalancer) ve port seçin. Dış dünyaya açılacaksanız Ingress tanımı ve TLS sertifikası (ör. cert-manager) planlayın.

İnşa, Push ve İlk Dağıtım

- Container imajınızı CI üzerinden versiyonlayın ve registry’ye push edin (örn. 1.2.3 tag’i).
- values.yaml içindeki image.tag değerini güncelleyin.
- İlk kurulum: helm upgrade --install uyg-app ./uyg-app -n prod
- Dağıtımı doğrulayın: kubectl get pods -n prod ve kubectl describe ile olayları inceleyin.

Yükseltme ve Geri Alma

- Versiyon güncellemesi: helm upgrade uyg-app ./uyg-app -n prod
- Farkları görmek için: helm diff upgrade (helm-diff eklentisi).
- Sorun varsa: helm rollback uyg-app <REVISION> -n prod. Helm, geçmiş sürümleri sakladığından geri dönüşler saniyeler içinde tamamlanır.

Gizli Bilgiler ve Config Yönetimi

Şifreler, token’lar ve API anahtarlarını Secret içinde tutun. Git’te açık tutmamak için Sealed Secrets veya External Secrets Operator kullanın. Konfigürasyonlarınızı ConfigMap olarak versiyonlayın; uygulama yeniden başlatması gerektiren değişikliklerde checksum/config anotasyonuyla otomatik rollout sağlayın.

Otomatik Ölçeklendirme ve Sağlık

HPA (Horizontal Pod Autoscaler) ile CPU/Memory metriklerine göre pod sayısını otomatik artırıp azaltın. readinessProbe doğru ayarlı değilse HPA ölçeklense bile trafiğin başarısız olacağını unutmayın. Ayrıca PodDisruptionBudget ile planlı bakım sırasında minimum sağlıklı pod sayısını garanti altına alın.

Güvenlik ve RBAC

Uygulamaya özel bir ServiceAccount tanımlayın, yalnızca gerekli izinleri veren bir Role/RoleBinding ekleyin. PodSecurityContext ile kullanıcı/GRUP ID belirleyin, root olarak çalışmayın. Ağ tarafında NetworkPolicy ile trafik kısıtlaması yaparak saldırı yüzeyini daraltın.

CI/CD ve GitOps

- CI adımları: test → build → scan → push → helm lint → helm template/diff → deploy.
- GitOps için Argo CD veya Flux kullanın. Helm chart’ınızı bir Git deposuna koyun, values dosyalarını ortam bazlı dallarda yönetin. Her commit, küme durumunu deklaratif olarak günceller; manuel hataları azaltır.

Gözlemlenebilirlik: Log, Metrik ve İz

Log’lar için stdout/stderr yazın; kümede Loki/ELK ile toplayın. Metrikler için Prometheus, dashboard için Grafana kurun. Uygulama düzeyinde OpenTelemetry ile dağıtık izlemeyi etkinleştirerek istek gecikmelerini uçtan uca görünür kılın.

Yaygın Hatalar ve İpuçları

- imagePullPolicy yanlış: Geliştirme dışında IfNotPresent genelde yeterlidir; prod’da immutable tag kullanın (örn. SHA digest).
- resource tanımsız: Limit/Request yoksa scheduler tutarsız davranır; önceliklendirme zorlaşır.
- probe endpoint’leri: Uygulama hazır olmadan trafiğe açmayın; readiness’i gerçek bağımlılıklar sağlandığında başarılı olacak şekilde ayarlayın.
- config değişikliği rollout: ConfigMap değişikliğini pod’lara yansıtmak için anotasyon checksum tekniğini kullanın.

Sonuç

Helm ile Kubernetes’e geçiş, yalnızca bir orkestrasyon değişimi değil; aynı zamanda daha iyi sürümleme, güvenlik, otomasyon ve gözlemlenebilirlik kültürüne geçiştir. Compose dünyasındaki sadeliği, şablonlanabilir manifestler, values tabanlı yapılandırma ve GitOps süreçleriyle kaybetmeden; aksine kurumsal ölçekte yönetilebilirlik kazanırsınız. Küçük başlayın, her sürümde bir iyileştirme ekleyin ve dağıtımlarınızı otomatikleştirerek güvenle ölçekleyin.

OpenTelemetry ile Node.js Uygulamalarında Dağıtık İzleme: Jaeger ile 15 Dakikada Kurulum

OpenTelemetry nedir ve neden şimdi?

Modern uygulamalar mikroservisler, HTTP çağrıları, mesaj kuyrukları ve veritabanı etkileşimleriyle dolu. Bir isteğin nerede yavaşladığını veya neden hata verdiğini anlamak için klasik loglar tek başına yetmiyor. OpenTelemetry (OTel), dil bağımsız bir standart ve SDK seti olarak uygulama içinde otomatik enstrümantasyon sağlar; iz (trace), span, metrik ve log verilerini toplayıp OTLP gibi açık protokollerle istediğiniz araca yollar. Bu rehberde, Node.js bir servise OTel entegre ederek izleri Jaeger üzerinden görselleştireceğiz.

Hedef

Amaç: Node.js uygulamanızdaki HTTP isteklerinin uçtan uca izlenmesini 15 dakikada etkinleştirmek. İzleri toplamak için OpenTelemetry Node SDK’sını kullanacağız, çıktıyı OTLP üzerinden gönderecek ve Jaeger All-in-One ile arayüzde görüntüleyeceğiz.

Önkoşullar

- Node.js 16+ ve npm yüklü olmalı. - Docker çalışıyor olmalı. - Uygulama Express, Fastify veya yerleşik HTTP modülü kullanıyor olabilir; OTel, otomatik enstrümantasyonla bu kütüphaneleri tanır.

Adım 1: Paketleri yükleyin

Projeye OpenTelemetry bağımlılıklarını ekleyin: npm i @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/exporter-trace-otlp-http

Bu paketler; API yüzeyi, Node SDK, otomatik enstrümantasyon, kaynak (resource) nitelikleri ve OTLP HTTP trace exporter içerir. İhtiyaca göre gRPC tabanlı exporter da tercih edebilirsiniz fakat yerelde HTTP pratik ve hızlıdır.

Adım 2: Tracing başlatıcısını oluşturun

Proje köküne tracing.js isminde bir dosya ekleyin ve SDK’yı minimum ayarlarla başlatın. Ana fikir: servis adını tanımlayın, OTLP exporter’ı 4318 portuna yönlendirin ve otomatik enstrümantasyon modüllerini etkinleştirin.

Örnek yapılandırma (özet): const { NodeSDK } = require('@opentelemetry/sdk-node'); const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node'); const { Resource } = require('@opentelemetry/resources'); const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions'); const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http'); const sdk = new NodeSDK({ resource: new Resource({ [SemanticResourceAttributes.SERVICE_NAME]: 'orders-api', [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0' }), traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }), instrumentations: [getNodeAutoInstrumentations()] }); sdk.start(); process.on('SIGTERM', () => sdk.shutdown());

Burada service.name gelecekteki sorgular için kritik; Jaeger’de projeyi bu ad üzerinden bulacaksınız. Versiyon alanı, sürüm bazlı karşılaştırmalar için faydalıdır.

Adım 3: Uygulamayı OTel ile çalıştırın

Node sürecini tracing başlatıcısı ile preload ederek başlatın: node -r ./tracing.js app.js

Eğer bir test isteği göndermek isterseniz, uygulama ayağa kalktıktan sonra örneğin curl http://localhost:3000/health gibi basit bir çağrı yapın. OTel, HTTP istemci ve sunucu katmanlarını, Express route’larını ve veritabanı sürücülerini otomatik olarak span’lere dönüştürür.

Adım 4: Jaeger All-in-One’ı başlatın

Jaeger’i tek komutla çalıştırabilirsiniz. Bu imaj, OTLP HTTP alıcısı ve web arayüzünü içerir: docker run -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:1.56

- 16686: Jaeger UI portu. - 4318: OTLP HTTP endpoint’i. Uygulamanızdaki exporter URL’si ile eşleşir. Arayüze tarayıcıdan erişip (localhost:16686) “services” alanında orders-api servisini seçerek izleri görüntüleyebilirsiniz.

Adım 5: Manuel span eklemek (opsiyonel)

Otomatik enstrümantasyon çoğu senaryo için yeterli olsa da domain mantığınızı daha iyi anlamak için manuel span eklemek değerlidir. Örneğin kritik bir iş kuralını ölçmek için: const { context, trace } = require('@opentelemetry/api'); const tracer = trace.getTracer('orders-business'); await tracer.startActiveSpan('price-calculation', span => { // iş mantığı ... span.setAttribute('discount.applied', true); span.end(); });

Bu şekilde, Jaeger’de sadece altyapı çağrılarını değil, iş süreçlerinizi de okunaklı şekilde takip edebilirsiniz.

Üretim için en iyi uygulamalar

- Örnekleme (sampling): Trafiğiniz yüksekse, varsayılan oranı düşürün. Çevresel değişkenle kontrol etmek pratik: OTEL_TRACES_SAMPLER=traceidratio ve OTEL_TRACES_SAMPLER_ARG=0.1 (yüzde 10). - Kaynak nitelikleri: Ortam bilgilerini ekleyin: deployment.environment=prod, cloud.region=eu-central-1. - Veri güvenliği: Hassas verileri span attribute veya event’lerde taşımayın. Maskleme/sansürleme katmanı ekleyin. - Bağımlılık izleme: HTTP client timeouts, retry politikaları ve hataları span event’lerinde açıkça belirtin. - Başlatma düzeni: Tracing dosyanızı uygulama kodundan önce yüklediğinizden emin olun; aksi halde ilk istekler enstrümanlanmayabilir.

Sorun giderme

- İzler gelmiyor: Exporter URL’sini ve portu doğrulayın (http://localhost:4318/v1/traces). - CORS/agent hatası: Sunucu tarafında çalıştığınızdan emin olun; tarayıcı için farklı SDK gerekir. - Servis görünmüyor: service.name niteliği boşsa Jaeger listede göstermeyebilir. - Ağ çakışmaları: 4318 portu başka bir süreç tarafından kullanılıyorsa, Jaeger’i farklı portla çalıştırın ve exporter URL’sini eşitleyin.

Sonuç

OpenTelemetry ile Node.js uygulamanıza dakikalar içinde dağıtık izleme ekleyebilir, Jaeger üzerinden gecikmeleri, hata oranlarını ve bağımlılık zincirlerini şeffaf biçimde görebilirsiniz. Daha ileri kullanımda OpenTelemetry Collector ekleyip verileri birden fazla hedefe (ör. Tempo, Zipkin) yönlendirebilir; metrik ve log’ları aynı bağlamda zenginleştirerek tam kapsamlı gözlemlenebilirlik elde edebilirsiniz. Başlangıç için bu kurulum, üretimde dahi temel ihtiyaçları karşılayacak kadar hafif ve esnektir.

GitHub Actions ile Monorepo’da Çoklu Platform Docker İmajı, Önbellekli Build ve SBOM/İmza (Buildx Rehberi)

Giriş

Monorepo yapısında birden fazla servis için Docker imajı üretmek, özellikle hem amd64 hem de arm64 mimarilerini hedeflemek istediğinizde çabucak karmaşıklaşır. GitHub Actions ve Docker Buildx, doğru yapılandırıldığında bu süreci hem hızlı hem de güvenli hale getiriyor. Bu yazıda, çoklu platform (multi-arch) imaj oluşturma, build önbelleği (cache) kullanma, SBOM üretme ve imaj imzalama adımlarını pratik bir akış üzerinden anlatacağım. Amacım, “tek seferde kurulup unutulan” bir CI/CD hattı kurmanıza yardımcı olmak.

Neden Çoklu Platform İmaj?

Apple Silicon (arm64) yaygınlaştıkça geliştiriciler ve üretim ortamları farklı mimarilerde çalışabiliyor. İmajlarınızı linux/amd64 ve linux/arm64 için aynı anda yayınlamak, hem geliştirici deneyimini iyileştirir hem de edge/IoT gibi arm tabanlı cihazlarda dağıtımı kolaylaştırır. Buildx, bu geçişi QEMU emülasyonu ile otomatikleştirebilir, böylece tek bir komutla iki mimariyi de üretebilirsiniz.

Gereksinimler ve Gizli Anahtarlar

Başlamadan önce bir container registry belirleyin (Docker Hub veya GHCR). GitHub deposunda Secrets bölümüne aşağıdaki bilgileri ekleyin: REGISTRY_USERNAME, REGISTRY_TOKEN (veya GHCR için GHCR_PAT). Eğer imaj imzalayacaksanız, Cosign anahtar çiftinizi ya da keyless (OIDC) yöntemi kullanacaksanız ilgili izinleri de ayarlayın. Monorepo kullanıyorsanız her servis için bir context yolu tanımlayın (ör. services/api, services/web).

Workflow’un İskele Yapısı

Tipik bir akışta, tetikleyiciler push (özellikle tag ile sürümleme), pull_request ve isteğe bağlı olarak workflow_dispatch olur. Adımlar sırasıyla şöyle ilerler: kodun çekilmesi (actions/checkout), QEMU kurulumu (çoklu platform için), Buildx kurulumu, registry’e giriş, build ve push. Performans için BuildKit önbelleğini GitHub Actions içi önbellek (type=gha) ile kullanmanızı öneririm. Bu sayede aynı katmanları tekrar tekrar derlemek zorunda kalmazsınız.

Örnek akış mantığı şu sırayı izler: “Checkout → QEMU kur → Buildx kur → Registry login → Çoklu platform build + push → SBOM üret → İmza → Artefact yükleme”. YAML dosyasında docker/build-push-action için platforms: linux/amd64,linux/arm64, cache-from: type=gha, cache-to: type=gha,mode=max gibi ayarları etkinleştirin. Etiketlemede semantik sürüm (örn. v1.4.2) ile latest tag’ini birlikte yayınlayın; branch tabanlı tag’ler (örn. edge) test ortamlarına akış sağlar.

SBOM ve Tedarik Zinciri Güvenliği

Güncel güvenlik süreçlerinde SBOM (Software Bill of Materials) zorunluluğa yakın bir standart haline geldi. Buildx/BuildKit ile attest=type=sbom kullanarak imajın içine SBOM gömebilir veya Syft gibi bir araçla ayrı bir dosya olarak üretip CI artefact’ı olarak saklayabilirsiniz. Ben genellikle her ikisini de yapıyorum: imaj attestation, dışa aktarılan bir SBOM ve basit bir HTML rapor; böylece hem makine hem de insan odaklı kontroller kapsanmış oluyor.

İmza tarafında, Cosign ile imajınızı imzalamak, üretim registry’nizde kimlik doğrulanmış ve değişmez bir iz bırakır. Keyless imza (OIDC) kullanıyorsanız GitHub Actions koşusunda sağlanan kimlik belirteçleriyle etkileşimsiz imza atabilirsiniz. Üretim tarafında ise; admission controller’lar veya politika motorları (örn. Kyverno, Connaisseur) ile “sadece imzalı imajlar” kuralını uygulamak, supply chain risklerini ciddi oranda azaltır.

Monorepo ve Build Matrisi

Monorepo’da birden çok dizini tek akışta derlemek için matris kullanın. Her matris girdisi bir servis yolunu ve hedef imaj adını taşısın. Değişiklik bazlı build için paths-filter ile dosya/dizin değişikliklerini algılayan bir ön adım ekleyip sadece etkilenen servisleri derlemek, gereksiz build’lerin önüne geçer. Bu, özellikle cache etkinleştirilmiş Buildx ile birleştiğinde, PR başına dakikalarca zaman tasarrufu sağlar.

Önbellek (Cache) İncelikleri

Build performansı, doğru katmanlaşmış bir Dockerfile ve doğru cache stratejisi ile dramatik biçimde iyileşir. Bağımlılık kurulumunu (örn. npm ci, pip install, go mod download) kaynak kodundan önceki katmanlarda tutun ve sadece lock dosyası değiştiğinde invalid olsun. GitHub Actions içinde type=gha cache’i kullanırken mode=max seçimi daha agresif bir yeniden kullanım sağlar. Pull request build’lerinde push: false ile imajı registry’ye itmeden cache’i yine de güncelleyebilirsiniz.

Sürümleme ve Etiket Stratejisi

Üretim tutarlılığı için semantik sürümleme öneririm. Tag’lerinizden dinamik olarak şu etiketleri çıkarın: vX.Y.Z, vX.Y, vX ve latest. Ana branş için edge veya canary etiketi de ekleyebilirsiniz. Bu yaklaşım tüketen taraflara esnek güncelleme kanalları sunar ve geri dönüş (rollback) senaryolarını netleştirir.

Sık Karşılaşılan Sorunlar

QEMU tabanlı derlemelerde nadiren de olsa bellek/süre limitine takılabilirsiniz; çözüm olarak job’a daha yüksek zaman limiti tanımlayın veya daha küçük base image’lar kullanın. “manifest list” hataları genellikle eksik push veya yanlış tag kombinasyonundan kaynaklanır; multi-arch push’un tek adımda yapılmasına dikkat edin. SBOM/attestation çıktılarının registry tarafından desteklenip desteklenmediğini kontrol edin; bazı özel registry’ler attestation’ı farklı isimlendirme ile saklayabiliyor.

Sonuç

GitHub Actions + Docker Buildx ikilisiyle monorepo’nuzda çoklu platform imaj üretmek, cache ile hızlandırmak, SBOM ve imza ile güvence altına almak zor değil; ancak birkaç temel ayrıntıyı doğru ayarlamak şart. Yukarıdaki iskelet yaklaşımı kendi proje yapınıza uyguladığınızda, hem geliştirici geri bildirim döngünüz hızlanacak hem de tedarik zinciri güvenliği gereksinimlerini karşıladığınızı bilerek daha rahat uyuyacaksınız. İleride bu akışı, imaj tarama, imza doğrulama ve politika kontrolü adımlarıyla genişleterek uçtan uca güvenli bir dağıtım hattına dönüştürmeniz mümkün.

Passkeys ile Şifresiz Giriş: WebAuthn + FIDO2 ile Adım Adım Uygulama Rehberi

Passkey nedir ve neden şimdi?

Parola sızıntıları, oltalama (phishing) ve zayıf parola alışkanlıkları yıllardır güvenlik ekosisteminin en zayıf halkası. Passkey, FIDO2 standartları ve WebAuthn API’si üzerine inşa edilen, kullanıcıların yalnızca cihazlarındaki biyometrik doğrulama (parmak izi, Face ID, Windows Hello) veya PIN ile oturum açmasını sağlayan şifresiz bir yöntemdir. Parolalar yok, tek kullanımlık SMS kodları yok; kriptografik anahtar çifti ve tarayıcı desteği var. Apple, Google ve Microsoft’un ekosistemlerinde senkronize edilebilen passkey’ler hem güvenliği hem de dönüşüm oranlarını artırır.

Bu rehberde, modern bir web uygulamasına passkey tabanlı kayıt ve giriş akışını nasıl ekleyeceğinizi, hangi teknik ayrıntılara dikkat etmeniz gerektiğini ve yaygın hataları nasıl önleyeceğinizi anlatıyorum. Anlatım sade, adımlar somut; odak noktamız uygulanabilirlik.

Mimariye hızlı bakış

WebAuthn, üç aktörle çalışır: Relying Party (siteniz), istemci (tarayıcı) ve authenticator (platform veya harici anahtar). Kayıt sırasında site, tarayıcıya bir challenge ve ayarlar gönderir; cihazda bir anahtar çifti oluşturulur, siteniz genel anahtarı güvenli şekilde kaydeder. Girişte, site bir challenge ile imza ister; cihaz, kullanıcı doğrulaması sonrası imzayı üretir ve siteniz bunu doğrular. Parola asla yok; kimlik doğrulama domain’e (rpId) bağlı olduğu için oltalama büyük ölçüde engellenir.

Önkoşullar ve kurulum gereksinimleri

- HTTPS zorunlu: WebAuthn yalnızca güvenli origin’lerde çalışır. Geliştirme için localhost istisnadır.

- rpId ve origin: rpId genellikle alan adınızdır (ör. example.com). Alt alanlardan çağırıyorsanız bunu planlayın.

- Session ve CSRF: Challenge değerlerini oturumda tutun; her istek için taze ve tekil challenge üretin. SameSite=Lax/Strict çerezleri tercih edin.

- Tarayıcı desteği: Chrome, Edge, Safari ve Firefox güncel sürümlerde passkey destekliyor. iOS 16+, Android 9+ geniş kapsama sahip.

Kayıt akışı: Sunucu tarafı

1) Kullanıcı kayıt butonuna bastığında sunucu benzersiz bir challenge üretir ve oturumda saklar. Ardından istemciye PublicKeyCredentialCreationOptions döndürür: { rp: { name, id }, user: { id, name, displayName }, challenge, pubKeyCredParams, authenticatorSelection, attestation }.

2) user.id değeri kararlı ve benzersiz olmalı (ör. 16-32 baytlık bir UUID veya key). Kullanıcı adını değiştirse bile user.id sabit kalmalıdır.

3) Attestation’ı çoğu senaryoda "none" olarak ayarlayın; gizlilik ve uyumluluk açısından yeterlidir.

4) İstemciden dönen attestationObject ve clientDataJSON alanlarını doğrulayın: challenge eşleşmesi, origin kontrolü ve attestation formatı. Başarılıysa credentialId, publicKey ve signCount’ı veritabanında kullanıcıyla eşleştirerek saklayın.

Giriş akışı: Sunucu ve istemci

1) Sunucu, giriş başlatıldığında yine tekil bir challenge üretir ve PublicKeyCredentialRequestOptions döndürür: { challenge, rpId, allowCredentials?, userVerification }. Passkey-first deneyimi için discoverable credentials (resident key) kullanımını tercih edebilirsiniz; bu durumda allowCredentials boş bırakılabilir.

2) İstemci tarafında, kayıt için navigator.credentials.create({ publicKey }), giriş için ise navigator.credentials.get({ publicKey }) çağrıları yapılır. Mobilde ve masaüstünde tarayıcı, sistem düzeyi biyometri istemini kendisi yönetir.

3) Dönen authenticatorData, clientDataJSON ve signature sunucuya gönderilir. Sunucu, ilgili publicKey ile imzayı doğrular, signCount artışını kontrol eder ve oturumu başlatır.

Conditional UI ve kullanıcı adı olmadan giriş

Chrome ve Android’de Conditional UI ile otomatik doldurma benzeri bir passkey deneyimi sunabilirsiniz. navigator.credentials.get({ publicKey, mediation: "conditional" }) şeklinde çağrıldığında kullanıcı adı alanına odaklanıldığında tarayıcı passkey önerir. Bu, “username-less” akışlarla birleştiğinde form sürtünmesini ciddi şekilde azaltır.

En iyi uygulamalar

- Resident key desteğini açın: authenticatorSelection: { residentKey: "preferred", userVerification: "required" }. Böylece kullanıcı adı olmadan giriş mümkün olur.

- Base64url dönüşümlerine dikkat: Tarayıcı ArrayBuffer döndürür; sunucuya gönderirken ve doğrularken URL-safe kodlama kullanın.

- Çoklu cihaz stratejisi: Passkey’ler iCloud Anahtar Zinciri ve Google Password Manager ile eşzamanlanabilir. Kullanıcıların ikinci cihaz eklemesini ve donanımsal anahtarları (YubiKey) desteklemeyi düşünün.

- Geri kazanım planı: Cihaz kaybında kilitlenme yaşanmaması için e-posta bağlantısı veya destek kanıtı gibi güvenli kurtarma akışları tasarlayın. Parolaya dönmek yerine sınırlı ayrıcalıklı, denetimli akışlar tercih edin.

Test ve hata ayıklama

- Chrome DevTools’ta Virtual Authenticator ile farklı authenticator türlerini ve UV/UP kombinasyonlarını simüle edin. chrome://webauthn üzerinden test kolaydır.

- Origin ve rpId uyuşmazlıkları en yaygın sorundur. Üretimde www ve kök alan adı tutarsızlıklarını önleyin.

- Sunucu saat senkronizasyonu, proxy ve CDN başlıkları (X-Forwarded-Proto) için yapılandırmalarınızı kontrol edin; HTTPS algısı bozulursa WebAuthn başarısız olabilir.

Güvenlik ve uyumluluk notları

Passkey’ler kimlik bilgilerinin etki alanına bağlanması sayesinde oltalamaya dirençlidir. Ortadaki adam saldırıları, parolalara göre anlamlı ölçüde zorlaşır. Kurumsal ortamlarda cihaz yönetimi, anahtar yedekleme politikaları ve regülasyon (KVKK/GDPR) gerekliliklerini değerlendirin. Attestation’a yalnızca gerçekten cihaz tedarik zinciri doğrulaması gerekiyorsa başvurun; aksi halde gizlilik dostu none yeterlidir.

Sonuç: Şifresiz geleceğe bugünden geçin

Passkey, kullanıcılar için sürtünmeyi azaltırken güvenliği yükselten nadir teknoloji kırılımlarından biri. Kayıt ve giriş akışlarında WebAuthn’u doğru kurguladığınızda, dönüşüm oranlarınız artar ve destek yükünüz azalır. Adımları küçükten büyüğe taşıyın: önce HTTPS ve rpId düzeni, sonra resident key ve conditional UI, en sonunda çoklu cihaz ve kurtarma planları. Bir kez doğru kurguladığınızda, şifresiz girişin kullanıcı memnuniyetine ve güvenliğe etkisini doğrudan göreceksiniz.

Passkey (FIDO2/WebAuthn) ile Parolasız Giriş: Modern Web Uygulamalarına Adım Adım Entegrasyon

Passkey ve WebAuthn Nedir, Neden Önemli?

Parolasız kimlik doğrulama, güvenlik ve kullanıcı deneyimi açısından modern webin en kritik dönüşümlerinden biri. Passkey teknolojisi, FIDO2 ve WebAuthn standartlarına dayanarak şifreleri tamamen ortadan kaldırır ve herkese açık anahtar kriptografisiyle phishing saldırılarını kökten azaltır. Kullanıcılar, platformlarının (iOS, Android, Windows, macOS) yerleşik güvenlik donanımını veya güvenlik anahtarlarını (YubiKey gibi) kullanarak tek dokunuşla giriş yapar. Bu makalede, bir web uygulamasına passkey (WebAuthn) entegrasyonunu adım adım, pratik ipuçlarıyla anlatıyorum.

WebAuthn Nasıl Çalışır? (Kısa Teknik Özet)

WebAuthn, tarayıcı üzerinden navigator.credentials API’si ile çalışır. Kayıt (registration) aşamasında sunucu bir challenge üretir ve tarayıcıya gönderir. Kullanıcının cihazı benzersiz bir anahtar çifti (özel/public) oluşturur; public key sunucuya kaydedilir. Giriş (authentication) aşamasında sunucu yine bir challenge yollar; cihaz, özel anahtarla bu challenge’ı imzalar ve tarayıcı imzayı sunucuya iletir. Sunucu public key ile imzayı doğruladığında kullanıcı giriş yapar. Şifre yoktur; dolayısıyla credential stuffing ve klasik phishing riskleri dramatik biçimde azalır.

Ön Koşullar ve Mimarinin Temelleri

Entegrasyon için HTTPS zorunludur; rpId (Relying Party ID) genellikle alan adınızın eTLD+1 biçimidir (örneğin example.com). Backend tarafında kayıt ve giriş için iki uç nokta gerekir: /webauthn/register ve /webauthn/login (veya benzer adlar). Bu uç noktalar challenge üretir, tarayıcıdan dönen yanıtları doğrular ve kimlik bilgilerini (credentialId, publicKey, aaguid vb.) saklar. Sunucu tarafında dilinize göre bir WebAuthn/FIDO2 kütüphanesi kullanmanız önerilir; örneğin Node.js için SimpleWebAuthn, .NET için Fido2NetLib, Go için popüler WebAuthn paketleri mevcuttur.

Adım 1: Kayıt (Registration) Akışı

1) Sunucu, kullanıcı hesabı oluşturulurken bir kayıt challenge’ı üretir ve tarayıcıya dönüş yapar. Dönen JSON içinde publicKey alanı olmalıdır (rp, user, challenge, pubKeyCredParams gibi).

2) Tarayıcı tarafında kayıt isteği şu şekilde tetiklenir: const cred = await navigator.credentials.create({ publicKey: options });. Buradaki options, sunucunun verdiği PublicKeyCredentialCreationOptions içeriğidir.

3) Dönen credential, id, rawId, response.attestationObject ve response.clientDataJSON içerir. Bu verileri JSON’a uygun biçimde base64url kodlayıp sunucuya gönderin: POST /webauthn/register/verify.

4) Sunucu, attestation politikasına (genellikle attestation: "none") göre doğrulama yapar, public key ve credentialId’yi kullanıcıyla eşleştirip veritabanına kaydeder. COSE algoritması olarak ES256 varsayılan ve yaygın bir tercihtir.

Adım 2: Giriş (Authentication) ve Passkey Deneyimi

1) Giriş aşamasında sunucu bir doğrulama challenge’ı üretir ve tarayıcıya yollar. Eğer discoverable credentials (kullanıcı adı girmeden hesap seçimi yapılabilen passkey’ler) destekliyorsanız, allowCredentials alanını boş bırakabilirsiniz.

2) Tarayıcı, aşağıdaki çağrıyla kullanıcıdan biyometrik/doğrulama isteği alır: const assertion = await navigator.credentials.get({ publicKey: requestOptions });. Modern tarayıcı ve platformlarda, mediation: "conditional" ile otomatik doldurma benzeri akış sağlayabilirsiniz: navigator.credentials.get({ publicKey: requestOptions, mediation: "conditional" }).

3) Dönen yanıtta response.authenticatorData, response.clientDataJSON ve response.signature bulunur. Bu verileri sunucuya gönderin: POST /webauthn/login/verify. Sunucu, ilgili public key ile imzayı doğrular, signCount değerini günceller ve oturumu başlatır.

En İyi Uygulamalar ve UX İpuçları

Passkey deneyimi, kullanıcı adı ve şifre kutularını tamamen devre dışı bırakabilir. Özellikle Conditional UI desteği ile (Chrome, Android, iOS ve Safari’nin güncel sürümleri) sayfa yüklenir yüklenmez platform, uygun passkey’leri önerir. Kullanıcı tek dokunuşla giriş yapar. Formlarınızda “Passkey ile giriş yap” butonunu net biçimde gösterin; ilk kurulumda parolayı da kabul edip passkey oluşturma adımını teşvik ederek geçişi yumuşatın.

Hesap kurtarma için e-posta doğrulama, yedek güvenlik anahtarları veya müşteri destek süreçleri tasarlayın. Passkey’ler iCloud veya Google hesabı üzerinden cihazlar arasında senkronize olabilir; bu özellik, kullanıcı değişen cihazlarda bile sorunsuz giriş deneyimi sağlar.

Güvenlik ve Uyum Detayları

- HTTPS zorunludur; localhost geliştirme ortamında tarayıcılar özel izinler sunar. Üretimde mutlaka geçerli bir TLS sertifikası kullanın ve TLS 1.2+ desteğini aktif tutun.

- rpId, cookie SameSite ve Secure bayrakları, Origin eşleşmeleri gibi detaylar önemlidir. Ters proxy (Nginx/Caddy/Cloudflare) arkasında header’ların doğru yönlendirildiğinden emin olun.

- Attestation politikanızı iş gereksinimlerine göre belirleyin. Çoğu SaaS için none yeterlidir; regülasyonlu sektörlerde direct veya enterprise gerekebilir.

- Zaman senkronizasyonu (NTP) ve sunucu saat farkı doğrulamada rol oynar; bu nedenle saat kaymasını minimal tutun.

Test, Hata Ayıklama ve Yayına Alma

Geliştirme sırasında tarayıcı konsolunda Security ve Network sekmelerini izleyin; WebAuthn hataları genellikle açıklayıcıdır. localhost üzerinde test ederken rpId olarak “localhost” kullanın. İlk yayında, kademeli açılış (feature flag) ile kullanıcıların küçük bir yüzdesine passkey’i sunup metrikleri takip etmek iyi bir stratejidir: başarı oranı, iptal oranı, geri dönüşler ve destek talepleri ölçülmelidir.

Sonuç: Parolasız Geleceğe Bugünden Geçin

Passkey (FIDO2/WebAuthn) entegrasyonu; daha güvenli, daha hızlı ve daha kullanıcı dostu bir oturum açma deneyimi sağlar. Şifre sıfırlama maliyetlerini düşürür, hesap ele geçirme vakalarını azaltır ve mobil cihazlarda tek dokunuşla giriş imkânı sunar. Bu rehberdeki adımları izleyerek, önce hibrit (parola + passkey) modeliyle başlayabilir, ardından kullanıcılarınız hazır olduğunda tamamen parolasız bir geleceğe geçebilirsiniz.