将 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 的差异按集群,而非全平台凭证就是访问边界凭证在原地签发、受作用域限制,并通过 Secretless 方式使用开始前准备迁移如何工作各工具的映射方式示例:迁移前后的 GitLab integration实施准备配置和凭证运行迁移迁移某个项目的 integrations迁移平台的 auto-assignment policies验证结果命令参考配置参考示例常见问题相关阅读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 的方式访问工具,而无需自行处理凭证。
一览:
开始前准备
请准备以下内容:
- Tekton Pipelines 已安装在运行迁移的集群上——迁移由 Tekton pipeline 执行。
- Connectors 系统及 connectors components(
ConnectorsGitLab、ConnectorsHarbor、ConnectorsSonarQube、ConnectorsNexus,取决于你要迁移哪些内容)已安装在目标集群上。参见 安装 Connectors Operator。 - 每个 connectors component 的 Connector Automatic Creation Task 已安装在运行迁移 pipeline 的 namespace 中:
- 工作站上可用
int2connCLI 和kubectl。
迁移如何工作
每个 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 及其新签发的凭证。
你需要针对每个 ACP 项目和目标集群运行一次 migrate。
各工具的映射方式
示例:迁移前后的 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(在下面的
kubeconfigmap 中引用)——用于在该集群上创建 Connectors 和 Secrets。其所需权限在同样的 Automatic Creation Task 指南中有说明。
请在迁移前刚刚准备好这些 Connectors,并在验证完成后将其移除。移除它们不会撤销 Tasks 已经签发出的受作用域限制凭证——这些凭证会继续独立存在。
配置。 一个单独的文件用于引用这些 Connectors,并告诉 pipeline 在哪里运行:
这两类 map 的 key 不同,请注意区分:
- 工具 map(
gitlab、harbor、sonarqube、nexus)按 tool host 作为 key——请严格按 v3 integration 地址中出现的 host 来填写,例如devops-gitlab.example.com或gitlab.acme.com:8080。 kubeconfigmap 按 target-cluster 名称 作为 key——也就是你传给--target-cluster的值。
请直接从 v3 integration 的地址中读取 host(以及端口,如果有),这样 map key 才能完全匹配:
上面的最小配置已经足够启动;凭证作用域会使用最小权限默认值。关于每个字段的含义——命名模板、按项目的 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。
对于该项目和该集群,结果将是一个 Pipeline 加上一个 PipelineRun,用于创建该项目的 v4 Connectors。你可以通过 --namespaces a,b 传入多个项目,通过不同的 --target-cluster 迁移到另一个集群,或者通过 --migrate-class harbor 仅限于某一个工具。
迁移平台的 auto-assignment policies
迁移这部分不会为任何现有项目创建 Connectors。相反,请运行:
这会生成一个 Pipeline,它将 ACP project 名称作为参数。在创建 ACP project 之后,请针对该项目运行这个 Pipeline 以初始化其 Connectors——它创建的内容对应原始 v3 的 auto-assignment rules。在这种模式下,--namespaces 和 --run 不适用,而 --target-cluster 是必需的。
你可以通过配置中的可选 autoAssignment 块来调整 auto-assignment policies 授予的权限:
验证结果
当满足以下条件时,迁移即成功:
-
命令以退出码
0结束。 -
目标集群上预期的 v4 Connectors 处于
Ready和AuthReady状态(说明新签发的凭证可用): -
新签发的凭证在工具侧可见——例如 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 已被应用:
只有在你针对某个项目运行该 Pipeline 后,Connectors 才会出现。
命令参考
migrate 是大多数用户需要使用的命令。
高级用法:migrate 由四个子命令组成——dump、analyze、execute 和 verify——你可以分别运行它们,以获得更细粒度的控制,例如将只读 audit 集群上的 dump 和目标集群上的 execute 分开执行。运行任一子命令时加上 --help 可查看其标志。
配置参考
配置是一个单独的 YAML 文件。pipeline.namespace 为必填项。pipeline.connectors 的各个 map 仅在某次迁移实际使用到相应工具和目标集群时才是必需的——缺失条目会在迁移运行时报告,而不是在加载时报告。其他所有字段都有默认值。
顶层
analyze / verify
Connector 命名
默认模板使用 {hostTag}(host 的短标签)和 {group}(GitLab group path);{tool}、{host}、{project} 和 {sourceName} 也可用。生成的名称是下游消费者引用的稳定标识符,因此请谨慎修改。
pipeline
autoAssignment(仅在 auto-assignment 模式下使用)
projects——一个以 ACP project 名称为 key 的 map,用于按项目覆盖
示例
常见问题
哪些工具类型可以迁移?
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,而不会创建重复项。