Inject configuration files across controllers - Limitations and Workarounds

3 minute read

Issue

  • I want to manage configuration files in Operations Center and inject them in the builds across my controllers

Environment

  • CloudBees Jenkins Enterprise - Operations Center (CJEOC)

  • CloudBees Jenkins Platform - Client controller (CJOC)

  • CloudBees Jenkins Enterprise - Managed controller (CJEMM)

  • CloudBees Jenkins Platform - Client controller (CJPCM)

  • CJP-3675: Add support to push Config File Provider Plugin

  • CJP-6744: File Credentials Binding issue if XML content and defined in CJOC

Resolution

At a controller level, there are different solutions. Some of them can be leveraged from the Operations Center but some cannot. In any case, the obvious workaround is to duplicate the chosen configuration in each controller, and the process of synchronizing the configuration could be scripted and maybe automated. Here are some of the solutions / limitations / workarounds in regards to the management/injection of configurations files across controllers.

1) Config File Provider plugin

Use the [Configuration File Provider Plugin]. You maintain managed files at the root or a folder level, and inject the file in the build environment with a build wrapper.

  • Suitable for:Freestyle and Pipeline jobs - "Provide Configuration files" wrapper for freestyle jobs, configFileProvider step for Pipeline jobs.

  • Limitation in CJOC: There is currently no support for the Config File Provider Plugin to manage configuration files from an Operations Center and use them in the attached controller. This is captured internally as CJP-3675: Add support to push Config File Provider Plugin

  • Workaround: The workaround is to duplicate the configuration in each controller. It could be cumbersome.

Script to facilitate that Workaround

To facilitate the duplication of the configuration across controllers, you could us the Config File Provider plugin in CJOC and manage your config files globally in CJOC. Then whenever you update your config files, execute the script sharedConfigFileProviderConfig.groovy under Manage Jenkins  Script Console in CJOC. This will push the config files that are defined at CJOC’s global level to all your controllers.

if a config file in the controller has the same ID as a config file configure CJOC, then the script overrides the config files configured at the global level of controllers.

2) Plain Credentials / Credentials Binding plugins

Use a combination of the Plan Credentials Plugin with the Credentials Binding Plugin. You can paste the content of your configuration file in Secret File or Secret Text credentials and inject the credentials in your builds with the credentials binding wrapper. The solution is explained in How inject your Maven settings.xml at folder level with the Credentials plugin? and Injecting Secrets into Jenkins Build Jobs. The same concepts can be used from an Operations Center. Credentials that are defined in an Operations Center are visible to the attached controllers - following the folder hierarchy if the controllers are created inside folders.

  • Suitable for: Freestyle and Pipeline jobs - "Use secret text(s) or file(s)" wrapper for freestyle jobs, withCredentials step for Pipeline jobs.

  • Limitation in CJOC: There is a known issue CJP-6744 that prevents Secret File containing XML content and defined in CJOC to be injected in a build on a controller.

  • Workaround: The workaround is to use Secret Text instead

3) Pipeline Shared Library

Use Pipeline Shared Libraries to store the configuration files. For example, you can store your configuration files in the resources of a shared library repository (see the directory structure in this documentation). Then you can use the libraryResource step to load the file content and use write to write the file in the workspace. You could actually write your own wrapper that injects the your configuration files. The benefit of this method is that any update to a configuration file will be reflected in all controllers and you also keep an history of every change.

  • Suitable for: Pipeline jobs only.

  • Limitation in CJOC: There is currently no support to share Pipeline Shared Library configuration across controllers.

  • Workaround: The workaround is to duplicate the configuration in each controller. But the configuration is simple.

Other solutions could be to have "predefined" build environments (required files are provisioned or available to the agent / container running the build) which would require external tools.