Yunus Emre Dere for Açıklab

Posted on Oct 24

RKE2'de Liman MYS & Keycloak Kurulumu: Longhorn ve Docker Hub Hata Çözümleri Dahil Tam Rehber

#kubernetes #keycloak #liman #docker

Kubernetes (K8s) dünyasında, Liman MYS gibi, envanter yönetiminden servis takibine kadar pek çok işlevi eklentilerle yürüten platformlar kullanırız. Bu farklı bileşenler ve yetkiler için merkezi bir kimlik doğrulama (Authentication) yönetimi hızla karmaşıklaşabilir. İşte bu noktada Keycloak devreye giriyor.

Bu rehberde, RKE2 (hafifletilmiş bir K8s dağıtımı) üzerinde Liman MYS ve Keycloak'u sıfırdan kuracak, bu iki güçlü sistemi birbirine bağlayacak (SSO) ve bu süreçte kesinlikle karşılaşacağınız en yaygın iki hatayı (Longhorn Pending ve Docker Hub TooManyRequests) adım adım çözeceğiz.

Faz 1: Gerekli Altyapı (Bizim "Sandbox" Ortamımız)

Başlamadan önce, RKE2 sunucumuzun uygulamaları barındırmaya hazır olması gerekir.

RKE2: Zaten kurulu olduğunu varsayıyoruz.
Helm: Kubernetes için bir paket yöneticisidir.
```
sudo snap install helm --classic
```
StorageClass (Longhorn): Liman ve Keycloak'un veritabanları gibi 'stateful' (durum bilgisi tutan) uygulamaları, verilerini kalıcı olarak saklamak zorundadır. Bunun için bir StorageClass (Depolama Sınıfı) sağlayıcısına ihtiyacımız var. Biz burada popüler ve RKE2 ile uyumlu olan Longhorn'u kullanacağız.

Aşağıdaki kod Longhorn'u ve onun 'longhorn' adlı StorageClass'ını kurar

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.9.0/deploy/longhorn.yaml

Longhorn'un longhorn-system namespace'inde kurulup pod'larının Running duruma gelmesini bekleyin.

Faz 2: Keycloak Kurulumu ve Erişimi

Artık altyapımız hazır olduğuna göre, kimlik sunucumuz olan Keycloak'u kuralım.

Adım 1: Keycloak'u Kurma

Topluluk tarafından sağlanan resmi YAML dosyası, hem Keycloak'u (bir StatefulSet olarak) hem de veritabanı için bir PostgreSQL'i (bir Deployment olarak) kurar.

kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/refs/heads/main/kubernetes/keycloak.yaml

Adım 2: Pod Kontrolü

Kurulumun tamamlandığını görmek için pod'ları kontrol edin.

kubectl get pods

NAME                       READY   STATUS    RESTARTS   AGE
keycloak-0                 1/1     Running   0          39h
keycloak-1                 1/1     Running   0          39h
postgres-65cf55dbf-nv5kx   1/1     Running   0          40h
redis-58f44d957b-6gzmw     1/1     Running   0          24h

Pod'ların Running durumuna geçmesi, Docker Hub limitlerine takılmazsanız birkaç dakika sürebilir. (Eğer ErrImagePull hatası alırsanız, Faz 4'teki çözüme atlayın).

Adım 3: Keycloak Ingress Yapılandırması

Keycloak'a tarayıcıdan temiz bir adresle (keycloak.test.local gibi) erişmek için bir Ingress oluşturacağız.

Önce, Keycloak servisinin hangi portu kullandığını öğrenelim:

kubectl get svc

NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
keycloak             ClusterIP   10.43.158.36   <none>        8080/TCP   40h
keycloak-discovery   ClusterIP   None           <none>        <none>     40h
kubernetes           ClusterIP   10.43.0.1      <none>        443/TCP    42h
postgres             ClusterIP   10.43.32.41    <none>        5432/TCP   40h

Gördüğümüz gibi, keycloak servisi 8080 portunu kullanıyor. Şimdi keycloak-ingress.yaml dosyamızı oluşturalım:

nano keycloak-ingress.yaml

Dosyanın içeriği:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: keycloak-ingress
spec:
  # RKE2'nin varsayılan nginx controller'ını kullan
  ingressClassName: nginx  
  rules:
  - host: "keycloak.test.local" # Keycloak'a bu adresle erişeceğiz
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keycloak   # Yukarıda öğrendiğimiz servis adı
            port:
              number: 8080 # Yukarıda öğrendiğimiz port

Ingress kuralını uygulayalım:

kubectl apply -f keycloak-ingress.yaml

Adım 4: Hosts Dosyası

keycloak.test.local adresinin RKE2 sunucumuzun IP'sine yönlenmesi için, tarayıcıyı kullandığımız kendi bilgisayarımızda (sunucuda değil!) /etc/hosts dosyasını düzenlememiz gerekiyor.

sudo nano /etc/hosts

Dosyanın en altına RKE2 sunucunuzun IP'sini ve host adını ekleyin:

<kubernetes-kurulu-server-ip-adresi>   keycloak.test.local

Artık tarayıcıdan http://keycloak.test.local adresine giderek Keycloak arayüzüne erişebilirsiniz.

Varsayılan hızlı başlangıç bilgileri:

Kullanıcı Adı: admin
Şifre: admin

Faz 3: Keycloak'u Liman için Yapılandırma

Liman'a "Bana güvenebilirsin" demek için Keycloak'ta bir "Client" (istemci) ve "Realm" (Bölge) oluşturmalıyız.

Realm Oluşturun: admin olarak giriş yaptıktan sonra, sol üstteki "master" yazan yerden "Manage realms" > "Create Realm" deyin. Realm adınızı Liman-Realm gibi bir şey yapın ve "Create"e tıklayın.
Client Oluşturun: Sol üstten Liman-Realm'i seçtiğinizden emin olun. Sol menüden "Clients" sekmesine ve ardından "Create Client"a tıklayın. "Client ID" kısmına liman-client gibi hatırlayacağınız bir isim verin. Gelen ekranda "Client authentication" ve "Authorization" seçeneklerini ON (Açık) konuma getirin. Aşağıdaki "Valid redirect URIs" alanına, Liman arayüzünde bizden istenen adresi girmeliyiz. Bu, Liman'ın Ingress host adına bağlı olacaktır. Şimdilik https://liman.test.local/keycloak/callback yazabilirsiniz. (Liman Ingress'ini oluştururken liman.test.local kullanacağız). Web origins kısmına da https://liman.test.local yazın ve kaydedin.
Client Secret'ı Alın: Kaydettikten sonra açılan "Credentials" sekmesine tıklayın ve "Client Secret" değerini kopyalayın. Bu, Liman'daki forma yapıştıracağımız "şifre" olacak.
Rolleri Token'a Ekleyin (Çok Önemli Adım!): Liman'ın, giriş yapan kullanıcının yetkilerini anlaması için bu rollerin Keycloak tarafından oluşturulan token'a eklenmesi gerekir.
- Sol menüden "Client Scopes"a tıklayın.
- roles adlı scope'u seçin.
- Açılan ekranda "Mappers" (Eşleyiciler) sekmesine tıklayın.
- realm-roles'e girin, "Add to access token" seçeneğini aktifleştirip kaydedin.
- Aynı işlemi client-roles için de yapın.
Test Kullanıcısı Oluşturun:
- Sol menüden "Users"a gidin ve "Add User" deyin.
- Kullanıcı bilgilerinizi girin, "Email verified" seçeneğini açın ve Create'e tıklayın.
- Kullanıcıyı oluşturduktan sonra, "Credentials" sekmesine giderek ona kalıcı bir şifre belirleyin (Temporary'i kapatarak).

Keycloak tarafı artık Liman'ı kabul etmeye hazır.

Faz 4: Liman MYS Kurulumu ve Hata Ayıklama

Şimdi Liman MYS'yi kuralım ve bu süreçte karşılaşacağımız iki yaygın hatayı çözelim.

git clone https://github.com/limanmys/core.git
cd core/k8s/helm
kubectl create namespace liman
helm install limancore . --namespace liman

kubectl get pods -n liman komutunu çalıştırdığınızda, pod'ların Pending (Beklemede) veya ErrImagePull durumunda takıldığını göreceksiniz. Panik yapmayın, bu normal.

HATA 1 ÇÖZÜMÜ: Pending (Beklemede) Pod'lar

db- ve limancore- pod'larının Pending kalmasının nedeni, Longhorn'un varsayılan olarak 3 replica (kopya) disk oluşturmaya çalışmasıdır. Bizim RKE2 kurulumumuz tek bir sunucudan (Node) oluştuğu için Longhorn "Verinin 3 kopyasını oluşturamam" diyerek diski (Volume) oluşturmayı reddeder.

Bunu düzeltmek için Longhorn arayüzüne erişip replica sayısını 1'e düşüreceğiz:

Longhorn Arayüzünü Erişime Açın:
```
kubectl edit svc longhorn-frontend -n longhorn-system
```
Açılan vi editöründe, spec: altındaki type: ClusterIP satırını type: NodePort olarak değiştirin ve kaydedip çıkın (Esc > :wq > Enter).

Portu Öğrenin:

kubectl get svc -n longhorn-system
NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
longhorn-admission-webhook    ClusterIP   10.43.130.170   <none>        9502/TCP       23h
longhorn-backend              ClusterIP   10.43.171.127   <none>        9500/TCP       23h
longhorn-conversion-webhook   ClusterIP   10.43.234.16    <none>        9501/TCP       23h
longhorn-frontend             NodePort    10.43.84.222    <none>        80:31248/TCP   23h
longhorn-recovery-backend     ClusterIP   10.43.60.100    <none>        9503/TCP       23h

longhorn-frontend servisinin NodePort değerini (örn: 80:31248/TCP) göreceksiniz. Bize 31248 portu lazım.

Replica Sayısını Düşürün: Tarayıcınızdan http://<sunucu-ip-adresi>:<port-sayısı> (örn: http://xx.xx.xx.xx:31248) adresine gidin. "Volume" sekmesine gidin. Faulted (Hatalı) durumda olan volüm'leri (liman db ve core için) göreceksiniz. Sağ taraftaki üç noktaya tıklayın ve "Update Replicas" (Replica'ları Güncelle) deyin. Değeri 3'ten 1'e düşürün ve OK'e basın.

Bunu hatalı olan tüm Liman volüm'leri için yaptığınızda, durumları "Healthy" (Sağlıklı) olacaktır ve pod'lar Pending durumundan çıkacaktır.

HATA 2 ÇÖZÜMÜ: ErrImagePull / TooManyRequests

Pending sorununu çözseniz bile, pod'ların bu kez ErrImagePull veya ImagePullBackOff hatası verdiğini göreceksiniz. Bunun nedeni, Docker Hub'ın anonim (giriş yapmamış) kullanıcılara çok düşük bir imaj indirme limiti koymasıdır.

Çözüm, RKE2 sunucumuza Docker Hub'a nasıl giriş yapacağını öğretmektir.

Docker Hub Access Token Oluşturun:
- Docker Hub'a giriş yapın.
- Ayarlar > Security > Personal Access Tokens sayfasına gidin.
- "Generate New Token" diyerek bir token oluşturun ve bu token'ı güvenli bir yere kopyalayın.

Kubernetes Secret Oluşturun: Terminalde, kopyaladığınız o token'ı kullanarak bir Kubernetes "giriş kartı" (secret) oluşturun:

kubectl create secret docker-registry dockerhub-auth \
  --docker-username="SizinDockerHubKullanıcıAdınız" \
  --docker-password="YENİ_OLUŞTURDUĞUNUZ_TOKEN" \
  --docker-email="SizinEmailAdresiniz" \
  -n liman

Secret'ı Pod'lara Tanıtın: liman namespace'indeki default (varsayılan) hizmet hesabını (Service Account) yamalayarak, bu namespace'de oluşturulan her pod'un imaj çekerken bu "giriş kartını" kullanmasını sağlayacağız:
```
kubectl patch serviceaccount default -n liman -p '{"imagePullSecrets": [{"name": "dockerhub-auth"}]}'
```
Pod'ları Yeniden Başlatın: Hatalı pod'ları silerek Kubernetes'in onları yeni ayarla (giriş yapmış olarak) yeniden başlatmasını sağlayın:
```
kubectl delete pods --all -n liman
```
Tekrar kubectl get pods -n liman -w komutuyla izlediğinizde, bu kez tüm pod'ların imajları başarıyla çektiğini ve Running durumuna geçtiğini göreceksiniz.

Faz 5: Liman Ingress ve Son Ayarlar

Artık çalışan bir Liman'ımız var. Ona da Keycloak gibi temiz bir adresle erişelim.

Liman Ingress Dosyası:

sudo nano liman-ingress.yaml

Dosyanın içeriği:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: liman
  namespace: liman
  annotations:
    # Arka uç (Liman) HTTPS (443) kullandığı için Nginx'e HTTPS konuşmasını söylüyoruz
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    # Liman'ın kendi imzaladığı sertifikayı Nginx'in dert etmemesini söylüyoruz
    nginx.ingress.kubernetes.io/proxy-ssl-verify: "off"
spec:
  ingressClassName: nginx
  rules:
  - host: "liman.test.local" # Liman'a bu adresle erişeceğiz
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: limancore # Liman'ın ana servis adı
            port:
              number: 443    # Liman'ın servis portu

Dosyayı kaydedin ve uygulayın:

kubectl apply -f liman-ingress.yaml -n liman

Hosts Dosyasını Güncelleyin: Tekrar kendi bilgisayarınızda sudo nano /etc/hosts dosyasını açın ve liman.test.local adresini de ekleyin:
```
<kubernetes-kurulu-server-ip-adresi>   keycloak.test.local
<kubernetes-kurulu-server-ip-adresi>   liman.test.local
```

Liman Admin Şifresini Alın: Liman'a ilk giriş için tek kullanımlık bir şifre almamız gerekiyor:

# Önce limancore pod'unun tam adını bulalım:
LIMAN_POD_NAME=$(kubectl get pods -n liman -l service=limancore -o jsonpath='{.items[0].metadata.name}')
echo "Liman Pod Adı: $LIMAN_POD_NAME"

# Şimdi o pod'dan şifreyi isteyelim:
kubectl exec -it $LIMAN_POD_NAME -n liman -- limanctl administrator

Size administrator kullanıcısı için bir şifre verecektir.

Liman'ı Keycloak'a Bağlayın:
- Tarayıcınızdan http://liman.test.local adresine gidin. (Ingress, isteğinizi otomatik olarak HTTPS'e yönlendirecektir).
- Aldığınız administrator şifresiyle giriş yapın.
- Ayarlar > Erişim > Keycloak sekmesine gidin.
- Buradaki alanları, Faz 3'te Keycloak'ta oluşturduğunuz bilgilerle doldurun:
  - Client ID: liman-client (veya ne isim verdiyseniz)
  - Client Secret: Keycloak'tan kopyaladığınız gizli şifre.
  - Redirect URL: https://liman.test.local/keycloak/callback (Keycloak'a girdiğiniz adresin aynısı)
  - Base URL: http://keycloak.default.svc.cluster.local:8080 (Keycloak adresiniz)
  - Realm: Liman-Realm (veya ne isim verdiyseniz)
- "Entegrasyonu aktifleştir" butonunu AÇIK hale getirin ve kaydedin.

Son Adım: Liman'ı Yeniden Başlatın

Liman'ın bu yeni ayarları çekmesi için limancore pod'unu yeniden başlatmamız gerekiyor:

# Pod'un tam adını tekrar bulup silin
kubectl delete pod $LIMAN_POD_NAME -n liman

Pod yeniden başladığında, Liman giriş ekranına geri dönün.

Artık "Giriş Yöntemi" olarak Keycloak'u seçebilir, Faz 3'te oluşturduğunuz test kullanıcısıyla giriş yapabilir ve Keycloak üzerinden Liman'a başarıyla bağlandığınızı görebilirsiniz.

Tebrikler! Artık RKE2 üzerinde çalışan, Longhorn ile kalıcı depolamaya sahip ve Keycloak ile SSO entegrasyonu tamamlanmış bir Liman MYS kurulumunuz var.

DEV Community