迁移 Zuul V2 CI 任务到 V3

OpenStack CI 系统已从 Zuul v2 迁移到 Zuul v3，所有 CI 任务也已迁移到新的 CI 系统。所有任务都已自动迁移到与 Zuul v3 兼容的格式；但是，以这种方式生成的任务并非最佳，并且未使用 Zuul v3 引入的功能，这些功能允许以 Ansible roles 的形式重用任务部分，以及任务之间的继承。

DevStack 托管一组 roles、plays 和 jobs，其他仓库可以使用它们来定义基于 DevStack 的 jobs。为了充分利用它们，必须将任务从旧的 v2 格式迁移到 v3 原生格式。

本文档提供指导和示例，以使迁移过程尽可能无痛且顺利。

在哪里托管任务定义。

在 Zuul V3 中，任务可以定义在包含它们所执行代码的仓库中。如果您正在为 OpenStack 服务编写 CI 任务，可以将基于 DevStack 的 CI 任务定义在托管服务代码的仓库之一中。如果您有一个无分支仓库，例如 Tempest 插件，那么这将是一个方便的选择来托管任务定义，因为不需要将任务更改回移植。例如，请参阅 sahara Tempest 插件仓库中的 .zuul.yaml 的开头

# In https://opendev.org/openstack/sahara-tests/src/branch/2025.2/.zuul.yaml:
- job:
    name: sahara-tests-tempest
    description: |
      Run Tempest tests from the Sahara plugin.
    parent: devstack-tempest

从哪个基础任务开始

如果您的任务需要通过 DevStack 部署的 OpenStack 云，但您不计划运行 Tempest 测试，可以从 DevStack 仓库中定义的其中一个基础 任务 开始。

devstack 任务可用于单节点任务和多节点任务，并且它包含集成网关中使用的服务列表（keystone、glance、nova、cinder、neutron 和 swift）。可以通过切换子任务中使用的 nodeset 来实现不同的拓扑。

devstack-base 任务类似于 devstack，但它没有指定要在 DevStack 中运行的任何必需的仓库或服务。它可以用于设置使用非常狭窄的 DevStack 设置的子任务。

如果您的任务需要通过 DevStack 部署的 OpenStack 云，并且您计划运行 Tempest 测试，可以从 Tempest 仓库中定义的其中一个基础任务开始。

devstack-tempest 任务可用于单节点任务和多节点任务。可以通过切换子任务中使用的 nodeset 来实现不同的拓扑。

可以按以下方式自定义任务，而无需编写任何 Ansible 代码

• 添加和/或删除 DevStack 服务

• 添加或修改 DevStack 和服务的配置

• 安装 DevStack 插件

• 扩展子节点的数量（仅限多节点）

• 定义要上传到 logs.o.o 的额外的日志文件和/或目录

• 定义要重写为 .txt 以方便访问的额外的日志文件扩展名

Tempest 任务可以进一步自定义如下

• 定义要使用的 Tempest tox 环境

• 定义测试并发性

• 定义测试正则表达式

通过添加预置和/或后置 playbook，或导入现有的自定义 roles 和 jobs，可以进一步扩展任务

• 添加预置和/或后置 playbook

• 覆盖运行 playbook，添加自定义 roles

以下（部分）示例在 Kuryr 仓库中扩展了 Tempest 单节点基础任务“devstack-tempest”。父任务名称在 job.parent 中定义。

# https://opendev.org/openstack/kuryr-kubernetes/src/branch/2025.2/.zuul.d/base.yaml:
- job:
    name: kuryr-kubernetes-tempest-base
    parent: devstack-tempest
    description: Base kuryr-kubernetes-job
    required-projects:
      - openstack/devstack-plugin-container
      - openstack/kuryr
      - openstack/kuryr-kubernetes
      - openstack/kuryr-tempest-plugin
      - openstack/neutron-lbaas
    vars:
      tempest_test_regex: '^(kuryr_tempest_plugin.tests.)'
      tox_envlist: 'all'
      devstack_localrc:
        KURYR_K8S_API_PORT: 8080
      devstack_services:
        kubernetes-api: true
        kubernetes-controller-manager: true
        kubernetes-scheduler: true
        kubelet: true
        kuryr-kubernetes: true
        (...)
      devstack_plugins:
        kuryr-kubernetes: https://opendev.org/openstack/kuryr
        devstack-plugin-container: https://opendev.org/openstack/devstack-plugin-container
        neutron-lbaas: https://opendev.org/openstack/neutron-lbaas
      tempest_plugins:
        - kuryr-tempest-plugin
      (...)

任务变量

可以在三个不同的位置向任务添加变量

• job.vars：这些是 nodeset 中所有节点都可用的全局变量

• job.host-vars.[HOST]：这些变量仅对指定的 HOST 可用

• job.group-vars.[GROUP]：这些变量仅对指定的 GROUP 可用

Zuul 通过任务继承合并字典变量。主机和组变量会覆盖定义为全局变量的同名变量。

在下面的示例中，对于 sundaes 任务，不属于 subnode 组的主机会运行 vanilla 和 chocolate。subnode 组中的主机将运行 stracciatella 和 strawberry。

- job:
    name: ice-creams
    vars:
      devstack_service:
        vanilla: true
        chocolate: false
    group-vars:
      subnode:
        devstack_service:
          pistacchio: true
          stracciatella: true

- job:
    name: sundaes
    parent: ice-creams
    vars:
      devstack_service:
        chocolate: true
    group-vars:
      subnode:
        devstack_service:
          strawberry: true
          pistacchio: false

DevStack 网关标志

旧的 CI 系统使用 DevStack、Tempest 和 devstack-gate 的组合来设置测试环境并对其运行测试。使用 Zuul V3，以前位于 devstack-gate 中的逻辑已移动到不同的仓库，包括 DevStack、Tempest 和 grenade。

Devstack-gate 暴露了一个基于许多 DEVSTACK_GATE_* 环境变量或标志的任务定义接口。本指南说明如何将 DEVSTACK_GATE 标志映射到新系统。

repo 列指示托管替换 devstack-gate 标志的代码的仓库。新实现列解释了如何在 Zuul v3 任务中重现相同或类似的行为。对于 localrc 设置，devstack-gate 定义了一个默认值。在 ansible jobs 中，默认值是父任务中定义的值，或者 DevStack 中的默认值（如果有）。

DevStack 网关标志

DevStack 网关标志	仓库	新实现
OVERRIDE_ZUUL_BRANCH	zuul	在任务定义中 override-checkout: [branch]。
DEVSTACK_GATE_NET_OVERLAY	zuul-jobs	为从 multinode 继承的所有任务设置了一个名为 br-infra 的桥接，并具有一个专门的 桥接 role。
DEVSTACK_CINDER_VOLUME_CLEAR	devstack	任务变量中的 devstack_localrc 中的 CINDER_VOLUME_CLEAR: true/false。
DEVSTACK_GATE_NEUTRON	devstack	默认情况下为 True。要禁用，请在任务定义中的 devstack_services 中禁用所有 neutron 服务。
DEVSTACK_GATE_CONFIGDRIVE	devstack	任务变量中的 devstack_localrc 中的 FORCE_CONFIG_DRIVE: true/false。
DEVSTACK_GATE_INSTALL_TESTONLY	devstack	任务变量中的 devstack_localrc 中的 INSTALL_TESTONLY_PACKAGES: true/false。
DEVSTACK_GATE_VIRT_DRIVER	devstack	任务变量中的 devstack_localrc 中的 VIRT_DRIVER: [virt driver]。
DEVSTACK_GATE_LIBVIRT_TYPE	devstack	任务变量中的 devstack_localrc 中的 LIBVIRT_TYPE: [libvirt type]。
DEVSTACK_GATE_TEMPEST	devstack 和 tempest	由使用的任务定义。 devstack 任务仅运行 devstack。 devstack-tempest 任务也会触发 Tempest 运行。
DEVSTACK_GATE_TEMPEST_FULL	tempest	任务变量中的 tox_envlist: full。
DEVSTACK_GATE_TEMPEST_ALL	tempest	tox_envlist: all 在任务变量中。
DEVSTACK_GATE_TEMPEST_ALL_PLUGINS	tempest	tox_envlist: all-plugin 在任务变量中。
DEVSTACK_GATE_TEMPEST_SCENARIOS	tempest	tox_envlist: scenario 在任务变量中。
TEMPEST_CONCURRENCY	tempest	任务变量中的 tempest_concurrency: [value]。这仅在从 devstack-tempest 继承的任务上可用。
DEVSTACK_GATE_TEMPEST_NOTESTS	tempest	任务变量中的 tox_envlist: venv-tempest。这将创建 Tempest 虚拟环境，但不会运行任何测试。
DEVSTACK_GATE_SMOKE_SERIAL	tempest	任务变量中的 tox_envlist: smoke-serial。
DEVSTACK_GATE_TEMPEST_DISABLE_TENANT_ISOLATION	tempest	任务变量中的 tox_envlist: full-serial。任务变量中的 TEMPEST_ALLOW_TENANT_ISOLATION: false。

以下标志尚未迁移或已过时，将不会迁移。

未迁移的 DevStack 网关标志

DevStack 网关标志	状态	细节
DEVSTACK_GATE_TOPOLOGY	WIP	拓扑取决于使用的基础任务，更具体地说取决于附加到它的 nodeset。新的任务格式允许项目定义传递到拓扑中存在的每个节点/节点组的变量。可以以基础任务的形式定义包含 nodeset 和匹配变量的命名拓扑。
DEVSTACK_GATE_GRENADE	TBD	Grenade Zuul V3 任务将托管在 grenade 仓库中。
GRENADE_BASE_BRANCH	TBD	Grenade Zuul V3 任务将托管在 grenade 仓库中。
DEVSTACK_GATE_NEUTRON_DVR	TBD	取决于多节点支持。
DEVSTACK_GATE_EXERCISES	TBD	可以按需完成。
DEVSTACK_GATE_IRONIC	TBD	这可能将在 ironic 侧实现。
DEVSTACK_GATE_IRONIC_DRIVER	TBD	这可能将在 ironic 侧实现。
DEVSTACK_GATE_IRONIC_BUILD_RAMDISK	TBD	这可能将在 ironic 侧实现。
DEVSTACK_GATE_POSTGRES	已过时	此标志存在于 d-g 中，但它所做的只是捕获 postgres 日志。这已经由 post 中的 roles 支持，因此该标志在新的 jobs 中无用。postgres 本身可以通过 devstack_service 任务变量启用。
DEVSTACK_GATE_ZEROMQ	已过时	这在 d-g 中没有效果。
DEVSTACK_GATE_MQ_DRIVER	已过时	这在 d-g 中没有效果。
DEVSTACK_GATE_TEMPEST_STRESS_ARGS	已过时	Stress 不在 Tempest 中了。
DEVSTACK_GATE_TEMPEST_HEAT_SLOW	已过时	这在任何地方都没有使用。
DEVSTACK_GATE_CELLS	已过时	这在 d-g 中没有效果。
DEVSTACK_GATE_NOVA_API_METADATA_SPLIT	已过时	这在 d-g 中没有效果。