Creating folders with CasC for controllers

Configuration as Code allows you to create folders if the “items.yaml” file is included with the configuration bundle. Only folders can be managed and only a subset of fields are supported.

Prerequisites

The following software and plugins must be installed to use folders with CasC:

CloudBees CI version 2.249.3.1 and later
Configuration as Code plugin
Folders plugin
CloudBees CasC API Plugin, version 1.2 or later
Optional: CloudBees Role-Based Access Control Plugin

Exporting folder configurations

You can export folder configurations from an existing controller. For more information, refer to Exporting a CasC configuration.

The exported file should be used as a starting point, as it may require modifications and adjustments to make it production-ready.

Example CasC configuration bundle with folders

bundle.yaml

apiVersion: "1"
id: "1-casc-with-folders"
description: "Bundle demo with folders"
version: "1"
plugins:
  - "plugins.yaml"
jcasc:
  - "jenkins.yaml"
catalog:
  - "plugin-catalog.yaml"
rbac:
  - "rbac.yaml"
items:
  - "items.yaml"

plugins.yaml

plugins:
- {id: configuration-as-code}
- {id: cloudbees-casc-api}
- {id: manage-permission}
- {id: nectar-rbac}

plugin-catalog.yaml

type: "plugin-catalog"
version: "1"
name: "cloudbees-assurance-program-extensions"
displayName: "Extensions to the CloudBees Assurance Program (CAP)"
configurations:
- description: "Extensions to the CAP"
  includePlugins:
    manage-permission: (1)
      version: 1.0.1 (2)

1	Add the `manage-permission` plugin to enable the Overall/Manage permission.
2	Replace 1.0.1 with most recent version.

jenkins.yaml

jenkins:
  systemMessage: "Configured automatically by Configuration as Code - with RBAC \n\n"
  authorizationStrategy: "cloudBeesRoleBasedAccessControl" (1)

1	Mandatory to use CloudBees RBAC configured with CasC.

rbac.yaml

removeStrategy:
  rbac: "SYNC" (1)

groups:
- name: "Administrators group"
  members:
    users:
    - "admin-user"
  roles:
  - name: "administer-role"
    grantedAt: "current" (2)
    propagates: "false"
- name: "Manager group"
  members:
    users:
    - "manager-user"
  roles: (3)
  - name: "manager-role"
    grantedAt: "current"
- name: "Developers group"
  members:
    users:
    - "dev-user"
    internal_groups: (4)
    - "Manager group"
    external_groups:
    - "ldap-developers"
  roles: (5)
  - name: "developer-role"
    grantedAt: "child"
- name: "Browsers"
  members:
    users:
    - "read-user"
    internal_groups:
    - "Administrators group"
    - "Manager group"
    - "Developers group"
  roles: (6) (7)
- name: "browser-role"

roles:
- name: "administer-role"
  filterable: "false"
  permissions:
  - hudson.model.Hudson.Administer
- name: "manager-role"
  filterable: "false"
  permissions:
  - hudson.model.Hudson.Manage
  - hudson.model.Hudson.Read
- name: "developer-role"
  filterable: "true"
  permissions: (8)
  - hudson.model.Hudson.Read
  - hudson.model.View.Delete
  - hudson.model.Item.Promote
  - hudson.model.View.Configure
  - hudson.model.Item.Configure
  - hudson.model.Item.Cancel
  - hudson.model.Item.Read
  - hudson.model.Item.Build
  - hudson.model.Item.Discover
  - hudson.model.Hudson.Read
  - hudson.model.Item.Create
  - hudson.model.View.Read
  - hudson.model.View.Create
  - hudson.model.Item.Delete
- name: "browser-role"
  filterable: "true"
  permissions:
  - hudson.model.Hudson.Read
- name: "authenticated" (9)
  filterable: "false"
  permissions:
  - hudson.model.Hudson.Read
- name: "anonymous" (10)
  filterable: "false"

1	For security reasons, SYNC is here to remove groups/roles from CloudBees Continuous Integration when they are removed from this file.
2	Other options that could be used here include: "child" or "grandchild".
3	If propagates is not included, the default value is "true".
4	Team managers are also members of the developer group.
5	If propagates is not included, the default value is "true".
6	If grantedAt is not included, the default value is "current".
7	If propagates is not included, the default value is "true".
8	The list of permissions (Permission.id) to grant this role.
9	Overriding RBAC embedded role to lower the permissions.
10	If there isn’t list of permissions included, the role has no permissions.

items.yaml

removeStrategy:
 items: "none"
 rbac: "sync"

items:
 - kind: "folder"
   name: "Acceptance Test Harness"
   description: "This contains all the Acceptance Test Harness jobs"
   groups:
     - name: "Administrators group"
       members:
         users:
           - "admin-user"
       roles:
         - name: "administer-role"
           grantedAt: "current"
           propagates: "false"
   items:
     - kind: "folder"
       name: "With test-a"
       groups:
         - name: "Test A Administrators"
           members:
             users:
               - "admin-user"
           roles:
             - name: "administer-role"
       items: (1)
         - kind: "folder"
           name: "product-a-ath"
         - kind: "folder"
           name: "product-b-ath"

1	Items can be nested within other items, enabling users to create a folder structure on a controller.