Provide external yaml file to JCasC configScripts

Question

I am configuring my Jenkins instance using jenkins-helm chart (https://github.com/jenkinsci/helm-charts/blob/main/charts/jenkins/VALUES_SUMMARY.md#jenkins-configuration-as-code-jcasc)

Currently Jenkins config is provided in values.yaml as:

jenkins:
  controller:
    JCasC:
      configScripts:
        key1:|-
          <a-very-big-yaml-value>

Is there a way to import this 'big-yaml-value' from separate yaml file, as it will enhance maintainability of code for us.

Answer 1

As I don't use the helm-charts,I can't answer authoritatively, but it is supported in the abstract. According to the JCasC Getting Started documentation:

First, start a Jenkins instance with the Configuration as Code plugin installed.

• Those running Jenkins as a Docker container (and maybe also pre-installing plugins), do include Configuration as Code plugin.

Second, the plugin looks for the CASC_JENKINS_CONFIG environment variable. The variable points to a comma-separated list of any of the following:

• Path to a folder containing a set of config files. For example, /var/jenkins_home/init.CasC.
• A full path to a single file. For example, /var/jenkins_home/init.CasC/jenkins.yaml.
• A URL pointing to a file served on the web. For example, https://acme.org/jenkins.yaml.

If an element of CASC_JENKINS_CONFIG points to a folder, the plugin will recursively traverse the folder to find file(s) with .yml,.yaml,.YAML,.YML suffix. It will exclude hidden files or files that contain a hidden folder in any part of the full path. It follows symbolic links for both files and directories.

So, yes, you can have multiple yml files. I have over 20 (for 120 plugins). They are broken down by capability (eg: global, agents, tools, credentials , including 2 for RBAC (1 for roles, for users, etc.)), plus some plugin specific yml files. Some are also reused across instances while others are specific.

You should be aware of Merge Strategy in the event of conflicts:

• ErrorOnConflictMergeStrategy (default)
  • The strategy name is errorOnConflict.
  • Throws an exception if there's a conflict in multiple YAML files.
• OverrideMergeStrategy
• The strategy name is override
• Override the config files according to the loading order.

Also be aware when updating an existing instance, certain plugin configurations may replace configurations, while others may augment an existing configuration, regardless of one yaml or many. And of course, not 100% of options are JCasC-able yet, so some init.groovy is also required. YMMV.

You may also wish to review: JCasC Handling Secrets.

Answer 2

The setup below worked for me. Will put the relevant parts.

Directory layout for the helm chart:

jenkins/
??? conf/
?   ??? shared-library.yaml
?   ??? big-yaml.yaml
??? templates/
?   ??? jenkins-custom-casc-config.yaml
??? values.yaml
??? Chart.yaml

In the values.yaml, we override the CASC_JENKINS_CONFIG so it takes into account an additional path for config files on top of the default one.

controller:
  containerEnv:
    - name: CASC_JENKINS_CONFIG
      value: "/var/jenkins_home/casc_configs,/var/jenkins_home/custom-casc_configs"
   
persistence:
  volumes:
    - name: jenkins-custom-casc-config
      configMap:
      name: jenkins-custom-casc-config
  mounts:
    - mountPath: /var/jenkins_home/custom-casc_configs
      name: jenkins-custom-casc-config

ConfigMap jenkins-custom-casc-config.yaml that loads all files present in the conf/ folder

apiVersion: v1
kind: ConfigMap
metadata:
  name: jenkins-custom-casc-config
data:
  {{- (.Files.Glob "conf/*").AsConfig | nindent 2 }}