Basic Keycloak deployment - Keycloak

执行基本的 Keycloak 部署

本指南介绍了如何使用 Operator 在 Kubernetes 或 OpenShift 上执行基本的 Keycloak 部署。

部署准备

一旦 Keycloak Operator 安装并在集群命名空间中运行，您就可以设置其他部署先决条件。

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

数据库

数据库应该是可用的，并且可以从安装 Keycloak 的集群命名空间访问。有关支持的数据库列表，请参阅配置数据库。 Keycloak Operator 不管理数据库，您需要自行 provision 数据库。考虑验证您的云提供商产品或使用数据库 operator。

出于开发目的，您可以使用临时的 PostgreSQL pod 安装。要 provision 它，请按照以下方法操作

创建 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 留空。 Operator 将为 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 Custom Resource Definition (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 实例是否已在集群中 provision，请通过输入以下命令检查已创建 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 资源。例如，在 OpenShift 上，您不允许在启用 HTTP/2 的 passthrough 路由上使用通配符证书。在 OpenShift 上启用 TLS 并使用默认 IngressClass 的通配符证书的 Keycloak CR 会创建这样的路由。在这种情况下，您必须使用 .spec.ingress.enabled: false 禁用内置 ingress。然后可以通过创建 reencrypt 路由来提供访问。

$ oc create route reencrypt --service=<keycloak-cr-name>-service --cert=<configured-certificate> --key=<certificate-key> --dest-ca-cert=<ca-certificate> --ca-cert=<ca-certificate> --hostname=<hostname>

出于调试和开发目的，请考虑使用端口转发直接连接到 Keycloak 服务。例如，输入此命令

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

配置与您的 Ingress Controller 匹配的反向代理设置

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 Controller 的文档。考虑将其配置为 reencrypt 或 edge TLS 终止，因为 passthrough TLS 不允许 Ingress 修改请求标头。错误配置将使 Keycloak 暴露于安全漏洞。

有关更多详细信息，请参阅使用反向代理指南。

访问 Admin Console

部署 Keycloak 时，operator 会生成任意初始管理员 username 和 password，并将这些凭据作为 basic-auth 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

您可以使用这些凭据来访问 Admin Console 或 Admin REST API。