Transform an exported bundle

Export a CasC configuration from a CloudBees CI installation describes the process of retrieving a complete CasC bundle configuration from a running CloudBees CI and warns against using the bundle as it is. You must transform the exported bundle before using it to configure a new operations center or controller. The transformation process varies depending on several factors, such as:

You own requirements.
The CloudBees CI version you are using.
Whether you want to use the CasC bundle to configure a new operations center or a controller.
The plugins you want to install.
The apiVersion property value in the bundle.yaml file. Different values, 1 or 2, change how plugins are managed using CasC. Refer to Manage plugins with CasC for further information.

CloudBees recommends some practices to help you transform the bundle.

Remove from the CasC bundle any information unique to the CloudBees CI installation you exported the bundle from.
If creating a CasC bundle for controllers connected to an operations center, remove any information provided by the operations center.
Remove default configurations.

Remove information unique to the CloudBees CI installation

CloudBees CI configurations contain configuration parameters that are unique to every installation. You must remove or update this information from the CasC bundle before using it to configure a new CloudBees CI instance, information like the following:

In the bundle jenkins.yaml file, remove secrets or credentials defined locally as the encryption process is tied to the CloudBees CI installation and uses local secrets and keys, such as the master.key file. CloudBees recommends using third-party tools to store credentials, such as CyberArk.

credentials:
  system:
    domainCredentials:
    - credentials:
      - usernamePassword:
          description: "<your-credential-description>"
          id: "<your-credential-id>"
          password: "{your-encrypted-credential}"
          scope: GLOBAL
          username: "<some-username>"▼

If you plan to create a new bundle, Change the id and description properties in the bundle.yaml file. CloudBees CI uses these properties to identify bundles.
Remove all the information in the jenkins.yaml file that is unique to a CloudBees CI installation. Information such as:
1. Your instance URL.
  location: adminAddress: "<your-administrator-email-address>" url: "<your-instance-URL"
  ▼
2. Any plugin configuration that includes your instance URL, such as a webhook URL for the GitHub plugin as displayed below:
  gitHubPluginConfig: hookUrl: "http://<your-instance-url/github-webhook/"
  ▼
Remove (managed controllers) or update (operations center and client controllers) the license information with your license in the jenkins.yaml file.
```
license:
  certificate: |
    ...
    <your-installation-certificate>
    ...
  key: |
    ...
    <your-installation-key>
    ...▼
```

Remove information provided by the operations center to the controllers

When creating a CasC bundle for controllers connected to an operations center, you must remove or any information provided by the operations center to the controllers. Information like the following:

Remove (managed controller), or modify (client controller) the operationsCenterRootAction property from the jenkins.yaml file. This property contains the controller connection details to the operations center.
```
operationsCenterRootAction:
  connectionDetails: ""----- BEGIN CONNECTION DETAILS -----\n
  ...
  /----- END CONNECTION DETAILS -----\n""▼
```
Remove or modify the license information from the jenkins.yaml. The operations center provides this license to managed controllers.
If the operations center enforces the security realm and authorization strategy for the controllers, remove the complete rbac.yaml file from the controller bundle, the rbac section from the controller’s bundle.yaml and any property that references this information in the jenkins.yaml file, such as the authorizationStrategy property.
```
apiVersion: "2"
id: "<your-{CTRL}-bundle-id>"
description: "<your-{CTRL}-bundle-description>"
version: "1"
...
rbac:
  - "rbac.yaml"
...▼
```
```
authorizationStrategy: "cloudBeesRoleBasedAccessControl"▼
```
Remove the Update Center configuration from the jenkins.yaml file in the controller CasC bundle. The operations center provides this information to the controllers.
```
updateCenter:
  sites:
  - id: "virtual-cap-core-oc"
    url: "https://jenkins-updates.cloudbees.com/update-center/envelope-core-oc/update-center.json"▼
```
If the operations center has a Kubernetes shared cloud, remove the LabelAtoms property from the jenkins.yaml file in the controller CasC bundle. This property contains labels from the Pod templates defined at the operations center level.
```
labelAtoms:
- name: "linux"
- name: "windows"
- name: "macosX"▼
```

Remove default configurations

Exported CasC configuration bundles contain all the configuration parameters used by the CloudBees CI installation you exported the bundle from, even the default configurations, which are in the jenkins.yaml file. Keeping these default configuration parameters and properties in the bundle is not recommended as they can change from one CloudBees CI version to another, and they can also be different depending on the plugins versions you have installed. Moreover, keeping default configurations in the bundle makes it harder to read, mantain and understand the bundle, so removing them is a good practice.

The default configuration parameters are placed in the jenkins.yaml file and refer to the following elements:

Default configuration for the CloudBees CI installation.
Default configuration for plugins.

If you hesitate to remove a specific configuration property from the bundle because you are unsure if the property is a default configuration, you can always leave it in the bundle.

Any change made from the CloudBees CI UI, such as adding a new plugin or changing a configuration parameter, overwrites the default configuration and should be kept in the bundle.

Look for CloudBees CI default configuration parameters

A CloudBees CI installation contains many default configuration parameters. As explained before, removing them from the bundle is a good practice to make it easier to read and maintain. However, it’s not always easy to identify the default configuration parameters in the jenkins.yaml file.

CloudBees recommends the following workflow to help you identify and remove the default CloudBees CI configuration parameters:

Create a test environment.
Create a baseline CasC bundle, for an operations center or for a controller, with:
- A bundle.yaml holding references only to a jenkins.yaml file and a plugins.yaml file.
- An empty jenkins.yaml file.
- No items.yaml file.
- No rbac.yaml file.
- No variables.yaml file.
- A minimum set of plugins in the plugins.yaml file containing, at least, the requirements for exporting a CasC configuration.
Apply the CasC bundle to an instance, operations center or controller, in the test environment.
Export the CasC configuration from the test environment before making any configuration change using the CloudBees CI UI.
Compare the original jenkins.yaml file in the exported bundle with the new one using a diff tool or an SCM.

The differences between them are the default configuration parameters.

Look for a plugin default configuration

When you install a plugin using a Configuration as Code bundle, the default configuration parameters for the plugin appear in the jenkins.yaml file, if the plugin is CasC-compatible and you export your current configuration.

It is difficult for administrators to know all the default configuration parameters for all the plugins installed in a CloudBees CI instance. CloudBees recommends the following options to help you identify and remove the default plugin configuration parameters from your CasC bundles:

Review the plugin documentation to check if the plugin is CasC compatible and review the default configuration parameters.
Use a test environment and follow these steps:
1. Apply a baseline CasC bundle with a minimum set of plugins in the plugins.yaml file, containing, at least, the requirements for exporting a CasC configuration.
2. Install the plugin you want to check.
3. Export the CasC configuration from the test environment before making any configuration change using the CloudBees CI UI.
  1. Compare the original jenkins.yaml file in the exported bundle with the new one using a diff tool or an SCM.

The difference between them is the default configuration for the plugin.

In addition to following the recommendations above to transform and clean a bundle, CloudBees recommends validating and testing the bundle before using it to configure a new CloudBees CI instance.

Refer to Validate a CasC bundle for more information, and, ideally, create a test environment for that purpose.