Installing on Kubernetes (Helm)

Kubernetes’te self-hosted kurulum: tek bir kurum (tek tenant) için training-api, eğitim paneli ve Keycloak. Postgres chart içinde (StatefulSet) ya da harici, Valkey chart içinde. Tek sunucu kurulumu: deploy/self-hosted.

Chart her sürümde imajlarla aynı numarayla yayınlanır (oci://egitim-registry.xenopsoftware.com/fleet-egitim/charts/fleet-egitim) ve cosign ile imzalıdır. İmajlar image.registry deposundan, chart’ın sürümüyle çekilir.

Kurulum

values.yaml (en az):

image:
  registry: egitim-registry.xenopsoftware.com/fleet-egitim
imagePullSecrets:
  - name: fleet-registry # konsol kimlik bilgisiyle (aşağıda)
hosts:
  panel: egitim.firma.com.tr
  api: egitim-api.firma.com.tr
  auth: egitim-giris.firma.com.tr
tenant:
  slug: firma # sonradan değiştirilemez
  name: Firma A.Ş.
  adminEmail: [email protected]
console: # kurulum kaydıyla verilir
  url: https://...
  tokenUri: https://...
  clientId: ...
ingress:
  className: nginx
  tlsSecretName: egitim-tls # üç adı kapsayan sertifika

Konsol kimlik bilgileri ve yöneticinin ilk (geçici) parolası values’a yazılmaz, kurulum komutunda verilir:

Chart ve imajlar, konsolun token’ıyla korunan depodadır. Ayrı bir depo hesabı yoktur: kullanıcı adı konsol client kimliği (console.clientId), parola konsol client secret’ı. Lisans geçerliyken çekilebilir; lisans biterse yeni sürüm çekilemez, çalışan pod’lar durmaz.

helm registry login egitim-registry.xenopsoftware.com -u <console.clientId>
kubectl create namespace egitim
kubectl -n egitim create secret docker-registry fleet-registry --docker-server=egitim-registry.xenopsoftware.com \
  --docker-username=<console.clientId> --docker-password=<konsol client secret'ı>

helm install egitim oci://egitim-registry.xenopsoftware.com/fleet-egitim/charts/fleet-egitim --version <sürüm> -n egitim \
  -f values.yaml \
  --set-string secrets.values.consoleClientSecret=... \
  --set-string secrets.values.consoleLearnerKey=... \
  --set-string secrets.values.tenantAdminPassword=...

Diğer parolalar ve anahtarlar ilk kurulumda üretilir ve egitim-secrets’ta tutulur. Yükseltmede korunur, helm uninstall’da silinmez. Bu secret’ı yedekleyin: training-crypto-secret-key olmadan şifreli alanlar okunamaz.

İlk açılışta Keycloak fleet realm’ini, training-api kurumun tenant’ını ve ilk yöneticisini açar. Servisler birbirini bekler (init container’lar), yeniden başlatma gerekmez.

Hazır secret

Secret’ları kurum kendi aracıyla (External Secrets, Sealed Secrets, Vault) yönetiyorsa secrets.existingSecret: <ad> verin. Secret şu anahtarları taşımalı:

Anahtar	İçerik
console-client-secret	Konsol kimlik bilgisi (kurulum kaydıyla)
console-learner-key	Kursiyer takma kimliği anahtarı; bir kez üretilir, değişmez
tenant-admin-password	İlk yöneticinin geçici parolası (isteğe bağlı)
keycloak-admin-password	Keycloak yönetim konsolu, kullanıcı admin
keycloak-backend-client-secret	training-api’nin Keycloak yönetim hesabı
training-db-password	training_app rolü
keycloak-db-password	keycloak rolü
postgres-password	Chart içi Postgres’in postgres kullanıcısı
valkey-password	Valkey
training-packages-token-secret	Paket erişim token’ları (HMAC)
training-crypto-secret-key	Şifreleme anahtarı, base64 32 bayt (openssl rand -base64 32)

Harici Postgres

postgres.enabled: false ve externalDatabase.host. Roller ve veritabanları önceden açılır. training_app superuser olmamalı ve RLS’i atlayamamalı, yoksa training-api açılmaz:

CREATE ROLE training_app LOGIN NOSUPERUSER NOBYPASSRLS PASSWORD '...';
CREATE DATABASE training OWNER training_app;
CREATE ROLE keycloak LOGIN NOSUPERUSER PASSWORD '...';
CREATE DATABASE keycloak OWNER keycloak;

Yükseltme

1. Yedek alın: training ve keycloak veritabanları ve egitim-secrets. Migration’lar yalnızca ileri yönlüdür.
2. helm upgrade egitim oci://egitim-registry.xenopsoftware.com/fleet-egitim/charts/fleet-egitim --version <yeni sürüm> -n egitim -f values.yaml

Aynı ana sürüm içinde en fazla bir minör sürüm atlanabilir; desteklenmeyen geçişte training-api veritabanına dokunmadan durur ve önce hangi sürüme geçileceğini loglar. Geri dönüş yedekten yapılır, helm rollback tek başına yetmez (şema ileri gitmiştir).

İmza doğrulama

cosign verify --key cosign.pub egitim-registry.xenopsoftware.com/fleet-egitim/charts/fleet-egitim@<digest>

Digest’ler ve cosign.pub sürümün release dosyalarındadır (images.txt).