Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 2 章 基本的 Red Hat build of Keycloak 部署

使用 Operator 安装红帽构建的 Keycloak。

2.1. 执行基本红帽构建的 Keycloak 部署
复制链接

本章论述了如何使用 Operator 在 OpenShift 中执行 Keycloak Deployment 的基本红帽构建。

2.1.1. 准备部署
复制链接

在集群命名空间中安装并运行 Red Hat build of Keycloak Operator 后，您可以设置其他部署先决条件。

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

2.1.1.1. 数据库
复制链接

数据库应该可用，并可从安装 Red Hat build of Keycloak 的集群命名空间中访问。有关支持的数据库列表 ，请参阅配置数据库。Red Hat build of 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
Copy to Clipboard Toggle word wrap

应用更改： 

oc apply -f example-postgres.yaml
Copy to Clipboard Toggle word wrap

2.1.1.2. 主机名
复制链接

对于生产环境就绪安装，您需要一个主机名，可用于联系红帽构建的 Keycloak。有关可用 配置，请参阅配置主机名(v2)。

出于开发目的，本章将使用 test.keycloak.org。

在 OpenShift 上运行 ingress 时，启用了 ingress，并将 spec.ingress.classname 设置为 openshift-default，您可能会使 spec.hostname.hostname 不在 Keycloak CR 中填充。Operator 会将默认主机名分配给 CR 的存储版本，类似于没有显式主机的 OpenShift Route 创建的内容，即 ingress-namespace.appsDomain 如果 appsDomain 发生了变化，或者因为任何原因需要不同的主机名，然后更新 Keycloak CR。

注意

如果您设置了 hostname-admin 或已弃用的 hostname-admin-url，即使启用了 ingress，也不会为 admin 访问创建 ingress。通常，通过单独的主机名的管理员访问权限通常具有访问限制，这目前无法通过 Keycloak CR 表达。另外，默认入口不会阻止访问 admin 端点，因此当您为 admin 端点有单独的主机名时，您可能都不希望通过 Keycloak CR 启用入口处理。

2.1.1.3. 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
Copy to Clipboard Toggle word wrap

您应该通过输入以下命令将其在集群命名空间中作为 Secret 安装： 

oc create secret tls example-tls-secret --cert certificate.pem --key key.pem
Copy to Clipboard Toggle word wrap

2.1.2. 部署红帽构建的 Keycloak
复制链接

要部署红帽构建的 Keycloak，您需要根据 Keycloak 自定义资源定义(CRD)创建一个自定义资源(CR)。

考虑将数据库凭据存储在单独的 Secret 中。输入以下命令： 

oc create secret generic keycloak-db-secret \
  --from-literal=username=[your_database_username] \
  --from-literal=password=[your_database_password]
Copy to Clipboard Toggle word wrap

您可以使用 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
Copy to Clipboard Toggle word wrap

应用更改： 

oc apply -f example-kc.yaml
Copy to Clipboard Toggle word wrap

要检查集群中是否已置备了红帽构建的 Keycloak 实例，请输入以下命令来检查创建的 CR 的状态： 

oc get keycloaks/example-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'
Copy to Clipboard Toggle word wrap

当部署就绪时，查找类似如下的输出： 

CONDITION: Ready
  STATUS: true
  MESSAGE:
CONDITION: HasErrors
  STATUS: false
  MESSAGE:
CONDITION: RollingUpdate
  STATUS: false
  MESSAGE:
Copy to Clipboard Toggle word wrap

2.1.3. 访问红帽构建的 Keycloak 部署
复制链接

红帽构建的 Keycloak 部署可以通过提供的主机名访问的基本 Ingress 公开。

在有多个默认 IngressClass 实例的安装中，或在 OpenShift 4.12+ 上运行时，您应该通过将 ingress spec with className 属性设置为所需的类名称来提供 ingressClassName：

编辑 YAML 文件 example-kc.yaml ： 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
    ...
    ingress:
      className: openshift-default
Copy to Clipboard Toggle word wrap

如果默认入口不适用于您的用例，请通过将带有 enabled 属性的 ingress spec 设置为 false 来禁用它：

编辑 YAML 文件 example-kc.yaml ： 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
    ...
    ingress:
      enabled: false
Copy to Clipboard Toggle word wrap

应用更改： 

oc apply -f example-kc.yaml
Copy to Clipboard Toggle word wrap

然后，您可以提供一个指向服务 < keycloak-cr-name>-service 的替代入口资源。例如，在 OpenShift 中，您不能在启用了 HTTP/2 的 passthrough Routes 上使用通配符证书。使用默认 IngressClass 的通配符证书启用了 TLS 的 Keycloak CR 会创建这样的路由。在这种情况下，您必须使用 .spec.ingress.enabled: false 禁用内置入口。然后，可通过创建重新加密路由来提供访问： 

$ 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>
Copy to Clipboard Toggle word wrap

为了进行调试和开发目的，请考虑使用端口转发直接连接到红帽构建的 Keycloak 服务。例如，输入以下命令： 

oc port-forward service/example-kc-service 8443:8443
Copy to Clipboard Toggle word wrap

Operator 支持配置哪些反向代理标头应该被服务器接受，其中包括 Forwarded 和 X-Forwarded fluentd 标头。

如果您 Ingress 实现集并覆盖 Forwarded 或 X-ForwardedDebug 标头，您可以反映在 Keycloak CR 中，如下所示： 

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  proxy:
    headers: forwarded|xforwarded
Copy to Clipboard Toggle word wrap
注意

如果没有指定 proxy.headers 字段，Operator 默认通过隐式设置 proxy=passthrough 来回退到旧的行为。这会在服务器日志中出现弃用警告。这个回退将在以后的发行版本中被删除。

警告

使用 proxy.headers 字段时，请确保您的 Ingress 正确设置并分别覆盖 Forwarded 或 X-Forwarded fluentd 标头。要设置这些标头，请查阅 Ingress Controller 的文档。考虑为重新加密或边缘 TLS 终止配置它，因为 passthrough TLS 不允许 Ingress 修改请求标头。错误配置会使红帽构建 Keycloak 暴露于安全漏洞。

如需了解更多详细信息 ，请参阅配置反向代理 指南。

2.1.4. 访问管理控制台
复制链接

在部署红帽构建的 Keycloak 时，Operator 会生成一个任意初始 admin 用户名和密码，并将这些凭证作为 basic-auth Secret 对象存储在与 CR 相同的命名空间中。

警告

在进行生产环境前，更改默认 admin 凭证并在红帽构建的 Keycloak 中启用 MFA。

要获取初始 admin 凭证，您必须读取和解码 Secret。Secret 名称派生自 Keycloak CR 名称以及固定的后缀 -initial-admin。要获取 example-kc CR 的用户名和密码，请输入以下命令： 

oc get secret example-kc-initial-admin -o jsonpath='{.data.username}' | base64 --decode
oc get secret example-kc-initial-admin -o jsonpath='{.data.password}' | base64 --decode
Copy to Clipboard Toggle word wrap

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

2.1.5. 安全注意事项
复制链接

警告

创建或编辑 Keycloak 或 KeycloakRealmImport CR 的任何人都应是一个命名空间级别 admin。

设置 Keycloak CR 镜像需要高度信任，因为运行任何镜像至少都可以访问用于环境变量的任何 Secret。

与不支持的 podTemplate 类似，可以部署替代工作负载，这些工作负载可能被授予与 Operator 本身相同的权限，这包括可以访问命名空间中的 Secret。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat