Adding controller CasC bundles to the operations center

You can add Configuration as Code bundles to a local folder on the operations center server or a source control management (SCM) tool. Once the CasC bundles have been added to the operations center, they are distributed to connected controllers using HTTP/HTTPS and you can configure how the bundles are synchronized with the operations center’s internal storage. This ensures any changes to the bundles are available to controllers using the CasC bundle.

Figure 1. Adding controller CasC bundles to the operations center

Beginning with CloudBees CI 2.319.3.3, you can configure the CasC bundle location as a local folder on the operations center server or using an SCM tool. When upgrading to CloudBees CI 2.319.3.3, if CasC controller bundles are detected in the $JENKINS_HOME/jcasc-bundles-store folder, they are automatically synchronized with the operations center’s internal storage and a local folder is automatically configured as the Configuration as Code bundle location on the Manage Jenkins Configure System screen. No changes are required to allow the bundles to continue to function as they did previously.
While the operations center simplifies the management of bundles, it is possible to configure a controller with a bundle without the operations center using the -Dcore.casc.config.bundle=/path/to/casc-bundle Java system property.
CasC bundle validation is automatically performed when the bundle is added to the operations center using the Configuration as Code bundle location. If problems are detected, an administrative monitor is displayed and validation messages are available on the Configuration as Code bundles screen. For more information, refer to Troubleshooting CasC for controllers.

If one or more CasC bundles contain files that are not part of the bundle (for example, README files, hidden files, or SCM control files), a validation warning is returned and the bundle cannot be synchronized with the operations center’s internal storage. You must increment the version number in the bundle.yaml file and synchronize the bundle.

Add CasC bundles to a local folder

You can manually add CasC bundles to a local folder on the operations center server and then configure the CasC bundle location.

To add CasC bundles to a local folder:

Add CasC bundles to a local folder on the operations center server.
- CloudBees CI on traditional platforms: Deploy a CasC bundle to the operations center
- CloudBees CI on modern cloud platforms: Deploy CasC bundles to the operations center using kubectl
Configure a local folder as the Configuration as Code bundle location.

CloudBees CI on traditional platforms: Deploy a CasC bundle to the operations center

To deploy a CasC bundle to the operations center:

Copy the directory containing the bundle files to a local folder on the operations center server.
Ensure the owner and group of the bundle folder and files are sufficient to allow the CloudBees CI user to read the files.

CloudBees CI on modern cloud platforms: Deploy CasC bundles to the operations center using kubectl

CasC bundles are stored on the operations center in the same way as on traditional platforms, but some additional steps are required to manipulate the files. The following sections explain how to add CasC bundles to a local folder on the operations center server using kubectl, the Kubernetes command-line tool. The following sample text is used, where you need to substitute your own values:

<NAMESPACE>: The Kubernetes namespace where you installed CloudBees CI on modern cloud platforms.
<MY_BUNDLE_FOLDER>: The folder on your machine that contains one or more CasC bundles.
<OC_LOCAL_FOLDER>: The local folder on the operations center server, where you are copying your CasC bundles.

List the bundles currently deployed to the operations center

Display a list of the bundles that are currently deployed to the operations center server and available for use:

kubectl exec --namespace <NAMESPACE> cjoc-0 -- ls /var/<OC_LOCAL_FOLDER>▼

For example, issue the following command to list all bundles that are deployed to a folder named oc-bundles on the operations center server, running in namespace cloudbees-core:

kubectl exec --namespace cloudbees-core cjoc-0 -- ls /var/oc-bundles▼

Example output:

bundle-1
bundle-2▼

Deploy bundles to the operations center

Put one or more bundles in a folder and copy the folder to the operations center server using the following command:

kubectl cp --namespace <NAMESPACE> <MY_BUNDLE_FOLDER> \
cjoc-0:/var/<OC_LOCAL_FOLDER>/▼

For example, add one or more bundles to a folder named my-bundles. Then issue the following command to deploy all bundles in the my-bundles folder to an oc-bundles folder on the operations center server, running in namespace cloudbees-core:

kubectl cp --namespace cloudbees-core my-bundles \
cjoc-0:/var/oc-bundles/▼

Remove a bundle from the operations center

Delete a bundle folder on the operations center server using the following command:

kubectl exec --namespace <NAMESPACE> cjoc-0 -- \
rm -rf /var/<OC_LOCAL_FOLDER>/<MY_BUNDLE_FOLDER>/▼

For example, issue the following command to delete a bundle named my-old-bundle from a local folder named oc-bundles on the operations center server, running in namespace cloudbees-core:

kubectl exec --namespace cloudbees-core cjoc-0 -- \
rm -rf /var/oc-bundles/my-old-bundle/▼

Update a bundle on the operations center

To update a bundle on the operations center, overwrite the bundle files with the updated bundle files.

If a controller is configured with a bundle using the -Dcore.casc.config.bundle=/path/to/casc-bundle Java system property, a bundle update is detected only when the version attribute in the bundle.yaml file has been incremented. If the version attribute is not incremented, the bundle update is not detected and cannot be applied.
When updating a bundle, do not remove the bundle folder on the operations center. This triggers the operations center to re-generate the bundle access token and the controller using the token must be restarted to retrieve the updated bundle from the operations center.

Configure a local folder as the Configuration as Code bundle location

Once you have added your CasC bundles to a local folder on the operations center server, you must configure one or more CasC bundle locations. Once configured, the CasC bundles can be distributed to connected controllers.

Recommendations when configuring the Configuration as Code bundle location

Keep the following recommendations in mind when configuring the Configuration as Code bundle location:

CloudBees CI 2.319.3.3 or later is required to configure the Configuration as Code bundle location.
If you configure more than one Configuration as Code bundle location, all CasC bundles must use unique bundle names. If more than one CasC bundle has the same bundle name, the bundles are not synchronized with the operations center’s internal storage and are not available to controllers.

If using GitHub as your repository, use webhooks as the setup to run the checkouts. For more information, refer to GitHub webhooks documentation.

Be mindful of the polling delay. For example, a polling of 60 seconds with more than 200 bundles will not work.

There is only one thread to perform checkouts, and it may take more than 60 seconds.
The requests are queued until the request that is running is executed.
Operations center requests ~60 useless checkouts per hour.

If you need an immediate sync, you can always perform a manual request.

To configure a local folder on the operations center server:

Ensure you are signed in to the operations center as a user with the Administer permission.
From the operations center dashboard, in the left pane, select Manage Jenkins.
Select Configure System.
Scroll down to Configuration as Code bundle location, and then select Load CasC bundles.
Select Configure… to configure the CasC bundle location.
Specify a Name for the CasC bundle location.
Polling is enabled by default, to automatically check the local folder for bundle updates based on the specified Polling interval and synchronize the updates with the operations center’s internal storage. You can deselect Polling if you plan to manually synchronize CasC bundles from the Load Configuration as Code bundles screen. For more information, refer to Synchronize CasC bundles with the operations center.
For the Retrieval method, select Local folder.
Specify the Path to the local folder on the operations center server that contains one or more CasC bundles.
Select Advanced.
1. Optionally, select Automatically clean up CasC bundles stored on the operations center to delete all controller CasC bundles from the operations center when Load CasC bundles is not selected.
2. If Polling is selected, you can optionally configure the Polling interval, in seconds, for the CasC bundle location.
Optionally, you can select the following:
- Add: Adds a Configuration as Code bundle location.
- Delete: Deletes the current Configuration as Code bundle location.
- Activated: Activates the current Configuration as Code bundle location. Clear this field to temporarily disable the current Configuration as Code bundle location.
Add, Delete, and Activated are supported with release 2.332.3.2 or later.
Select Save. The CasC bundles should now be available on the operations center and ready to be used by controllers.

Add CasC bundles from an SCM tool

You can store CasC bundles in an SCM repository and automatically add the CasC bundles to the operations center’s internal storage by configuring an SCM as the Configuration as Code bundle location.

This guide assumes the following layout:

my-company.com/repo.git
├── bundle-1
│   ├── bundle.yaml
│   ├── jenkins.yaml
│   ├── plugins.yaml
│   ├── plugin-catalog.yaml
│   ├── items.yaml
│   ├── rbac.yaml
│   └── variables.yaml
└── bundle-2
    ├── bundle.yaml
    ├── jenkins.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    ├── rbac.yaml
    └── variables.yaml▼

You can also add bundles from an SCM tool by Creating a Freestyle job in the operations center. However, beginning with CloudBees CI 2.319.3.3, this option is only supported for backwards-compatibility with existing applications. For all new applications, CloudBees recommends configuring an SCM as the Configuration as Code bundle location.

Configure an SCM as the Configuration as Code bundle location

CasC controller bundles can be added to the operations center using an SCM tool. Once configured, the CasC bundles can be distributed to connected controllers.

CloudBees CI 2.319.3.3 or later and the Git plugin, or any Git-based plugin in the CloudBees Assurance Program (CAP), are required to configure an SCM as the Configuration as Code bundle location.
If you configure more than one Configuration as Code bundle location, all CasC bundles must use unique bundle names. If more than one CasC bundle has the same bundle name, the bundles are not synchronized with the operations center’s internal storage and are not available to controllers.
Git submodules are not supported when you configure an SCM as the Configuration as Code bundle location and select Recursively update submodules for the selected Project Repository.

To configure an SCM tool as the CasC bundle location:

Ensure you are signed in to the operations center as a user with the Administer permission.
From the operations center dashboard, in the left pane, select Manage Jenkins.
Select Configure System.
Scroll down to Configuration as Code bundle location and select Load CasC bundles.
Select Configure… to configure the CasC bundle location.
Specify a Name for the CasC bundle location.
Polling is enabled by default, to automatically check the SCM repository for bundle updates based on the specified Polling interval and synchronize the updates with the operations center’s internal storage. You can deselect Polling if you plan to manually synchronize CasC bundles from the Load Configuration as Code bundles screen or automatically synchronize CasC bundles using an SCM webhook. For more information, refer to Synchronize CasC bundles with the operations center.
For the Retrieval method, select SCM.

Git is the only supported SCM tool and it is preselected.
Optionally, specify the Default version (a branch, tag, or commit) to check out from the SCM repository. If you do not specify a Default version or the specified version cannot be found, the first HEAD in the repository is used; this is typically the default main branch.
For the Project Repository, specify the URL of the SCM repository. This uses the same syntax as your git clone command. For example, https://github.com/my-company/repo.git or git@github.com:my-company/repo.git.
Specify the Credentials to scan branches and check out sources from the SCM repository.
1. Select Add Jenkins to launch the Jenkins Credentials Provider.
2. For Kind, select Username with password.
3. For Username, enter the username for the SCM repository.
4. For Password, enter the password for the SCM repository.
5. Select Add.
6. From the Credentials drop-down, select the credentials you added.
By default, the Discover branches behavior is selected to automatically discover branches in the SCM repository. You can delete this behavior or select Add to add additional SCM Behaviors.
Select Advanced.
1. Optionally, select Automatically clean up CasC bundles stored on the operations center to delete all controller CasC bundles from the operations center when Load CasC bundles is not selected.
2. If Polling is selected, you can optionally configure the Polling interval, in seconds, for the CasC bundle location.
  
  Polling is disabled if the Polling interval is equal to or less than zero seconds.
Optionally, you can select the following:
- Add: Adds a Configuration as Code bundle location.
- Delete: Deletes the current Configuration as Code bundle location.
- Activated: Activates the current Configuration as Code bundle location. Leave this field blank to temporarily disable the current Configuration as Code bundle location.
Add, Delete, and Activated are supported with release 2.332.3.2 or later.
Select Save. The CasC bundles should now be available on the operations center and ready to be used by controllers.

Create a Freestyle job in the operations center

You can also create a Freestyle job to add CasC bundles from an SCM tool to the operations center.

Beginning with CloudBees CI 2.319.3.3, creating a Freestyle job to add CasC bundles from an SCM tool is only supported for backwards-compatibility with existing applications. For all new applications, CloudBees recommends configuring an SCM as the Configuration as Code bundle location.

The executor must be configured in an operations center instance and is not supported on an agent or a controller. If the Freestyle job is triggered on an agent or controller that is attached to the operations center, the build will fail.

To create a Freestyle job and add CasC bundles to the operations center:

Ensure you are signed in to the operations center as a user with the Administer permission.
From the operations center dashboard, select New Item in the left pane.
Specify an item name, select Freestyle project, and then select OK.

You must use a Freestyle job because Pipeline jobs are not supported in the operations center.
Scroll down to Source Code Management, select an SCM, and then enter the repository location.
Scroll down to Build, and then select Add build step.

Select the type of build step. You have two options:

Option 1: Select the Synchronize bundles from workspace with internal storage build step.

Optionally, select Purge deleted bundles to automatically purge bundles from the operations center that have been deleted from the SCM tool.

This build step is deprecated and will be removed in February 2023. Please consider using the Configuration as Code bundle location setting, available since version 2.319.3.3.

Option 2: Select the Execute shell build step and add the following script, replacing <OC_LOCAL_FOLDER> with the local bundle folder on your operations center server.

cp -r my-controller-1 <OC_LOCAL_FOLDER>
cp -r my-controller-2 <OC_LOCAL_FOLDER>▼

If creating a new Freestyle job with the Execute shell build step, you must first add a local folder to the operations center server, configure the Configuration as Code bundle location for the local folder, and replace <OC_LOCAL_FOLDER> in the build step to use the local folder path. For more information, refer to Add CasC bundles to a local folder.
The Execute shell build step can synchronize new bundles or update existing bundles stored in the operations center. However, bundles that have been deleted from the SCM tool are not automatically purged from the operations center’s internal storage.

Select Save.
Manually trigger a build. The CasC bundles should now be available on the operations center and ready to be used by controllers.

Synchronize CasC bundles with the operations center

Once you have added your controller CasC bundles to the operations center, you can configure how the bundles are synchronized with the operations center’s internal storage. This ensures any changes to the bundles are available to controllers using the CasC bundle. The following options are available for synchronizing your CasC bundles with the operations center:

Manually synchronize CasC bundles
Automatically synchronize CasC bundles using polling
Automatically synchronize CasC bundles from an SCM tool

Manually synchronize CasC bundles

Once you have configured the Configuration as Code bundle location, if you make changes to your CasC bundle, you can manually synchronize the CasC bundle with the operations center’s internal storage.

Manually synchronizing CasC bundles is not supported when using a Freestyle job to add CasC bundles from an SCM tool to the operations center.

To manually synchronize CasC bundles:

Ensure you are signed in to the operations center as a user with the Administer permission.
From the operations center dashboard, in the left pane, select Load CasC bundles.
Select Check out and apply.

Once you have synchronized the CasC bundle with the operations center’s internal storage, the updates are available to controllers using the CasC bundle.
Apply the updated bundle to controllers from the Configuration as Code export and update screen.

For more information, refer to Updating a CasC bundle for a controller.

Automatically synchronize CasC bundles using polling

When configuring the Configuration as Code bundle location, Polling is enabled by default and checks for changes to CasC bundles in the local folder on the operations center server or in the SCM repository, based on the specified Polling interval.

If changes are detected, they are automatically synchronized with the operations center’s internal storage and the updated bundles are available to controllers using the CasC bundle. You can then apply the updated bundle to connected controllers from the Configuration as Code export and update screen. For more information, refer to Updating a CasC bundle for a controller.

CloudBees recommends that you disable Polling if you are using an SCM webhook to automatically synchronize CasC bundles.
Polling is not supported if using a Freestyle job to add CasC bundles from an SCM tool to the operations center.

Recommendations when configuring the Configuration as Code bundle location

Keep the following recommendations in mind when configuring the Configuration as Code bundle location:

If using GitHub as your repository, use webhooks as the setup to run the checkouts.

Be mindful of the polling delay. For example, a polling of 60 seconds with more than 200 bundles will not work.

There is only one thread to perform checkouts, and it may take more than 60 seconds.
The requests are queued until the request that is running is executed.
Operations center requests ~60 useless checkouts per hour.

If you need an immediate sync, you can always perform a manual request.

Automatically synchronize CasC bundles from an SCM tool

You can also use an SCM webhook to automatically synchronize your CasC bundles stored in a GitHub repository with the operations center’s internal storage. You can configure a webhook in the GitHub repository to synchronize CasC bundles based on push events.

If changes are detected in the SCM repository, they are automatically synchronized with the operations center’s internal storage and the updates are available to controllers using the CasC bundle. You can then apply the updated bundle to connected controllers from the Configuration as Code export and update screen.

For more information, refer to Updating a CasC bundle for a controller.

The GitHub plugin is required to use a GitHub webhook to automatically synchronize CasC bundles. For more information on creating a GitHub webhook, refer to Creating webhooks in the GitHub Developer guide.
When you configure a webhook in GitHub, you must specify the Payload URL. This is the operations center URL that receives the webhook POST requests, in the following format: https://<operations-center>/github-webhook/. For example, https://operations-center:8888/github-webhook/.