基本 Keycloak 部署 - Keycloak

执行基本 Keycloak 部署

本指南介绍如何使用操作符在 Kubernetes 或 OpenShift 上执行基本 Keycloak 部署。

准备部署

在 Keycloak 操作符安装并在集群命名空间中运行后，您可以设置其他部署先决条件。

数据库
主机名
TLS 证书和关联密钥

数据库

数据库应可用且可从 Keycloak 安装所在的集群命名空间访问。有关支持的数据库列表，请参见配置数据库。Keycloak 操作符不管理数据库，您需要自行配置它。请考虑验证您的云提供商产品或使用数据库操作符。

出于开发目的，您可以使用短暂的 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 控制器匹配的反向代理设置

操作符支持配置服务器应接受的反向代理标头，包括 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 字段，操作符会默认回退到旧式行为，默认情况下会隐式设置 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。