Migrate from CloudBees CI on traditional platforms to CloudBees CI on modern cloud platforms

11 minute read

There are several advantages to migrating your workloads from CloudBees CI on traditional platforms to CloudBees CI on modern cloud platforms, such as modernizing your workloads and pipelines using Kubernetes and helping administrators to manage and scale growing installations due to ever-increasing teams, projects, and jobs.

There are different migration paths available based on your unique needs, and the migration does not have to be done all at the same time. For example, you could perform the migration in “chunks,” which would allow some workloads and pipelines to continue to use static agents, while others begin to use Kubernetes agents.

Prepare for the migration

Before migrating, CloudBees recommends that you complete the following steps to prepare for the migration:

  1. Determine your migration path.

  2. Plan for the migration.

  3. Determine the Java version.

  4. Install recommended plugins.

  5. Split monolithic environments.

  6. Consider your organizational approach.

  7. Generate a support bundle.

Determine your migration path

The following migration paths are available:

  • Basic migration: For the basic migration, you are going to install CloudBees CI on modern cloud platforms and migrate the client controllers to managed controllers, but continue to use static agents and your existing pipelines.

  • Intermediate migration: When performing an intermediate migration, you are going to install CloudBees CI on modern cloud platforms and connect your existing client controllers, pipelines, and static agents, but also begin using managed controllers. However, there is a subset of your workload that can be modernized since you are running in Kubernetes, and you can slowly migrate over time by modernizing your controllers and agents in “chunks.”

  • Advanced migration: Performing an advanced migration requires a complete rearchitecting of your pipelines and agents. You must migrate from CloudBees CI on traditional platforms, where you are accustomed to using client controllers and static agents with all tools in one place, to CloudBees CI on modern cloud platforms with managed controllers, a model of a pod template with multiple containers, and a pipeline that is orchestrated across those containers.

Plan for the migration

Your team should first review the following information, to gain a better understanding of modern environments and to plan for the migration:

Determine the Java version

The primary consideration with the Java version is agent connectivity. If you are planning to continue to use static agents in CloudBees CI on modern cloud platforms, you must perform any necessary Java upgrades in CloudBees CI on traditional platforms, prior to migrating to CloudBees CI on modern cloud platforms. For more information, refer to Migrate to Java 17.

Before starting the migration, CloudBees recommends that you install the following plugins.

  1. Install the CloudBees Inactive Items Plugin to the client controller prior to migration, to clean up the source environment before moving to the managed controller. For more information, refer to CloudBees Inactive Items Plugin.

  2. Install the Health Advisor by CloudBees Plugin on the client controller, to help in identifying existing known issues and clean them up before the migration. For more information, refer to Quiet start.

  3. Install the CloudBees Quiet Start Plugin (either on the client controller prior to the backup or on the managed controller during the migration), to ensure that builds do not start automatically when CloudBees CI on modern cloud platforms is placed online. This is especially useful when restoring the client controller backup to the managed controller. For more information, refer to Jenkins Health Advisor by CloudBees.

Split monolithic environments

If you have a monolithic client controller in CloudBees CI on traditional platforms, you should split the controller before starting the migration. For implementation details, refer to Split a controller in CloudBees CI on traditional platforms.

Consider your organizational approach

When using client controllers, it is common to organize items at a folder-level. When migrating, especially if moving from a monolithic environment, you should consider organizing at a managed controller-level instead. For example:

  • Use Multibranch Pipelines to automatically create Pipelines based on branches and pull requests in your repository. For more information refer to Managing Multibranch Pipeline options in template.yaml.

  • Create a GitHub Organization project to create a Multibranch Pipeline for each repository in an organization. This Multibranch Pipeline then creates a separate project for each branch that contains a Jenkinsfile in the top level directory. For more information, refer to Create a GitHub Organization project.

Generate a support bundle

Before upgrading, CloudBees recommends that you generate a support bundle on the client controller. For more information, refer to Generating a support bundle.

Perform the migration

Complete the following steps, based on your type of migration:

Perform a basic migration

For the basic migration, you are going to install CloudBees CI on modern cloud platforms and migrate the client controllers to managed controllers, but continue to use static agents and your existing pipelines.

To perform a basic migration:

  1. Install CloudBees CI on modern cloud platforms. This must be the same product version that you are already running in CloudBees CI on traditional platforms.

    Special care must be taken to consider which Kubernetes versions your destination product version can run on, and if that Kubernetes version is supported by your Kubernetes vendor. For more information, refer to Supported platforms for CloudBees CI on modern cloud platforms.

  2. Provision a managed controller based on your configuration. Note that you must provision the managed controller with:

    • The appropriate memory and CPU for your intended workload.

      The amount of memory required can depend on:

      • The number of jobs you are migrating from the client controller to the managed controller.

      • Whether you enable High Availability (active/active), because it allows you to have multiple replicas running a monolithic workload.

      • Whether you use Horizontal Scalability (HS) and a Kubernetes autoscaler to scale up more nodes. This provides the ability to run larger controllers with less risk of outage and better scaling across controllers. For more information about managed controller sizing guidelines, refer to Cluster sizing and scaling.

    • The relevant JVM arguments. For example:

      • Some of the system properties that were enabled on the client controller have to be migrated.

      • You must update the heap memory JVM argument. In CloudBees CI on modern cloud platforms, this is specified as a ratio of the pod memory size.

  3. Use the CloudBees Backup Plugin to back up the client controllers in CloudBees CI on traditional platforms. For more information, refer to Using the CloudBees Backup plugin.

  4. Use the CloudBees Backup Plugin to restore the client controller backup onto a managed controller in CloudBees CI on modern cloud platforms. For more information, refer to Restoring from the CloudBees Backup Plugin.

  5. Connect the static agents in CloudBees CI on modern cloud platforms. The type of agent you use may depend on network connectivity, and whether the agents are network addressable. Both agent types are equivalent in terms of performance and functionality.

Intermediate migration

When performing an intermediate migration, you are going to install CloudBees CI on modern cloud platforms and connect your existing client controllers, pipelines, and static agents, but also begin using managed controllers. However, there is a subset of your workload that can be modernized since you are running in Kubernetes, and you can slowly migrate over time by modernizing your controllers and agents in “chunks.”

The client controllers and managed controllers can be run on CloudBees CI on modern cloud platforms under the same licensing agreement.

This is a useful migration option if you have specific requirements for continuing to use your existing client controllers. For example:

  • You have specialized client controller hardware, a GPU, or a different CPU architecture from a managed controller.

  • Moving to a modern environment can be cost-prohibitive. For example, you would not want to have 16 GB or 32 GB managed controllers running in CloudBees CI on modern cloud platforms because node types do not typically have that much memory available. Even if the memory were available, you would pay very high cloud costs for your Kubernetes cluster.

To perform an intermediate migration:

  1. Install CloudBees CI on modern cloud platforms. This must be the same product version that you are already running in CloudBees CI on traditional platforms.

    Special care must be taken to consider which Kubernetes versions your destination product version can run on, and if that Kubernetes version is supported by your Kubernetes vendor. For more information, refer to Supported platforms for CloudBees CI on modern cloud platforms.

  2. Connect the client controller to CloudBees CI on modern cloud platforms.

  3. Provision a managed controller based on your configuration. Note that you must provision the managed controller with:

    • The appropriate memory and CPU for your intended workload.

      The amount of memory required can depend on:

      • The number of jobs you are migrating from the client controller to the managed controller.

      • Whether you enable High Availability (active/active), because it allows you to have multiple replicas running a monolithic workload.

      • Whether you use Horizontal Scalability (HS) and a Kubernetes autoscaler to scale up more nodes. This provides the ability to run larger controllers with less risk of outage and better scaling across controllers. For more information about managed controller sizing guidelines, refer to Cluster sizing and scaling.

    • The relevant JVM arguments. For example:

      • Some of the system properties that were enabled on the client controller have to be migrated.

      • You must update the heap memory JVM argument. In CloudBees CI on modern cloud platforms, this is specified as a ratio of the pod memory size.

  4. Use Move/Copy/Promote to copy jobs from the client controller to the new managed controller.

  5. Connect the static agents in CloudBees CI on modern cloud platforms. The type of agent you use may depend on network connectivity, and whether the agents are network addressable. Both agent types are equivalent in terms of performance and functionality.

To now begin modernizing your controllers and agents in “chunks,” you can:

Perform an advanced migration

How to Use Kubernetes Pods As Jenkins Agents

Watch tutorial

Learn how to use Kubernetes pods as Jenkins agents

Watch tutorial

Performing an advanced migration requires a complete rearchitecting of your pipelines and agents. You must migrate from CloudBees CI on traditional platforms, where you are accustomed to using client controllers and static agents with all tools in one place, to CloudBees CI on modern cloud platforms with managed controllers, a model of a pod template with multiple containers, and a pipeline that is orchestrated across those containers.

Due to the advanced nature of this type of migration, these steps provide a high-level overview of the advanced migration process. The CloudBees Professional Services team is available to tailor solutions to your unique needs. Please contact your CloudBees Customer Success Manager for more information.

When performing an advanced migration, the following options are available, depending on your workflows and the nature of your static agents:

Option 1: Connect a client controller to a Kubernetes agent in CloudBees CI on traditional platforms

This option allows you to continue to use CloudBees CI on traditional platforms and begin to rewrite your pipelines and connect to Kubernetes agents, prior to migrating to CloudBees CI on modern cloud platforms and converting your client controllers to managed controllers.

To connect a client controller to a Kubernetes agent in CloudBees CI on traditional platforms:

  1. Install the Kubernetes plugin to CloudBees CI on traditional platforms.

  2. Connect the client controller to a Kubernetes cloud agent. For more information, refer to Kubernetes plugin for Jenkins - Configuration.

  3. Rewrite your pipelines to use Kubernetes agents in the Jenkinsfile. For more information, refer to Editing pod templates using pipelines and Selecting an agent for your Pipeline job.

  4. Install CloudBees CI on modern cloud platforms. This must be the same product version that you are already running in CloudBees CI on traditional platforms.

    Special care must be taken to consider which Kubernetes versions your destination product version can run on, and if that Kubernetes version is supported by your Kubernetes vendor. For more information, refer to Supported platforms for CloudBees CI on modern cloud platforms.

  5. Provision a managed controller based on your configuration. Note that you must provision the managed controller with:

    • The appropriate memory and CPU for your intended workload.

      The amount of memory required can depend on:

      • The number of jobs you are migrating from the client controller to the managed controller.

      • Whether you enable High Availability (active/active), because it allows you to have multiple replicas running a monolithic workload.

      • Whether you use Horizontal Scalability (HS) and a Kubernetes autoscaler to scale up more nodes. This provides the ability to run larger controllers with less risk of outage and better scaling across controllers. For more information about managed controller sizing guidelines, refer to Cluster sizing and scaling.

    • The relevant JVM arguments. For example:

      • Some of the system properties that were enabled on the client controller have to be migrated.

      • You must update the heap memory JVM argument. In CloudBees CI on modern cloud platforms, this is specified as a ratio of the pod memory size.

  6. Use the CloudBees Backup Plugin to back up the client controllers in CloudBees CI on traditional platforms. For more information, refer to Using the CloudBees Backup plugin.

  7. Use the CloudBees Backup Plugin to restore the client controller backup onto a managed controller in CloudBees CI on modern cloud platforms. For more information, refer to Restoring from the CloudBees Backup Plugin.

Option 2: Connect a managed controller to a static agent in CloudBees CI on modern cloud platforms

With this option, you can migrate to CloudBees CI on modern cloud platforms and provision managed controllers, connect to the existing static agents, and then rewrite your pipelines.

To connect a managed controller to a static agent in CloudBees CI on modern cloud platforms:

  1. Install CloudBees CI on modern cloud platforms. This must be the same product version that you are already running in CloudBees CI on traditional platforms.

    Special care must be taken to consider which Kubernetes versions your destination product version can run on, and if that Kubernetes version is supported by your Kubernetes vendor. For more information, refer to Supported platforms for CloudBees CI on modern cloud platforms.

  2. Provision a managed controller based on your configuration. Note that you must provision the managed controller with:

    • The appropriate memory and CPU for your intended workload.

      The amount of memory required can depend on:

      • The number of jobs you are migrating from the client controller to the managed controller.

      • Whether you enable High Availability (active/active), because it allows you to have multiple replicas running a monolithic workload.

      • Whether you use Horizontal Scalability (HS) and a Kubernetes autoscaler to scale up more nodes. This provides the ability to run larger controllers with less risk of outage and better scaling across controllers. For more information about managed controller sizing guidelines, refer to Cluster sizing and scaling.

    • The relevant JVM arguments. For example:

      • Some of the system properties that were enabled on the client controller have to be migrated.

      • You must update the heap memory JVM argument. In CloudBees CI on modern cloud platforms, this is specified as a ratio of the pod memory size.

  3. Use the CloudBees Backup Plugin to back up the client controllers in CloudBees CI on traditional platforms. For more information, refer to Using the CloudBees Backup plugin.

  4. Use the CloudBees Backup Plugin to restore the client controller backup onto a managed controller in CloudBees CI on modern cloud platforms. For more information, refer to Restoring from the CloudBees Backup Plugin.

  5. Connect the static agents in CloudBees CI on modern cloud platforms. The type of agent you use may depend on network connectivity, and whether the agents are network addressable. Both agent types are equivalent in terms of performance and functionality.

    For this option, you must connect the static agent in CloudBees CI on modern cloud platforms to rewrite your pipelines.

  6. Rewrite your pipelines to use Kubernetes agents in the Jenkinsfile. For more information, refer to Editing pod templates using pipelines and Selecting an agent for your Pipeline job.

    CloudBees CI on modern cloud platforms is connected to Kubernetes cloud by default, so you do not need to manually connect the managed controllers to Kubernetes agents.

  7. (Optional) As a best practice from an administrative perspective, disconnect the static agents from CloudBees CI on modern cloud platforms.

Introduction
Migrate from Jenkins LTS to CloudBees CI on traditional platforms