EnglishDemoGiriş
Menü

Kurulum

Helm ile production kurulumu

Kaynak chart'ı kullanarak Secret, PostgreSQL, S3 veya RWX storage, ingress/TLS, HPA, PDB, probe, rollout ve rollback yapılandırmasını uçtan uca hazırlayın.

Bu içerik nasıl kullanılmalı?Doğrulanmış ürün davranışıDokümantasyon sürümüLatest

Bu sayfadaki davranışlar, belirtilen kaynak snapshot'ında uygulama veya kabul kanıtıyla eşleştirildi.

Yayın kanalları ve kurulum kaynakları

İlk iki bağlantı Smart Kubaba yönetim arayüzünde Hosted release repository'lerini format filtresiyle açar. İstemcilerin kullanacağı gerçek Docker/Go protokol endpoint'leri ilgili repository ayrıntısından alınmalıdır. Doğrudan CLI modül arşivi ve repository listeleri erişim politikası gerektirebilir.

Kurulum topolojisi ve ön koşullar

Chart, Smart Kubaba'yı stateless ve yatay ölçeklenebilir bir uygulama katmanı olarak dağıtır. Kalıcı doğruluk durumu cluster dışındaki veya paylaşılan servislerde tutulur.

  • Kubernetes 1.24+ uyumlu cluster, Helm 3 ve kubectl erişimi; HPA etkinse Metrics Server.
  • Uygulama pod'larından erişilebilen harici PostgreSQL ve yeterli max_connections bütçesi.
  • Production için S3-compatible shared object storage veya tüm replica'ların gerçekten aynı içeriği gördüğü ReadWriteMany filesystem.
  • Önceden oluşturulmuş application Secret, imagePullSecret, ingress controller, DNS kaydı ve TLS Secret.
  • Hostname spread DoNotSchedule kullanılırken en az üç uygun worker node; zone label yoksa zone spread davranışı ayrıca doğrulanmalıdır.

Chart hangi kaynakları oluşturur?

Chart template'leri application credential üretmez; deployment kaynaklarını mevcut platform servislerine bağlar ve lisans doğrulama public key'ini ayrı bir Kubernetes Secret ile dağıtır.

  • Deployment: non-root UID/GID 999, RollingUpdate maxUnavailable=0/maxSurge=1, 10 saniye minReady ve 600 saniye progress deadline.
  • Service: sessionAffinity=None kullanan ClusterIP ve varsayılan 8080 portu.
  • Ingress: tek host, / Prefix route, seçilebilir ingressClass ve TLS Secret referansı.
  • HPA: CPU utilization, 30 saniye scale-up ve 300 saniye scale-down stabilization; PDB varsayılan minAvailable=2.
  • Startup/readiness/liveness probe'ları; readiness PostgreSQL ve shared storage durumunu, liveness yalnız process sağlığını kapsar.
  • Persistence açıksa mevcut veya chart-created PVC; kapalıysa geçici /data/smart-kubaba emptyDir.
  • Lisans doğrulama Secret'ı: license.existingSecret boşken chart oluşturur; mevcut bir Secret adı verilirse onu kullanır.

Eksiksiz production values.yaml

Aşağıdaki örnek chart'taki bütün value alanlarını içerir ve S3-backed HA production profiline göre güvenli placeholder'larla hazırlanmıştır. image.tag mutlaka immutable release ile değiştirilmelidir.

  • ingress annotation anahtarları kaynak production profilindeki F5 NGINX Controller içindir; ingress-nginx veya başka controller kullanıyorsanız kendi eşdeğerlerinizi girin.
  • autoscaling.enabled=true iken Deployment replicaCount kullanmaz; başlangıç replica sayısını HPA minReplicas belirler.
  • 20 GiB ingress sınırı backend upload limitleriyle eşleşmeli; limitsiz body-size kullanılmamalıdır.
values-production.yamlDosyayı indiryaml
replicaCount: 3
revisionHistoryLimit: 10
fullnameOverride: smart-kubaba

image:
  repository: kubaba.s3t.co/smart-kubaba
  tag: "REPLACE_WITH_IMMUTABLE_RELEASE"
  pullPolicy: Always
  pullSecrets:
    - kubaba-s3t-co-docker-config

# This Secret must already exist. The chart never creates credentials.
existingSecret: smart-kubaba-secrets

# The chart distributes the license verification public key in a dedicated
# Kubernetes Secret. Keep existingSecret empty to use the chart-managed Secret.
license:
  publicKey: "MCowBQYDK2VwAyEAKj+bp9Ahv5MlaEjV/Q4I9Uo2KsHjNBmdvTgpY8Aapwk="
  existingSecret: ""

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  className: nginx
  annotations:
    # F5 NGINX Ingress annotations used by the source production profile.
    # Replace these keys when the cluster uses ingress-nginx or another controller.
    nginx.org/client-max-body-size: "20g"
    nginx.org/proxy-read-timeout: "3600s"
    nginx.org/proxy-send-timeout: "3600s"
  host: kubaba.example.com
  tls:
    enabled: true
    secretName: kubaba-tls

# Recommended production profile: shared S3-compatible object storage.
# Bucket, region, endpoint and optional credentials come from existingSecret.
storage:
  type: S3
  rootDirectory: /data/smart-kubaba/storage
  archiveDirectory: /data/smart-kubaba/archive

# S3 keeps durable application objects outside the pod. The chart still mounts
# an emptyDir at /data/smart-kubaba for bounded temporary OSV work files.
persistence:
  enabled: false
  existingClaim: ""
  storageClass: ""
  accessModes:
    - ReadWriteMany
  size: 100Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 4
  targetCPUUtilizationPercentage: 70

podDisruptionBudget:
  enabled: true
  minAvailable: 2

resources:
  requests:
    cpu: 500m
    memory: 768Mi
    ephemeral-storage: 1Gi
  limits:
    cpu: "2"
    memory: 2Gi
    ephemeral-storage: 10Gi

javaToolOptions: "-Xms256m -Xmx1280m -XX:+ExitOnOutOfMemoryError"
terminationGracePeriodSeconds: 60
preStopDelaySeconds: 10

# Pool sizes are per pod. Reserve PostgreSQL headroom for migrations,
# administration, monitoring and non-application clients.
databasePool:
  maximumSize: 10
  minimumIdle: 2
  connectionTimeoutMillis: 10000
  validationTimeoutMillis: 5000
  idleTimeoutMillis: 600000
  maxLifetimeMillis: 1800000
  leakDetectionThresholdMillis: 0

probes:
  startup:
    failureThreshold: 24
    periodSeconds: 5
  readiness:
    failureThreshold: 6
    periodSeconds: 10
  liveness:
    failureThreshold: 3
    periodSeconds: 20

nodeSelector: {}
tolerations: []
affinity: {}

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: DoNotSchedule
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: ScheduleAnyway

Filesystem/RWX alternatifi

S3 yerine filesystem kullanılacaksa aynı PVC bütün replica'larda aynı anda mount edilmelidir. Node-local disk veya ReadWriteOnce volume, çok replica'lı production için uygun değildir.

  • existingClaim boş bırakılırsa chart accessModes ve size ile PVC üretir; production'da önceden test edilmiş mevcut claim tercih edilir.
  • Longhorn için standart non-migratable RWX StorageClass kullanılmalıdır; migratable=true block-mode live migration içindir ve NFS share-manager sağlamaz.
Filesystem overrideyaml
# Use this override only with storage shared by every replica.
storage:
  type: FILESYSTEM
  rootDirectory: /data/smart-kubaba/storage
  archiveDirectory: /data/smart-kubaba/archive

persistence:
  enabled: true
  # Prefer a pre-created, tested RWX claim for production.
  existingClaim: smart-kubaba-data-rwx
  storageClass: ""
  accessModes:
    - ReadWriteMany
  size: 100Gi

Temel, image, Service ve Secret parametreleri

Bu alanlar oluşturulan kaynak adlarını, uygulama image'ını ve platform bağlantılarını belirler. Varsayılanların production ortamına doğrudan uygun olduğu varsayılmamalıdır.

  • replicaCount (3): yalnız autoscaling.enabled=false iken Deployment replicas değeridir; HPA açıkken minReplicas tabanı kullanılır.
  • revisionHistoryLimit (10): Deployment'in saklayacağı eski ReplicaSet sayısıdır; rollback geçmişi ve cluster kaynak tüketimi birlikte değerlendirilir.
  • fullnameOverride (boş): boşsa <release>-smart-kubaba adı üretilir; mevcut kaynakları Helm'e alırken selector değişimini önlemek için sabitlenebilir.
  • image.repository (kubaba.s3t.co/smart-kubaba): image kaynağıdır; verilen Docker release repository bu image yayın kanalının protokol köküdür.
  • image.tag (boş): boşsa Chart.appVersion kullanılır; production'da doğrulanmış immutable tag/digest eşlemesi açıkça verilmelidir.
  • image.pullPolicy (Always) ve image.pullSecrets: çekme davranışı ile önceden oluşturulmuş dockerconfigjson Secret adlarını belirler; chart credential üretmez.
  • existingSecret (smart-kubaba-secrets): envFrom ile uygulamaya verilen Secret'tır ve zorunludur; gerçek değerler values.yaml içine yazılmaz.
  • license.publicKey ve license.existingSecret: chart-managed public-key Secret'ını veya SMART_KUBABA_LICENSE_PUBLIC_KEY anahtarını içeren mevcut Secret'ı seçer.
  • service.type (ClusterIP) ve service.port (8080): Service görünürlüğü ve portunu belirler; container target port sabit http/8080'dır.

Ingress, storage ve persistence parametreleri

Ingress controller sözleşmesi ile kalıcı artifact katmanı birlikte planlanmalıdır; yalnız YAML'ın render edilmesi veri dayanıklılığı kanıtı değildir.

  • ingress.enabled (false): Ingress üretimini açar; kapalıyken host/TLS alanları kaynak oluşturmaz.
  • ingress.className (nginx), annotations ve host: controller sınıfı, controller'a özgü ayarlar ve tek canonical host'tur; annotation anahtarları controller'lar arasında taşınabilir değildir.
  • ingress.tls.enabled (true) ve secretName (kubaba-tls): Ingress TLS bölümünü ve önceden oluşturulmuş certificate Secret'ını belirler; chart sertifika üretmez.
  • storage.type (FILESYSTEM): FILESYSTEM veya S3 backend seçer; S3 bucket/region/endpoint/credential değerleri existingSecret üzerinden gelir.
  • storage.rootDirectory ve archiveDirectory: container içindeki aktif/arşiv path'leridir; FILESYSTEM modunda mounted volume üzerinde, S3 modunda uygulama prefix davranışıyla değerlendirilir.
  • persistence.enabled (true): true iken PVC mount edilir; false iken /data/smart-kubaba emptyDir olur ve yalnız S3-backed kalıcı nesnelerle geçici çalışma alanı olarak kullanılmalıdır.
  • persistence.existingClaim: doluysa chart PVC üretmez ve bu claim'i kullanır; boşsa storageClass, accessModes ve size ile yeni PVC oluşturur.
  • persistence.storageClass, accessModes ([ReadWriteMany]) ve size (100Gi): yalnız chart-created PVC sözleşmesidir; class'ın gerçek multi-node RWX sağladığı ayrıca sınanmalıdır.

Kaynak, autoscaling ve yerleşim parametreleri

Uygulama replica sayısı ile PostgreSQL bağlantı bütçesi, storage throughput'u ve node/zone kapasitesi birlikte ölçülmelidir.

  • resources.requests/limits: CPU, memory ve ephemeral-storage scheduler garantilerini ve container limitlerini belirler; özellikle image/SBOM geçici çalışma alanı için ephemeral storage izlenmelidir.
  • autoscaling.enabled (true): HPA kaynağını açar; Metrics Server gerekir ve Deployment replicaCount alanı render edilmez.
  • autoscaling.minReplicas (3), maxReplicas (10), targetCPUUtilizationPercentage (70): replica aralığı ve CPU hedefidir; maxReplicas × DB pool bağlantı bütçesine sığmalıdır.
  • podDisruptionBudget.enabled (true) ve minAvailable (2): gönüllü disruption sırasında minimum hazır pod sayısıdır; minReplicas ile çelişmemelidir.
  • nodeSelector, tolerations ve affinity: uygun node seçimi, taint toleransı ve gelişmiş yerleşim kurallarıdır; boş map/list render edilmez.
  • topologySpreadConstraints: her kural maxSkew, topologyKey ve whenUnsatisfiable taşır; chart selector'ı otomatik ekler. Hostname DoNotSchedule için yeterli node yoksa pod Pending kalabilir.

JVM, database pool, probe ve kapanış parametreleri

Bu değerler uygulamanın bellek, bağlantı ve rollout davranışını doğrudan etkiler; ölçüm olmadan yalnız replica sayısına göre büyütülmemelidir.

  • javaToolOptions: JAVA_TOOL_OPTIONS değeridir; varsayılan Xms256m/Xmx1280m, 2Gi memory limitinde native/direct buffer ve JVM overhead için alan bırakır.
  • terminationGracePeriodSeconds (60) ve preStopDelaySeconds (10): endpoint'in trafikten çıkması ve uygulamanın 45 saniyelik shutdown timeout'u için toplam kapanış penceresini belirler.
  • databasePool.maximumSize (10) ve minimumIdle (2): pod başına HikariCP sınırlarıdır; bütün replica'lar, migration ve yönetim bağlantıları PostgreSQL max_connections altında kalmalıdır.
  • connectionTimeoutMillis (10000) ve validationTimeoutMillis (5000): bağlantı alma/doğrulama üst sınırlarıdır; validation timeout connection timeout'tan küçük tutulmalıdır.
  • idleTimeoutMillis (600000), maxLifetimeMillis (1800000), leakDetectionThresholdMillis (0): idle/lifetime ve opsiyonel leak teşhis eşikleridir; database/network timeout'larıyla uyumlu olmalıdır.
  • probes.startup/readiness/liveness failureThreshold ve periodSeconds: başarısızlık toleransını belirler; sabit timeoutSeconds 3'tür. Readiness dependency durumunu, liveness process sağlığını ölçer.

Values birleştirme, inceleme ve override sırası

Chart varsayılanları önce yüklenir; -f dosyaları soldan sağa birleştirilir ve --set/--set-string en son uygulanır. Secret olmayan ortam farklarını ayrı values dosyasında tutun; image tag gibi string alanlarda tür dönüşümünü önlemek için --set-string kullanın.

  1. helm show values ile seçilen chart sürümünün gerçek varsayılanlarını kaydedin; başka branch'teki values.yaml'a güvenmeyin.
  2. helm template çıktısında image, Secret referansları, PVC, securityContext, probe, HPA/PDB ve Ingress alanlarını uygulamadan önce inceleyin.
  3. helm get values --all ile kurulu release'in efektif değerlerini, helm get manifest ile cluster'a gönderilen manifesti karşılaştırma kanıtı olarak saklayın.
Values inceleme komutlarıbash
# Inspect the exact defaults shipped by the selected chart version.
helm repo add kubaba https://kubaba.s3t.co/repository/helm/helm-release/
helm repo update kubaba
helm search repo kubaba/smart-kubaba --versions
helm show values kubaba/smart-kubaba --version "<chart-version>" > values-defaults.yaml

# Keep environment-specific overrides in a separate, secret-free file.
helm lint kubaba/smart-kubaba \
  --version "<chart-version>" \
  -f values-production.yaml

helm template smart-kubaba kubaba/smart-kubaba \
  --version "<chart-version>" \
  --namespace kubaba \
  -f values-production.yaml \
  --set-string image.tag="<immutable-image-tag>" \
  > rendered-smart-kubaba.yaml

# After installation, compare effective values and the rendered manifest.
helm -n kubaba get values smart-kubaba --all
helm -n kubaba get manifest smart-kubaba > installed-smart-kubaba.yaml

Secret ve image pull yapısı

existingSecret ile gösterilen Kubernetes Secret application environment anahtarlarını envFrom üzerinden sağlar; chart bu credential Secret'ını oluşturmaz ve gerçek değerler values.yaml içine yazılmaz. Lisans doğrulama public key'i ayrı license ayarıyla otomatik dağıtılır.

  • PostgreSQL URL, kullanıcı ve parola ile bootstrap admin kullanıcı/parolası ilk kurulumdan önce secret manager'da oluşturulmalıdır.
  • S3 access key'leri verilmezse backend AWS default credential provider chain kullanabilir; workload identity/instance role tercih edilebilir.
  • image.pullSecrets ayrı kubernetes.io/dockerconfigjson Secret referansıdır; application Secret içine Docker config konmaz.
  • Bootstrap admin initial password yalnız kullanıcı henüz yokken kullanılır; kurulum sonrasında secret rotation ve yönetici parola politikası ayrıca işletilmelidir.
  • Varsayılan kurulumda Helm public key için smart-kubaba-license-verification Secret'ını oluşturur; manuel public key Secret'ı hazırlamak gerekmez.
Secret anahtar referansıtext
Required for first installation:
SMART_KUBABA_DB_URL
SMART_KUBABA_DB_USERNAME
SMART_KUBABA_DB_PASSWORD
SMART_KUBABA_ADMIN_USERNAME
SMART_KUBABA_ADMIN_INITIAL_PASSWORD

Required when storage.type is S3:
SMART_KUBABA_STORAGE_S3_BUCKET
SMART_KUBABA_STORAGE_S3_REGION

Provider-dependent S3 keys:
SMART_KUBABA_STORAGE_S3_ENDPOINT_URL
SMART_KUBABA_STORAGE_S3_PATH_STYLE_ACCESS
SMART_KUBABA_STORAGE_S3_ACCESS_KEY_ID
SMART_KUBABA_STORAGE_S3_SECRET_ACCESS_KEY

Optional OIDC redirect keys:
SMART_KUBABA_OIDC_SUCCESS_REDIRECT
SMART_KUBABA_OIDC_FAILURE_REDIRECT

The image pull credential is a separate kubernetes.io/dockerconfigjson
Secret named by image.pullSecrets.

Kurulum adımları

Komutlar D:/workspace/smart-kubaba repository kökünden çalıştırılacak şekilde hazırlanmıştır.

  1. values-production.yaml içindeki image tag, host, TLS Secret, ingress class, storage ve kapasite değerlerini hedef ortama göre güncelleyin.
  2. kubaba namespace, smart-kubaba-secrets ve registry pull Secret'ını platform secret manager üzerinden oluşturun.
  3. helm lint ile schema/template hatalarını, helm template ile render edilmiş manifest ve secret referanslarını inceleyin.
  4. Render çıktısında smart-kubaba-license-verification Secret'ının ve pod üzerindeki SMART_KUBABA_LICENSE_PUBLIC_KEY referansının bulunduğunu doğrulayın.
  5. İlk kurulumda immutable image tag ile helm upgrade --install çalıştırın ve wait/timeout sınırını koruyun.
  6. Deployment rollout, pod readiness, Service/Ingress, HPA/PDB ve readiness endpoint sonucunu doğrulayın.
Kurulum ve render komutlarıbash
# Run from the Smart Kubaba source repository.
kubectl create namespace kubaba --dry-run=client -o yaml | kubectl apply -f -

# Create smart-kubaba-secrets and the registry pull Secret through the
# platform secret manager before continuing. Do not commit plaintext values.

helm lint ./helm/smart-kubaba \
  -f values-production.yaml

helm template smart-kubaba ./helm/smart-kubaba \
  --namespace kubaba \
  -f values-production.yaml \
  --set-string image.tag="<release>" \
  > rendered-smart-kubaba.yaml

helm upgrade --install smart-kubaba ./helm/smart-kubaba \
  --namespace kubaba \
  --create-namespace \
  -f values-production.yaml \
  --set-string image.tag="<release>" \
  --wait \
  --timeout 15m

Kurulum doğrulaması

Helm başarılı sonucu tek başına kabul değildir. Uygulama, veritabanı, storage, package trafiği ve operasyon kayıtları birlikte doğrulanmalıdır.

  • Bütün pod'lar Ready, Deployment Available, HPA/PDB beklenen durumda ve Ingress TLS sertifikası geçerli olmalıdır.
  • Readiness UP; PostgreSQL/Flyway ve global shared storage sağlıklı olmalıdır. Liveness external dependency kesintisinde process'i gereksiz yeniden başlatmamalıdır.
  • Yönetim login'i, Hosted publish/download, Proxy fetch/cache, Group resolution ve Package Usage/Audit/Outbound kayıtları kabul senaryosuyla çalıştırılmalıdır.
  • S3 veya RWX storage birden fazla replica üzerinden aynı artifact checksum'ını sunmalıdır.
Doğrulama komutlarıbash
kubectl -n kubaba get deployment,service,ingress,pods,hpa,pdb,pvc
kubectl -n kubaba rollout status deployment/smart-kubaba --timeout=10m
kubectl -n kubaba wait --for=condition=Ready pod -l app=smart-kubaba --timeout=10m

helm -n kubaba status smart-kubaba
helm -n kubaba get values smart-kubaba --all
helm -n kubaba get manifest smart-kubaba > installed-smart-kubaba.yaml

# Readiness includes PostgreSQL and shared-storage availability.
kubectl -n kubaba port-forward service/smart-kubaba 8080:8080
curl --fail --silent --show-error http://127.0.0.1:8080/actuator/health/readiness

Upgrade, rollback ve kaldırma

Kurulu release'lerde sonraki upgrade'ler --atomic ile başarısız rollout'u otomatik geri alabilir. İlk kez mevcut raw-manifest kaynaklarını Helm'e alıyorsanız otomatik cleanup/atomic kullanmadan waited adoption yapılmalıdır.

  • Her upgrade öncesinde PostgreSQL migration zinciri, chart appVersion/image tag ve önceki Helm revision kaydedilmelidir.
  • Rollback yalnız pod/image durumunu geri almak değildir; Flyway history ile mevcut kod migration seti ayrıca karşılaştırılmalıdır.
  • helm uninstall PostgreSQL, S3 bucket veya external PVC backup'ını silmez; veri saklama ve recovery ayrı operatör kararıdır.
Release yaşam döngüsübash
# Later upgrades: pin an immutable chart/image release and enable atomic rollback.
helm upgrade smart-kubaba ./helm/smart-kubaba \
  --namespace kubaba \
  -f values-production.yaml \
  --set-string image.tag="<new-release>" \
  --atomic \
  --wait \
  --timeout 15m

helm -n kubaba history smart-kubaba

# Select a known-good revision from helm history.
helm -n kubaba rollback smart-kubaba <revision> --wait --timeout 15m

# Removal does not replace PostgreSQL/object-storage recovery planning.
helm -n kubaba uninstall smart-kubaba

Kapasite ve güvenlik sınırları

  • databasePool.maximumSize pod başınadır. autoscaling.maxReplicas × maximumSize değerine migration, admin, monitoring ve diğer client headroom'u eklenerek PostgreSQL max_connections altında kalınmalıdır.
  • javaToolOptions ve resource limits birlikte ölçülmelidir; heap limitini container memory limitine eşitlemek native/direct buffer ve JVM overhead için alan bırakmaz.
  • SMART_KUBABA_COOKIE_SECURE=true chart tarafından zorunlu verilir; production yönetim trafiği TLS dışında yayımlanmamalıdır.
  • Secret değerleri Helm command line, values file, rendered manifest, Git veya CI loglarına yazılmamalıdır.
  • Bu chart backup/restore, RTO/RPO, certificate issuance, PostgreSQL HA veya object-storage durability garantisi sağlamaz; bunlar platform runbook'larıyla tamamlanmalıdır.