将 v3 Integrations 迁移到 Connectors

当你从 Alauda DevOps v3 迁移到 v4 时,项目所依赖的工具集成——GitLab、Harbor、SonarQube 和 Nexus——需要以 v4 形式重新建立。v3 将它们建模为 Integration / ClusterIntegration 资源;v4 则将工具访问建模为 Connectors。由于这两种模型对工具访问的描述方式不同,因此迁移并不是一一对应的转换。

int2conn 是面向实施团队的命令行 helper。对于 ACP 项目,它会读取现有的 v3 集成,并在目标集群上将它们重新创建为 v4 Connectors,同时要求每个目标工具为每个 Connector 签发一个新的、最小权限的 credential。它会替你处理重复性工作;请将其视为迁移辅助工具,迁移过程仍由你主导并审查,而不是完全自动切换。

Connectors 与 v3 Integrations 的差异

迁移会重新创建你的集成的 意图,而不是逐字段复制。下面三点差异决定了每一次迁移。

按集群划分,而不是平台级共享

在 v3 中,integration 由 platform-project 级别拥有,并由项目覆盖的所有集群共享。在 v4 中,Connector 属于特定集群,并且存在于三种作用域之一——集群级、在该集群上跨项目的 namespaces 共享,或单个 namespace。由于不同集群可能有不同需求,因此你需要一次迁移一个目标集群,并按集群决定是否迁移以及要带哪些 integrations。

credential 就是访问边界

在 v3 中,项目能够访问哪些资源由平台 resource allocation 决定。在 v4 中,没有单独的分配步骤:Connector 的访问范围完全取决于它的 credential 所限定的范围,因此每个项目都通过其自身 credential 的范围实现隔离。

credential 在原地签发、按范围限定,并且 Secretless

在 v3 中,credential 在创建 integration 时进行配置。在 v4 中,int2conn 会判断每个 integration 覆盖了哪些资源,并要求工具 签发一个仅限定于这些资源的新 credential——你现有的 v3 secrets 从不会被读取或带入。随后,消费端 Pod 通过 Connectors Proxy 和 CSI Driver 以 Secretless 方式访问该工具,而无需自行处理 credential。

快速对比:

方面v3 Integrationv4 Connector
集群作用域由 platform-project 级别拥有,并在项目的各个集群之间共享属于单个集群(集群级、项目级或 namespace 级)
租户隔离项目的访问由平台 resource allocation 管理每个项目都通过其 Connector 自身的 credential 范围实现隔离
credential在创建 integration 时配置为每个 Connector 重新签发、最小权限,并通过 Proxy / CSI 以 Secretless 方式提供

开始之前

请准备以下内容:

迁移如何工作

每个 connectors 组件都会提供一个 Connector Automatic Creation Task——这是一个 Tekton Task,用于与工具通信、签发限定范围的 credential,并创建对应的 v4 Connector 及其 Secret。int2conn 不会直接创建 Connectors;它会驱动这些 Task。

对于一个 ACP 项目和一个目标集群,migrate 会读取该项目的 v3 integrations,将其分析为需要创建的 Connectors 集合,并生成一个 Tekton Pipeline,为每个工具连接正确的 Task。运行该 Pipeline——即 PipelineRun——才会在目标集群上创建 Connectors 及其新签发的 credential。

v3 integrations  ──►  int2conn migrate  ──►  Tekton Pipeline + PipelineRun  ──►  v4 Connectors
   (read)             (read → analyze →        (runs each tool's Automatic        (+ freshly minted
                       render pipeline)          Creation Task)                     scoped credentials)

你需要针对每个 ACP 项目和目标集群运行一次 migrate。

每种工具的映射方式

工具v3 来源v4 结果
GitLab每个拥有的 group每个 group 一个 Connector——任意层级的 subgroup 都会成为自己的 Connector;显式集成的 repository 会映射到其所在的 group
Harbor主机上的所有项目每个 Harbor 主机一个 Connector——一个 robot account 可以跨越该主机上的多个项目
SonarQube每个 (project, host) 对每个主机一个 Connector,project pattern 由项目的 GitLab groups 推导而来(或者由你自行配置)
Nexus主机上的所有 repositories每个主机一个 Connector,聚合该主机的 repositories(这些 repositories 必须已存在于目标 Nexus 中)

示例:迁移前后的 GitLab integration

假设某个 ACP 项目在 v3 中集成了 GitLab group acme/backend 及其 subgroup acme/backend/api,两者都通过一个共享的平台 credential 访问。

迁移后,该项目在目标集群上会有 两个 GitLab Connectors——一个对应 acme/backend,一个对应 acme/backend/api——因为 GitLab Group Access Token 不能跨 group 使用。每个 Connector 都由其自己的 Group Access Token 提供支持,该 token 仅在对应 group 上签发,并且只限定于该 group 的 repository 读/写访问,而不是像 v3 integration 那样使用单个共享 credential。

Harbor 的情况不同,因为 robot account 可以跨越一个主机上的多个项目:某个在 harbor.example.com 上集成了三个 Harbor 项目的项目,迁移后会变成 一个 Connector,由一个 robot account 提供支持,该 account 可以拉取(默认只读)这三个项目。SonarQube 和 Nexus 也同样会收敛为每个主机一个 Connector。

实现

准备配置和 credentials

迁移 pipeline 会运行工具的 Automatic Creation Tasks,而这些 Task 需要两类 credential:每个工具各一个 credential(用于签发限定范围的 credentials),以及一个 kubeconfig(用于在目标集群上创建 Connectors)。你需要将它们都以 Connectors 的形式提供,并在一个配置文件中引用它们。

Pipeline 需要的 Connectors。 请在一个隔离的 namespace 中准备这些内容——也就是你在下面设置为 pipeline.namespace 的那个 namespace:

  • 每个工具主机一个 Connector——其 credential 会被 Task 用来在该工具上签发限定范围的 credentials。每个工具的 Automatic Creation Task 指南(链接见 开始之前)会列出该 credential 所需的精确权限。
  • 每个目标集群一个 Kubernetes Connector(由下面 kubeconfig map 引用)——用于在该集群上创建 Connectors 和 Secrets。它所需的权限也在相同的 Automatic Creation Task 指南中有说明。
保持这些 credentials 短生命周期

请在迁移前不久准备这些 Connectors,并在确认完成后将其移除。移除它们不会撤销 Task 已经签发出来的 scoped credentials——这些 credentials 会独立存在。

配置。 单个文件会引用这些 Connectors,并告诉 pipeline 在哪里运行:

# config.yaml
schedule: ""                               # optional cron for periodic credential rotation; empty = one-time

pipeline:
  namespace: integration-migration-mgr     # where the migration Pipeline / PipelineRun run

  connectors:
    # Per tool host -> the Connector for that host ("<namespace>/<name>").
    gitlab:
      devops-gitlab.example.com: integration-migration-mgr/migrate-gitlab
    harbor:
      devops-harbor.example.com: integration-migration-mgr/migrate-harbor
    # add sonarqube: / nexus: in the same shape when migrating those tools

    # Per target-cluster name (the value of --target-cluster) -> the Kubernetes Connector.
    kubeconfig:
      global: integration-migration-mgr/migrate-kubeconfig

这两类 map 的键不同,请务必区分:

  • 工具 map(gitlab、harbor、sonarqube、nexus)以工具主机为键——请按 v3 integration 地址中出现的原样写入主机名,例如 devops-gitlab.example.com 或 gitlab.acme.com:8080。
  • kubeconfig map 以目标集群名称为键——也就是你传给 --target-cluster 的值。

请直接从 v3 integration 的地址中读取其主机(以及端口,如果有),确保 map 的键完全匹配:

kubectl get integration <name> -n <project-namespace> -o jsonpath='{.spec.address.url}'

上面的最小配置已经足够开始;credential scopes 使用的是最小权限默认值。关于每个字段的含义——命名模板、按项目的 schedule 和 SonarQube patterns、taskParams 以及 auto-assignment 块——请参见 配置参考。

运行迁移

你可以迁移两类内容:项目自己的 integrations,以及平台的 auto-assignment policies——这些是 v3 中会自动将工具资源分配给项目的规则(例如同名分配或 public-project 分配)。两者都会在目标集群上生成 Tekton 资源,但运行方式不同,具体如下。

将 kubectl 指向运行 pipeline 的集群,或者传入 --pipeline-kubeconfig;v3 integrations 会从你当前的 kubectl context 中读取,或者从 --source-kubeconfig 中读取,而后者可以指向与目标不同的集群。

迁移项目的 integrations

这会重新创建 ACP 项目已经拥有的 integrations——请传入项目 namespaces 和目标集群。不带 --run 运行时,会应用 Pipeline 以便你审查将要执行的内容;添加 --run 则会创建执行迁移的 PipelineRun。只有这种项目 integration 模式支持 --run。

# Apply the Pipeline so you can review what will run — nothing is migrated yet.
int2conn migrate --config config.yaml --namespaces my-project --target-cluster global

# Create the PipelineRun and perform the migration.
int2conn migrate --config config.yaml --namespaces my-project --target-cluster global --run

对于该项目和该集群,结果将是一个 Pipeline 加上一个 PipelineRun,用于创建该项目的 v4 Connectors。你可以通过 --namespaces a,b 迁移多个项目,通过不同的 --target-cluster 迁移到另一个集群,或者使用 --migrate-class harbor 仅限于一种工具。

迁移平台的 auto-assignment policies

迁移这些内容不会为任何现有项目创建 Connectors。相反,请运行:

int2conn migrate --mode auto-assignment --config config.yaml --target-cluster global

这会生成一个 Pipeline,并将 ACP 项目名称作为参数传入。在创建 ACP 项目后,请针对该项目运行这个 Pipeline,以初始化它的 Connectors——其创建结果对应于原始的 v3 auto-assignment 规则。在此模式下,--namespaces 和 --run 不适用,并且必须提供 --target-cluster。

你可以通过配置中的可选 autoAssignment 块来调整 auto-assignment policies 授予的权限:

autoAssignment:
  harbor:
    # Robot permissions for a tenant's own ("private") projects — includes push.
    privatePermissions: "repository:read,list,pull,push;tag:list;artifact:list,read"
    # Robot permissions for shared / public ("attribute-based") projects — read-only.
    attributeBasedPermissions: "repository:read,list,pull;tag:list;artifact:list,read"

验证结果

当满足以下条件时,迁移即成功:

  • 命令以退出码 0 结束。

  • 目标集群上预期的 v4 Connectors 处于 Ready 和 AuthReady 状态(签发的 credential 可用):

    kubectl get connector -n my-project
  • 新签发的 credential 在工具侧可见——例如 GitLab group 下 Settings → Access Tokens 中的 GitLab Group Access Token、Harbor robot account、SonarQube user token,或 Nexus user。

migrate --run 会等待 PipelineRun 完成,然后验证 Connectors 并报告结果。

对于 auto-assignment 迁移,此时还没有 Connectors——你需要确认的是该项目参数化的 Pipeline 已经被应用:

kubectl get pipeline -n integration-migration-mgr

只有在你为某个项目运行该 Pipeline 之后,才会出现它的 Connectors。

命令参考

migrate 是大多数用户需要使用的命令。

标志是否必需用途
--config是迁移配置文件的路径。
--namespaces是(integration 模式)逗号分隔的 ACP 项目 namespaces,表示要迁移哪些项目。在 auto-assignment 模式下不使用。
--target-cluster是目标集群名称;用于选择 kubeconfig map 中的条目。
--run否不带此参数时,会应用 Pipeline 资源,供你审查;带上此参数时,会创建 PipelineRun(执行迁移),在设置了 schedule 时还会应用 ScheduledTrigger,并等待运行结束后进行验证。
--pipeline-kubeconfig否运行 pipeline 的集群所使用的 kubeconfig。若未提供,则回退到标准的 kubectl discovery chain。
--source-kubeconfig否v3 源集群所使用的 kubeconfig(只读)。若未提供,则回退到标准的 kubectl discovery chain。
--migrate-class否要包含的工具(逗号分隔):gitlab、harbor、sonarqube、nexus。不指定则迁移全部。
--mode否integration(默认)迁移项目的 integrations;auto-assignment 迁移平台策略。在 auto-assignment 模式下,不接受 --namespaces 和 --run,并且必须提供 --target-cluster。

高级用法:migrate 由四个子命令组合而成——dump、analyze、execute 和 verify——你可以分别运行它们以获得更细粒度的控制,例如将只读的 audit 集群与目标集群分开进行 dump 和 execute。运行任一子命令时加上 --help 可查看其参数。

配置参考

配置是单个 YAML 文件。pipeline.namespace 是必需的。pipeline.connectors 这些 map 仅在迁移实际使用到的工具和目标集群上才是必需的——缺少条目会在迁移运行时报告,而不是在加载时报告。其他所有字段都有默认值。

顶层

字段默认值含义
schedule""用于周期性 credential rotation 的 Cron 表达式。为空表示一次性迁移(不创建 ScheduledTrigger)。可由按项目的值覆盖。

analyze / verify

字段默认值含义
analyze.includeUnhealthyfalse同时迁移健康状态不是 healthy 的 v3 integrations。默认情况下,这些内容会被排除。
verify.skipConnectorReadyfalse在 PipelineRun 成功后就停止验证,而不等待每个 Connector 都变为 AuthReady。当 Connector 调谐较慢或外部工具短暂不可达时,这很有用。

Connector 命名

字段默认值含义
gitlab.connectorNameTemplate{hostTag}-{group}生成 GitLab Connectors 的名称模板。
harbor.connectorNameTemplate{hostTag}生成 Harbor Connectors 的名称模板。

默认模板使用 {hostTag}(主机的短标识)和 {group}(GitLab group 路径);{tool}、{host}、{project} 和 {sourceName} 也可用。生成的名称是下游消费者引用的稳定标识,因此修改时请谨慎。

pipeline

字段默认值含义
pipeline.namespace(必需)迁移 Pipeline / PipelineRun 运行所在的 namespace;同时也要在这里准备所引用的 Connectors。
pipeline.connectors.gitlab / .harbor / .sonarqube / .nexus(按你迁移的工具分别必需)工具主机 → 该主机对应 Connector 的 "<namespace>/<name>" 映射;该 Connector 的 credential 用于为该主机签发限定范围的 credentials。
pipeline.connectors.kubeconfig(你使用的目标集群必需)目标集群名称(即 --target-cluster 的值) → 用于在该集群上创建 Connectors 的 Kubernetes Connector 的 "<namespace>/<name>" 映射。
pipeline.taskParams.gitlab / .harbor / .sonarqube / .nexustask 默认值以 Tekton 风格 {name, value} 表示的参数,会传递给每个工具的 Automatic Creation Task——可用来覆盖 task 默认值,例如 token 的生命周期。可用参数在各自 task 的指南中列出;其中一些参数会自动设置,不能覆盖。默认值为最小权限,因此大多数迁移都不需要配置。

autoAssignment(仅在 auto-assignment 模式下使用)

字段默认值含义
autoAssignment.harbor.privatePermissionstask 默认值Harbor robot 针对租户自己的(“private”)项目的权限——包括 push。
autoAssignment.harbor.attributeBasedPermissionstask 默认值Harbor robot 针对共享 / public(“attribute-based”)项目的权限——只读。

projects——以 ACP 项目名为键的 map,用于按项目覆盖配置

字段默认值含义
projects.<name>.schedule全局 schedule覆盖某一个项目的 rotation cron。
projects.<name>.sonarProjectPattern自动推导当自动推导出的 pattern 不符合预期时,覆盖某一个项目的 SonarQube projectPattern。

示例

# Migrate one ACP project's integrations to the Connectors on the global cluster.
int2conn migrate --config config.yaml --namespaces my-project --target-cluster global --run

# Migrate several projects at once.
int2conn migrate --config config.yaml --namespaces my-project,team-devops --target-cluster global --run

# Migrate a project to a business cluster instead of global.
int2conn migrate --config config.yaml --namespaces my-project --target-cluster biz-1 --run

# Migrate only the Harbor integrations of a project.
int2conn migrate --config config.yaml --namespaces my-project --target-cluster global --migrate-class harbor --run

# Read the v3 data from a separate source cluster.
int2conn migrate --config config.yaml --namespaces my-project --target-cluster global \
  --source-kubeconfig ~/.kube/v3-cluster --run

常见问题

可以迁移哪些工具类型? GitLab、Harbor、SonarQube 和 Nexus。其他任何类型的 integrations(例如 JFrog、GitHub,或某些解决方案特定的插件)都不会迁移;它们会显示在 plan 中,因此不会被静默丢弃。

我的项目集成了多个 GitLab 或 Harbor 实例,支持吗? 支持。工具 map 以 host 为键,因此每个 host 都会成为自己的 v4 Connector,并且原始的 host-to-resource 映射会被保留。

如何将同一个项目迁移到多个集群? 针对每个目标集群分别运行一次 migrate,并在 kubeconfig map 中使用对应的条目。每个集群都会拥有自己的 Connectors 和自己的 credential,因此它们彼此独立。

迁移后如何轮转 credentials? 在配置中设置 schedule,并使用 --run 运行。迁移随后会生成一个 ScheduledTrigger,按该 cron 重新运行 pipeline,每次都会签发一个新的 credential;在成功运行后,Connector 会继续提供轮转后的 credential。

Connector 不是 Ready / AuthReady,或者没有创建工具 credential。我该检查什么? 查看迁移 PipelineRun(以及其 TaskRun)在 pipeline 集群上的日志。常见原因是配置中的 host 键与 v3 integration 地址并不完全匹配,或者某个 Connector 的 credential 缺少 Task 所需的权限。

重复运行一次迁移安全吗? 安全。Pipeline 和 Connector 的名称是确定性的,因此重复运行只会重新调谐现有资源,而不会创建重复项。