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