Adding a CasC bundle to the operations center

4 minute readScalabilityAutomation

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 controller determines how you can make the configuration bundle available for distribution by the operations center:

  • Client controllers: Deploying a bundle to the operations center

  • Managed controllers: Manipulating CasC bundles using kubectl

Client controllers: Deploying a bundle to the operations center

To deploy a CasC bundle to the operations center for client controllers, copy the directory containing the bundle files to your $JENKINS_HOME/jcasc-bundles-store directory. Ensure the owner and group of the bundle directory and files match those of other files under $JENKINS_HOME and are sufficient to allow the Jenkins user to read the files.

Managed controllers: Manipulating CasC bundles using kubectl

Configuration 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 manipulate the bundles using kubectl, the Kubernetes command-line tool. The following sample text will be used where you need to substitute your own values:

  • <NAMESPACE> - the Kubernetes namespace into which you installed CloudBees CI on modern cloud platforms

  • <BUNDLE_DIR> - the local directory containing your bundle files

Users loading bundles from an SCM do not need to use kubectl to manage bundles. For more information, see Loading CasC bundles from a SCM tool.

Listing the bundles currently deployed to the operations center

Run the following command to display a list of the bundles that are currently deployed to the operations center and available for use:

kubectl exec --namespace <NAMESPACE> cjoc-0 -- ls $JENKINS_HOME/jcasc-bundles-store/

Example command to list the bundles deployed to the operations center running in namespace cloudbees-core:

kubectl exec --namespace cloudbees-core cjoc-0 -- ls $JENKINS_HOME/jcasc-bundles-store/

Example output:

bundle-1
bundle-2

Deploying a single bundle to the operations center

Copy the directory containing the bundle files to the operations center using the following command:

kubectl cp --namespace <NAMESPACE> <BUNDLE_DIR> \
cjoc-0:$JENKINS_HOME/jcasc-bundles-store/

Example command to deploy the bundle directory my-new-bundle to the operations center running in namespace cloudbees-core:

kubectl cp --namespace cloudbees-core my-new-bundle \
cjoc-0:$JENKINS_HOME/jcasc-bundles-store/

Deploying multiple bundles to the operations center

Put all bundles into a directory named jcasc-bundles-store. Copy the jcasc-bundles-store directory to the operations center using the following command:

kubectl cp --namespace <NAMESPACE> <BUNDLE_DIR> \
cjoc-0:$JENKINS_HOME

Example command to deploy all bundles to the operations center running in namespace cloudbees-core:

kubectl cp --namespace cloudbees-core jcasc-bundles-store \
cjoc-0:$JENKINS_HOME

Removing a bundle from the operations center

Delete the bundle directory on the operations center using the following command:

kubectl exec --namespace <NAMESPACE> cjoc-0 -- \
rm -rf $JENKINS_HOME/jcasc-bundles-store/<BUNDLE_DIR>

Example command to delete the bundle named my-old-bundle from the operations center running in namespace cloudbees-core:

kubectl exec --namespace cloudbees-core cjoc-0 -- \
rm -rf $JENKINS_HOME/jcasc-bundles-store/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 directory 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 SCM tool

The operations center distributes Configuration as Code (CasC) for Controllers bundles to controllers from local storage; however, Configuration as Code (CasC) for Controllers bundles can also be pulled from an external source control management (SCM) system using a Freestyle job in the operations center that can be triggered manually or using a webhook.

Prerequisites

Configuration as Code (CasC) for Controllers bundles can be 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
  …

Creating a job in operations center

Operations center distributes bundles from local storage, so to use files from an external SCM system you must create a Freestyle job to pull those bundles from the SCM to local storage.

To create a job to pull Configuration as Code (CasC) for Controllers bundles from an SCM to local storage:

  1. Create a Freestyle job in operations center.

    You must use a Freestyle job as Pipeline jobs are not supported in operations center.
  2. In the Source Code Management section, select an SCM that is supported by Jenkins and enter the repository location.

  3. In the Build section, add an Execute Shell step with the following script:

    cp -r my-master-1 $JENKINS_HOME/jcasc-bundles-store
    cp -r my-master-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.
  4. Save and trigger a build.

Afterwards, Configuration as Code (CasC) for Controllers bundles should be available in local storage and ready to be used by controllers following the normal procedure.

Triggering the job automatically using Webhooks

One way to trigger a Freestyle job to pull Configuration as Code (CasC) for Controllers 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 Configuration as Code (CasC) for Controllers bundle.

In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.