安装指南

本指南介绍如何在 Kubernetes 集群上安装 Connectors 系统。单个 ConnectorsConfig 资源即可驱动整个安装过程 — Connectors Operator 会将其协调为每个组件对应的一个受管理子 CR(ConnectorsCore、ConnectorsGit、ConnectorsOCI,…)。

简介

Connectors 系统采用模块化架构,由以下部分组成:

  • Connectors Operator — 用于协调 ConnectorsConfig 并安装其他所有组件的管理组件。
  • ConnectorsConfig — 声明已安装组件的单个集群范围资源。
  • Connectors 组件 — ConnectorsCore 以及可选的各工具组件。
组件必需用途
ConnectorsCore是所有其他组件使用的基础组件。
ConnectorsGit否通用 Git 服务。
ConnectorsGitHub否GitHub 专属功能。
ConnectorsGitLab否GitLab 专属功能。
ConnectorsOCI否OCI 容器注册表。
ConnectorsK8S否Kubernetes 集群。
ConnectorsMaven否Maven 仓库。
ConnectorsPyPI否Python 软件包注册表。
ConnectorsNPM否Node.js 软件包注册表。
ConnectorsHarbor否Harbor 专属 API,以及 OCI 功能。
ConnectorsSonarQube否SonarQube 和 SonarCloud 平台。
ConnectorsNexus否Sonatype Nexus 仓库管理器。
ConnectorsJFrog否JFrog Artifactory 仓库管理器。

管理员只需管理 ConnectorsConfig。operator 会根据该资源创建、更新和删除每个组件的子资源。

前提条件

  • Kubernetes 集群。
  • 已配置为与集群通信的 kubectl CLI。
  • 集群管理员权限。
  • 平台的 OperatorHub 中提供的 Alauda DevOps Connectors operator 软件包。

Pod 安全要求

Kubernetes 在命名空间级别强制执行 Pod 安全标准(PSS)。Connectors 系统使用两个具有不同权限要求的命名空间:

命名空间建议策略原因
operator 命名空间(connectors-operator)restricted运行标准 Kubernetes 控制器,不需要特权功能。baseline 也可行,但 restricted 更符合最小权限原则。
组件命名空间(创建 ConnectorsConfig 及其子资源的命名空间)privilegedConnectorsCore 提供的 connectors-csi DaemonSet 需要主机级访问权限(hostPath 卷、特权系统调用)。整个命名空间必须允许这些访问。

如果组件命名空间配置为 restricted 或 baseline,CSI 驱动程序将无法启动。有关恢复操作步骤,请参阅故障排除。

ConnectorsConfig 的工作原理

ConnectorsConfig 是整个 Connectors 安装的集群范围控制资源。平台管理员编辑 ConnectorsConfig;operator 会将其协调为每个组件的子 CR。请勿直接编辑受管理的子 CR(ConnectorsCore、ConnectorsGit、……)——operator 会在下一次协调时覆盖这些资源。

集群单例

虽然 ConnectorsConfig 具有命名空间范围,但准入 webhook 会在每次创建时跨所有命名空间列出资源;如果任何其他 ConnectorsConfig 已存在,则拒绝该请求——包括当前正在删除的资源(其 finalizer 可能仍在清理子 CR)。这确保了集群范围的单例:每个受管理的子 CR 恰好属于一个父资源,并且集群对于已安装的组件只有一个事实来源。

operator 启动时自动创建

当 operator 启动且不存在 ConnectorsConfig 时,它会创建一个默认资源,并默认启用所有受支持的组件。目标命名空间按以下优先级确定:

  1. 现有 ConnectorsCore 所在的命名空间——在升级路径中保留该命名空间,以便将受管理的子资源创建到之前独立安装所在的位置。请参阅升级指南中的迁移到 ConnectorsConfig。
  2. operator 自身的安装命名空间(通过 Downward API 注入的 SYSTEM_NAMESPACE)——用于全新安装。

引导过程作为经过 leader 选举的可运行任务执行,因此会在每次 leader 选举时重新执行(首次部署、滚动重启、leader pod 替换)。该过程是幂等的——如果 ConnectorsConfig 已存在,引导过程将退出,不会更改集群状态。

通过查找 BootstrapStarted 和 BootstrapCompleted 事件,确认引导过程已运行:

kubectl describe connectorsconfig connectors-config -n <namespace>

级联删除

删除 ConnectorsConfig 会通过所有者引用(Controller=true、BlockOwnerDeletion=true)触发所有受管理子 CR 的级联删除。父资源的 finalizer 会阻止删除 ConnectorsConfig 本身,直到每个子 CR 都完成自身的 finalizer,因此即使某个组件需要一段时间才能完成排空,删除过程也是安全的。

安装标志

spec.installFlags 允许管理员选择不执行少量安装时行为。每个条目都使用稳定的标志名称作为键;值的格式针对每个标志分别进行了说明。

可用标志:

键用途示例值
pipeline-integration限制要安装的 ResourceInterface schema 版本。当 Tekton 版本低于 operator 提供的版本时使用。"<=2"

示例——在整个集群中将 Pipeline Integration 限制为 schema 版本 2 及更低版本:

apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
spec:
  installFlags:
    pipeline-integration: "<=2"   # install v1 and v2; skip v3+

对于 pipeline-integration,值是字符串。支持以下基本格式:

值效果
"<=N"安装不高于 N 的 schema 版本
">=N"安装 N 及更高版本的 schema 版本
"=N"仅安装 schema 版本 N

也接受复合格式,例如 "<2 || >=4"、"!=2"、">=1, <=3",以及通配符 / 波浪号 / 插入号范围("1.x"、"~1.2"、"^1.2")——该值会作为完整的 semver 约束表达式进行解析。上述基本格式已涵盖常见情况。

同一标志也可以在 ConnectorsConfig 上按组件设置(例如 spec.components.harbor.spec.installFlags),以仅覆盖该组件的集群范围值。

步骤 1:安装 Connectors operator

从平台的 OperatorHub 安装 Alauda DevOps Connectors operator — 不要手动创建 operator Subscription。

  1. 以管理员身份登录平台。
  2. 导航至 管理员 → Marketplace → OperatorHub。
  3. 搜索 Alauda DevOps Connectors,然后打开该 operator 的详情页。
  4. 单击 安装,然后选择:
    • Channel — 选择要跟踪的发布 channel。
    • 安装命名空间 — operator 自身的命名空间 (推荐使用默认值 connectors-operator;任何命名空间均可)。
    • 批准策略 — 根据升级策略选择 Automatic 或 Manual。
  5. 如果选择了 Manual,请批准安装计划。
  6. 等待 operator 的订阅在 operator 详情页上报告 Succeeded。

当 operator 报告为 Ready 后,从命令行验证 controller pod 和预期的 CRD:

kubectl get pods -n connectors-operator
NAME                                                  READY   STATUS    RESTARTS   AGE
connectors-operator-controller-manager-xxxxxx-xxxxx   2/2     Running   0          1m
kubectl get crds | grep operator.connectors.alauda.io

你应看到包括 connectorsconfigs.operator.connectors.alauda.io、connectorscores.operator.connectors.alauda.io 在内的 CRD, 以及每个受支持组件各对应一个 CRD。

步骤 2:安装 Connectors 组件

组件通过单个 ConnectorsConfig 资源安装。 有关每个集群只能有一个此类资源的限制,请参阅集群单例。

默认安装(推荐)

当 operator 启动且不存在 ConnectorsConfig 时,它会自动创建一个默认资源, 并使用默认设置启用所有受支持的组件:

apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
  namespace: connectors-operator   # fresh install: the operator's install namespace
spec: {}

目标命名空间不一定是 operator 的安装命名空间。在升级路径中,如果已存在 ConnectorsCore,bootstrap 会复用该命名空间,以便新的受管子资源与现有的独立安装 部署在一起。有关完整的解析规则,请参阅自动创建命名空间优先级。

验证安装是否最终达到预期状态(如果 bootstrap 选择了其他命名空间,请替换该命名空间):

kubectl get connectorsconfig -A
kubectl wait --for=condition=Ready connectorsconfig/connectors-config \
  -n connectors-operator --timeout=600s

如需选择其他安装命名空间,或在创建组件之前自定义 spec,请按照下面的手动安装操作步骤, 在 operator 启动之前预先自行创建 ConnectorsConfig。bootstrap 会检测到现有的 ConnectorsConfig,并跳过自身的默认创建。

手动安装

如果禁用了自动创建,请在应托管组件的命名空间中自行创建 ConnectorsConfig。 命名空间名称可自行选择 — 下面以 connectors-system 为例。无论你在哪个命名空间中创建 ConnectorsConfig,每个组件子 CR 都将在该命名空间中创建。

kubectl create namespace connectors-system

cat <<EOF | kubectl apply -f -
apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
  namespace: connectors-system
spec: {}
EOF

验证安装

下面的命令使用 connectors-operator — 默认安装命名空间。如果你在其他命名空间中自行创建了 ConnectorsConfig(即采用上面的手动安装路径),请将其替换为相应的命名空间。

检查汇总条件:

kubectl get connectorsconfig -A
kubectl describe connectorsconfig connectors-config -n connectors-operator

status.conditions[Ready]=True 表示每个已启用的组件都已完成安装。有关各组件的阶段及每个条件的含义,请参阅状态和阶段。

列出每个组件注册的 ConnectorClass 资源 — 这些是 Connectors 系统公开的各工具集成类型(请参阅 ConnectorClass):

kubectl get 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 参考。

停用组件

spec:
  components:
    sonarqube: { enabled: false }
    nexus:     { enabled: false }

设置功能标志 core

featureFlags 用于切换 ConnectorsCore 上的可选行为。有关支持的标志及其具体变更的完整列表,请参阅 功能标志。

spec:
  components:
    core:
      spec:
        featureFlags:
          enable-multi-connector: "true"
          enable-custom-ca-certs: "true"

覆盖镜像仓库(集群范围)

spec:
  registry: registry.example.com/connectors

除非组件使用自己的 spec.components.<name>.spec.registry 在本地覆盖,否则该仓库前缀将应用于每个组件的工作负载镜像。

从私有仓库拉取镜像

如果组件镜像存储在需要身份验证的仓库中,请列出要附加到每个组件工作负载 Pod 的镜像拉取 Secret 名称:

spec:
  imagePullSecrets:
    - my-registry-cred

引用的 Secret(类型为 kubernetes.io/dockerconfigjson)必须已存在于组件命名空间中 — operator 会将这些名称注入每个调谐后工作负载的 imagePullSecrets,但不会创建这些 Secret。

组件可以在 spec.components.<name>.spec.imagePullSecrets 下添加自己的 Secret;与大多数设置不同,这两个列表会合并为去重并集(集群范围 + 组件),因此组件条目会添加到集群范围列表中,而不是替换它。

调整工作负载副本数和资源

每个组件都嵌入相同的 workloads 架构。部署名称因组件而异,可通过以下命令查找:

kubectl -n <components-namespace> get deploy

以下模式统一适用于 core、git、gitlab、 github、oci、harbor、k8s、maven、npm、pypi、sonarqube、 nexus 和 jfrog:

spec:
  components:
    git:
      spec:
        workloads:
          - name: connectors-git-plugin
            replicas: 2
            template:
              spec:
                containers:
                  - name: plugin
                    resources:
                      limits:   { cpu: 300m, memory: 256Mi }
                      requests: { cpu: 100m, memory: 128Mi }

对外公开 OCI Proxy

ConnectorsOCI 支持三种公开模式。请选择一种:

# ClusterIP (default): in-cluster access only
spec:
  components:
    oci:
      spec: {}
# NodePort: external access via a node IP
spec:
  components:
    oci:
      spec:
        expose:
          type: NodePort
          domain: 192.168.1.100
          nodePort:
            port: 30080
# Ingress: external access via a hostname
spec:
  components:
    oci:
      spec:
        expose:
          type: Ingress
          domain: connectors.proxy.example.com

状态与阶段

ConnectorsConfig.status 同时报告集群汇总条件和各组件状态。

条件

条件为 True 时
ComponentsReady每个已启用组件都报告 Ready=True。消息会跟踪 ready/enabled (disabled) 计数。
Migrated已记录任何 bootstrap 迁移,或无需迁移。原因:MigrationCompleted 或 NonMigration。
ReadyComponentsReady 和 Migrated 均为 True。

各组件阶段

status.components 将组件名称映射到一个阶段:

阶段含义
Pending尚未创建子 CR(首次 reconcile 前的初始状态)。
Creating子 CR 刚刚创建,或其 installer 仍在推出。
Updatinginstaller 正在推出更新后的 bundle。
Ready子 CR 报告 Ready=True。
Migrating一个 ConnectorsConfig 之前的独立 CR 仍在终止,而受管理的子 CR 已经到位。在迁移期间,这是无害的临时状态。
Deleting组件已被禁用或移除,其子 CR 正在删除。
Failed非临时错误阻止安装(请参阅状态 message)。
Disabled组件在 spec.components 中已被禁用。

卸载

移除 ConnectorsConfig 会级联移除所有受管理的组件(请将命名空间替换为安装时使用的命名空间):

kubectl delete connectorsconfig connectors-config -n connectors-operator

ConnectorsConfig 上的 finalizer 会阻止父资源被移除,直至所有子 CR 均完成清理。因此,即使某个组件需要一段时间才能完成清理,删除操作也是安全的。

如需同时移除 operator 本身,请先查找实际的 Subscription 名称——OperatorHub 会根据 operator 软件包为其命名,该名称可能因平台而异:

kubectl get subscription -n connectors-operator
kubectl delete subscription -n connectors-operator <subscription-name>
kubectl delete namespace connectors-operator

如果将组件安装在单独的命名空间中(手动安装),还需删除该命名空间。

故障排除

connectors-csi 未就绪

如果 daemonset/connectors-csi 未就绪,请检查 pod 事件:

Error creating: pods "connectors-csi-d4r6r" is forbidden: violates
PodSecurity "baseline:latest": non-default capabilities (container
"driver" must not include "SYS_ADMIN" in securityContext.capabilities.add),
host namespaces (hostNetwork=true), hostPath volumes (volumes
"socket-dir", "mountpoint-dir", "registration-dir") ...

组件命名空间的 Pod Security 级别对 CSI driver 而言限制过严。请将其设置为 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 会拒绝接管该 CR(message: child CR ... already exists but is not managed by ConnectorsConfig — delete it manually to allow adoption)。删除不受管理的 CR,controller 将在下一次 reconcile 时创建新的受管理子资源。

如果您正处于从 ConnectorsConfig 之前的版本升级的过程中,请参阅迁移到 ConnectorsConfig了解相关背景。

相关文档