Kubernetes Ortamında S3 Yükleme Hatalarının Giderilmesi

Yayımlama Tarihi 20 Eki 2025
Son Güncellenme 04 May 2026
Okuma Süresi 10 dakika
Yazar Can Şentay

Dijital Bülten

Bulut dünyasındaki yeniliklerden haberdar olmak için bültenimize abone olun.

Kubernetes Ortamında S3 Yükleme Hatalarının Giderilmesi

Yönetici Özeti

Bu belge, Kubernetes ortamından kaynaklanan Amazon S3 (S3 uyumlu) nesne depolama yüklemelerinde karşılaşılan kritik bir sorunu detaylandırmaktadır. Kullanıcılar, UploadPart işlemi sırasında aralıklı olarak ValidationError ve NotFound hataları almaktaydı. Bu hatalar, özellikle yol tabanlı (path-style) erişim ve daha küçük dosya parçacıklarının yüklenmesi sırasında daha sık görülüyordu, ancak aynı bucket'lardan dosya indirme işlemleri başarılı oluyordu.

Detaylı incelemeler sonucunda, sorunun temel nedeninin S3 uyumlu servisin, Content-Length başlığının açıkça tanımlanmadığı durumlarda parçalı yüklemeleri (chunked uploads) işleme biçimindeki uyumsuzluk olduğu tespit edilmiştir. Bu davranış, standart S3 protokollerinden sapma göstermekte ve gözlemlenen yükleme hatalarına yol açmaktaydı.

Çözüm, yükleme istekleri için doğru sağlama toplamı (checksum) hesaplamasının yapılmasını sağlayacak bir yapılandırma değişikliği uygulamayı içermektedir. Bu, boto3 istemcisinde botocore.config.Config kullanılarak programatik olarak veya ortam değişkenleri ( AWS_REQUEST_CHECKSUM_CALCULATION , AWS_RESPONSE_CHECKSUM_VALIDATION ) veya AWS CLI yapılandırma dosyası aracılığıyla küresel olarak gerçekleştirilebilir. request_checksum_calculation parametresini WHEN_REQUIRED olarak ayarlayarak, gerekli sağlama toplamlarının hesaplanıp iletilmesini sağlıyoruz, bu da S3 uyumlu servisin gereksinimleriyle uyumludur. Bu çözüm, Kubernetes'ten S3 yüklemelerinin güvenilirliğini önemli ölçüde artırarak veri bütünlüğünü ve operasyonel istikrarı sağlamaktadır.

Sorun Tanımı

Kubernetes'ten S3 uyumlu bir servise dosya yükleme işlemleri sırasında kullanıcılar sürekli hatalarla karşılaşmaktaydı. Bu hatalar, UploadPart işlemi sırasında ValidationError ve konteynerle ilgili NotFound hataları olarak kendini göstermekteydi. Bu sorun, S3 uç noktası için yol tabanlı (path-style) erişim kullanıldığında ve daha küçük dosya parçacıklarıyla uğraşırken özellikle gözlemlenmişti.

İlginç bir şekilde, aynı S3 uyumlu servis ve bucket'tan indirme işlemleri tutarlı bir şekilde başarılı oluyordu. Bu farklılık, sorunun genel bir bağlantı sorunu olmadığını, daha çok yükleme işlemine özgü olduğunu düşündürmekteydi. VZ ekibi tarafından da doğrulanan ilgili S3 uyumlu servis, içerik uzunluğunun açıkça tanımlanmadığı parçalı yüklemeleri desteklememektedir. Müşteri, varsayılan yapılandırmalara güvenerek ve genellikle bu tür yapılandırmaları yönetecek ExtraArgs , Callback veya Config gibi açık argümanlar geçirmeyerek Python ve boto3 kütüphanesini kullandığını doğrulamıştır. Sorun dahili olarak DTCS-3193 olarak takip edilmiştir.
Kök Neden Analizi

S3 yükleme hatalarına ilişkin inceleme, müşterinin yükleme mekanizması ile S3 uyumlu servisin parçalı verileri işleme biçimi arasındaki kritik bir uyumsuzluğu ortaya çıkarmıştır. Spesifik olarak, UploadPart işlemi sırasındaki ValidationError ve NotFound hataları, S3 uyumlu servisin sınırlamasından kaynaklanmaktaydı: içerik uzunluğu tanımlanmadığında parçalı yüklemeleri desteklememektedir.

Bu sınırlama, müşterinin S3 uç noktası için yol tabanlı erişim kullanmasıyla daha da kötüleşmektedir. Sanal ana bilgisayar (virtual-host) stili genellikle çeşitli S3 özellikleriyle uyumluluğu açısından tercih edilse de, yol tabanlı stil bazen altta yatan servis farklılıklarını ortaya çıkarabilir. Müşteri, Python ve boto3 kütüphanesini kullandığını ve varsayılan yapılandırmalara güvendiğini, yani süreci geçersiz kılacak veya yönetecek herhangi bir özel ayar sağlamadığını doğrulamıştır. İçerik uzunluğu tanımlanmamış parçalı yüklemeler için servisin kısıtlamasıyla birleştiğinde bu varsayılan davranış, gözlemlenen ValidationError 'a yol açmıştır. NotFound hataları muhtemelen bir kaskat etkisidir ve servisin önceki doğrulama hatası nedeniyle eksik yüklemeyi doğru bir şekilde bulamadığını veya işleyemediğini göstermektedir.

VZ ekibinden alınan onay, bu bulguyu pekiştirerek, onların servislerinin (VHI) tanımlanmış Content-Length olmadan parçalı yüklemeleri desteklemediğini belirtmiştir. Bu doğrudan, boto3 'nin (varsayılan olarak) çok parçalı yüklemeleri nasıl işlediği, potansiyel olarak toplam boyutu önceden kesin olarak belirtmeden parçalar gönderdiği ve S3 uyumlu servisin bunları reddettiği kök nedene işaret etmektedir.
Çözüm Mimarisi ve Uygulaması

Çözümün özü, S3 uyumlu servisin parçalı yüklemeler ve tanımlanmamış içerik uzunluğu ile ilgili sınırlamasını ele almayı içermektedir. Bu, request_checksum_calculation parametresinin yapılandırılmasıyla elde edilir. Varsayılan olarak, boto3 çok parçalı yüklemenin tüm parçaları için sağlama toplamlarını hesaplamaya çalışabilir, bu da altta yatan servis bu süreci beklendiği gibi işlemediğinde, özellikle içerik uzunluğu her parça için açıkça tanımlanmadığında sorunlara yol açabilir.

request_checksum_calculation parametresi, istekler sırasında sağlama toplamlarının nasıl işlendiğini kontrol eder. Bunu when_required olarak ayarlamak, boto3 'ye yalnızca servis tarafından açıkça ihtiyaç duyulduğunda veya isteğin bütünlük kontrolleri için gerektirdiği durumlarda sağlama toplamı hesaplamaları yapmasını talimatını verir. Bu, tanımlanmamış içerik uzunluklarıyla ilgili sorunlu davranışı atlar.

Bu yapılandırmayı uygulamak için üç ana yöntem vardır:

Yöntem 1: Boto3 Kod Yapılandırması

En doğrudan yaklaşım, Python uygulama kodunda boto3 'yi yapılandırmaktır. Bu, bir botocore.config.Config nesnesi oluşturularak ve istemci başlatılırken geçirilerek yapılır.

import boto3 from botocore.config import Config s3_client = boto3.client( 's3', endpoint_url='YOUR_S3_ENDPOINT', aws_access_key_id='YOUR_ACCESS_KEY', aws_secret_access_key='YOUR_SECRET_KEY', config=Config( s3_use_sigv4=True, # İmza sürüm 4'ün kullanıldığından emin olun s3_verify_ssl=False, # Kendi kendine imzalanan sertifikalar kullanılıyorsa ayarlayın signature_version='s3v4', s3_addressing_style='path', # Gerekirse adresleme stilini açıkça ayarlayın request_checksum_calculation='when_required', response_checksum_validation='when_required' # Yanıtları doğrulamak da iyi bir uygulamadır ) ) # Şimdi yüklemeler için s3_client'ı kullanın # s3_client.upload_file(...)

Bu yöntem, ayrıntılı kontrol sağlar ve ayarın belirli S3 istemci örneğine uygulandığından emin olur.

Yöntem 2: Ortam Değişkeni Yapılandırmas

Alternatif olarak, yapılandırma ortam değişkenleri aracılığıyla yönetilebilir, bu da Kubernetes gibi kapsayıcılaştırılmış ortamlar için özellikle yararlıdır.

export AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED export AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED # Diğer ilgili AWS ortam değişkenleri de burada ayarlanabilir # export AWS_ACCESS_KEY_ID=... # export AWS_SECRET_ACCESS_KEY=... # export AWS_ENDPOINT_URL=...

Bu ortam değişkenleri ayarlandığında, boto3 ve diğer AWS SDK'ları bunları otomatik olarak alacak ve kod değişiklikleri gerektirmeden belirtilen sağlama toplamı davranışını uygulayacaktır. Bu yaklaşım, özellikle birden fazla pod veya hizmet arasında dağıtım ve yönetimi basitleştirir.

Yöntem 3: AWS CLI Yapılandırma Dosyası

AWS Komut Satırı Arayüzü (CLI) aracılığıyla S3 uyumlu hizmetlerle etkileşim kuran kullanıcılar için yapılandırma ~/.aws/config dosyasına ayarlanabilir.

[default] output = json region = us-east-1 # Veya sizin özel bölgeniz [profile my-s3-profile] s3 = endpoint_url = YOUR_S3_ENDPOINT signature_version = s3v4 addressing_style = path request_checksum_calculation = WHEN_REQUIRED response_checksum_validation = WHEN_REQUIRED

Bu profili kullandığınızda (örneğin, aws s3 cp my-file s3://my-bucket/ --profile my-s3-profile ), belirtilen ayarlar uygulanacaktır. Bu, sorun giderme veya AWS CLI'ye dayanan komut dosyaları için uygun bir yöntemdir.

Bu yöntemlerin her biri, içerik uzunlukları her parça için açıkça tanımlanmasa bile parçalı yüklemelerin S3 uyumlu servis tarafından doğru bir şekilde işlenmesini sağlayarak ValidationError 'ı etkili bir şekilde çözer. Servisten alınan verilerin bütünlüğünü sağlamak için response_checksum_validation='when_required' ayarının da ayarlanması önerilir.
Faydalar ve Sonuçlar

Sağlama toplamı yapılandırma çözümünün uygulanması, Kubernetes podlarından kaynaklanan daha önce karşılaşılan S3 yükleme hatalarını doğrudan çözmüştür. Bu, S3 uyumlu hizmetlere veri yüklemeleri için önemli ölçüde daha iyi bir güvenilirlik sağlar. Seçilen yaklaşım, özellikle request_checksum_calculation='when_required' ayarı, S3 uyumlu servis ile yol tabanlı erişim ve daha küçük dosya parçacıkları gibi özel koşullar altında bile etkili bir şekilde doğrulanmış ve çalışmıştır.

Ayrıca, bu çözüm Kubernetes dağıtımlarımızın çeşitli S3 uyumlu depolama çözümleriyle genel uyumluluğunu artırmaktadır. Bu temel yükleme mekanizmasını ele alarak, daha sağlam ve öngörülebilir bir veri aktarım hattı oluşturduk, operasyonel yükü en aza indirdik ve veri bütünlüğünü sağladık. Başarılı uygulama, farklı depolama arka uçlarının özel gereksinimlerini karşılamak için boto3 yapılandırmalarının ince ayarının etkinliğini doğrulamaktadır.