安装指南
本指南介绍如何在 Kubernetes 集群上安装 Connectors 系统。单个 ConnectorsConfig 资源驱动整个安装过程 — Connectors Operator 会将其协调为每个组件对应的一个受管理子 CR(ConnectorsCore、ConnectorsGit、ConnectorsOCI,……)。
目录
简介前置条件Pod 安全要求ConnectorsConfig 的工作原理集群单例operator 启动时自动创建删除级联安装标志步骤 1:安装 Connectors operator步骤 2:安装 Connectors 组件默认安装(推荐)手动安装验证安装第 3 步:自定义安装(高级)禁用组件设置功能标志core覆盖镜像仓库(集群范围)从私有仓库拉取镜像调整工作负载副本数和资源在外部公开 OCI Proxy状态和阶段条件每个组件的阶段卸载故障排除connectors-csi 未就绪组件卡在 Failed 阶段相关文档简介
Connectors 系统采用模块化架构,由以下部分组成:
- Connectors Operator — 管理组件,负责协调
ConnectorsConfig并安装其他所有组件。 - ConnectorsConfig — 集群范围内唯一的资源,用于声明要安装哪些组件。
- Connectors 组件 —
ConnectorsCore以及可选的各工具组件。
管理员只需管理 ConnectorsConfig。operator 会创建、更新和删除由该资源派生的每个组件子资源。
前置条件
- 一个 Kubernetes 集群。
- 已配置为与集群通信的
kubectlCLI。 - 集群管理员权限。
- 平台的 OperatorHub 中提供的
Alauda Container Platform Connectorsoperator 软件包。
Pod 安全要求
Kubernetes 在命名空间级别强制执行 Pod Security Standards(PSS)。 Connectors 系统使用两个具有不同权限要求的命名空间:
如果组件命名空间配置为 restricted 或 baseline,
CSI driver 将无法启动。有关恢复操作步骤,请参阅故障排除。
ConnectorsConfig 的工作原理
ConnectorsConfig 是整个 Connectors 安装的集群范围控制资源。平台管理员编辑
ConnectorsConfig;operator 将其协调为各组件的子 CR。请勿直接编辑受管理的子 CR(ConnectorsCore、ConnectorsGit、……)——operator 会在下一次协调时覆盖它们。
集群单例
虽然 ConnectorsConfig 属于命名空间范围,但 admission webhook 会在每次创建时跨所有命名空间列出资源;如果已存在任何其他
ConnectorsConfig,则会拒绝该请求——包括当前正在删除的资源(其 finalizer 可能仍在清理子 CR)。这会强制实施集群范围的单例:每个受管理的子 CR 都恰好属于一个父资源,并且集群中只有一个用于确定已安装组件的事实来源。
operator 启动时自动创建
当 operator 启动且不存在 ConnectorsConfig 时,它会创建一个默认资源,并按默认设置启用所有受支持的组件。目标命名空间按以下优先级确定:
- 现有
ConnectorsCore所在的命名空间 — 在升级路径中保留该命名空间,以便将受管理的子资源放置在之前独立安装所在的位置。请参阅升级指南中的迁移到 ConnectorsConfig。 - operator 自身的安装命名空间(通过 Downward API 注入的
SYSTEM_NAMESPACE)— 用于全新安装。
引导过程作为经过 leader 选举的可运行任务执行,因此会在每次 leader 选举时重新执行(首次部署、滚动重启、leader pod 替换)。该过程是幂等的——如果
ConnectorsConfig 已存在,引导过程会退出,而不会更改集群状态。
通过查找 BootstrapStarted 和 BootstrapCompleted 事件,确认引导过程已运行:
删除级联
删除 ConnectorsConfig 会通过所有者引用(Controller=true、BlockOwnerDeletion=true)触发每个受管理子 CR 的级联删除。父资源的 finalizer 会阻止 ConnectorsConfig 本身被删除,直到每个子 CR 都完成其自身的 finalizer,因此即使某个组件需要一段时间才能完成排空,删除操作仍然是安全的。
安装标志
spec.installFlags 允许管理员选择退出一小组安装时行为。每个条目都由稳定的标志名称标识;其值的格式针对各个标志分别进行了说明。
可用标志:
示例 — 将整个集群中的 Pipeline Integration 限制为 schema-version 2 及以下:
对于 pipeline-integration,值为字符串。支持以下基本格式:
也接受复合格式,例如 "<2 || >=4"、"!=2"、">=1, <=3",以及通配符 / 波浪号 / 插入号范围("1.x"、"~1.2"、"^1.2")——该值会作为完整的 semver 约束表达式进行解析。
上述基本格式已涵盖常见情况。
同一标志还可以在 ConnectorsConfig 上按组件设置(例如 spec.components.harbor.spec.installFlags),以仅覆盖该组件的集群范围值。
步骤 1:安装 Connectors operator
从平台的 OperatorHub 安装 Alauda Container Platform Connectors operator — 不要手动创建 operator Subscription。
- 以管理员身份登录平台。
- 导航到 管理员 → Marketplace → OperatorHub。
- 搜索
Alauda Container Platform Connectors,然后打开该 operator 的详细信息页面。 - 点击 安装,然后选择:
- Channel — 选择要跟踪的发布频道。
- 安装命名空间 — operator 自身的命名空间
(推荐使用
connectors-operator作为默认值;也可以使用任何命名空间)。 - 审批策略 — 根据升级策略选择 Automatic 或 Manual。
- 如果选择了 Manual,请批准安装计划。
- 等待 operator 的订阅在 operator 详细信息页面中报告为
Succeeded。
operator 报告为 Ready 后,从命令行验证 controller pod
和预期的 CRD:
你应该会看到包括 connectorsconfigs.operator.connectors.alauda.io、
connectorscores.operator.connectors.alauda.io 在内的 CRD,以及每个受支持组件对应的一个 CRD。
步骤 2:安装 Connectors 组件
组件通过单个 ConnectorsConfig 资源安装。
有关每个集群只能有一个该资源的限制,请参阅Cluster Singleton。
默认安装(推荐)
operator 启动且不存在 ConnectorsConfig 时,会自动创建一个默认资源,
并以默认设置启用所有受支持的组件:
目标命名空间不一定是 operator 的安装命名空间。在升级路径中,如果已经存在
ConnectorsCore,bootstrap 会复用该命名空间,使新的受管子资源与现有的独立安装共存。有关完整的解析规则,请参阅
Auto-creation namespace priority。
验证安装是否完成(如果 bootstrap 选择了其他命名空间,请替换命名空间):
如果要选择其他安装命名空间,或要在创建组件前自定义 spec,请按照下面的
Manual Install 操作步骤,在 operator 启动之前自行预先创建
ConnectorsConfig。bootstrap 会检测到现有的
ConnectorsConfig,并跳过默认创建。
手动安装
如果已禁用自动创建,请在应托管组件的命名空间中自行创建
ConnectorsConfig。命名空间名称由你决定 — 下面使用
connectors-system 作为示例。无论在哪个命名空间中创建
ConnectorsConfig,每个组件子 CR 都会在该命名空间中创建。
验证安装
以下命令使用 connectors-operator — 默认安装命名空间。如果你按照上述手动安装路径在其他命名空间中自行创建了
ConnectorsConfig,请替换为相应的命名空间。
检查汇总条件:
status.conditions[Ready]=True 表示每个已启用组件都已完成安装。有关每个组件的阶段以及各条件的含义,请参阅Status & Phases。
列出每个组件注册的 ConnectorClass 资源 — 这些是 Connectors 系统公开的各工具集成类型(请参阅
ConnectorClass):
第 3 步:自定义安装(高级)
spec: {} 使用默认设置启用每个组件。大多数安装无需其他配置。需要禁用某些组件、调整功能标志或覆盖工作负载设置时,请使用本节。
ConnectorsConfig.spec 包含两类设置:
spec.components— 以组件短名称为键的映射(core、git、github、gitlab、oci、harbor、k8s、maven、npm、pypi、sonarqube、nexus、jfrog)。每个值都是一个ComponentConfig,包含enabled(默认为true;不接受core.enabled: false)和spec(组件专属配置,其架构与相应独立组件 CR 相同)。 未列在映射中的组件将使用默认设置启用。spec根级别的集群范围默认值 —registry、labels、annotations、imagePullSecrets和installFlags直接位于spec下,并作为每个组件的默认值。合并优先级为组件值优先:当某个键同时在spec根级别和组件上设置时,仅当组件未设置该键时,才回退到spec根级别的值。唯一的例外是imagePullSecrets,它会将spec根级别列表与组件列表合并为去重并集,而不是进行覆盖。
以下示例涵盖最常见的自定义项。有关完整的每组件架构,请参阅
ConnectorsConfig CRD 参考。
禁用组件
设置功能标志 core
featureFlags 用于切换 ConnectorsCore 上的可选行为。有关支持的标志及其具体变更,请参阅
Feature Flags。
覆盖镜像仓库(集群范围)
除非组件使用自身的 spec.components.<name>.spec.registry 在本地覆盖,否则该仓库前缀将应用于每个组件的工作负载镜像。
从私有仓库拉取镜像
当组件镜像位于需要身份验证的仓库中时,请列出要附加到每个组件工作负载 Pod 的镜像拉取 Secret 名称:
所引用的 Secret(类型为 kubernetes.io/dockerconfigjson)必须已存在于组件命名空间中 — operator 会将这些名称注入每个协调后工作负载的 imagePullSecrets,但不会创建这些 secret。
组件可以在 spec.components.<name>.spec.imagePullSecrets 下添加自身的 secret;与大多数设置不同,这两个列表会合并为去重并集(集群范围 + 组件),因此组件条目会添加到集群范围列表,而不是将其替换。
调整工作负载副本数和资源
每个组件都嵌入相同的 workloads 架构。部署名称因组件而异,可通过以下命令查找:
以下模式统一适用于 core、git、gitlab、
github、oci、harbor、k8s、maven、npm、pypi、sonarqube、
nexus 和 jfrog:
在外部公开 OCI Proxy
ConnectorsOCI 支持三种公开模式。请选择其中一种:
状态和阶段
ConnectorsConfig.status 同时报告汇总集群条件和每个组件的状态。
条件
每个组件的阶段
status.components 将组件名称映射到一个阶段:
卸载
删除 ConnectorsConfig 会级联删除每个受管组件
(将命名空间替换为安装时使用的命名空间):
ConnectorsConfig 上的终结器会阻止删除父对象,直到每个子 CR
都完成清理,因此即使某个组件需要一段时间进行清理,删除操作也是安全的。
如果还要删除 operator 本身,请先查找实际的 Subscription
名称——OperatorHub 会根据 operator 软件包为其命名,该名称在不同平台之间
可能有所不同:
如果在单独的命名空间中安装了组件(手动安装),也请删除该命名空间。
故障排除
connectors-csi 未就绪
如果 daemonset/connectors-csi 未就绪,请检查 pod 事件:
组件命名空间的 Pod Security 级别对 CSI 驱动程序限制过严。将其设置为
privileged,更新命名空间标签,然后重启
connectors-csi DaemonSet。请参阅
Pod Security 要求。
组件卡在 Failed 阶段
status.components.<name>.message 是首先要查看的位置。每当组件进入此状态时,
controller 都会在父对象上发出一个 ComponentConflict Warning 事件。
两个常见原因都源于升级遗留的过时独立 CR:
- 集群范围冲突 — 另一个命名空间中存在相同类型的 CR
(或同一命名空间中存在不同名称的 CR)。消息会列出每个冲突的
namespace/name。删除有问题的 CR,然后 controller 会在下一次 reconcile 时恢复。 - 确定性名称处存在未受管 CR — 预期名称和命名空间处已经存在 CR,
但它不带有
ManagedBy=connectorsconfig标签。controller 拒绝接管它 (message: child CR ... already exists but is not managed by ConnectorsConfig — delete it manually to allow adoption)。删除未受管 CR,controller 会在下一次 reconcile 时创建新的受管子对象。
如果你正在从 ConnectorsConfig 之前的版本进行升级,请参阅
迁移到 ConnectorsConfig
以了解相关背景。
相关文档
- 升级 Connectors Operator —
包含从
ConnectorsConfig之前版本安装的单向迁移。 - Feature Flags — 可通过
spec.components.core.spec.featureFlags配置的完整标志列表。 - 快速入门 — 安装后创建你的第一个
Connector。 - 架构概览 — 了解各组件如何协同工作。
ConnectorsConfigCRD 参考。