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

第 2 章 基本红帽构建的 Keycloak 部署

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

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

2.1.1. 准备部署
复制链接

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

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

2.1.1.1. 数据库
复制链接

数据库应该可从安装红帽构建的 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
Copy to Clipboard Toggle word wrap

应用更改： 

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

2.1.1.2. 主机名
复制链接

对于生产环境就绪安装，您需要一个可用于联系红帽构建的 Keycloak 的主机名。请参阅为可用配置配置主机名。https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html-single/server_guide/#hostname-

出于开发目的，本章将使用 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。

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 和 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

如果默认入口不适合您的用例，请通过将 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-Forwarded34） 标头。

如果 Ingress 实现设置并覆盖 Forwarded 或 X-Forwarded114 标头，您可以在 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-Forwarded34） 标头。要设置这些标头，请参阅 Ingress Controller 的文档。考虑将其配置为重新加密或边缘 TLS 终止，因为 passthrough TLS 不允许 Ingress 修改请求标头。错误配置会将红帽构建的 Keycloak 暴露给安全漏洞。

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

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

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

警告

在进入生产环境前，更改默认的 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 REST API。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat