Setting up a client controller using CasC

4 minute readScalabilityAutomation

Controller send requests for their bundles through a secure HTTP(S) endpoint in operations center. Each controller is aware of the bundle it is connected to through the casc-bundle-link.yaml file that contains the bundle URL and access token.

You can configure a client controller using Configuration as Code (CasC) for Controllers by providing it with the location of the appropriate bundle and access token contained in the casc-bundle-link.yaml file. The client controller fetches its configuration bundle using the details in the casc-bundle-link.yaml file and configures itself accordingly.

Figure 1. Setting up a client controller

The process of setting up a client controller involves the following steps:

Prerequisites

The following plugins must be installed to your controller:

Assigning a bundle to a controller

To assign a bundle to a controller:

  1. Ensure you are signed in to the operations center as a user with the Configure or Administer permission.

  2. From the operations center dashboard, select the down arrow to the right of your controller’s name, and then select Configure.

    Figure 2. Controller dropdown menu
  3. Scroll down to Configuration as Code (CasC).

  4. Select the appropriate bundle to assign to the controller.

    If a Default bundle has already been selected from the Configuration as Code bundles screen, it is pre-selected in the Bundle dropdown.
  5. Select Save.

  6. If the controller has already been provisioned, you must restart the controller for the configuration change to take effect.

For the Download linkfile option to be accessible from the Manage screen, you must first configure the bundle availability and assign a bundle to the controller. For more information, refer to Configuring bundle availability for controllers and Assigning a bundle to a controller.
  1. Ensure you are logged in to operations center as a user with the Administer permission.

  2. From the operations center dashboard, in the left pane, select Manage Jenkins.

  3. From the operations center dashboard, select the down arrow to the right of your controller’s name, and then select Manage.

    Figure 3. Controller dropdown menu
  4. Scroll down to Configuration as Code (linkfile).

  5. Select Download linkfile to download the casc-bundle-link.yaml file.

  6. Save the file anywhere in the controller’s filesystem.

    CloudBees recommends saving the casc-bundle-link.yaml file in the controller’s $JENKINS_HOME directory.

The casc-bundle-link.yaml file contains the following properties:

PropertyTypeDescription

url

String

The URL where the bundle can be fetched. This URL references both the operations center server and the ID of the bundle.

token

String

The access token to authenticate the request with the operations center server.

The URL to access a particular bundle from an operations center server has a well-defined format: http[s]://<oc-server>:<port>/config-bundle/<bundle directory>. For example, for an operations center server on host oc.example.org and port 8080, the bundle that is placed in directory bundle-1 can be accessed as: https://oc.example.org:8080/config-bundle/bundle-1.

The client controller is directed to use the casc-bundle-link.yaml file by setting a Java system property. On startup, the client controller reads the casc-bundle-link.yaml file, fetches its Configuration as Code (CasC) for Controllers bundle from the operations center using the details specified in the casc-bundle-link.yaml file, then initializes itself with the provided configuration.

To point the client controller at the casc-bundle-link.yaml file, set the Java system property core.casc.config.bundle to the location of the link file. For example, to start a client controller using the casc-bundle-link.yaml file at $JENKINS_HOME/casc-bundle-link.yaml use the following command: java -Dcore.casc.config.bundle=$JENKINS_HOME/casc-bundle-link.yaml -jar jenkins.war

After you start the client controller with the correct java system property, open operations center and connect the client controller in the UI.

Errors when processing the casc-bundle-link.yaml file, fetching the bundle from the operations center, or initializing based on the bundle appear in the controller’s log file.

Regenerating a bundle token

You can regenerate a bundle’s access token using the casc-bundle-regenerate-token CLI command. Re-generating the access token is not usually required and should only be done in certain situations, such as for security purposes. Any controller currently using the token will lose access to it after it is regenerated. For more information, refer to Configuration as Code (CasC) CLI.

For client controllers, if the token needs to be regenerated, the casc-bundle-link.yaml file needs to be updated with the new token. For more information, see Configuring client controllers with the casc-bundle-link.yaml file.

Adding the CasC bundle column to the operations center dashboard

Once you have set up your controller and assigned a bundle to it, you can add the CasC bundle column to the operations center dashboard to display the CasC bundle assigned to each controller.

  1. From the operations center dashboard, select Edit View in the left pane.

  2. Scroll down to Columns.

  3. Select Add column.

  4. Select CasC bundle.

  5. Select OK.

    The CasC bundle column is now displayed in the operations center dashboard.

    Figure 4. CasC bundle column