Creating items with CasC for the operations center

6 minute readScalabilityAutomation
Creating Folders with extended fields, Freestyle jobs, managed controllers, and client controllers is a Preview feature.
Preview

A Preview feature:

  • Has not undergone end-to-end testing with CloudBees products

  • Is provided without service-level agreements (SLA) and therefore does not include CloudBees' commitment on functionality or performance

  • May impact other stable areas of the product when used

  • May have limited documentation

  • May not be feature complete during the Preview period

  • May graduate from preview state to fully supported or be removed from the product

  • May introduce incompatible, backward-breaking changes that could revoke the ability to upgrade

Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

Configuration as Code allows you to create items if the items.yaml file is included in the configuration bundle.

You can export item configurations from an existing instance. However, the exported file should only be used as a starting point, as it may require modifications and adjustments to make it production-ready. For more information, refer to Exporting a CasC configuration.

Supported items using CasC

The following items are supported using CasC. You must install the prerequisite CloudBees Jenkins Platform software and plugins based on the item type you are creating.

If using RBAC to define roles and groups for items, you must also install the Configuration as Code plugin and Operations Center Server Role Based Access Control plugin.
Table 1. Supported item types and prerequisites
Item typePrerequisites

Folders with limited fields

Folders with extended fields (recommended)

Freestyle jobs

Client controller

Example CasC configuration bundle with items

Example bundle.yaml file

id: "bundle-1"
version: "1"
apiVersion: "1"
description: "My CloudBees Configuration as Code (CasC) bundle"
jcasc:
  - "jenkins.yaml"
plugins:
  - "plugins.yaml"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"

Example jenkins.yaml file

jenkins:
  systemMessage: "Operations Center configured using CasC."
  numExecutors: 0
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: admin
          password: admin
        - id: developer
          password: developer
        - id: read
          password: read
  authorizationStrategy: "cloudBeesRoleBasedAccessControl" (1)
security:
  securitySettingsEnforcement:
    global:
      realmAndAuthorization:
        canCustomMapping: false
        canOverride: true
        defaultMappingFactory: "restrictedEquivalentRAMF"
  controllerExecutorCount:
    enforce:
      canOverride: false
      count: 0
cloudBeesCasCServer:
  visibility: true (2)
1Mandatory to use CloudBees RBAC configured with CasC.
2Optional if using the items.yaml file to create a controller item. When the visibility is set to true, all CasC bundles that do not have an availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.

Example plugins.yaml file

plugins:
  # In CAP
  - { id: "cloudbees-casc-api" }
  - { id: "configuration-as-code" }
  - { id: "operations-center-sso" }
  - { id: "operations-center-rbac" }

Example items.yaml file

If creating a new controller item, refer to Creating a new controller item using CasC for the operations center.
Folders with limited fields
Folders with extended fields
Freestyle job
Client controller
removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "folder"
    name: "project-alpha"
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - "ldap-project-alpha"
        roles:
          - name: "developer"
    items: (1)
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles: (2)
      - "developer"
      - "browser"
1Items can be nested within other items, enabling users to create a folder structure.
2Roles can be filtered, for example to allow only administrators to view certain projects.
removeStrategy:
  items: "none"
  rbac: "sync"

items: (1)
  - kind: "folder"
    name: "project-alpha"
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - "ldap-project-alpha"
        roles:
          - name: "developer"
    items:
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
    properties:
      - envVars:
          vars:
            FOO: "BAR"
            BAR: "BAZ"
      - folderLibraries:
          libraries:
            - libraryConfiguration:
                implicit: false
                allowVersionOverride: true
                retriever:
                  modernSCM:
                    scm:
                      github:
                        traits:
                          - gitHubBranchDiscovery:
                              strategyId: 1
                          - gitHubPullRequestDiscovery:
                              strategyId: 1
                          - gitHubForkDiscovery:
                              trust:
                                gitHubTrustEveryone: {}
                              strategyId: 1
                        repoOwner: "company"
                        id: "library-id"
                        repository: "project-alpha"
                        configuredByUrl: true
                        repositoryUrl: "https://github.com/company/project-alpha"
                name: "my-library"
                includeInChangesets: true
      - itemRestrictions:
          allowedTypes:
            - "org.jenkinsci.plugins.workflow.job.WorkflowJob"
            - "hudson.matrix.MatrixProject"
            - "hudson.model.FreeStyleProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.jobTemplate.JobTemplate"
            - "com.cloudbees.hudson.plugins.folder.Folder"
            - "com.cloudbees.hudson.plugins.modeling.impl.builder.BuilderTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.auxiliary.AuxModel"
            - "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.publisher.PublisherTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.folder.FolderTemplate"
            - "com.infradna.hudson.plugins.backup.BackupProject"
          filter: true
    items:
      - kind: "freeStyle"
        name: "project-alpha-freestyle"
        displayName: "Freestyle job in the Project Alpha folder"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles: (2)
      - "developer"
      - "browser"
1Items can be nested within other items, enabling users to create a folder structure.
2Roles can be filtered, for example to allow only administrators to view certain projects.
removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
      scm:
        gitSCM:
          extensions:
            - checkoutOption:
                timeout: 4
          gitTool: git
          userRemoteConfigs:
            - userRemoteConfig:
                name: "developer-a"
                credentialsId: "credentials-id"
                url: "git@github.com:company/project-alpha.git"
          browser:
            githubWeb:
              repoUrl: "https://github.com/company/project-alpha"
          doGenerateSubmoduleConfigurations: false
          branches:
            - branchSpec:
                name: "*/main"
      buildDiscarder:
        logRotator:
          artifactDaysToKeep: 3
          daysToKeep: 1
          numToKeep: 2
          artifactNumToKeep: 4
      scmCheckoutStrategy:
        standard: { }
      builders:
        - shell:
            command: "pwd"
removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: clientController
    displayName: "client-controller-beta"
    name: "client-controller-beta"
    description: "This is Project Beta's client controller!"
    groups:
      - name: "Project Beta Developers"
        members:
          users:
            - developer-1
        roles:
          - name: developer
    properties:
    - configurationAsCode:
        bundle: bundle-2
    - healthReporting:
        enabled: false
    - owner:
        delay: 5
        owners: ''
    - envelopeExtension:
          allowExceptions: false
    - sharedConfigurationOptOut:
          optOut: false
    - licensing:
        strategy:
          perUserLicensingStrategy: {}
    - webSocket:
        enabled: true

Example rbac.yaml file

removeStrategy:
  rbac: "SYNC" (1)

roles:
  - name: administer
    permissions:
      - hudson.model.Hudson.Administer
  - name: developer
    permissions:
      - hudson.model.Hudson.Read
      - hudson.model.Item.Read
      - hudson.model.Item.Create
      - hudson.model.Item.Configure
    filterable: "true" (2)
  - name: browser
    permissions:
    - hudson.model.Hudson.Read
    - hudson.model.Item.Read
    filterable: "true"
  - name: authenticated
    filterable: "true"
    permissions:
    - hudson.model.Hudson.Read

groups:
  - name: Administrators
    roles:
      - name: administer
        grantedAt: current (3)
    members:
      users:
        - admin
      external_groups:
        - "ldap-cb-admins"
  - name: Developers
    roles: (4) (5)
      - name: developer
    members:
      users:
        - developer
      internal_groups:
        - "some-other-group"
      external_groups:
        - "ldap-cb-developers"
  - name: Browsers
    roles:
      - name: browser
    members:
      users:
        - read
1For security reasons, SYNC is here to remove groups/roles from CloudBees Continuous Integration when they are removed from this file.
2If filterable is not included, the default value is “false”.
3Other options that could be used here include: "child" or "grandchild".
4If propagates is not included, the default value is "true".
5If grantedAt is not included, the default value is "current".

Creating a new controller item using CasC for the operations center

You can export the current configuration for the operations center to create a new controller item using CasC. The following steps assume:

  • You have set up an operations center instance and configured it using CasC.

  • You have set up a controller.

  • If the controller is configured using CasC, you have also created a controller CasC bundle, added the CasC bundle to the operations center, and configured the controller bundle availability.

    If the controller is configured using a CasC bundle, you can add the cloudBeesCasCServer property to the operations center jenkins.yaml file. When the visibility is set to true, all CasC bundles that do not have an availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.

Adding a client controller item to the operations center CasC bundle

To add a client controller item to the operations center CasC bundle:

  1. Export the current configuration from the operations center.

  2. Open the operations center items.yaml file from the exported configuration.

  3. Copy the clientController item and paste it into the items.yaml file.

  4. Specify a unique name for the controller. For example:

        name: "client-controller-beta"
  5. If configuring the controller to use CasC, specify the CasC bundle that should be assigned to the controller. For example:

          - configurationAsCode:
              bundle: bundle-2
  6. Update the operations center CasC bundle.

    Select Reload Configuration to apply the new configuration without restarting the operations center.
  7. From the operations center dashboard, select the down arrow to the right of your controller’s name, and then select Configure.

    Figure 1. Controller dropdown menu
  8. Verify the controller settings are correct. If you assigned a CasC bundle to the controller, scroll down to Configuration as Code (CasC) and verify the controller CasC bundle that you specified in the operations center items.yaml file is assigned to the controller.

  9. Download the casc-bundle-link.yaml file.

  10. Configure the client controller with the casc-bundle-link.yaml file.