Migrating managed controllers and team controllers

2 minute read

It is not possible to transform a managed controller into a team controller(or a team controller into a managed controller), so the migration path is based on the CloudBees CI feature Move/Copy.

Although this guide points to Move and Copy as equivalent methods of migration, it is strongly recommended to use Copy, so a version of the original item is always available as a recovery backup.

Even after a successful migration, the original controller should be kept around for validation and recovery purposes. As there are manual steps in the migration, it is possible to forget replicating some required items (credentials or global configuration usually) so having the original controller at hand is going to be useful. The Backup Plugin would be also helpful to keep a full backup of the original controller.

Before starting the migration

  • This guide explains the process to migrate a managed controller to a team controller, however, the same process can be used to migrate a team controller to a managed controller.

  • This process applies to CloudBees CI on modern cloud platforms only.

The starting point is a CloudBees CI cluster where a managed controller (to be migrated) is connected to operations center. The team controller has been created in the same cluster so it is connected to the same operations center.

Also make sure the team controller is aligned in terms of plugins with the managed controller (the Move or Copy dialog shows a warning about this in any case).

The migration

Pipelines often use peripheral data (such as credentials, shared libraries, tools configuration, etc) which is outside the Pipeline definition itself, so a different migration process is required for the migration of this data.

Migrate credentials

Pipelines often use credentials defined in CloudBees CI. Those credentials need to be migrated separately (unless they are defined in the folder containing the Pipelines).

  • Folder scoped credentials: nothing to do, the Move/Copy operation takes care of them.

  • CloudBees CI (top level) scoped credentials: manual migration is needed, either recreate them in the folder before moving/copying it or recreate them in the team controller.

Migrate Pipelines

Use the Move/Copy CloudBees CI feature to move pipelines to the appropriate folders associated with the targeted team controller or managed controller.

These folders associated with the targeted controller are automatically created and contain all Pipelines and Team configuration. If your target is a team controller, make sure the pipelines are moved/copied into the Team Folder on the team controller. The Team Folder is at the root level on the team controller and its name is the same as the team controller name.

If you migrated to a team controller, the migrated items should be visible in your new Team now:

Global configuration

Any CloudBees CI global configuration (i.e anything under Manage Jenkins) which affects Pipeline execution has to be manually migrated. For example, Tools Configuration (Maven, JDK, etc) or Configure System settings (i.e. global GitHub or Bitbucket configuration).