Apinizer Olası Sorunları ve Çözümleri

Coğrafi Bilgi Sistemleri Servislerinde GetCapabilities Routing Sorunu

Problem

Coğrafi Bilgi Sistemleri servislerinde GetCapabilities ile dönmekte olan WSDL içerisindeki adreslerin Apinizer'a taşınması gerekmektedir.

Çözüm

2. bölgeye eklenecek bir Business Rule veya Script poliçesi ile url'de query param olarak 'request' anahtarında 'GetCapabilities' değeri geliyorsa string replace ile buradaki adres Apinizer'da ilgili proxy'e yönlenecek şekilde değiştirilmelidir.

Client IP Adresinin 10.244.x.x Şeklinde Görülmesi

Problem

Client IP adresi Kubernetes ortamında 10.244.x.x şeklinde görülmektedir.

Sebep/Neden

Kubernetes NodePort yapısında eğer client'dan X-Forwarded-For değer gelmiyorsa default olarak arka taraftaki uygulamaya pod'un IP adresini yönlendiriyor. Çözüm olarak externalTrafficPolicy değer Local yaparak çözebiliyoruz ancak bu defa NodePort gelen isteği Cluster'daki diğer sunuculara yönlendirmediğinden erişim sıkıntısı oluşuyor. İlgili Node'u bilip ona gitmek gerekiyor.

Çözüm

bilgi

Apinizer Worker'ları Nginx veya F5 gibi bir yapının arkasına konacağı için, ilgili loadbalancer'ın konfigürasyon dosyasına aşağıdaki gibi header'a xff bilgisinin eklenmesi gerekiyor.

Nginx için bu ayar aşağıdaki gibi yapılabilir:

location /apigateway/ {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://api.inst.com/apigateway/;
} # end location

API Trafik Loglarında Alt Çizgi İçeren Header'ların Görünmemesi

Problem

API Trafik Loglarında alt çizgi içeren Header'ların görünmemesi/aktarılmaması.

Sebep/Neden

uyarı

Bu sorun Apinizer'la alakalı olmamakla birlikte, Apinizer'ın önünde kullanılma ihtimali olan Nginx'in varsayılan ayarları ile ilgilidir.

Nginx, web sunucusu ve ters proxy sunucusu olarak yaygın bir şekilde kullanılmaktadır. Ancak, Nginx'in varsayılan konfigürasyonunda, isimlerinde alt çizgi (_) karakteri bulunan HTTP header'ları işlenmez ve geçirilmez. Bu, alt çizgilerin HTTP RFC'sinde standart olmamasından kaynaklanmaktadır.

Çözüm

Bu sorunu çözmek için Nginx konfigürasyon dosyasında underscores_in_headers direktifini on olarak ayarlamalısınız. Bu, Nginx'in alt çizgi içeren header'ları doğru bir şekilde işlemesini sağlar.

vi /etc/nginx/nginx.conf
http {
    underscores_in_headers on;
}

Ingress Nginx için:

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
  labels:
    app: ingress-nginx
data:
  enable-underscores-in-headers: "true"

Türkçe Karakterler Bozularak İletiliyor

Problem

Türkçe karakterler bozularak iletiliyor.

Sebep/Neden

Client tarafından veri gönderimi sırasında Content-Type header'ına karakter set bilgisi set edilmelidir.

Çözüm

bilgi

Client örnek olarak gönderdiği Content-Type: application/xml ikilisinde value kısmını application/xml; charset=UTF-8 olacak şekilde ayarlayarak göndermelidir.

XML→JSON Dönüşümünde Bilimsel Gösterim (Scientific Notation) Hatası

Problem

REST API Proxy tanımında backend'den XML yanıt dönen servislerde, XML→JSON dönüşümü sırasında hata oluşuyor. Örneğin ProductCode alanındaki 1234E567890 gibi değerler dönüşümü kesintiye uğratıyor.

Sebep/Neden

Jackson tabanlı XML→JSON dönüşümünde harf ve rakam karışımı içeren alanlar (ürün kodu, seri numarası vb.) sayısal ifade olarak yorumlanabilir. E harfi bilimsel gösterim (exponential notation) olarak algılandığında değer BigDecimal'a çevrilmeye çalışılır ve dönüşüm hatası oluşur.

Çözüm

Write Numbers as Strings Seçeneğini Etkinleştirin

API Proxy tanımında Yanıt Seçenekleri (Response Options) bölümünde Jackson Transformation kullanılıyorsa Write Numbers as Strings (Numerik değerleri String olarak yaz) seçeneği işaretlenmelidir.

Örnek Yanıtı Doğrulayın

Show Sample Message (Örnek Mesaj Göster) ile dönüşüm sonucunu kontrol edin.

not

Write Numbers as Strings seçeneği tüm dönüşüm için geçerlidir; yalnızca sorunlu alanı etkilemez. Quantity, Amount gibi gerçek sayısal alanlar da JSON'da string olarak döner. Bu API'yi tüketen client uygulamasının ilgili alanları string olarak okuyup gerekli yerlerde tip dönüşümü yapması gerekir.

PKIX Path Building Failed Hatası

Problem

PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Çözüm

Sertifikayı Apinizer'a Ekle

İlgili adresin public sertifikası Sertifika Yönetimi sayfasından Apinizer'a eklenmelidir.

Sertifikayı İndir (Opsiyonel)

Adrese erişebilen bir tarayıcı yok ise openssl uygulaması yüklü ve adrese erişebilen bir sunucuda aşağıdaki komut ile indirilebilir:

openssl s_client -showcerts -connect server.com:443 </dev/null 2>/dev/null|openssl x509 -outform PEM > serverscertfile.pem

Apinizer 2024.05.4+ Versiyonunda Login Sorunu

Problem

Apinizer'ı 2024.05.4 veya sonrası bir versiyonuna güncelledim ancak arayüze login olamıyorum.

Sebep/Neden

uyarı

2024.05.4 versiyonunda yapılan güvenlik yaması ile Apinizer Yönetim Konsolunda tarayıcılarının bulunduğu istemci IP'lerinin değer kontrolü zorunlu hale getirilmiştir.

Bu sebeple arayüze "Kubernetes Ingress Controller" kullanarak bağlanan kurumların X-Forwarded-For header'ı ile client ip bilgisini gönderecek ayarları yapması gerekmektedir.

Çözüm

ConfigMap Ayarlarını Yapılandır

Config Maps tanımındaki data bölümüne "use-forwarded-headers" anahtarı "true" değeri ile eklenmelidir:

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
data:
  use-forwarded-headers: "true"

Ingress Annotation Ekleyin

Ingress kaynak tanımındaki anotasyon bölümüne "nginx.ingress.kubernetes.io/use-forwarded-headers" anahtarı "true" değeri ile eklenmelidir:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: apinizer-manager-ingress
  namespace: apinizer
  annotations:
    nginx.ingress.kubernetes.io/use-forwarded-headers: "true"

not

Load balancer tarafında aşağıdaki header'lardan birinin mutlaka gelmesi gerekiyor:

• X-Forwarded-For
• Proxy-Client-IP
• WL-Proxy-Client-IP
• HTTP_X_FORWARDED_FOR
• HTTP_X_FORWARDED
• HTTP_X_CLUSTER_CLIENT_IP
• HTTP_CLIENT_IP
• HTTP_FORWARDED_FOR
• HTTP_FORWARDED
• HTTP_VIA
• REMOTE_ADDR

bilgi

Gateway, istemci IP'sini belirlemek için yukarıdaki header'ları sırayla kontrol eder ve ilk geçerli IP'yi kullanır.

:::

Alt Çizgi İçeren Header Key'leri İletilmiyor

Problem

_ (alt çizgi) karakteri içeren header key'leri Apinizer Gateway'e gelirken log'lara ve backend'e iletilmiyor.

Sebep/Neden

Varsayılan olarak Nginx ve Ingress-Nginx Controller, _ (alt çizgi) karakteri bulunan header'ları kabul etmez. Bu nedenle header gateway'e ulaşmadan engellenmektedir.

Çözüm

Ingress Nginx ConfigMap Ayarları

Config Maps tanımındaki data bölümüne "enable-underscores-in-headers" anahtarı "true" değeri ile eklenmelidir:

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
data:
  enable-underscores-in-headers: "true"

Nginx Konfigürasyonu

Nginx'in bu header'ı gönderebilmesi için ise underscores_in_headers on; konfigürasyonu yapılmalıdır:

server {
    ...
    underscores_in_headers on;
    ...
}

SOAP Servislerde WS-S/WS-STS Token Alma Sertifika Sorunu

Problem

SOAP servislerde kullanılan WS-S ya da WS-STS politikaları "PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target" hatası nedeniyle token alamıyor.

Sebep/Neden

SOAP servis çağrımında Apinizer'a yüklenmiş sertifikayı görememesi nedeniyle bu servisin token alımının reverse proxy üzerinden yapılması gerekiyor.

Çözüm

İlgili token alma adresi ile routing yapan bir reverse proxy oluşturulur ve token kullanan servisteki wss/wssts politikasının token alma adresi bu servis olarak verilir. Nadir durumlarda reverse proxy üzerinden script ile xml mesajındaki adresin değiştirilmesi gerekebilir.

LDAP Login Ayarı Sırasında ERR_13611_VALUE_MISSING_ON_RDN Hatası

Problem

LDAP login ayarı sırasında ERR_13611_VALUE_MISSING_ON_RDN hatası.

Sebep/Neden

Bu hata genelde eksik bir değeri ifade eder.

Çözüm

uyarı

Özellikle User Base DN Attribute gereksiz görüldüğü için atlanır, bu değerin girilerek LDAP'ta kişi aramasının kısıtlı seviyede yapılması sorunu çözebilir.

DNS Çözümleme Performans Sorunu

Problem

Yoğun environment kullanımı veya yüksek sayıda rate limit tanımı olan sistemlerde, bazı servis adreslerinin anlık olarak çözülememesi.

Sebep/Neden

Bu durum, DNS çözümleme performansının yetersiz kalmasından kaynaklanmaktadır.

Çözüm

CoreDNS Kaynak Limitlerini Artır

CPU ve RAM kaynakları yükseltilerek daha fazla sorgunun aynı anda işlenebilmesi sağlanmalıdır.

CoreDNS Node'lar Üzerine Dağıt

Her worker node üzerinde bir adet CoreDNS podu olacak şekilde deployment yeniden yapılandırılmalıdır. Bu sayede DNS sorguları merkezi bir noktaya yığılmadan dağıtık şekilde işlenebilmektedir.

MSSQL Bağlantılarında SSL Sertifika Sorunu

Problem

Apinizer'ı 2025.07.4 veya sonrası bir versiyonuna güncelledim ancak Sql Server (MSSQL) bağlantılarımda hata alıyorum: Failed to initialize pool: "encrypt" property is set to "true" and "trustServerCertificate" property is set to "false" but the driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption: Error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.

Sebep/Neden

uyarı

2025.07.4 versiyonunda yapılan güvenlik güncellemesi ile MSSQL jdbc kütüphanesi güncellenmiştir.

Bu kütüphane ile jdbc bağlantılarında tls 1.2 ve üstü zorunlu tutulmaktadır. Encrypt default değeri true'dur ve bu da doğru bir sertifika ile bağlantı ister. Self sign, doğru yapılandırılmamış sertifika kullanan ya da sertifika kullanmayan veritabanlarında bu hata ile karşılaşılmaktadır.

Çözüm

Sertifikayı Yapılandır

Veritabanınıza olan bağlantıda ssl sertifikası doğru şekilde yapılandırılmalıdır. İlgili sertifika Apinizer'da Secret Manager > Certificates altına eklenmelidir.

Not

Not: İç sistemlerinizde ve development ya da test ortamlarınızda, MSSQL tipi veritabanı bağlantılarında (DB2API dahil) bu hata JDBC URL'sine aşağıdaki parametreler eklenerek geçici olarak giderilebilir:

• ;trustServerCertificate=true (önerilen geçici çözüm; dikkatle eklenmeli, güvenlik açısından olası sonuçları göz önünde bulundurulmalıdır)
• Bazı ortamlarda ek olarak ;encrypt=true de gerekebilir
• ;encrypt=false (önerilmez)

Oracle Bağlantılarında Timezone Bölgesi Hatası

Problem

Oracle tipi veritabanı bağlantılarında (DB2API dahil) bağlantı kurulamıyor ve aşağıdaki hata alınıyor:

DB Connection (...) could not be established. ... Failed to initialize pool: ORA-00604: error occurred at recursive SQL level 1 ORA-01882: timezone region not found

Sebep/Neden

Oracle JDBC sürücüsü, connection string'de timezone bölgesi tanımı uygun şekilde sağlanmadığında ORA-01882: timezone region not found hatası verir.

Çözüm

Connection String Parametresini Ekleyin

Oracle veritabanı connection string'ine ?oracle.jdbc.timezoneAsRegion=false parametresini ekleyin. Bağlantı URL'sinde zaten sorgu parametresi varsa &oracle.jdbc.timezoneAsRegion=false kullanın.

Uyarı

Bu parametre, Oracle JDBC sürücüsünün timezone bilgisini bölge adı yerine offset olarak yorumlamasını sağlar. Bağlantı tanımınızı güncelledikten sonra DB2API veya ilgili bağlantıyı yeniden test edin.

100 MB’dan Büyük Dosya Yüklemelerinde Servis Hatası

Problem

Büyük boyutlu dosya yüklemelerinde servis hata veriyor ve istekler başarısız oluyor.

Sebep/Neden

Dosya yükleme ile ilgili parametrelerin varsayılan değerinin 100 MB olması, mevcut büyük dosya yükleme ihtiyaçları için yetersiz kalmaktadır.

Çözüm

Bu limiti artırmak için Kubernetes ortamında worker isimli deployment üzerinde, ilgili parametrelerin byte cinsinden uygun değerlerle güncellenmesi gerekmektedir.
multipartConfigMaxFileSize
multipartConfigMaxRequestSize
multipartConfigFileSizeThreshold

uyarı

max value = "2147483647" yani 2GB - 1byte olabilir.

   - name: multipartConfigMaxFileSize
     value: "2147483647"        
   - name: multipartConfigMaxRequestSize
     value: "2147483647"        
   - name: multipartConfigFileSizeThreshold
     value: "2147483647"      

bilgi

Değerler byte cinsinden tanımlanmalı ve worker deployment’ının spec -> containers -> env alanı altında aşağıdaki resimdeki gibi eklenmelidir.

Apinizer Güncellemesinde Cache Pod'unun Hata Döngüsüne Girmesi

Problem

Apinizer güncellemesinde cache deployment'ları güncellenirken aşağıdaki hata ile karşılaşılırsa Cache pod'u hata döngüsüne girer:

Joining node's version 4.2.8 is not compatible with cluster version 4.1
(Rolling Member Upgrades are only supported in Hazelcast Enterprise)

Çözüm

Bu durumu çözmek için aşağıdaki yöntemlerden birini kullanabilirsiniz:

1. Cache Replicasını 0'a Ayarlayıp Tekrar Yükseltme

Cache deployment'ının replicasını 0 yaparak tüm pod'ları durdurun:

kubectl scale deployment cache --replicas=0 -n apinizer

Pod'ların tamamen kapanmasını bekleyin. Ardından replicasını tekrar orijinal değerine ayarlayarak pod'ları yeniden başlatın:

kubectl scale deployment cache --replicas=1 -n apinizer

Yeni pod'lar güncellenmiş sürümle başlayacaktır.

---

2. Eski ReplicaSet Tanımını Silme

Eski replicaset tanımlarını silerek temiz bir başlangıç yapabilirsiniz.

Bu işlem eski pod'ları silebileceğinden dikkatle yapılmalıdır. Deployment otomatik olarak yeni pod'lar oluşturacaktır.

---

3. DeploymentStrategy'i Recreate'e Çevirme

Deployment YAML dosyasını düzenleyerek deploymentStrategy'i RollingUpdate yerine Recreate olarak ayarlayın:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cache
spec:
  strategy:
    type: Recreate
  replicas: 1
  # ... diğer ayarlar

Bu yöntem pod'ları yeniler pod'lar sırayla değil tamamı birden kapatılır ve yeniden oluşturulur.

---

Bu yöntemlerden birini uygulamak hatayı çözer.