Contextator
ENTR

İşletim

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:

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

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 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’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:

kubectl create secret generic contextator-secret-key \
  --from-literal=SECRET_KEY=$(openssl rand -hex 32)
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:

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):

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:

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:

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’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’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ığı:

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ğı). 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’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.

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ğı ve Git Deposu Kaynağı).

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ı). 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). 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.

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

Gezinmek için ok tuşları, açmak için Enter.