Export a CasC configuration from a CloudBees CI installation

Export a CasC configuration

You can export a CasC configuration from an existing CloudBees CI instance to create a template bundle. You can use the template bundle to set up a new CloudBees CI instance using CasC.

The CasC bundle configuration exported from a running CloudBees CI should not be used directly. This exported configuration requires some modifications before it can be used to create a new CloudBees CI instance. For more information, refer to Transform an exported bundle.

You can also export an individual CasC item and use it to create a new item by adding it to the items.yaml file. For more information, refer to Export an individual CasC item in an operations center or Export an individual CasC item in a controller.

The export feature relies on Jenkins LTS - Configuration as Code export, which has limitations. Therefore, the exported configuration is not a complete, correct, and ready-to-use CasC bundle. For more information, refer to the JCasC Jenkins LTS documentation.
The exported configuration is incomplete because some plugins are only partially compatible with Configuration as Code. They can read and load the CasC configuration, however, they do not generate the correct YAML files when exporting. In addition, the jenkins.yaml file may include extraneous default values for some properties that can be removed.
When exporting CasC bundles from existing operations center instances, you must verify there are no BeeKeeper plugin warnings, as the export logic relies on the CloudBees Assurance Program (CAP) to generate a consistent plugins.yaml file. If there are BeeKeeper warnings, the export still returns content, but the consistency of the plugins.yaml file cannot be guaranteed. The files may be unusable and require modifications due to warning comments in the files for plugin conflicts.

To prevent the environment configuration from being leaked, the variable expressions within exports are escaped. In the following pipeline example:

pipeline {
  agent any

  environment {
    greeting = 'Hello, World!'
  }

  stages {
    stage('Print Greeting') {
      steps {
        echo "${env.greeting}"
        sh 'echo ${GLOBAL_ENV}'
      }
    }
  }
}▼

The export will render as follows:

kind: pipeline
name: testWithVars
concurrentBuild: true
definition:
  cpsFlowDefinition:
    sandbox: true
    script: |-
      pipeline {
        agent any

        environment {
          greeting = 'Hello, World!'
        }

        stages {
          stage('Print Greeting') {
            steps {
              echo "^${env.greeting}" (1)
              sh 'echo ^${GLOBAL_ENV}'
            }
          }
        }
      }
description: ''
disabled: false
displayName: testWithVars1
resumeBlocked: false▼

1	The user must remove the ^ characters where it applies.

Prerequisites

The following plugins must be installed to export the current configuration:

If using CloudBees CI 2.289.3.2 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.14 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Client plugin, version 1.44 or later
Configuration as Code plugin

Exporting the current configuration

To export the current configuration from a test operations center instance:

Install your operations center or controller as a test instance.
Configure the plugins and global configuration using the UI.
Optionally, for a controller, configure a plugin catalog using the UI.
Select Manage Jenkins in the left pane.
Select CloudBees Configuration as Code export and update.

Figure 1. CloudBees Configuration as Code export and update
Select Current configuration.

Figure 2. Current configuration

Select Download to export the configuration. You can export individual YAML files or export all files in zip format.

You can have a configuration bundle without the plugins.yaml, plugin-catalog (for controller CasC bundles), items.yaml, and rbac.yaml files. If you do not include these files in your bundle, do not list them in your bundle.yaml file.

For controllers, if CAP/Beekeeper is disabled on the controller, the exported configuration includes the plugins.yaml and plugin-catalog.yaml files, but they contain one of the following warning messages:

plugin-catalog.yaml message: Cannot export catalog because CAP is not enabled
plugins.yaml message: Cannot export plugins because CAP is not enabled

Save the files using the following file names:
- bundle.yaml
- jenkins.yaml
- plugins.yaml
- plugin-catalog.yaml (for controller CasC bundles)
- items.yaml
- rbac.yaml
- variables.yaml
  
  For the bundle to be valid, the above files must use these exact filenames. If you rename these files, you must update them in your bundle.yaml file.
Uninstall or delete the original test instance for the operations center or controller if it is no longer needed.
Before using the exported CasC bundle, refer to Transform an exported bundle.

If your CloudBees CI instance has not been configured using a CasC bundle, the exported bundle uses apiVersion:1 in the bundle.yaml file. However, if a CasC bundle has been used for the configuration, when exporting the current configuration, the value for the apiVersion property in the bundle.yaml is the value for the calculated effective bundle.

Using YAML anchors

If a YAML file contains repetitive elements, you can replace them with YAML anchors. Any part of the YAML file can be defined as an anchor and used as the reference if the anchor name has a prefix of x-.

Example of YAML anchors

The following example items.yaml file has the x-colors-declaration anchor that is used in the choice parameter element.

  x-colors-declaration: &colors
  - red
  - green
  - blue

  removeStrategy:
    items: "none"
    rbac: "sync"

  items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
    blockBuildWhenDownstreamBuilding: false
    blockBuildWhenUpstreamBuilding: false
    concurrentBuild: false
    parameters:
    - choice:
        name: foreground-color
        choices: *colors
    - choice:
        name: background-color
        choices: *colors
    scm:
      none: {}
    scmCheckoutStrategy:
      standard: {}▼

This produces the following result:

  removeStrategy:
    items: "none"
    rbac: "sync"

  items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
    blockBuildWhenDownstreamBuilding: false
    blockBuildWhenUpstreamBuilding: false
    concurrentBuild: false
    parameters:
    - choice:
        name: foreground-color
        choices:
        - red
        - green
        - blue
    - choice:
        name: background-color
        choices:
        - red
        - green
        - blue
    scm:
      none: {}
    scmCheckoutStrategy:
      standard: {}▼