cfManifestSubstituteVariables

Description

Step to substitute variables in a given YAML file with those specified in one or more variables files given by the manifestVariablesFiles parameter. This follows the behavior of cf push --vars-file, and can be used as a pre-deployment step if commands other than cf push are used for deployment (e.g. cf blue-green-deploy).

The format to reference a variable in the manifest YAML file is to use double parentheses (( and )), e.g. ((variableName)).

You can declare variable assignments as key value-pairs inside a YAML variables file following the Cloud Foundry standards format.

Optionally, you can also specify a direct list of key-value mappings for variables using the manifestVariables parameter. Variables given in the manifestVariables list will take precedence over those found in variables files. This follows the behavior of cf push --var, and works in combination with manifestVariablesFiles.

The step is activated by the presence of the file specified by the manifestFile parameter and all variables files specified by the manifestVariablesFiles parameter, or if variables are passed in directly via manifestVariables.

In case no manifestVariablesFiles were explicitly specified, a default named manifest-variables.yml will be looked for and if present will activate this step also. This is to support convention over configuration.

Parameters

name	mandatory	default	possible values
manifestFile	no
manifestVariables	no
manifestVariablesFiles	no
outputManifestFile	no
script	yes

• manifestFile - The String path of the Yaml file to replace variables in. Defaults to "manifest.yml" if not specified otherwise.
• manifestVariables - A List of Map entries for key-value pairs used for variable substitution within the file given by manifestFile. Defaults to an empty list, if not specified otherwise. This can be used to set variables like it is provided by cf push --var key=value. The order of the maps of variables given in the list is relevant in case there are conflicting variable names and values between maps contained within the list. In case of conflicts, the last specified map in the list will win. Though each map entry in the list can contain more than one key-value pair for variable substitution, it is recommended to stick to one entry per map, and rather declare more maps within the list. The reason is that if a map in the list contains more than one key-value entry, and the entries are conflicting, the conflict resolution behavior is undefined (since map entries have no sequence). Note: variables defined via manifestVariables always win over conflicting variables defined via any file given by manifestVariablesFiles - no matter what is declared before. This reproduces the same behavior as can be observed when using cf push --var in combination with cf push --vars-file.
• manifestVariablesFiles - The List of String paths of the Yaml files containing the variable values to use as a replacement in the manifest file. Defaults to ["manifest-variables.yml"] if not specified otherwise. The order of the files given in the list is relevant in case there are conflicting variable names and values within variable files. In such a case, the values of the last file win.
• outputManifestFile - The String path of the Yaml file to produce as output. If not specified this will default to manifestFile and overwrite it.
• script - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

Step configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter	general	step/stage
manifestFile		X
manifestVariables		X
manifestVariablesFiles		X
outputManifestFile		X
script

Dependencies

The step depends on the following Jenkins plugins

• pipeline-utility-steps
• workflow-basic-steps
• workflow-cps-global-lib
• workflow-durable-task-step

Transitive dependencies are omitted.

The list might be incomplete.

Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.

Side effects

Unless configured otherwise, this step will replace the input manifest.yml with a version that has all variable references replaced. This alters the source tree in your Jenkins workspace. If you prefer to generate a separate output file, use the step's outputManifestFile parameter. Keep in mind, however, that your Cloud Foundry deployment step should then also reference this output file - otherwise CF deployment will fail with unresolved variable reference errors.

Exceptions

• org.yaml.snakeyaml.scanner.ScannerException - in case any of the loaded input files contains malformed Yaml and cannot be parsed.

• hudson.AbortException - in case of internal errors and when not all variables could be replaced due to missing replacement values.

Example

Usage of pipeline step:

cfManifestSubstituteVariables (
  script: this,
  manifestFile: "path/to/manifest.yml",                      //optional, default: manifest.yml
  manifestVariablesFiles: ["path/to/manifest-variables.yml"] //optional, default: ['manifest-variables.yml']
  manifestVariables: [[key : value], [key : value]]          //optional, default: []
)

For example, you can refer to the parameters using relative paths (similar to cf push --vars-file):

cfManifestSubstituteVariables (
  script: this,
  manifestFile: "manifest.yml",
  manifestVariablesFiles: ["manifest-variables.yml"]
)

Furthermore, you can also specify variables and their values directly (similar to cf push --var):

cfManifestSubstituteVariables (
  script: this,
  manifestFile: "manifest.yml",
  manifestVariablesFiles: ["manifest-variables.yml"],
  manifestVariables: [[key1 : value1], [key2 : value2]]
)

If you are using the Cloud Foundry Create-Service-Push CLI plugin you will most likely also have a services-manifest.yml file. Also in this file you can specify variable references, that can be resolved from the same variables file, e.g. like this:

// resolve variables in manifest.yml
cfManifestSubstituteVariables (
  script: this,
  manifestFile: "manifest.yml",
  manifestVariablesFiles: ["manifest-variables.yml"]
)

// resolve variables in services-manifest.yml from same file.
cfManifestSubstituteVariables (
  script: this,
  manifestFile: "services-manifest.yml",
  manifestVariablesFiles: ["manifest-variables.yml"]
)