安装指南

本指南将在 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否除 OCI 能力外,还提供 Harbor 特定 API。
ConnectorsSonarQube否SonarQube 和 SonarCloud 平台。
ConnectorsNexus否Sonatype Nexus repository manager。
ConnectorsJFrog否JFrog Artifactory repository manager。

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

前提条件

  • 一个 Kubernetes 集群。
  • 已配置好可与集群通信的 kubectl CLI。
  • cluster-admin 权限。
  • 平台的 OperatorHub 中可用的 Alauda DevOps Connectors operator 包。

安装所需的 Pod 安全要求

Kubernetes 会在命名空间级别强制执行 Pod Security Standards(PSS)。 Connectors 系统使用两个命名空间,并且它们的权限要求不同:

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

如果组件命名空间配置为 restricted 或 baseline,CSI 驱动将无法启动。请参见 故障排查 获取恢复步骤。

ConnectorsConfig 的工作原理

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

集群单例

尽管 ConnectorsConfig 是 namespaced 的,但 admission webhook 会在每次创建时跨所有命名空间进行检查;如果已存在任何其他 ConnectorsConfig,请求就会被拒绝——包括正在删除中的资源(其 finalizer 可能仍在清理子 CR)。这确保了集群范围内只有一个实例:每个受管子 CR 都只属于一个父资源,并且集群对于已安装的组件有单一事实来源。

Operator 启动时自动创建

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

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

该引导过程作为 leader-elected runnable 执行,因此每次 leader 选举时都会重新运行(首次部署、滚动重启、leader pod 替换)。该操作是幂等的——如果已经存在 ConnectorsConfig,bootstrap 会退出,不会触碰集群状态。

可通过查看 BootstrapStarted 和 BootstrapCompleted 事件确认 bootstrap 已运行:

kubectl describe connectorsconfig connectors-config -n <namespace>

删除级联

删除 ConnectorsConfig 会通过 owner reference(Controller=true、BlockOwnerDeletion=true)级联删除所有受管子 CR。父资源的 finalizer 会阻止 ConnectorsConfig 本身被移除,直到所有子 CR 完成各自的 finalizer,因此即使某个组件需要一段时间来清理,删除过程也是安全的。

安装标志

spec.installFlags 允许管理员关闭一小部分安装时行为。每个条目都使用稳定的 flag 名称作为键;其值的结构按 flag 分别说明。

可用标志:

键作用示例值
pipeline-integration限制将安装哪些 ResourceInterface schema-version。适用于 Tekton 版本低于 operator 所带版本的情况。"<=2"

示例——将集群范围内的 Pipeline Integration 限制为 schema-version 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-version
">=N"安装 N 及以上的 schema-version
"=N"仅安装 schema-version N

也支持组合形式,例如 "<2 || >=4"、"!=2"、">=1, <=3",以及通配符 / 波浪号 / 脱字符范围("1.x"、"~1.2"、"^1.2")——该值会按完整的 semver constraint expression 解析。上面的基本形式覆盖了常见场景。

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

步骤 1:安装 Connectors Operator

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

  1. 以管理员身份登录平台。
  2. 导航到 Administrator → Marketplace → OperatorHub。
  3. 搜索 Alauda DevOps Connectors 并打开该 operator 的详情页。
  4. 单击 Install,然后选择:
    • Channel — 选择要跟踪的发布通道。
    • Install namespace — operator 自身的命名空间(推荐默认值 connectors-operator;任何命名空间都可以)。
    • Approval strategy — 根据你的升级策略选择 Automatic 或 Manual。
  5. 如果选择了 Manual,请批准 install plan。
  6. 等待 operator 的 subscription 在详情页中显示 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: {} 会使用默认值启用所有组件。大多数安装无需额外配置。只有在你需要关闭某些组件、调整 feature flag 或覆盖工作负载设置时,才使用本节。

ConnectorsConfig.spec 包含两类设置:

  • spec.components — 以短组件名为键的映射(core、git、github、gitlab、oci、harbor、k8s、maven、npm、pypi、sonarqube、nexus、jfrog)。每个值都是一个 ComponentConfig,其中包含 enabled(默认 true;core.enabled: false 会被拒绝)和 spec(组件特定配置,schema 与对应的独立组件 CR 相同)。映射中未列出的组件会使用默认设置启用。
  • spec 根级别的集群默认值 — registry、labels、annotations 和 installFlags 直接位于 spec 下,并作为默认值应用到每个组件。合并优先级为组件值优先——如果同一个键同时在 spec 根级别和组件级别设置,则仅当组件未提供该键时,才回退到 spec 根级别的值。

下面的五个示例覆盖了最常见的自定义场景。关于每个组件的完整 schema,请参考 ConnectorsConfig CRD reference。

禁用组件

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

在 core 上设置 Feature Flags

featureFlags 用于切换 ConnectorsCore 上的可选行为。有关支持的所有 flag 及其作用,请参见 Feature Flags。

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 在本地覆盖,否则该 registry 前缀会应用到每个组件的工作负载镜像。

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

每个组件都嵌入了相同的 workloads schema。Deployment 名称因组件而异;可使用以下命令查找:

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 仍在终止,而受管子资源已经就位。属于迁移期间的正常短暂状态。参见 迁移。
Deleting组件已被禁用或移除,其子 CR 正在删除中。
Failed非短暂性错误阻止了安装(参见 status 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 驱动来说过于严格。请将其设置为 privileged,更新命名空间标签,并重启 connectors-csi DaemonSet。参见 安装所需的 Pod 安全要求。

某个组件卡在 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 获取背景说明。

相关文档