Restoring from the CloudBees Backup Plugin

The CloudBees Backup Plugin is only available for CloudBees CI. This chapter explains how to restore from a backup created with the CloudBees Backup Plugin. Refer to Restoring $JENKINS_HOME manually to restore other Jenkins-based deployments.

Restoring from backup (using a restore job)

Masters with CloudBees Backup Plugin 3.38 or later installed have support for the Restore job type. The Operations Center does not have a restore option, so to restore an Operations Center when using CloudBees CI on traditional platforms you can follow the steps for Restoring manually. If you are using CloudBees CI on modern cloud platforms, follow to steps to Backup and restore on Kubernetes - Using a rescue-pod.

To restore a backup:

  1. Select New Item from the left pane.

  2. Select Backup and Restore and enter an item name.

  3. Select OK.

    After you select OK, you are directed to the restore job configuration. Configuration of a restore job is very similar to that of a Freestyle job.

  4. Under the Build heading, select Add build step and Restore from backup.

  5. Then, just like a backup job, you must configure where the backup is retrieved from. The latest backup available in the given source will be used to restore.

  6. When running the restore job, the backup file is downloaded from the configured backend to the Jenkins filesystem, checked for integrity, then unpacked. After these steps are completed, you will be prompted to restart the Jenkins instance.

  7. Upon restart, $JENKINS_HOME is replaced with the content of the backup file, and the restore process is complete.

Restore is supported only from full backup files

The restore process will replace the current `$JENKINS_HOME with the data from backup archive. Therefore it is important to restore from a full backup. If there is data in $JENKINS_HOME that is not in the backup and needs to be kept, select the Advanced button under Restore options and select the Preserve Jenkins home contents checkbox. This will copy the current $JENKINS_HOME into a directory named "archive-<timestamp>".

Excluding files from a restore job

When a restore job is performed, everything in the $JENKINS_HOME directory is moved to a file named archive_<timestamp>. If you have files that are introduced by the file system in your $JENKINS_HOME directory, for example .snapshot files, you must exclude them from the restore process or you will receive an error when you try to restore.

To exclude system files from the restore process on a CloudBees CI on traditional platforms Client Master:

  1. In the backup job, add a comma-separated list of Ant-style patterns in the system configuration excludes list.

    See Setting backup options for more information.
  2. In the restore job, select the Advanced button.

  3. Select the Preserve Jenkins home contents checkbox under Restore options.

  4. Restart the Client Master, using the following system property:

    -Dcb.backup.restore.keepFilesPattern='<Ant-style patterns>

    Example with Ant-style patterns to exclude .snapshots files:

    -Dcb.backup.restore.keepFilesPattern='.snapshots,**/.snapshots'

To exclude system files from the restore process on a CloudBees CI on modern cloud platforms Managed Master:

  1. In the backup job, add a comma-separated list of Ant-style patterns in the system configuration excludes list.

    See Setting backup options for more information.
  2. In the restore job, select the Advanced button.

  3. Select the Preserve Jenkins home contents checkbox under Restore options.

  4. From Operations Center select Manage Jenkins > Configure Master Provisioning.

  5. Under the Additional options heading, add the following system property to Global System Properties: cb.backup.restore.keepFilesPattern=<Ant-style patterns>

    Example with Ant-style patterns to exclude .snapshots files: cb.backup.restore.keepFilesPattern=.snapshots,**/.snapshots

  6. Select Save.

  7. Select the gear icon for the master.

  8. Select Restart under Manage in the left navigation pane.

After you have reprovisioned the master, you should see the new system property listed the master’s Manage Jenkins > System Information.