基本的 Keycloak 部署 - Keycloak

執行基本的 Keycloak 部署

本指南描述如何使用 Operator 在 Kubernetes 或 OpenShift 上執行基本的 Keycloak 部署。

部署準備

一旦 Keycloak Operator 安裝並在叢集命名空間中運行，您就可以設定其他部署先決條件。

資料庫
主機名稱
TLS 憑證和相關金鑰

資料庫

資料庫應可從安裝 Keycloak 的叢集命名空間中存取。如需支援的資料庫清單，請參閱設定資料庫。Keycloak Operator 不管理資料庫，您需要自行佈建。考慮驗證您的雲端供應商產品或使用資料庫運算子。

為了開發目的，您可以使用臨時的 PostgreSQL pod 安裝。若要佈建它，請遵循以下方法

建立 YAML 檔案 example-postgres.yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgresql-db
spec:
  serviceName: postgresql-db-service
  selector:
    matchLabels:
      app: postgresql-db
  replicas: 1
  template:
    metadata:
      labels:
        app: postgresql-db
    spec:
      containers:
        - name: postgresql-db
          image: postgres:15
          volumeMounts:
            - mountPath: /data
              name: cache-volume
          env:
            - name: POSTGRES_USER
              value: testuser
            - name: POSTGRES_PASSWORD
              value: testpassword
            - name: PGDATA
              value: /data/pgdata
            - name: POSTGRES_DB
              value: keycloak
      volumes:
        - name: cache-volume
          emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: postgres-db
spec:
  selector:
    app: postgresql-db
  type: LoadBalancer
  ports:
  - port: 5432
    targetPort: 5432

套用變更

kubectl apply -f example-postgres.yaml

主機名稱

對於生產環境就緒的安裝，您需要一個可用於聯繫 Keycloak 的主機名稱。有關可用配置，請參閱設定主機名稱 (v2)。

為了開發目的，本指南將使用 test.keycloak.org。

在 OpenShift 上執行時，如果啟用 ingress，並且 spec.ingress.classname 設定為 openshift-default，您可以將 Keycloak CR 中的 spec.hostname.hostname 保持為未填寫。運算子會將一個預設主機名稱分配給 CR 的已儲存版本，類似於沒有明確主機的 OpenShift Route 所建立的內容 - 即 ingress-namespace.appsDomain。如果 appsDomain 變更，或您因為任何原因需要不同的主機名稱，則請更新 Keycloak CR。

如果您設定 hostname-admin，或已棄用的 hostname-admin-url，即使您啟用 ingress，也不會專門為管理員存取建立 ingress。透過單獨主機名稱進行管理員存取通常預期會有存取限制，目前無法透過 Keycloak CR 來表示。此外，預設的 ingress 不會阻止存取管理員端點，因此當您有單獨的管理員端點主機名稱時，您可能根本不希望透過 Keycloak CR 啟用 ingress 處理。

TLS 憑證和金鑰

請洽您的憑證授權單位以取得憑證和金鑰。

為了開發目的，您可以輸入此命令來取得自我簽署憑證

openssl req -subj '/CN=test.keycloak.org/O=Test Keycloak./C=US' -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

您應該透過輸入此命令，將其以 Secret 的形式安裝在叢集命名空間中

kubectl create secret tls example-tls-secret --cert certificate.pem --key key.pem

部署 Keycloak

若要部署 Keycloak，您可以根據 Keycloak 自訂資源定義 (CRD) 建立自訂資源 (CR)。

考慮將資料庫憑證儲存在單獨的 Secret 中。輸入以下命令

kubectl create secret generic keycloak-db-secret \
  --from-literal=username=[your_database_username] \
  --from-literal=password=[your_database_password]

您可以使用 Keycloak CRD 自訂多個欄位。對於基本部署，您可以堅持以下方法

建立 YAML 檔案 example-kc.yaml

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  instances: 1
  db:
    vendor: postgres
    host: postgres-db
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  http:
    tlsSecret: example-tls-secret
  hostname:
    hostname: test.keycloak.org
  proxy:
    headers: xforwarded # double check your reverse proxy sets and overwrites the X-Forwarded-* headers

套用變更

kubectl apply -f example-kc.yaml

若要檢查 Keycloak 執行個體是否已在叢集中佈建，請輸入以下命令來檢查已建立 CR 的狀態

kubectl get keycloaks/example-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'

當部署準備就緒時，請尋找類似以下的輸出

CONDITION: Ready
  STATUS: true
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:
CONDITION: RollingUpdate
  STATUS: false
  MESSAGE:

存取 Keycloak 部署

Keycloak 部署透過基本 Ingress 公開，並且可透過提供的主機名稱存取。在具有多個預設 IngressClass 執行個體的安裝中，或在 OpenShift 4.12+ 上執行時，您應該透過將 ingress spec 的 className 屬性設定為所需的類別名稱來提供 ingressClassName

編輯 YAML 檔案 example-kc.yaml

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
    ...
    ingress:
      className: openshift-default

如果預設的 ingress 不符合您的使用案例，請透過將 ingress spec 的 enabled 屬性設定為 false 值來停用它

編輯 YAML 檔案 example-kc.yaml

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
    ...
    ingress:
      enabled: false

套用變更

kubectl apply -f example-kc.yaml

您可以提供指向服務 <keycloak-cr-name>-service 的替代 ingress 資源。

為了除錯和開發目的，請考慮使用連接埠轉發直接連接到 Keycloak 服務。例如，輸入此命令

kubectl port-forward service/example-kc-service 8443:8443

設定符合您 Ingress 控制器的反向代理設定

Operator 支援設定伺服器應接受哪些反向代理標頭，其中包括 Forwarded 和 X-Forwarded-* 標頭。

如果您的 Ingress 實作設定並覆寫 Forwarded 或 X-Forwarded-* 標頭，您可以在 Keycloak CR 中反映這一點，如下所示

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  proxy:
    headers: forwarded|xforwarded

如果未指定 proxy.headers 欄位，則 Operator 會透過預設隱式設定 proxy=passthrough 來恢復為舊版行為。這會在伺服器日誌中產生棄用警告。此回復將在未來版本中移除。

當使用 proxy.headers 欄位時，請確保您的 Ingress 正確設定並覆寫 Forwarded 或 X-Forwarded-* 標頭。若要設定這些標頭，請查閱您的 Ingress 控制器的文件。考慮將其設定為重新加密或邊緣 TLS 終止，因為傳遞 TLS 不允許 Ingress 修改請求標頭。設定錯誤會使 Keycloak 暴露於安全性漏洞。

如需更多詳細資訊，請參閱使用反向代理指南。

存取管理控制台

部署 Keycloak 時，運算子會產生任意的初始管理員 username 和 password，並將這些憑證以基本驗證 Secret 物件的形式儲存在與 CR 相同的命名空間中。

在進入生產環境之前，請變更預設管理員憑證並在 Keycloak 中啟用 MFA。

若要擷取初始管理員憑證，您必須讀取並解碼 Secret。Secret 名稱是從 Keycloak CR 名稱加上固定後綴 -initial-admin 衍生而來。若要取得 example-kc CR 的使用者名稱和密碼，請輸入以下命令

kubectl get secret example-kc-initial-admin -o jsonpath='{.data.username}' | base64 --decode
kubectl get secret example-kc-initial-admin -o jsonpath='{.data.password}' | base64 --decode

您可以使用這些憑證來存取管理控制台或管理 REST API。