Keycloak Operator 安装

如何在 Kubernetes 和 OpenShift 上安装 Keycloak Operator

安装 Keycloak Operator

本指南介绍如何在 Kubernetes 或 OpenShift 集群中安装 Keycloak Operator。

使用 Operator Lifecycle Manager 安装

在 Kubernetes 环境中安装 Keycloak Operator 的推荐方法是使用 Operator Lifecycle Manager (OLM)。

先决条件

  • 确保您的环境中已安装 OLM。 有关详细信息,请参阅 安装 OLM

  • 请确保您拥有 cluster-admin 权限或管理员授予的同等权限级别。

使用 OpenShift Web 控制台

以下步骤介绍如何安装 Keycloak Operator。 但是,有关使用 OLM 安装 Operator 的通用说明,请参阅 使用 OLM 安装您的 Operator。 在默认目录中,Keycloak Operator 被命名为 keycloak-operator。 确保使用 fast 频道查找 Operator。

在 OpenShift 集群上执行此过程。

  1. 打开 OpenShift 容器平台 Web 控制台。

  2. 在左侧列中,单击 主页OperatorsOperatorHub

  3. 在搜索输入框中搜索 “keycloak”。

    Select the Keycloak Operator in the UI
  4. 从结果列表中选择 Keycloak Operator。

  5. 按照屏幕上的说明进行操作。

    确保您从 fast 频道安装

    Configure Keycloak Operator

您可以选择让 Operator 监视其安装的命名空间,或监视您选择的单个命名空间。

配置 OLM 升级的手动批准

重要提示:自动 OLM 升级

默认情况下,当新版本发布时,OLM 会自动更新 Keycloak Operator。 这可能会导致几个重大问题

  • 当使用默认 Keycloak 镜像时,Operator 使用相应 Keycloak 版本的匹配镜像,从而导致 Operator 升级时发生意外的 Keycloak 升级

  • 即使在使用自定义镜像时,主要的 Operator 升级也可能会为现有的 Keycloak CR 配置引入重大的兼容性问题,可能需要手动干预

  • Keycloak CR 中的新字段或行为更改可能会影响现有部署

  • 由于与数据库迁移相关的更改,无法降级到之前的 Keycloak 版本

建议

我们强烈建议为 Keycloak Operator 使用手动批准模式。 这确保您可以

  1. 在批准升级之前,查看发行说明并遵循迁移更改

  2. 安排维护窗口以进行升级

  3. 首先在非生产环境中测试升级

  4. 备份数据库,以便在出现问题时可以降级到之前的 Keycloak 版本

要防止 OLM 自动升级,请在安装 Operator 时将批准策略设置为 Manual

使用 OpenShift Web 控制台

安装 Operator 时,在更新批准策略部分选择 Manual 批准

Configure manual approval in OLM
使用 CLI

对于命令行安装,请创建一个 Subscription,并将 installPlanApproval: Manual

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: keycloak-operator
  namespace: <target-namespace>
spec:
  channel: fast
  name: keycloak-operator
  source: <catalog-source>
  sourceNamespace: <catalog-namespace>
  installPlanApproval: Manual

安装后,任何升级都需要通过 OLM 界面或通过 CLI 手动批准。

不使用 Operator Lifecycle Manager,通过 kubectl 安装

您可以通过使用 kubectl 命令在 Vanilla Kubernetes 集群上安装 Operator

  1. 通过输入以下命令来安装 CRD

    kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.2.0/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
    kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.2.0/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
  2. 通过输入以下命令来安装 Keycloak Operator 部署

    kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.2.0/kubernetes/kubernetes.yml

Operator 将监视其安装的命名空间。 您可以选择使用 -n 选项选择一个命名空间。

安装多个 Operator

目前,Operator 监视多个或所有命名空间尚未完全支持。 在您想要监视多个命名空间的情况下,您可以安装多个 Operator。

如果您这样做,请注意

  • 所有 Operator 共享 CRD(自定义资源定义),因为它们是集群范围安装的。

  • 来自较新 Operator 版本的 CRD 修订不会引入破坏性更改,除非最终删除已被充分弃用的字段。 因此,较新的 CRD 通常是向后兼容的。

  • 最后安装的 CRD 将是正在使用的 CRD。 这也适用于 OLM 安装,其中作为最后一个安装的 Operator 版本也会安装并覆盖集群中已存在的 CRD。

  • 较旧的 CRD 可能与较新的 Operator 使用的新字段不向前兼容。 当使用 OLM 时,它将检查您的自定义资源是否与正在安装的 CRD 兼容,因此新字段的使用可能会阻止同时安装较旧的 Operator 版本。

  • 较新的 CRD 引入的字段将不受较旧的 Operator 支持。 较旧的 Operator 将无法处理使用此类新字段的 CR,并在反序列化无法识别的字段时出错。

因此,在多 Operator 安装场景中,建议您尽可能保持版本对齐,以最大限度地减少不同版本可能出现的问题。

本页内容