Valid since:
XL Deploy 8.5.0
XL Release 8.5.0
XL JetPack 8.5.0

This topic provides a reference for the DevOps as Code YAML file structure for a blueprint. You can review the publicly-available blueprint files alongside the content in this topic to get a better understanding of how fields, values and options are specified.

By default, the XL CLI is configured to access the read-only XebiaLabs public blueprint repository provided in the XebiaLabs public software distribution site. The source files for the blueprints are stored in the blueprints repository on GitHub.

You can also see the curated list of Blueprints provided by XebiaLabs that includes links to GitHub readme files with details for each blueprint.

Root YAML fields

All blueprint YAML files have the following root fields:

Field name Expected value Examples Required?
apiVersion xl/v1 - Yes
kind Blueprint - Yes
metadata - See below No
spec - See below Yes

Metadata fields

Field name Expected value Examples Required?
projectName - Sample Project No
description - A long description that describes the blueprint project No
author - My Company No
version - 1.0 No

Spec fields

Fields in the spec section include parameters and files.

Parameters fields

Parameters are defined by the blueprint creator in the blueprint.yaml file and can be used in the blueprint template files. If no value is defined for a parameter in the blueprint.yaml file, the user will be prompted to enter its value during execution of the bluerpint. By default, parameter values will be used to replace variables in template files during blueprint generation.

Field name Expected value(s) Examples Default Value Required? Details
name - AppName - Yes Variable name, to be used in templates
type Input/Select/Confirm/Editor/File   - Yes Prompt type. See Spec field notes for more details
value - - eu-west-1
- !fn aws.regions(ecs)[0]
- !expression "Foo == 'foo' ?
- 'A' : 'B'
- No If present, the user will not be asked a question to provide a value
The !expression tag is only available in version 8.6
default - - eu-west-1
- !fn aws.regions(ecs)[0]
- !expression "Foo == 'foo' ?
- 'A' : 'B'
- No Default value. Will be presented during the question prompt. Also will be the variable value if question is skipped
The !expression tag is only available in version 8.6
description - Application name. Will be used in various AWS resource names - No If present, will be used instead of the default question text
secret true or false - false No Variables that are marked as secret are saved in secrets.xlvals files so that they will not be checked into GIT repo and will not be replaced by default in the template files. See Spec field notes for more details
options - - eu-west-1
- us-east-1
- us-west-1
- !fn aws.regions(ecs)[0]
- !expression "Foo == 'foo' ?
- 'A' : 'B'
- No* Set of options for the Select input type. Can consist of any number of text values or custom tags
*Required for the Select input type
The !expression tag is only available in version 8.6
pattern - [a-z-]* - No Validation regular expression. To be verified at the time of user input
dependsOnTrue - - CreateNewCluster
- !fn aws.credentials().IsAvailable
- !expression "CreateNewCluster == true"
- No If this question is needed to be asked of user, and depends on the value of another, the dependsOn field can be defined. A valid variable name should be given and the variable name used should have been defined before order-wise.
Function tags also can be used, but the expected result should always be boolean
The !expression tag is only available in version 8.6
dependsOnFalse - - CreateNewCluster
- !fn aws.credentials().IsAvailable
- !expression "CreateNewCluster == true"
- No Reverse logic for dependsOnTrue as describe above
The !expression tag is only available in version 8.6
saveInXlVals true or false - See details No true for secret fields, false for other fields
Spec field notes

Note 1: The Editor and File values are available in version 8.6 only. For the type field, the File type does not support the value parameter. Also, the default parameter for this field expects to have a file path instead of a final value string. Note 2: For the secret field, parameters marked as secret support default values as well. When a secret parameter question is asked to the user, the default value will be shown in the prompt as raw text. If the user provides an empty response, this default value will be used.

Files fields

Field name Expected value(s) Examples Default Value Required? Details
path - xebialabs/xlr-pipeline.yaml - Yes File/template path to be copied/processed
dependsOnTrue - - CreateNewCluster
- !fn aws.credentials().IsAvailable
- !expression "CreateNewCluster == true"
- No This file will be generated only when value of a variable or function returns as true. A valid variable name should be given and the variable name used should have been defined. Function tags also can be used, but the expected result should always be boolean
The !expression tag is only available in version 8.6
dependsOnFalse - - CreateNewCluster
- !fn aws.credentials().IsAvailable
- !expression "CreateNewCluster == true"
- No Reverse logic for dependsOnTrue as describe above
The !expression tag is only available in version 8.6

Supported custom YAML tags

This section describes function and expression tags that you can use with blueprints.

Function tag (!fn)

Blueprints support custom functions !fn that can be used within variable definitions in the spec section of the YAML file.

You can use a function tag in the value, default, options, dependsOnTrue and dependsOnFalse fields.

Syntax

!fn DOMAIN.MODULE (PARAMETERS...).ATTRIBUTE|[INDEX]

Available custom functions

Domain Module Examples Parameters Attributes/Index Description
aws credentials aws.credentials().AccessKeyID Profile name (optional) AccessKeyID
SecretAccessKey
SessionToken
ProviderName
IsAvailable
Read AWS credentials package from the system aws-cli config file
aws regions aws.regions(ecs)
aws.regions(ecs)[0]
AWS service ID Any index of the resulting array Get the list of available regions for the specified AWS service
k8s config k8s.config().IsAvailable
k8s.config(myContext).ClusterServer
Context name (optional) - ClusterServer
- ClusterCertificateAuthorityData
- ClusterInsecureSkipTLSVerify
- ContextCluster
- ContextNamespace
- ContextUser
- UserClientCertificateData
- UserClientKeyData
- IsAvailable
Available in version 8.6 only. Get the specified Kubernetes context. If no context is specified, the current context in use will be fetched. The base64-encoded values are decoded automatically

Expression tag (!expression)

As of version 8.6, blueprints support custom expressions to be used within variable definitions and file declarations in the spec section of the YAML file. Expression tags can be used in value, default, options, dependsOnTrue and dependsOnFalse fields.

You can use a variable defined in the parameter section inside an expression. Variable names are case-sensitive and you should define the variable before it is used in an expression. In other words, you cannot refer to a variable that will be defined after the expression is defined in the blueprint.yaml file.

Syntax

!expression "EXPRESSION"

Operators and types supported

  • Modifiers: + - / * & | ^ ** % >> <<
  • Comparators: > >= < <= == != =~ !~
  • Logical ops: || &&
  • Numeric constants, as 64-bit floating point (12345.678)
  • String constants (single quotes: 'foobar')
  • Date constants (single quotes, using any permutation of RFC3339, ISO8601, ruby date, or unix date; date parsing is automatically tried with any string constant)
  • Boolean constants: true false
  • Parenthesis to control order of evaluation ( )
  • Arrays (anything separated by , within parenthesis: (1, 2, 'foo'))
  • Prefixes: ! - ~
  • Ternary conditional: ? :
  • Null coalescence: ??

For more details on what types each operator supports, see the manual for govaluate.

Types

The supported types are float64, bool, string, and arrays. When using expressions to return values for options, ensure that the expression returns an array. When using expressions on dependsOnTrue and dependsOnFalse fields, ensure that it returns boolean.

Escaping characters

You can escape characters for parameters that have spaces, slashes, pluses, ampersands or other characters that may be interpreted as special.

For example:

"response-time < 100"

This would be parsed as “[response] minus [time] is less than 100” whereas the intention is for “response-time” to be a variable that simply includes a dash.

You can work around this in two ways:

Method 1: Escape the entire parameter name

Example:

"[response-time] < 100"

Method 2: Use backslashes to escape only the minus sign

Example:

"response\\-time < 100"

Note: You can use backslashes anywhere in an expression to escape the very next character. Square-bracketed parameter names can be used instead of plain parameter names at any time.

Available custom functions for expressions

You can use the following functions in an expression:

Function Parameters Examples Description
strlen Variable or Text(string) - !expression "strlen('Foo') > 5"
- !expression "strlen(FooVariable) > 5"
Get the length of the given string variable
max Variable or numbers(float64, float64) - !expression "max(5, 10) > 5"
- !expression "max(FooVariable, 100)"
Get the maximum of the two given numbers
min Variable or numbers(float64, float64) - !expression "min(5, 10) > 5"
- !expression "min(FooVariable, 100)"
Get the minimum of the two given numbers
ceil Variable or number(float64) - !expression "ceil(5.8) > 5"
- !expression "ceil(FooVariable) > 5"
Ceil the given number to nearest whole number
floor Variable or number(float64) - !expression "floor(5.8) > 5"
- !expression "floor(FooVariable) > 5"
Floor the given number to nearest whole number
round Variable or number(float64) - !expression "round(5.8) > 5"
- !expression "round(FooVariable) > 5"
Round the given number to nearest whole number
randPassword - - !expression "randPassword()" Generates a random password of length 16
string Variable - !expression "string(Foo > 10 ? Foo : Bar)" Return string value

Blueprint YAML example

Here is an example of a blueprint.yaml file using expressions for complex behaviors:

apiVersion: xl/v1
kind: Blueprint
metadata:
  projectName: Blueprint Project
  description: A Blueprint project
  author: XebiaLabs
  version: 1.0
spec:
  parameters:
  - name: Provider
    description: what is your Kubernetes provider?
    type: Select
    options:
      - AWS
      - GCP
      - Azure
    default: AWS
  - name: Service
    description: What service do you want to deploy?
    type: Select
    options:
      - !expression "Provider == 'GCP' ? ('GKE', 'CloudStorage') : (Provider == 'AWS' ? ('EKS', 'S3') : ('AKS', 'AzureStorage'))"
    default: !expression "Provider == 'GCP' ? 'GKE' : (Provider == 'AWS' ? 'EKS' : 'AKS')"
  - name: K8sClusterName
    description: What is your Kubernetes cluster name
    type: Input
    dependsOnTrue: !expression "Service == 'GKE' || Service == 'EKS' || Service == 'AKS'"
  files:
  - path: xld-k8s-infrastructure.yml
    dependsOnTrue: !expression "Service == 'GKE' || Service == 'EKS' || Service == 'AKS'"
  - path: xld-storage-infrastructure.yml
    dependsOnTrue: !expression "Service == 'CloudStorage' || Service == 'S3' || Service == 'AzureStorage'"

Go templates

You can use GoLang templating in blueprint template files (.tmpl). See the following cheatsheet for more details how to use GoLang templates.

Support for additional Sprig functions are included in the templating engine, as well as list of custom XL functions. The table below describes additional functions that are currently available.

Please refer to below table for additional functions available.

Function Example Description
kebabcase .AppName | kebabcase Convert string to use kebab case (separated by -)

Note: Parameters marked as secret cannot be used with Go template functions and Sprig functions as their values will not be directly replaced in the templates.

Blueprint repository

Remote blueprint repositories are supported for fetching blueprint files.

  • Running the xl command for the first time will generate a default configuration file in your home directory (~/.xebialabs/config.yaml). This file includes the default XebiaLabs blueprint repository URL.
  • You can manually update the config.yaml file.
  • You can also use the appropriate command line flags when running the command in order to specify a different remote blueprint repository.

For more details, see Manage blueprint repositories.