Geliştirme dokümantasyonu

Bu belgeler Keydra'nın geliştirilmekte olan hâlini anlatır; yayımlanmış bir sürüm değildir. Anlatılanlar bir sürüm çıkana kadar değişebilir.

Keydra’yı dağıtma

Keydra'nın gereksinimleri, yayımlanan üç imajdan hangisini seçeceğiniz ve kurulumu dışarı açmadan önce yapılandırmanız gerekenler.

Gereksinimler#

Keydra’nın çalışması için gerekenler
Bileşen	Gereksinim
Java	Kaynaktan derleme için 21. Yayımlanan imaj kendi çalışma zamanıyla gelir.
PostgreSQL	Zorunlu ve alternatifi yok. Keydra kendi verisini burada tutar; uygulama uçtan uca bloklamayan bir yapıdadır ve reaktif bir PostgreSQL sürücüsü kullanır.
Kapsayıcı motoru	İmajı çalıştırmak için Podman ya da Docker. Depo Podman ile derlenir; manifestleri Compose dosyası değil, Kubernetes Pod manifestidir.
Bir hedef	Keydra’nın çalıştığı yerden erişilebilen en az bir sunucu. Redis, Valkey ya da uyumlu bir türev, bir Aerospike veya bir TiKV.
Keydra’nın deposu için Redis	İsteğe bağlı. Yalnızca aynı veritabanına birden fazla örnek bağlanacaksa gerekir. Bu depo hedeflerinizden biri olmamalıdır.
ClickHouse	İsteğe bağlı. Yalnızca ölçüm kayıtlarının yeniden başlatmadan sonra da durması gerekiyorsa.
SMTP aktarıcısı	İsteğe bağlı. Yalnızca davet ve parola sıfırlama bağlantıları e-postayla gidecekse.

Node ve derleme araçları

Node 24.19.0 ve yarn yalnızca ön ucu kaynaktan derlerken gerekir. Yayımlanan imajı çalıştıran bir kurulumda ikisine de ihtiyaç yoktur.

Yayımlanan imajlar#

Keydra, quay.io/keydrahq adresinde üç imaj olarak yayımlanır. Hangisini seçeceğiniz, arayüzü Keydra’nın mı yoksa başka bir sunucunun mu sunacağına bağlıdır.

İmaj İçeriği

İmaj	İçeriği
`quay.io/keydrahq/keydra`	Arayüz, API’nin statik kaynakları içine gömülüdür; tek kapsayıcı ikisini birden sunar. Olağan kurulum budur ve depodaki manifestler de bu imajı kullanır.
`quay.io/keydrahq/keydra-backend`	Yalnızca API. Arayüzü ayrı sunan kurulumlar içindir: bir CDN’den, mevcut bir web sunucusundan ya da kendi pod’undan.
`quay.io/keydrahq/keydra-ui`	Arayüz ve ihtiyaç duyduğu vekil sunucu. İmaj nginx taşır: statik dosyaları sunar, `/api/v1` ve `/graphql` isteklerini — üzerlerindeki WebSocket yükseltmeleriyle birlikte — `KEYDRA_BACKEND` neyi gösteriyorsa oraya iletir. Yani ayrık kurulumda ikisinin önüne ayrı bir ters vekil sunucu koymanız gerekmez; aradığınız vekil sunucu budur.

quay.io/keydrahq/keydra

Arayüz, API’nin statik kaynakları içine gömülüdür; tek kapsayıcı ikisini birden sunar. Olağan kurulum budur ve depodaki manifestler de bu imajı kullanır.

quay.io/keydrahq/keydra-backend

Yalnızca API. Arayüzü ayrı sunan kurulumlar içindir: bir CDN’den, mevcut bir web sunucusundan ya da kendi pod’undan.

quay.io/keydrahq/keydra-ui

Arayüz ve ihtiyaç duyduğu vekil sunucu. İmaj nginx taşır: statik dosyaları sunar, /api/v1 ve /graphql isteklerini — üzerlerindeki WebSocket yükseltmeleriyle birlikte — KEYDRA_BACKEND neyi gösteriyorsa oraya iletir. Yani ayrık kurulumda ikisinin önüne ayrı bir ters vekil sunucu koymanız gerekmez; aradığınız vekil sunucu budur.

Arayüz ile API aynı kökende olmalıdır

Arayüz, /api/v1 ve /graphql adreslerini göreli yol olarak çağırır. Onu başka bir yerdeki API’ye yönlendiren bir ayar bilinçli olarak yoktur: statik bir pakete gömülen mutlak API adresi, çalışma zamanına ait bir bilgiyi derleme zamanında sabitlemek olur; üstelik çerezleri çapraz kökene taşır.

Bu yüzden arayüz ile API’nin tek bir adres üzerinden cevap vermesi gerekir. quay.io/keydrahq/keydra-ui tam olarak bu adres olmak için hazırlanmıştır: arayüzü / altında sunar, /api/v1 ve /graphql isteklerini — üzerlerindeki WebSocket yükseltmeleriyle birlikte — KEYDRA_BACKEND’e iletir. Oturum çerezi böylece birinci taraf çerezi olarak kalır ve `SameSite=Lax beklendiği gibi çalışır.

Elinizde bir vekil sunucu varsa onu bu imajın önüne koyabilirsiniz; ama ikisinin arasına koymayın: yönlendirme zaten yapılmış durumdadır.

İkisini ayrı çalıştırmak için bir nedeniniz yoksa quay.io/keydrahq/keydra imajını kullanın.

Etiketler

Buradaki örneklerde latest kullanılıyor. Kurulumlarda bunun yerine bir sürüm sabitleyin; aksi hâlde yeniden başlatma, kimsenin planlamadığı bir yükseltmeye dönüşebilir.

Keydra’yı dağıtma#

Ön koşullar

Podman ya da OCI imajı çalıştırabilen başka bir motor.
Keydra’nın erişebileceği bir PostgreSQL; ya da aşağıdaki manifestteki kapsayıcı.

Prosedür

Sırları oluşturun. KEYDRA_SECRET_KEY, saklanan bütün kimlik bilgilerini şifreler:
bash
```
printf 'keydra' | podman secret create keydra-db-password -
openssl rand -base64 32 | podman secret create keydra-secret-key -
```
Önemli:Önemli

`KEYDRA_SECRET_KEY’i kaybetmek, saklanan bütün kimlik bilgilerini kaybetmek demektir; paylaşmak ise hepsini paylaşmak. Diğer sırlarınızı nerede tutuyorsanız orada tutun, depoda değil.

İmajı çekin:

bash

podman pull quay.io/keydrahq/keydra:latest

PostgreSQL ile birlikte çalıştırın:
bash
```
podman play kube deploy/keydra-prod.yaml
```
Manifest yerel olarak derlenmiş bir imajı gösterir. Yayımlanan imajı kullanmak için satırı değiştirin:
yaml
```
    - name: keydra
      image: quay.io/keydrahq/keydra:latest
```

Doğrulama

bash

curl -s http://localhost:8181/q/health/ready

Ardından http://localhost:8181 adresini açın.

Sonraki adımlar

Helm ile Kubernetes’e kurulum#

Chart iki biçimi de kurar: API ile onu çağıran arayüzü tek imajda sunan biçimi ya da ikisini ayrı çalıştıran biçimi. Başlatamayacağı bir kurulumu kurmaz; aşağıdaki adımlardan ikisi, yoksa CrashLoopBackOff olarak karşınıza çıkacak reddedişlerdir.

Ön koşullar

Bir Kubernetes kümesi ve Helm 3.
Kümenin erişebildiği bir PostgreSQL. Chart bunu kurmaz: orada her bağlantı profili, hesap, yetki ve denetim kaydı durur; bir uygulamanın chart’ına paketlenmiş veritabanı ise kimsenin yedeklemediği ve yükseltmenin yerine yenisini koyduğu bir pod’da çalışan veritabanıdır.

Yordam

Secret’ı oluşturun. Chart anahtarı üretmez ve bu bilinçlidir: üretilmiş bir anahtar bir sonraki yükseltmede yeniden üretilir, örnek de kayıtlı tek bir kimlik bilgisini okuyamadan açılır — üstelik bunu bir başlatma hatası olarak değil, hedef hedef bildirir.
bash
```
kubectl create secret generic keydra \
  --from-literal=secret-key="$(openssl rand -base64 32)" \
  --from-literal=database-password='...'
```
Önemli:Önemli

O anahtarı kaybetmek, kayıtlı bütün kimlik bilgilerini kaybetmek demektir. Paylaşmak da onları paylaşmak demektir.
Chart deposunu ekleyin:
bash
```
helm repo add keydra https://keydrahq.github.io/keydra-helm
helm repo update
```
Aynı paket, her şeyi tek bir sicilden çeken kümeler için OCI artefaktı olarak da yayımlanır: helm install keydra oci://quay.io/keydrahq/charts/keydra --version <sürüm>.

Kurun:

bash

helm install keydra keydra/keydra \
  --set database.url=postgresql://postgres:5432/keydra \
  --set existingSecret.name=keydra

Bir vekil sunucunun arkasında olduğunu söyleyin; Ingress altında her zaman öyledir:
bash
```
helm upgrade keydra keydra/keydra --reuse-values \
  --set proxy.enabled=true \
  --set proxy.trusted=10.0.0.0/8 \
  --set publicUrl=https://keydra.example.com \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=keydra.example.com
```
Söylenmezse Keydra her oturum açmayı ingress denetleyicisinden geliyormuş gibi görür: bir oturum açmayı öncekilerle karşılaştıran denetimler herkesi herkesle karşılaştırmaya başlar ve deneme sınırı bütün kümeyi tek bir ağ sayar. Vekil sunucuları adlandırmak seçimlik değildir; anahtar açıkken kimse adlandırılmamışsa her istemci her adresi iddia edebilir ve chart kurulumu üretmeyi reddeder.

Doğrulama

helm test keydra, sürüme yalnızca çalışan bir kurulumun cevaplayabileceğini soran bir pod başlatır: hazır olduğunu, arayüzün sunulduğunu ve insanlara verilen adreste /q/metrics adresinin 404 döndüğünü.

Henüz hiç hesap yoktur. İlk yöneticiyi bir kez oluşturun; o uç, bir yönetici olduğu anda çalışmayı bırakır:

bash

curl -fsS -X POST https://keydra.example.com/api/v1/auth/setup \
  -H 'Content-Type: application/json' \
  -d '{"username":"siz","password":"..."}'

İki biçim

mode: standalone varsayılandır ve tek imajdır. mode: split, quay.io/keydrahq/keydra-backend ile quay.io/keydrahq/keydra-ui imajlarını iki Service arkasında iki Deployment olarak kurar. İkincisi, ikisi farklı ölçekleniyorsa — tek bir statik dosya kümesinin arkasında birden çok API kopyası — ya da arayüz API’nin bulunmadığı bir yere aitse anlamlıdır.

bash

helm install keydra keydra/keydra --set mode=split ...

İmajları siz adlandırmazsınız; chart’ı biçimden seçer. Çünkü bir biçim için doğru olan varsayılan diğeri için yanlıştır ve hepsi bir arada imajın sessizce ayrık bir kuruluma çekilmesi, çalışıyormuş gibi görünürdü.

Operator ile Kubernetes’e kurulum#

Operator, chart’ın oluşturduğu nesnelerin aynısını oluşturur; farkı, bunları Helm’in tuttuğu bir sürümden değil, kümenin sahip olduğu bir kaynaktan üretmesidir. Keydra kurmak söz konusu olduğunda ikisi aynı işi yapar; operator’ü, kurulumun sonrasında da kümece öyle tutulmasını istediğinizde ya da bir hedefin forma yazılan bir şey değil bir kaynak olmasını istediğinizde seçersiniz.

Ön koşullar

Bir Kubernetes kümesi ya da bir OpenShift.
Kümenin erişebildiği bir PostgreSQL. Operator bunu kurmaz, chart’ın kurmadığı gerekçeyle: orada her bağlantı profili, hesap, yetki ve denetim kaydı durur; bir uygulamanın yanına kendi getirdiği veritabanı ise kimsenin yedeklemediği veritabanıdır.

Yordam

Operator’ü kurun. OpenShift’te OperatorHub içinde Keydra girdisini bulup oradan kurun; bu adımın altındaki hiçbir şeye gerek kalmaz. Diğer kümelerde:
bash
```
kubectl create namespace keydra-operator
kubectl apply -f https://github.com/keydrahq/keydra-operator/releases/latest/download/crds.yaml
kubectl apply -f https://github.com/keydrahq/keydra-operator/releases/latest/download/operator.yaml
```
Tek dosya değil iki dosya, çünkü ikisini farklı zamanlarda farklı kişiler uygular: özel kaynak tanımları küme genelindedir ve bir kez girer, yönetici ise birinin yükselttiği bir Deployment’tır.
Kurulumun yaşayacağı ad alanında Secret’ı oluşturun. Operator bunu yazmaz ve chart’tan ayrıldığı bu nokta bilinçlidir: özel kaynağa konan bir anahtarı, o ad alanında get keydra diyebilen herkes okur — Secret okuyabilenlerden daha geniş ve en az düşünülmüş kitle.
bash
```
kubectl create secret generic keydra \
  --from-literal=secret-key="$(openssl rand -base64 32)" \
  --from-literal=database-password='...'
```
Önemli:Önemli

O anahtarı kaybetmek, kayıtlı bütün kimlik bilgilerini kaybetmek demektir. Paylaşmak da onları paylaşmak demektir.

Kurulumu tarif edip uygulayın:

yaml

apiVersion: keydra.io/v1alpha1
kind: Keydra
metadata:
  name: keydra
spec:
  database:
    url: postgresql://keydra-db:5432/keydra
  secret:
    name: keydra
  route:                      # <1>
    enabled: true
  proxy:                      # <2>
    enabled: true
    trusted: 10.0.0.0/8

1 OpenShift’te. Diğer kümelerde ingress.enabled ile ingress.hosts kullanın ve publicUrl alanına tarayıcının ulaşacağı adresi yazın: yönlendirme adresi kimlik sağlayıcıyla önceden anlaşılır ve harfi harfine tutmak zorundadır.

2 Ingress ya da Route’un ardında her zaman önde bir şey vardır. Kendisine bir şey söylenmediğinde Keydra her oturum açmayı ingress denetleyicisinden geliyormuş gibi görür: bir oturum açmayı öncekilerle karşılaştıran denetimler böylece herkesi herkesle karşılaştırır, deneme sınırı da bütün kümeyi tek ağ sayar. Vekilleri adlandırmak isteğe bağlı değildir — API sunucusu, anahtarı açıp kimseyi adlandırmayan bir kaynağı reddeder.

Doğrulama

Sonucu kaynağın kendisi söyler, öğrenmek için başka bir şey okumak gerekmez:
bash
```
$ kubectl get keydra
NAME     READY   REPLICAS   URL                                AGE
keydra   True    1          https://keydra.apps.example.com    2m
```
Bir şey ters gittiği sürece READY değeri False olur ve gerekçesi kubectl describe keydra keydra çıktısında durur. İlk beklenmesi gereken, Secret’ta eksik olan anahtarı adlandıran bir Degraded koşuludur.

Henüz hiç hesap yoktur. İlk yöneticiyi, bir tane olduğu anda çalışmayı bırakan uç nokta üzerinden bir kez oluşturun:

bash

curl -fsS -X POST https://keydra.apps.example.com/api/v1/auth/setup \
  -H 'Content-Type: application/json' \
  -d '{"username":"you","password":"..."}'

Hedefi kaynak olarak beyan etmek

Chart’ın yapamadığı kısım budur. Kümede başka bir şeyin oluşturduğu bir sunucu, Keydra’ya onu oluşturan manifest’in kendisiyle devredilir ve aynı silmeyle geri alınır: bir kaynak öyle diyor diye var olan profil, kaynak gittiğinde var olmayı da bırakır.

Bunun için operator’ün oturum açacağı bir hesap gerekir, çünkü Keydra’da makine çağıranı diye bir kavram yoktur: operator tarayıcının açtığı gibi oturum açar ve oturumu saklar. Ona bir kişinin hesabını değil kendi hesabını verin ki denetim kaydı hangi değişikliğin birinin yazması, hangisinin bir kaynağın uygulanması olduğunu söyleyebilsin. Bağlantı profili yazmak yöneticiye ait bir izin olduğundan, hesabın o rolü taşıması gerekir.

bash

kubectl create secret generic keydra-api \
  --from-literal=api-username=operator \
  --from-literal=api-password='...'

Kurulumda adlandırın ve hedefleri beyan edin:

yaml

apiVersion: keydra.io/v1alpha1
kind: Keydra
metadata:
  name: keydra
spec:
  apiAccount:
    secretName: keydra-api
  # …
---
apiVersion: keydra.io/v1alpha1
kind: KeydraConnection
metadata:
  name: orders-cache
spec:
  keydraRef: keydra
  host: orders-redis
  port: 6379
  guarded: true
  passwordSecret:
    name: orders-redis
    key: password

keydraRef aynı ad alanındaki bir kurulumu adlandırır; ad alanları arası referans bilinçli olarak mümkün değildir, çünkü kendi ad alanında kaynak oluşturabilen herkesin başkasının konsoluna hedef eklemesi anlamına gelirdi.

Not

Operator, kendi oluşturmadığı bir profili sahiplenmez. O adda bir hedef Keydra içinde zaten varsa — biri arayüzden eklemişse — kaynak reddedilir; sahiplenip sonra kaynak gittiğinde silmek yerine.

Mevcut bir profili kaynağa çevirmek bu yüzden düzenleme değil bilinçli bir karardır ve bir bedeli vardır: silip yeniden oluşturmak profilin kimliğini değiştirir, kapsamı o bağlantı olan yetkiler de sunucu grubu üyelikleri de o kimliğe bağlıdır. O hedefi görebilen kişiler görememeye başlar.

Chart’tan operator’e geçmek

İkisi aynı adlarla ve aynı etiketlerle aynı nesneleri üretir; geçişi silip yeniden kurmak değil sahiplenmek yapan da budur. Adımlar operator’ün kendi belgelerinde, çünkü önemli olan kısımlar Keydra ile değil Helm ile ilgilidir: sürüme nesnelerini geride bırakması söylenmeli ve chart’ın ürettiği Secret, operator’e gösterilebilecek bir Secret’a kopyalanmalıdır.

Keydra’yı dışarı açmadan önce kimlik doğrulamayı yapılandırma#

Güvenlik denetimi varsayılan olarak açıktır. deploy/keydra-prod.yaml bunu kapalı getirir; böylece manifest, yalnızca sizin erişebildiğiniz bir makinede hiçbir ayar yapmadan çalışır. Bu durumda arayüz her sayfada "güvenlik kapalı" uyarısı gösterir: güvenli görünen ama açık olan bir kurulum, ifşa olmanın en yaygın yoludur.

Prosedür

Kullanıcıların nasıl giriş yapacağına karar verin. Her biri tek başına yeterlidir:
- Yerel hesaplar. Yapılandırma gerektirmez. İlk çalıştırmada yöneticiyi oluşturun, geri kalan kullanıcıları davet edin.
- Kimlik sağlayıcı. Ortam değişkeniyle değil, Keydra çalışırken arayüzden tanımlanır — bkz. Kimlik sağlayıcıları.
Manifestten KEYDRA_SECURITY_ENABLED satırını kaldırarak ya da true yaparak denetimi açın.
Keydra’ya genel adresini bildirin; sağlayıcı yönlendirmesi bu adrese döner:
properties
```
KEYDRA_PUBLIC_URL=https://keydra.example.com
```
Keydra ters vekil sunucu arkasındaysa bunu belirtin ve istemci adresi konusunda hangi vekillere güvenileceğini yazın:
properties
```
KEYDRA_BEHIND_PROXY=true
KEYDRA_TRUSTED_PROXIES=10.0.0.0/8
```
HTTPS üzerinden sunun. Oturum çerezi üretimde Secure işaretlidir; düz HTTP üzerinden giden bir oturum çerezi ağda açıkta gider.

Doğrulama

Keydra’yı gizli pencerede açın. Arayüz yerine giriş formu ya da sağlayıcı düğmesi görünmeli, hiçbir sayfada "güvenlik kapalı" uyarısı bulunmamalıdır.

Uyarı

KEYDRA_SECURITY_ENABLED=false ayarı, adrese erişebilen herkesi bütün izinlerle içeri alır. Bunu yalnızca gösterim için ya da yalnızca sizin erişebildiğiniz bir makinede kullanın; dışarı açık hiçbir kurulumda kullanmayın.

Bir kurulumun ayarlayabileceği her şey#

Aşağıda Keydra’nın okuduğu bütün ortam değişkenleri, ilgili oldukları karara göre gruplanmış hâlde ve paketlenmiş çalışma zamanının başlangıç değerleriyle birlikte listelenir. Varsayılanı ve değeri boş olan ayarlar kapalıdır ya da tanımsızdır.

İki grup diğerlerinden önce okunmalıdır. Zorunlu ayarlar, çünkü Keydra onlar olmadan başlamaz. Güvenlik denetimi, çerezler ve oturumlar, çünkü varsayılanları güvenlidir ve birini kapatmak ince ayar değil karardır.

Zorunlu ayarlar
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_DB_URL`	`postgresql://localhost:5432/keydra`	Reaktif PostgreSQL adresi; `postgresql://sunucu:port/veritabani` biçiminde. JDBC öneki yok — uygulama bloklamayan bir yapıdadır ve reaktif bir sürücü kullanır.
`KEYDRA_DB_USERNAME`	`keydra`	Veritabanı kullanıcısı.
`KEYDRA_DB_PASSWORD`		Veritabanı parolası. Bir sır tutar. Günlüğe yazılmaz, API tarafından döndürülmez.
`KEYDRA_SECRET_KEY`		Saklanan her kimlik bilgisini şifreleyen anahtar — hedef parolaları, tünel anahtarları, sağlayıcı sırları, hedef kimlik bilgileri. 32 rastgele bayt, base64. Varsayılanı yoktur: o olmadan saklanan hiçbir şey okunamaz. Bir sır tutar. Günlüğe yazılmaz, API tarafından döndürülmez.

Adres ve ters vekil sunucu
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_PUBLIC_URL`		Tarayıcının gördüğü biçimiyle Keydra’nın adresi. Sağlayıcı yönlendirmeleri ve giden postadaki bağlantılar bu adresten üretilir; sürecin bağlandığı adres değil, kullanıcıların gerçekten yazdığı adres olmalıdır.
`KEYDRA_BEHIND_PROXY`	`false`	`X-Forwarded-*` başlıklarına inanılıp inanılmayacağı. Yalnızca bir ters vekil sunucunun arkasındayken açın: önünde hiçbir şey yokken onlara güvenen bir kurulum, çağıranın kendi adresini kendisinin bildirdiği bir kurulumdur.
`KEYDRA_TRUSTED_PROXIES`		O başlıkları hangi vekillerin ayarlayabileceği; adres ya da CIDR aralığı olarak. Bu olmadan onlara inanmak, herkese inanmak demektir.
`KEYDRA_CSP`	`default-src 'self'; script-src 'self'; s…`	Tarayıcıya uygulatılan içerik güvenliği politikası. Sabit metin yerine bir özellik olması, varlıkları başka yerden sunan bir kurulumun başlığı kapatmak yerine ihtiyaç duyduğu tek yönergeyi genişletebilmesi içindir. Birini genişletmek hepsini yeniden yazmak demektir; asıl nokta da budur: politika ya bütündür ya hiçtir.
`KEYDRA_MAX_BODY_SIZE`	`25M`	Kabul edilen en büyük istek gövdesi. Bir anahtar içe aktarımını ve bir yedek geri yüklemesini sınırlayan budur.
`KEYDRA_ACCESS_LOG`	`true`	Her isteğin günlüğe yazılıp yazılmayacağı. Bir istek satırı bir yol taşır ve buradaki bir yol bir anahtarı adlandırabilir.

Güvenlik denetimi, çerezler ve oturumlar
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_SECURITY_ENABLED`	`true`	Keydra’nın kimin neyi yapabileceğini uygulayıp uygulamadığı. Kapatmak, adrese erişebilen herkesi bütün izinlerle içeri alır ve her sayfa bunu söyler — güvenli görünen açık bir örnek, insanın ifşa olma biçimidir.
`KEYDRA_COOKIE_SECURE`	`true`	Oturum çerezinin Secure olarak işaretlenip işaretlenmediği. Üretimde açık: düz HTTP üzerinden giden bir oturum çerezi, hat üzerindeki bir oturum çerezidir.
`KEYDRA_SOCKET_ORIGIN_CHECK`	`true`	Bir WebSocket el sıkışmasının, Keydra’nın tanıdığı bir kaynaktan gelmesinin zorunlu olup olmadığı. Bir soket, bir fetch gibi aynı köken politikasının kapsamında değildir; bu, onun yerine geçen kontroldür.
`KEYDRA_SOCKET_ORIGINS`		Genel adresin dışında, bir WebSocket’in açılabileceği kaynaklar. Arayüzün başka bir yerden sunulduğu kurulumlar için.
`KEYDRA_SIGN_IN_THROTTLE`	`true`	Art arda gelen giriş hatalarının sayılıp reddedilip reddedilmediği. Sınır, parola özetinden önce yanıtlanır; çünkü Argon2id bilerek yavaştır ve sınırsız deneme, parola tahmin etmenin yanında sunucunun belleğini harcamanın da yoludur.
`KEYDRA_GEOIP_DATABASE`		Varsa bir GeoIP veritabanı. Bir girişin öncekilerle karşılaştırılırken nereden geldiğini söylemek için kullanılır.
`KEYDRA_SESSION_SWEEP_INTERVAL`	`1h`	Süresi dolmuş oturum satırlarının ne sıklıkta silindiği. Kimsenin budamadığı bir oturum tablosu, uygulama çalıştığı sürece büyüyen bir tablodur.
`KEYDRA_INVITATION_VALID_FOR`	`P7D`	Davet ve parola sıfırlama bağlantılarının geçerlilik süresi. Süresiz bir bağlantı, adım sayısı fazla bir paroladır.
`KEYDRA_PREVIOUS_SECRET_KEYS`		Hâlâ okunabilen ama artık yazma yapmayan anahtarlar. Anahtar değişimini kesintiden ayıran özellik budur: yeni anahtar yazar, eskiler kendi yazdıklarını çözmeyi sürdürür ve yeniden şifreleme bütün kayıtları kurulum ayaktayken taşır. Bir sır tutar. Günlüğe yazılmaz, API tarafından döndürülmez.

Dışarı çıkan bağlantı kısıtlamaları
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_EGRESS_ALLOW_PRIVATE`	`true`	Birinin yazdığı bir adresin özel bir ağda olup olamayacağı. Genelde evet: iç bir sohbet aktarıcısına giden webhook ve aynı alt ağdaki S3 uyumlu depo olağan durumlardır. Link-local her hâlükârda reddedilir ve ayarı yoktur.
`KEYDRA_EGRESS_ALLOW_LOOPBACK`	`false`	Birinin yazdığı bir adresin Keydra’nın çalıştığı makineyi gösterip gösteremeyeceği. Geliştirme dışında kapalı.
`KEYDRA_EGRESS_ALLOWED_HOSTS`		Yukarıdaki kurallardan bağımsız olarak izin verilen sunucular. Bir kurulumun erişmek zorunda olduğu tek bir iç adres için kaçış kapağı.

Açılışta tanımlanan OIDC sağlayıcı
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_OIDC_URL`		Açılışta yapılandırılan tek bir OIDC sağlayıcının yayıncısı. Desteklenen yol arayüzden eklenen sağlayıcılardır ve bu dördüne ihtiyaç duymaz; bu, henüz giriş yapıp sağlayıcı ekleyecek kimse yokken bir sağlayıcı tanımlayan kurulumlar içindir.
`KEYDRA_OIDC_CLIENT_ID`	`keydra`	O sağlayıcıdaki istemci kimliği.
`KEYDRA_OIDC_SECRET`		O sağlayıcıdaki istemci sırrı. Bir sır tutar. Günlüğe yazılmaz, API tarafından döndürülmez.
`KEYDRA_OIDC_ROLES_CLAIM`	`realm_access/roles`	Rollerin belirteç içindeki yeri; bir yol olarak. `viewer`, `operator` ya da `admin` talebi, o rolün örnek kapsamındaki bir yetkisine dönüşür.

Çok örnekli kurulum
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_INSTANCE_ID`		Örneğin kendine verdiği ad. Hakkında sayfasında, her günlük satırında ve ürettiği her ölçümde görünür. Ayarlanmadığında kendiliğinden üretilir.
`KEYDRA_STORE_URL`	`redis://localhost:6481`	Ortak önbellek ve örnekler arası bildirim yayını için Keydra’nın kendi Redis adresi. Hedeflerinizden biri olmamalıdır: birinin göz attığı bir sunucuda duran önbellek, birinin toplu silme yaparken boşalttığı önbellek olur. Tek örnekli kurulumlarda boş bırakın.
`KEYDRA_LEASE_SECONDS`	`15`	Lider kirasının yenilenmeden önce ne kadar tutulduğu. Yenilemeyi bırakan örnek, kirayı sonraki isteyene kaptırır; dolayısıyla bu aynı zamanda bir çökmenin işi ne kadar kesintiye uğratabileceğidir.
`KEYDRA_RECONCILE_SECONDS`	`30`	Örneğin, lider işlerini üstlenip üstlenmemesi gerektiğini hangi sıklıkta denetlediği. Kirayı kimse tutmuyorsa alır; kaybettiyse zamanlanmış işleri bırakır.

Posta sunucusu
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_MAIL_HOST`		Giden postanın geçtiği SMTP aktarıcısı — davetler, parola sıfırlamaları ve e-posta uyarı gönderimleri.
`KEYDRA_MAIL_PORT`	`587`	Aktarıcı portu.
`KEYDRA_MAIL_TLS`	`true`	Aktarıcıya TLS ile bağlanılıp bağlanılmayacağı.
`KEYDRA_MAIL_USERNAME`		Keydra’nın aktarıcıya kimliğini doğrularken kullandığı hesap.
`KEYDRA_MAIL_API_KEY`		Aktarıcı parolası ya da API anahtarı. Bir sır tutar. Günlüğe yazılmaz, API tarafından döndürülmez.
`KEYDRA_MAIL_FROM`		Giden postanın gönderildiği adres. Çoğu aktarıcı bu olmadan bir mesajı reddeder.

Yedek ve ölçüm deposu
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_BACKUP_DIR`	`backups`	Yerel bir yedek hedefinin içine yazdığı dizin. Hedefler dizini buna göreli olarak adlandırır; böylece hiçbir hedef makinedeki rastgele bir yola yönlendirilemez.
`KEYDRA_CLICKHOUSE_ENABLED`	`false`	Okumaların ayrıca yeniden başlatmaya dayanan bir yere yazılıp yazılmayacağı. Varsayılan olarak kapalı: bir kuruluma ikinci bir servis eklemek gerçek bir maliyettir ve bunu istemeyen bir örneğe gerekli olduğu söylenmemelidir.
`KEYDRA_CLICKHOUSE_URL`	`http://localhost:8123`	ClickHouse’un HTTP arabirimi. JDBC sürücüsü yerine HTTP, çünkü sürücü bloklayıcıdır — bu uygulama ise değildir.
`KEYDRA_CLICKHOUSE_USER`	`default`	ClickHouse kullanıcısı.
`KEYDRA_CLICKHOUSE_PASSWORD`		ClickHouse parolası. Bir sır tutar. Günlüğe yazılmaz, API tarafından döndürülmez.

Günlükler ve izler
Ortam değişkeni	Varsayılan	Açıklama
`KEYDRA_OTLP_ENDPOINT`		OpenTelemetry izlerinin aktarılacağı yer. İzlemeyi açan şey bunun ayarlanmasıdır; ikinci bir bayrak yoktur.
`KEYDRA_JSON_LOGS`	`true`	İnsan okuyabilir biçim yerine konsolda JSON; böylece bir günlük toplayıcı, insan için yazılmış bir düzeni ayrıştırmak zorunda kalmaz.

Not

Aynı ayarlar, her birinin ayarladığı özellikle birlikte alfabetik olarak Yapılandırma referansında listelenir. Bu sayfa onları verdiğiniz karara göre gruplar; o sayfa "bu nedir" sorusunu yanıtlar.

Eksiksiz bir örnek#

Hiçbir ayar tahmin edilmek zorunda kalmasın diye bütün gruplar bir arada verilmiştir. Çoğu kurulum bunun küçük bir bölümünü kullanır: Zorunlu ayarlar altındaki dört değişken, bir adres ve gerçekten çalıştırdıkları bileşenler.

yaml

env:
  # --- Zorunlu --------------------------------------------------------------
  - name: KEYDRA_DB_URL
    value: postgresql://db.internal:5432/keydra
  - name: KEYDRA_DB_USERNAME
    value: keydra
  - name: KEYDRA_DB_PASSWORD
    valueFrom: { secretKeyRef: { name: keydra-db-password, key: keydra-db-password } }
  # 32 rastgele bayt, base64. Kaybetmek, saklanan bütün kimlik bilgilerini kaybetmektir.
  - name: KEYDRA_SECRET_KEY
    valueFrom: { secretKeyRef: { name: keydra-secret-key, key: keydra-secret-key } }

  # --- Adres ve ters vekil sunucu -------------------------------------------
  - name: KEYDRA_PUBLIC_URL
    value: https://keydra.example.com
  - name: KEYDRA_BEHIND_PROXY
    value: "true"
  - name: KEYDRA_TRUSTED_PROXIES
    value: 10.0.0.0/8
  # Yalnızca bir anahtar içe aktarımı ya da bir yedek geri yüklemesi bundan büyükse artırın.
  - name: KEYDRA_MAX_BODY_SIZE
    value: 25M

  # --- Güvenlik denetimi ----------------------------------------------------
  # Varsayılan olarak açık. Kapalıysa adrese erişebilen herkesi içeri alır.
  - name: KEYDRA_SECURITY_ENABLED
    value: "true"
  - name: KEYDRA_COOKIE_SECURE
    value: "true"

  # --- Birden fazla örnek ---------------------------------------------------
  - name: KEYDRA_INSTANCE_ID
    value: keydra-a
  # Keydra'nın kendi Redis'i. Asla hedeflerinizden biri değil.
  - name: KEYDRA_STORE_URL
    value: redis://store.internal:6379

  # --- Giden posta ----------------------------------------------------------
  - name: KEYDRA_MAIL_HOST
    value: smtp.example.com
  - name: KEYDRA_MAIL_PORT
    value: "587"
  - name: KEYDRA_MAIL_TLS
    value: "true"
  - name: KEYDRA_MAIL_USERNAME
    value: keydra
  - name: KEYDRA_MAIL_API_KEY
    valueFrom: { secretKeyRef: { name: keydra-mail-key, key: keydra-mail-key } }
  - name: KEYDRA_MAIL_FROM
    value: keydra@example.com

  # --- Ölçüm deposu ---------------------------------------------------------
  - name: KEYDRA_CLICKHOUSE_ENABLED
    value: "true"
  - name: KEYDRA_CLICKHOUSE_URL
    value: http://clickhouse.internal:8123
  - name: KEYDRA_CLICKHOUSE_USER
    value: keydra
  - name: KEYDRA_CLICKHOUSE_PASSWORD
    valueFrom: { secretKeyRef: { name: keydra-clickhouse, key: keydra-clickhouse } }

  # --- Gözlemlenebilirlik ---------------------------------------------------
  - name: KEYDRA_OTLP_ENDPOINT
    value: http://otel-collector.internal:4317
  - name: KEYDRA_JSON_LOGS
    value: "true"

Her sır bir sırdan gelir

Yukarıdaki dört valueFrom girdisi süs değildir. Manifeste düz yazılan bir parola; depoya, dağıtım geçmişine ve manifesti ekrana basan her araca da yazılmış olur. Özellikle KEYDRA_SECRET_KEY, Keydra’nın tuttuğu bütün kimlik bilgilerini açan tek anahtardır.

Bu sayfanın listelemediği ayarlar#

Keydra bir Quarkus uygulamasıdır. Bu yüzden KEYDRA_ önekli karşılığı olmayan Quarkus ayarları da kullanılabilir. Dönüşüm kuralı Quarkus’a aittir: özellik adını büyük harfe çevirin, alfanümerik olmayan karakterleri alt çizgiyle değiştirin. Örneğin quarkus.http.port için QUARKUS_HTTP_PORT yazılır.

Adında olağandışı karakterler bulunan bir özellik için buna güvenmeden önce eşlemeyi Quarkus sürümünüze karşı doğrulayın.

Portlar ve uç noktalar#

Keydra’nın dinlediği adresler
Adres	Port	Açıklama
`/`	8181	Arayüz ve altındaki her şey. Tek port hem API’yi hem onu çağıran sayfayı sunar.
`/api/v1`	8181	REST API.
`/graphql`	8181	GraphQL yüzeyi. `GET` reddedilir. İç gözlem ve şema belgesi geliştirmede açık, üretimde kapalıdır.
`/q/health`, `/q/health/live`, `/q/health/ready`	8181	Sağlık yoklamaları. Manifestler hazır olma için `ready`, canlılık için `live` kullanır.
`/q/metrics`	8181	Prometheus ölçümleri.
`/api/openapi`	8181	OpenAPI belgesi.
`/q/swagger-ui`	8181	API’yi etkileşimli olarak gezme. Yalnızca geliştirme profilinde açıktır.

Geliştirme portları
Bileşen	Ana makine portu	Notlar
Arka uç	8181	`./mvnw quarkus:dev`
Ön uç geliştirme sunucusu	9000	`yarn dev`; `/api` ve `/graphql` arka uca yönlendirilir
Redis hedefi	6479	`deploy/keydra-dev.yaml` dosyasından
Valkey hedefi	6480	`deploy/keydra-dev.yaml` dosyasından
Keydra’nın deposu için Redis	6481	Hedeflerden biri değildir
PostgreSQL	5442	Keydra’nın kendi veritabanı
ClickHouse	8223	İsteğe bağlı ölçüm deposu

Ana makine portları bilinçli olarak varsayılanlardan kaydırılmıştır: makinede zaten bir Redis ya da PostgreSQL çalışıyorsa pod yine de açılır. Pod içinde bileşenler kendi standart portlarını kullanmayı sürdürür.

İmajı kaynaktan derleme#

Bu adım yalnızca Keydra’nın kendisini değiştiriyorsanız gerekir. Kurulumlarda yayımlanan imajları kullanın.

Ön koşullar

Keydra deposunun bir kopyası.
Podman.

Prosedür

bash

podman build -t localhost/keydra:dev -f Containerfile .

Depodaki Containerfile, tekil imajı üç aşamada üretir: ön uç Node ile derlenir, arka uç Maven ile derlenir — derlenen ön uç src/main/resources/META-INF/resources altına kopyalanır — ve son aşamada ikisinin de araçlarını taşımayan bir JRE imajı hazırlanır.

Doğrulama

bash

podman run --rm -p 8181:8181 \
  -e KEYDRA_DB_URL=postgresql://host.containers.internal:5442/keydra \
  -e KEYDRA_DB_USERNAME=keydra \
  -e KEYDRA_DB_PASSWORD=keydra \
  -e KEYDRA_SECRET_KEY="$(openssl rand -base64 32)" \
  localhost/keydra:dev

İmaj root olmayan kullanıcıyla çalışır

İmaj USER keydra tanımlar ve ana makinenin değil kapsayıcının bellek sınırını okur; böylece sınırlı bir kapsayıcı, kullanamayacağı bir belleğe göre yığın boyutu ayarlamaz. İmaj derlenirken test çalıştırılmaz: testler kapsayıcı gerektirir, derleme kapsayıcısında ise kapsayıcı yoktur. Testleri CI çalıştırır.

Bu sayfayı düzenle