Manage values in YAML

You can manage values separately from your DevOps as Code YAML files so that they can be pulled in when applying XL YAML files. DevOps as Code supports multiple methods to configure and manage values including a dedicated file format using the .xlvals extension, environment variables or by explicitly specifying a value in XL CLI command syntax.

Methods to manage values

Each of the following methods are parsed in the order presented below.

• Method 1: One or more .xlvals files in the /.xebialabs folder in your home directory. Multiple files in this folder are parsed in alphabetical order.
• Method 2: One or more .xlvals files in your project directory alongside your YAML files.
  • A YAML file can only parse .xlvals files stored in the same directory.
  • You can have a YAML file stored at a higher level in the directory structure that imports one or more YAML files that reside in a subdirectory. However, any .xlvals files related to a YAML file in a subdirectory must be in the same directory.
  • Multiple .xlvals files in this directory are parsed in alphabetical order.
• Method 3: Environment variables that are prefixed with XL_VALUE_; for example, XL_VALUE_mykey=myvalue.
• Method 4: Invoked explicitly as a parameter when using the XL CLI; for example, by adding the global flag --values mykey=myvalue.

How value methods are parsed

The XL CLI will parse the methods for managing values in the order implied in the method order described above.

• If there are multiple .xlvals files in a directory, each file will be parsed in alphabetical order.
• If you have multiple environment variables defined that are prefixed with XL_VALUE_, each variable will be parsed in alphabetical order.
• If a duplicate key is encountered as parsing continues through the method order, the last encountered key is used. For example, if you have a value defined for USER in an .xlvals file in your .xebialabs directory (method 1), and you have the different value for USER defined in an .xlvals file in your project directory (method 2), then the value in the project directory is used and the value in the .xebialabs directory is ignored.

.xlvals file format

An .xlvals file is simply a list of keys and values, and follows the standard implementation of the Java .properties file format.

Here is an example of key/value definitions using the = delimiter:

# my keys and values

appversion=1.0.2
environmentName=myenv
hostname=myhostname
port=443

Environment variables

You can configure and use environment variables on your system by using the XL_VALUE_ prefix. For example:

XL_VALUE_mykey=myvalue

Command line syntax for values

You can specify a key "on the fly" during execution of an XL CLI command using the --values global flag. This example shows how to pass multiple keys:

xl apply  -f xldeploy/application.yaml  --values myvar1=val1,myvar2=val2

Using values in your YAML files

Once you have defined your values using one of the methods described above, you can use !value and !format tags in your YAML files to specify a key for which the corresponding value will be pulled in when the YAML file is applied.

!value tag

The !value tag simply takes the name as a parameter. For example:

environment: !value environmentName

!format tag

You can use the !format tag for more complex values such as URLs or path names. You can use a string and encapsulate using the % symbol to mark the value name. For example:

apiServerURL: !format https://%hostname%:%port%

You can escape % characters by doubling them. For example, if value is 15, the following line:

percentage: !format %value%%%

results in:

percentage: 15%

Manage secret values

Any sensitive fields can be added to the template as !value keys, and passed in xl apply either in .xlvals files or directly in the CLI. This method has the advantage of not storing secrets in templates, and instead being able to put the secrets values file into a secure location such as a .gitignore file.

In xl generate, secret values will automatically be set as !value keys. Admins can use the --secrets flag to generate a secrets.xlvals file with the values supplied.