Ana içeriğe geç

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​

  1. 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.

worker deployment yaml. dosyası

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:

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.

Eski ReplicaSet Tanımını Silme

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

Uyarı

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

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.

Application Logs Aşırı Üretimi ve Eşik Bildirimleri​

Problem​

Application Logs kayıtları beklenenin üzerinde artmakta ve aşağıdaki bildirim alınmaktadır:

This notification was created because threshold value was exceeded for Apinizer Gateway - Application Logs Monitor! Please control your log levels or clear old logs.

Sebep/Neden​

Bu durum birden fazla nedenden kaynaklanabilir.

Debug ihtiyacı için API Proxy'nin Log Level'ının değiştirilmesi​

Application Logs sekmesinde debug seviyesi açık bırakıldığında log hacmi artar. Apinizer bu seviyeyi otomatik olarak kapatmaz.

ERROR seviyesinde yoğun log üretimi​

Loglar ERROR seviyesinde olmasına rağmen kayıt sayısı yüksekse sistemde bir sorun olabilir ve bu loglar incelenmelidir. Gerçek hata bildirimleri göz ardı edilmemelidir.

bilgi

Application Logs ayar ekranında anlık durum değil, sayfadan kaydedilen son ayar görüntülenmektedir.

Çözüm​

uyarı

Log seviyesinin yönetici tarafından doğrudan ERROR'e çekilmesi, ilgili yazılım ekiplerinin çalışma sırasında beklediği logların kaçırılmasına neden olabilir. Bu nedenle öncelikle ilgili ekiplerin bilgilendirilmesi gerekmektedir.

Loglar ERROR dışında bir seviyedeyse Application Logs sekmesinden seviye ERROR'e çekilebilir. Her pod başlangıcında varsayılan olarak sabitlemek için worker deployment dosyasına aşağıdaki parametre eklenebilir:

logLevel: ERROR

Detaylı bilgi için Gateway Ayarları — Ek Değişkenler sayfasına bakılabilir.

Eski Logları Düzenli Temizleyin

Bu logların 3 günde bir temizlenmesi önerilmektedir. Bunun için Admin menüsündeki Uygulama Logu Temizleme Görevleri sayfasındaki ilgili ayarlar etkin değilse etkinleştirilmeli ve düzenlenmelidir.

Alarm Eşiğini Ortama Göre Ayarlayın

Application Logs fazlalığı için varsayılan olarak alert açıktır. Kayıt sayısı 10.000 limitine ulaştığında Apinizer sağ üst köşesinden erişilebilen bildirimler oluşmaktadır. Test ortamında yoğun loglama kullanılıyorsa günlük log alarm eşiği worker için uygun bir seviyeye çekilebilir.

not

İleriki versiyonlarda debug seviyesinin varsayılan olarak kısa süreli açılması ve süre sonunda otomatik kapanması planlanmaktadır.

En son tarihinde güncellendi