Adding a CasC bundle for controllers to the operations center

Configuration bundles are made available from the operations center to connected controllers using HTTP/HTTPS. Configuration bundles are stored on the operations center server as a folder containing the bundle files.

Multiple Configuration as Code (CasC) for Controllers bundles can be deployed to the operations center server and are all stored in $JENKINS_HOME/jcasc-bundles-store. For example:

$JENKINS_HOME/jcasc-bundles-store/
├── bundle-1
│   ├── bundle.yaml
│   ├── jenkins.yaml
│   ├── plugins.yaml
│   ├── plugin-catalog.yaml
│   ├── items.yaml
│   └── rbac.yaml
└── bundle-2
    ├── bundle.yaml
    ├── jenkins.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    └── rbac.yaml

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.

Adding files to the operations center manually

The operations center distributes CasC bundles to controllers from local storage.

The type of platform determines how you can make the configuration bundle available for distribution by the operations center:

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

CloudBees CI on traditional platforms: Deploying 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: Deploying 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.

Listing 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

Deploying 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/

Removing 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/

Updating 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.

Loading CasC bundles from a source control management (SCM) tool

The operations center distributes CasC bundles to controllers from local storage. CasC controller bundles can also be synchronized with an external SCM tool using a Freestyle job that can be triggered manually or triggered automatically using webhooks.

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.

Prerequisites

CasC bundles can be stored in one or more SCM repositories. However, this guide assumes all bundles are in the same Git repository, with the following layout:

mycompany.com/config-bundles.git
- bundle-1
  -- bundle.yaml
  -- jenkins.yaml
  -- plugins.yaml
  -- plugin-catalog.yaml
  -- items.yaml
  -- rbac.yaml
- bundle-2
  -- bundle.yaml
  -- jenkins.yaml
  -- plugins.yaml
  -- plugin-catalog.yaml
  -- items.yaml
  -- rbac.yaml

Creating a Freestyle job in the operations center

The operations center distributes bundles from local storage. To synchronize CasC bundles from an external SCM tool, you must create a Freestyle job to pull the bundles from the SCM tool to the operations center’s local storage.

To create a Freestyle job to synchronize CasC bundles:

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.

Option 2: Select the Execute shell build step and add the following script:

cp -r my-controller-1 $JENKINS_HOME/jcasc-bundles-store
cp -r my-controller-2 $JENKINS_HOME/jcasc-bundles-store

$JENKINS_HOME/ is the default Jenkins home directory in CloudBees CI. Update the script if your Jenkins home directory is in a different location.
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 local storage.

Select Save, and then trigger a build.

The CasC bundles should now be available in the operations center’s local storage and ready to be used by controllers.

Triggering the Freestyle job automatically using webhooks

One way to trigger a Freestyle job to pull CasC bundles from an SCM is through the use of webhooks. If your SCM supports webhooks, configure a webhook in the SCM to trigger builds on the importing job on push events.

Setting up a webhook through your SCM will ensure a change made in the repository will be automatically available to controllers using the CasC bundle.