# Kubernetes Üzerinde Çalıştırma

> Helm chart'ının kurulumu — veritabanı ve SECRET_KEY yönetimi, ingress, kalıcılık, probe'lar, security context, kaynak boyutlandırma ve kaldırma.

- Güncelleme: 2026-11-04
- Kaynak: https://contextator.com/tr/docs/kubernetes/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
Contextator'ı Kubernetes üzerinde çalıştırmanın desteklenen yolu bir Helm chart'ıdır. Bu sayfadaki her
şeyin kaynağı: depodaki `charts/contextator/` altındaki chart'ın kendisi ve onun kendi, daha uzun
`charts/contextator/README.md`'si.

## Kurulum

```bash
helm repo add contextator https://contextator.github.io/Contextator
helm repo update
helm install contextator contextator/contextator \
  --set database.url="postgres://user:pass@host:5432/contextator" \
  --set-string image.tag="<version>-slim"
```

`database.url` (ya da zaten yönettiğiniz bir Secret için `database.existingSecret`) ve `image.tag`
ikisi de zorunludur ve varsayılanı yoktur — ikisinden biri eksikse chart hiçbir şey render etmeden önce
`helm install`/`helm template`'i anında başarısız kılar. `image.tag` bir `-slim` build'ine işaret etmelidir;
o son ek olmadan gelen tag'ler gömülü PostgreSQL'li tam imajdır, bu chart için yanlış topolojidir. Ya da
chart dizininin checkout edilmiş bir kopyasından doğrudan kurun:
`helm install contextator ./charts/contextator -f my-values.yaml` — aynı iki değer, değer dosyasında ya
da komut satırında olsun, yine zorunludur.

## Tasarım gereği tek replica

`replicaCount` desteklenen bir değer değildir — chart onu doğrudan reddeder
(`additional properties 'replicaCount' not allowed`) ve bu bilerek yapılmıştır, bir eksiklik değil:
Contextator kendi indeksleme kuyruğuna karşı tek bir yazıcı çalıştırır, ve onu kümelemek ürünün henüz
sahip olmadığı bir koordinasyon katmanı gerektirirdi. Pod'un sayısını değil, kendi
kaynaklarını ölçekleyin; aşağıdaki [Kaynak boyutlandırma](#kaynak-boyutlandırma) bölümüne bakın.

## Veritabanı

Chart'a ya doğrudan bir bağlantı dizesi verin (`database.url`) ya da zaten yönettiğiniz bir Secret'a
işaret edin (`database.existingSecret`) — [Yapılandırma](/tr/docs/configuration/)'nın Kubernetes dışında
`DATABASE_URL` için anlattığı seçimin aynısı. PostgreSQL'in kendisi bu chart'ın parçası değildir; onu
ayrıca çalıştırın ya da yönetilen bir örneğe işaret edin.

## SECRET_KEY: bir kez üretilir, sabit kalır

`SECRET_KEY` kaynak kimlik bilgilerini durağan halde şifreler — git, Notion, Confluence ve GitHub tokenları, S3 anahtar çiftleri, Google Drive anahtarları ve
webhook sırları — bu yüzden onu kaybetmek yalnızca herkesi oturumdan atmaz, aynı zamanda o saklanan
kimlik bilgilerini kurtarılamaz hale getirir. Ayarlanmadan bırakıldığında chart ilk kurulumda bir tane
üretir ve — yeni bir tane üretmeye karar vermeden önce çalışan kümenin Secret'ını Helm'in `lookup`
fonksiyonuyla okuduğu için — siz hiçbir şey yapmadan sonraki her `helm upgrade` boyunca aynı değeri
korur.

**`lookup` fonksiyonu yalnızca gerçek, erişilebilir bir kümeye karşı çalışır.** Chart'ı offline render
etmek — `helm template`, ya da render edilmiş bir manifestten canlı bir `lookup` olmadan reconcile eden
bir GitOps controller'ı — her seferinde var olan bir Secret görmez ve her render'da yeni bir anahtar
üretir, ki bu tam olarak çalışan bir örneğin altında değişmemesi gereken değerdir. Böyle bir kurulumda,
anahtarı bir kez kendiniz üretin ve chart'a onu üretmesine izin vermek yerine var olan bir Secret olarak
elden verin:

```bash
kubectl create secret generic contextator-secret-key \
  --from-literal=SECRET_KEY=$(openssl rand -hex 32)
```

```yaml
secretKey:
  existingSecret: contextator-secret-key
  existingSecretKey: SECRET_KEY
```

**Onu rotasyona sokmak** bir değer değişimi değil, iki adımlı bir harekettir. Önce mevcut değeri yeni bir
adla saklayın — `contextator-secret-key` yeni anahtarla üzerine yazılmak üzeredir, bu yüzden herhangi bir
şey üretmeden önce eskisini kopyalayıp çıkarın:

```bash
kubectl -n <namespace> create secret generic contextator-secret-key-previous \
  --from-literal=SECRET_KEY="$(kubectl -n <namespace> get secret contextator-secret-key -o jsonpath='{.data.SECRET_KEY}' | base64 -d)"
```

Sonra yeni anahtarı üretin ve onu `contextator-secret-key`'e yerinde yazın (`kubectl create` tek başına
zaten var olan bir Secret'ta başarısız olur):

```bash
kubectl -n <namespace> create secret generic contextator-secret-key \
  --from-literal=SECRET_KEY="$(openssl rand -hex 32)" \
  --dry-run=client -o yaml | kubectl -n <namespace> apply -f -
```

Yeni anahtar yukarıdaki gibi sabitlenmişken (`secretKey.existingSecret`/`secretKey.existingSecretKey`),
sürece eskisini `envSecret` üzerinden `SECRET_KEY_PREVIOUS` olarak verin; onun girdileri her zaman
`NAME: {secretName, secretKey}` biçimindedir:

```yaml
envSecret:
  SECRET_KEY_PREVIOUS:
    secretName: contextator-secret-key-previous
    secretKey: SECRET_KEY
```

İkisi de mevcutken ve Pod yeniden başlatıldıktan sonra, Deployment adını bulun (`<release>-contextator`,
release adı zaten `contextator` içermiyorsa ve `fullnameOverride` ayarlanmamışsa) ve rotasyonu onun
içinde çalıştırın:

```sh
kubectl -n <namespace> get deploy -l app.kubernetes.io/instance=<release>
kubectl -n <namespace> exec deploy/<deployment-name> -- npm run rotate-secret
```

Eski anahtarın şifrelediğini çözer ve yenisinin altında yeniden şifreler. Dönüştürülecek bir şey
kalmadığını bildirdiğinde, `SECRET_KEY_PREVIOUS`'ı (`envSecret` girdisini) kaldırın ve Pod'un tekrar
yeniden başlamasına izin verin — eski anahtarı emekliye ayıran o kaldırmadır. Anahtar tamamen kaybolduysa
ve kurtaracak bir `SECRET_KEY_PREVIOUS` yoksa, onun altında saklanan kaynak kimlik bilgileri çözülemez —
geri dönüşün tek yolu o kaynakları yeniden eklemektir.

## Ingress ve reverse-proxy üçlüsü

Chart'ın önündeki bir Ingress, herhangi bir başka reverse proxy gibidir, ve
[Yapılandırma](/tr/docs/configuration/#bir-reverse-proxy-arkasında-çalışmak)'daki aynı üçlü geçerlidir:
`config.trustProxy`, `config.publicBaseUrl` ve `env.AUTH_COOKIE_SECURE` birlikte hareket eder, yoksa
IP başına oturum açma sınırı, MCP connector yetkilendirmesi ve oturum çerezi her biri kendi sessiz
biçiminde bozulur.

**Bir sıçrama sayısı (`2`, `3`, …) reddedilir; `"1"` ve `"true"` da öyle.** Bu,
[Yapılandırma](/tr/docs/configuration/#bir-reverse-proxy-arkasında-çalışmak)'nın Kubernetes dışında anlattığı
aynı korumadır: chart 2.0.0'ın values şeması `config.trustProxy`'nin ikisinden birine ayarlanmasını reddeder
(büyük/küçük harf fark etmez, çevredeki boşluklar yok sayılır); böylece `helm upgrade` hiçbir şey değişmeden
önce durur, uygulamanın kendisi de aynı değeri 0.5.0'dan beri başlangıçta reddeder. Bunun yerine proxy'yi
adlandırın, onu gerçekten kapsayan en dar aralığı:

```yaml
config:
  publicBaseUrl: "https://contextator.example.com"
  trustProxy: "<ingress-controller-pod-ip-or-cidr>"
env:
  AUTH_COOKIE_SECURE: "1"
```

Değer yalnızca socket'in eşine karşı değil her sıçramaya karşı eşleştirilir, bu yüzden tüm pod CIDR'ını
yapıştırmak bu Service'e ulaşabilen her diğer pod'a da güvenir — yalnızca ingress controller'dan başka
bir şeyin bu pod'un portuna ulaşmasına izin vermeyen bir NetworkPolicy arkasında güvenlidir.

## Chart 2.0.0'a yükseltmek

Chart 2.0.0 bir major sürümdür, çünkü values şeması artık bir değeri reddeder: `config.trustProxy`'nin `"1"`
ya da `"true"` olarak ayarlanması; bu, uygulamaya `X-Forwarded-For`'un en soldaki değerini kim yazdıysa ona
inanmasını söylüyordu. Uygulama 0.5.0 aynı değeri başlangıçta reddeder; bu yüzden onu kabul etmeye devam eden
bir sürüm CrashLoop'a girerdi — bunun yerine şema, hiçbir şey değişmeden önce `helm upgrade`'i durdurur.

Yükseltmeden önce, values dosyanız ya da `--set` bayraklarınız bunu ayarlıyorsa:

- proxy başka bir host'ta ya da başka bir Pod'dadır: `config.trustProxy`'yi onun adresine ya da CIDR bloğuna
  ayarlayın, örneğin `"172.18.0.0/16"` — proxy'yi tutan en dar aralık, istemcilerinizin bulunduğu ağ değil;
- proxy uygulamayla aynı host'ta çalışır: `"loopback"`;
- Pod'un önünde hiçbir şey yoktur: `"0"`, ya da boş bırakın.

`helm template t charts/contextator --set-string config.trustProxy=1` reddi gösterir. `--set`, `1` ve `true`'yu
bir sayıya ve bir boolean'a çevirir; şema bunları zaten tür hatası olarak reddediyordu, bu yüzden bu kuralı
sınayan biçim `--set-string`'dir. Serbest biçimli `env` haritasıyla ayarlanan bir `TRUST_PROXY`'yi şema görmez,
ama uygulama Pod başladığında onu aynı şekilde reddeder.

## Kalıcılık

İki `ReadWriteOnce` PersistentVolumeClaim: `/data` (yüklenen dosyalar, git checkout'ları, Notion, Confluence, web, S3, Google Drive ve GitHub çekimleri) ve
`/app/.cache/models` (indirilen gömme modeli, böylece bir pod yeniden başlatması onu yeniden indirmez).
`/data`'nın, canlı bir kümede, bir pod yeniden başlatmasından bütün çıktığı doğrulanmıştır.

## Probe'lar

Liveness, porttaki salt bir TCP kontrolüdür — veritabanına bağımlı olmadan tıkanmış bir süreci
yakalamaya yeter. Readiness ve startup ikisi de gerçek bir `GET /api/health` çağrısıdır, bu yüzden bir
pod yalnızca bir bağlantı kabul ettiğinde değil, uygulama gerçekten cevap verebildiğinde ready
işaretlenir. Bir veritabanı kesintisine karşı canlı bir kümede doğrulanmıştır: pod bu süre boyunca
`READY 0/1` raporlar, liveness hiçbir zaman veritabanına bağımlı olmadığı için **sıfır** restart alır,
ve veritabanı geri geldiği anda hiçbir manuel pod restart'ı gerekmeden otomatik olarak ready'e döner.

## Security context

Container **uid 0** olarak başlamak zorundadır — opsiyonel değildir, ve bunu yasaklayan sertleştirilmiş
bir `securityContext`, *"the container must start as root"* hatasıyla başlangıçta başarısız olur. Bu
kısa, yapısal bir gerekliliktir, kalıcı değil: entrypoint o ilk anı root olarak yukarıdaki iki bağlı
volume'un sahipliğini düzeltmek için kullanır (taze bir PVC varsayılan olarak `root` sahiplidir), sonra
herhangi bir uygulama kodu çalışmadan önce `gosu` ile ayrıcalıksız bir `node` kullanıcısına hemen
devreder. Trafiği gerçekten sunan süreç hiçbir zaman root olarak çalışmaz.

İmaj ayrıca `wget` ya da `curl` taşımaz — kendi healthcheck'i ve chart testleri, Dockerfile'dan
varsayılmak yerine gerçek bir `helm test` çalıştırmasıyla doğrulanmış şekilde, Node'un yerleşik
`fetch()`'iyle birlikte `node -e` kullanır.

## Kaynak boyutlandırma

Aşağıdaki sayılar tahmin edilmemiş, çalışan bir örneğe karşı ölçülmüştür:

| Durum | CPU | Bellek |
|-------|-----|--------|
| Boşta | düşük | ~770–820 MiB RSS |
| İndeksleme patlaması | 2–3 saniye boyunca ~10 çekirdek | — |
| Soğuk başlangıç | ilk model yüklemesi (indirme + başlatma) ~72,4 sn | — |

`resources.requests`/`resources.limits`'i boşta değerinin üzerinde bir marjla ve indeksleme
patlamaları için yeterli burst kapasitesiyle ayarlayın; bir patlama sırasında sıkı bir CPU limiti diğer
pod'ları etkilemek yerine yalnızca tek bir indeksleme çalışmasını yavaşlatır, çünkü zaten hep tek bir
replica vardır.

Bir git kaynağı kendi tepe noktasını ekler: git kütüphanesi pack'i bellekte tutup iki kez kopyalar, bu yüzden tek bir
fetch boşta değerinin üstüne yaklaşık `config.gitMaxPackBytes`'ın iki katını (256 MiB varsayılanda 512 MiB) kullanabilir;
ayrıştırma buna daha fazlasını ekler. Büyük bir depo için `config.gitMaxPackBytes`'ı yükseltirseniz
`resources.limits.memory`'yi de onunla birlikte yükseltin ve limiti yeni değerin iki katının ve boşta kullanımın
rahatça üstünde tutun (bkz. [Git Deposu Kaynağı](/tr/docs/git-repository-source/#bir-yanıt-ne-kadar-büyük-olabilir)). 0.3.2 ile geldi.

## Kaldırma

`helm uninstall` varsayılan olarak iki PersistentVolumeClaim'i geride bırakır — bunlar bir
`helm.sh/resource-policy: keep` anotasyonu taşır, bu yüzden yüklenen dosyalar, checkout'lar ve önbelleğe alınmış
model kazara bir kaldırmadan sağ çıkar (`persistence.retainOnUninstall: false` bunu kapatır). İndeksin kendisi harici PostgreSQL'inizde yaşar, ve `helm uninstall` ona hiç dokunmaz. `SECRET_KEY` Secret'ı böyle bir politika taşımaz ve release ile
birlikte **silinir**; aynı veriye karşı yeniden kurmayı planlıyorsanız önce anahtarı kaydedin (yukarıdaki
[SECRET_KEY: bir kez üretilir, sabit kalır](#secret_key-bir-kez-üretilir-sabit-kalır)'e bakın) yoksa
hayatta kalan PVC'lerin hâlâ referans verdiği kaynak kimlik bilgilerini çözemezsiniz.

## Metrikler ve ServiceMonitor

`GET /metrics`, uygulama portunda sunulur ve herkese açık değildir. Cluster'da Prometheus Operator'ın
CRD'leri varken, chart'ın bir ServiceMonitor üretmesi için `metrics.serviceMonitor.enabled: true`
ayarlayın; `interval` (varsayılan `30s`), `scrapeTimeout` (varsayılan `10s`, `interval`'i asla aşmaz —
aksi halde chart render etmeyi reddeder) ve `labels` (genellikle Prometheus'unuzun
`serviceMonitorSelector`'ının eşleştirdiği, ör. `release: kube-prometheus-stack`) yanında durur.

Scrape bir kimlik bilgisi ister. Onu `envSecret.METRICS_TOKEN` içine koyun — Pod'da `METRICS_TOKEN`'ı
ayarlayan aynı Secret girdisi, en az 16 karakter — ya da güvendiğiniz bir ağda `env.METRICS_PUBLIC: "1"`
ayarlayın. İkisi de yoksa her scrape `401` ile yanıtlanır. Bkz. [Yapılandırma](/tr/docs/configuration/#gözlemlenebilirlik).

## Katı values şeması

Chart, değerlerini katı bir JSON Schema'ya karşı doğrular — tanınmayan bir key, sessizce yok
sayılmak yerine `helm install`/`helm upgrade`'i anında başarısız kılar. Yanlış yolda aranması kolay
olduğu için adıyla bilinmeye değer bir key: `config.mcpStructuredOutput` tipli, üst düzey bir `config.*`
key'idir, başka bir yerde iç içe serbest bir değer değil. Aynısı web ve git kaynaklarının izin listeleri olan `config.webAllowedHosts` ve
`config.gitAllowedHosts` için de geçerlidir: her biri host adlarından oluşan bir listedir ve iç ağdaki bir host'u okuyan
bir kaynağın host'u buraya eklenmelidir (bkz. [Dokümantasyon Sitesi Kaynağı](/tr/docs/documentation-site-source/) ve
[Git Deposu Kaynağı](/tr/docs/git-repository-source/)).

`config.mcpReportGapPerHour` aynı türden tipli bir key'dir: en az `0` olan bir tamsayı, `MCP_REPORT_GAP_PER_HOUR`
olarak ayarlanır; bir MCP kimlik bilgisinin saatte kabul edilmiş kaç `report_gap` raporu olabileceği (bkz.
[MCP Araçları](/tr/docs/mcp-tools/#report_gap)). Ayarlanmazsa uygulamanın varsayılanı `20` geçerlidir; `0` sınırı
kapatır.

Uygulama 0.6.0 ile gelen chart 2.1.0, yeni kaynakların ayarları için tipli `config.*` key'leri ekler:
`config.sourceAllowedHosts` (`SOURCE_ALLOWED_HOSTS`, Confluence, S3 ve GitHub Enterprise Server host'ları için izin listesi),
`config.s3MaxObjects`, `config.gdriveMaxFiles`, `config.githubMaxIssues` ve `config.githubMaxDiscussions` (1 ile 100 000
arası tamsayılar; varsayılan `null`, uygulamanın 5 000 varsayılanını bırakır) ve `config.oidcGroupsClaim`
(`OIDC_GROUPS_CLAIM`, bkz. [Tek Oturum Açma](/tr/docs/sso/)). Uygulama 0.7.0 ile gelen chart 2.2.0 şunları ekler: `config.piiScan` (`PII_SCAN`; varsayılan `true` onu ayarsız bırakır ve
tarama açık kalır, `false` yeni taramayı kapatır), `config.confluenceMaxPages` ve `config.notionMaxPages`
(`CONFLUENCE_MAX_PAGES`, `NOTION_MAX_PAGES`; 1 ile 100 000 arası tamsayılar, `null` uygulamanın 5 000 varsayılanını bırakır)
ve Notion OAuth key'leri `config.notionOauthClientId`, `config.notionOauthRedirectUri` ve `config.notionOauthClientSecret`.
Secret bir değer değil, yönettiğiniz bir Secret'a `{ secretName, secretKey }` referansıdır; şema ikisinden yalnızca birinin
verilmesini reddeder. Alternatif olarak `NOTION_OAUTH_CLIENT_SECRET` `envSecret` ile geçirilebilir, ama ikisi birden değil.
Bkz. [Notion](/tr/docs/notion/#connect-with-notion-oauth).

### Chart 3.0.0'a yükseltme

Uygulama 1.0.0 ile gelen chart 3.0.0 bir major sürümdür, çünkü şema artık eskiden kabul ettiği bir key'i reddeder:
0.6.0'dan beri kullanımdan kaldırılmış olan ve uygulamanın `CONFLUENCE_ALLOWED_HOSTS` değişkeniyle birlikte kaldırılan
`config.confluenceAllowedHosts`. `helm upgrade` eski key'de, hiçbir şey değişmeden durur. Values'ınız onu ayarlıyorsa
host'larını `config.sourceAllowedHosts`'a taşıyın — Confluence, S3 ve GitHub Enterprise Server kaynakları onu paylaşır —
ve eski key'i silin; yükseltme notlarının tamamı chart'ın kendi README'sindedir. Chart değerlerini yöneten uyumluluk
politikası [`docs/compatibility.md`](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md)
sayfasındadır.

## Yayımlama

Chart release'leri deponun kendi release iş akışını izler ve `gh-pages` üzerinde barındırılan bir Helm
deposuna yayımlanır, uygulamanın kendi sürümünden bağımsız olarak sürümlenir — tam release ve
sürümleme kurallarını depodaki chart'ın kendi `charts/contextator/README.md`'sinde bulabilirsiniz.
