将 v3 Integrations 迁移到 Connectors

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

int2conn 是供实施团队使用的命令行 helper。对于一个 ACP 项目,它会读取现有的 v3 integrations,并在目标集群上将它们重新创建为 v4 Connectors,同时要求每个目标工具为每个 Connector 生成一个新的、最小权限的凭证。它替你承担重复性工作;请将它视为迁移辅助工具,而不是完全自动化的切换工具,迁移过程仍然需要你主导并审阅。

Connectors 与 v3 Integrations 的差异

迁移的目标是重新创建你现有 integrations 的意图,而不是逐字段复制。三个差异决定了每一次迁移的决策。

按集群,而非全平台

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

凭证就是访问边界

在 v3 中,项目能够访问哪些资源由平台的 resource allocation 决定。在 v4 中,不再有单独的分配步骤:Connector 的访问范围完全由其凭证的作用域决定,因此每个项目都通过其自身凭证的作用域实现隔离。

凭证在原地签发、受作用域限制,并通过 Secretless 方式使用

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

一览:

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

开始前准备

请准备以下内容:

迁移如何工作

每个 connectors component 都会随附一个 Connector Automatic Creation Task——一个 Tekton Task,它会与工具通信、签发受作用域限制的凭证,并创建匹配的 v4 Connector 及其 Secret。int2conn 不会直接创建 Connectors;它是驱动这些 Tasks 来完成创建。

对于一个 ACP 项目和一个目标集群,migrate 会读取该项目的 v3 integrations,将其分析为需要创建的 Connectors 集合,并渲染一个 Tekton Pipeline,把每个工具对应的正确 Task 串联起来。运行该 Pipeline——即 PipelineRun——才会在目标集群上创建 Connectors 及其新签发的凭证。

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某个 host 上的所有 project每个 Harbor host 对应一个 Connector(一个 robot account 可以跨该 host 上的多个 project)
SonarQube每个 (project, host) 对每个 host 对应一个 Connector,其 project pattern 由项目的 GitLab groups 派生(也可以由你配置)
Nexus某个 host 上的所有 repository每个 host 对应一个 Connector,聚合该 host 的 repositories(这些 repositories 必须已经存在于目标 Nexus 中)

示例:迁移前后的 GitLab integration

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

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

Harbor 的情况不同,因为一个 robot account 可以覆盖某个 host 的多个 project:某个集成了 harbor.example.com 上三个 Harbor project 的项目会变成 一个 Connector,它由一个单独的 robot account 支撑,该账号可以拉取(默认只读)这三个 project。SonarQube 和 Nexus 也同样会收敛为每个 host 一个 Connector。

实施

准备配置和凭证

迁移 pipeline 会运行工具的 Automatic Creation Tasks,而这些 Tasks 需要两类凭证:一类是每个工具使用的凭证(用于签发受作用域限制的凭证),另一类是 kubeconfig(用于在目标集群上创建 Connectors)。你需要将两者都作为 Connectors 提供,并在一个配置文件中引用它们。

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

  • 每个工具 host 一个 Connector——其凭证会被 Task 用来在该工具上签发受作用域限制的凭证。每个工具的 Automatic Creation Task 指南(在 开始前准备 中链接)列出了该凭证所需的确切权限。
  • 每个目标集群一个 Kubernetes Connector(在下面的 kubeconfig map 中引用)——用于在该集群上创建 Connectors 和 Secrets。其所需权限在同样的 Automatic Creation Task 指南中有说明。
保持这些凭证的短生命周期

请在迁移前刚刚准备好这些 Connectors,并在验证完成后将其移除。移除它们不会撤销 Tasks 已经签发出的受作用域限制凭证——这些凭证会继续独立存在。

配置。 一个单独的文件用于引用这些 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 的 key 不同,请注意区分:

  • 工具 map(gitlab、harbor、sonarqube、nexus)按 tool host 作为 key——请严格按 v3 integration 地址中出现的 host 来填写,例如 devops-gitlab.example.com 或 gitlab.acme.com:8080。
  • kubeconfig map 按 target-cluster 名称 作为 key——也就是你传给 --target-cluster 的值。

请直接从 v3 integration 的地址中读取 host(以及端口,如果有),这样 map key 才能完全匹配:

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

上面的最小配置已经足够启动;凭证作用域会使用最小权限默认值。关于每个字段的含义——命名模板、按项目的 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 project 名称作为参数。在创建 ACP project 之后,请针对该项目运行这个 Pipeline 以初始化其 Connectors——它创建的内容对应原始 v3 的 auto-assignment rules。在这种模式下,--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 状态(说明新签发的凭证可用):

    kubectl get connector -n my-project
  • 新签发的凭证在工具侧可见——例如 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 project 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""用于周期性凭证轮换的 Cron 表达式。为空表示一次性迁移(不创建 ScheduledTrigger)。可由单个项目的值覆盖。

analyze / verify

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

Connector 命名

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

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

pipeline

字段默认值含义
pipeline.namespace(必填)运行迁移 Pipeline / PipelineRun 的 namespace;也请在此准备所引用的 Connectors。
pipeline.connectors.gitlab / .harbor / .sonarqube / .nexus(按你要迁移的工具分别必填)tool host → "<namespace>/<name>" 的 map,其中该 Connector 的凭证用于为该 host 签发受作用域限制的凭证。
pipeline.connectors.kubeconfig(你使用的目标集群必填)target-cluster 名称(即 --target-cluster 的值) → "<namespace>/<name>" 的 map,其中的 Kubernetes Connector 用于在该集群上创建 Connectors。
pipeline.taskParams.gitlab / .harbor / .sonarqube / .nexustask 默认值以 Tekton 风格 {name, value} 表示的参数,会转发给每个工具的 Automatic Creation Task——可用它们覆盖某个 task 默认值,例如 token 生命周期。可用参数列在各自 task 的指南中;其中一些会自动设置,无法覆盖。默认值为最小权限,因此大多数迁移不需要设置这些参数。

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

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

projects——一个以 ACP project 名称为 key 的 map,用于按项目覆盖

字段默认值含义
projects.<name>.schedule全局 schedule覆盖某个项目的轮换 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 或特定解决方案插件)都不会迁移;它们会保留在计划中,因此不会被静默丢弃。

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

如何将同一个项目迁移到多个集群?
针对每个目标集群分别运行一次 migrate,并使用 kubeconfig map 中对应的那一行。每个集群都会获得自己的 Connectors 和自己的凭证,因此彼此独立。

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

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

重复运行一次迁移是否安全?
安全。Pipeline 和 Connector 名称是确定性的,因此重复运行会对现有资源进行 reconcile,而不会创建重复项。