Blueprint YAML format

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 Deploy/Release public blueprint repository provided in the Deploy/Release 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.

For more information about the available blueprint command flags, refer to xl blueprint command details.

Root YAML fields

All blueprint YAML files have the following root fields:

Metadata fields

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 blueprint. By default, parameter values will be used to replace variables in template files during blueprint generation.

Spec field notes

Note 1: If the type is SecretInput, SecretEditor or SecretFile the parameter is saved in a secrets.xlvals file so that they won’t be checked into the GIT repository and will not be replaced by actual values in the template files by default.
Note 2: 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 3: Parameters with SecretInput, SecretEditor or SecretFile type support default values as well.
When a SecretInput, SecretEditor or SecretFile parameter question is being presented, the default value will be shown on the prompt as raw text; and if the user enters an empty response for the question this default value will be used instead.

Types

The types that can be used for inputs are:

• Input: Used for simple text or number inputs.
• SecretInput: Used for simple secret or password inputs. These are by default saved in secrets.xlvals files so that they won’t be checked in the GIT repo and will not be replaced with actual values in the template files.
• Select: Used for select inputs where user can choose from given options.
• Confirm: Used for boolean inputs.
• Editor: Used for multiline or complex text input.
• SecretEditor: Used for multiline or complex secret inputs. These are by default saved in secrets.xlvals files so that they won’t be checked in the GIT repo and will not be replaced with actual values in the template files.
• File: Used for fetching the content of a given file path.
• SecretFile: Used for fetching the content of a given file path and treat it as secret. These are by default saved in secrets.xlvals files so that they won’t be checked in the GIT repo and will not be replaced with actual values in the template files.

Files fields

IncludeBefore/IncludeAfter fields for composability

includeBefore/IncludeAfter values will decide if the blueprint should be composed before or after the master blueprint. This will affect the order in which the parameters will be presented to the user and the order in which files are written. Entries in before/after will stack based on the order of definition. For more information, see Blueprint composability.

The following generic example shows a blueprint.yaml using Includes to compose multiple blueprints:

apiVersion: xl/v2
kind: Blueprint
metadata:
  name: Composed blueprint
  version: 2.0
spec:
  parameters:
  - name: Foo
    prompt: what is value for Foo?

  files:
  - path: xlr-pipeline.yml
    writeIf: !expr "Foo == 'foo'"

  includeBefore: # the `aws/datalake` will be executed first followed by the current blueprint.yaml
  # we will look for `aws/datalake` in the current-repository being used
  - blueprint: aws/datalake
    # with 'parameterOverrides' we can provide values for any parameter in the blueprint being composed. This way we can force to skip any question by providing a value for it
    parameterOverrides:
    # we are overriding the value and promptIf fields of the TestFoo parameter in the `aws/datalake` blueprint
    - name: TestFoo
      value: hello
      promptIf: !expr "3 > 2"
    # 'fileOverrides' can be used to skip files and can be conditional using dependsOn
    fileOverrides:
    - path: xld-environment.yml.tmpl
      writeIf: !expr "false" # we are skipping this file
    - path: xlr-pipeline.yml
      renameTo: xlr-pipeline-new.yml # we are renaming this file since the current blueprint.yaml already has this file defined in the file section above
  includeAfter: # the `k8s/environment` will be executed after the current blueprint.yaml
  # we will look for `k8s/environment` in the current-repository being used
  - blueprint: k8s/environment
    parameterOverrides:
    - name: Test
      value: hello2
    fileOverrides:
    - path: xld-environment.yml.tmpl
      writeIf: !expr "false"

Supported custom YAML tags

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

Expression tag (!expr)

Blueprints support custom expressions to be used within parameter definitions, file declarations, and includeBefore/includeAfter. The expression tag can be used in the parameter/parameterOverrides fields default, value, promptIf, options, validate; the file/fileOverrides field writeIf, and the includeBefore/includeAfter field includeIf.

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

Custom expression syntax

!expr "EXPRESSION"

Operators and types supported

• Modifiers: + - / * & | ^ ** % >> <<
• Comparators: > >= < <= == != =~ !~
• Logical operators: || &&
• 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 and false
• Parenthesis to control order of evaluation ( )
• Arrays (anything separated by , within parenthesis: (1, 2, 'foo'))
• Prefixes: ! - ~
• Ternary conditional: ? :
• Null coalescence: ??

See MANUAL.md from govaluate for more information on what types each operator supports.

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

Blueprint YAML example

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

apiVersion: xl/v2
kind: Blueprint
metadata:
  name: Blueprint Project
  description: A Blueprint project
  author: XebiaLabs
  version: 1.0
spec:
  parameters:
  - name: Provider
    prompt: what is your Kubernetes provider?
    type: Select
    options:
      - AWS
      - GCP
      - Azure
    default: AWS

  - name: Service
    prompt: What service do you want to deploy?
    type: Select
    options:
      - !expr "Provider == 'GCP' ? ('GKE', 'CloudStorage') : (Provider == 'AWS' ? ('EKS', 'S3') : ('AKS', 'AzureStorage'))"
    default: !expr "Provider == 'GCP' ? 'GKE' : (Provider == 'AWS' ? 'EKS' : 'AKS')"

  - name: K8sClusterName
    prompt: What is your Kubernetes cluster name
    type: Input
    promptIf: !expr "Service == 'GKE' || Service == 'EKS' || Service == 'AKS'"
    default: !expr "k8sConfig('ClusterServer')"

  # AWS specific variables
  - name: UseAWSCredentialsFromSystem
    prompt: Do you want to use AWS credentials from your ~/.aws/credentials file?
    type: Confirm
    promptIf: !expr "Provider == 'AWS' && awsCredentials('IsAvailable')"

  - name: AWSAccessKey
    type: SecretInput
    prompt: What is the AWS Access Key ID?
    promptIf: !expr "Provider == 'AWS' && !UseAWSCredentialsFromSystem"
    default: !expr "awsCredentials('AccessKeyID')"

  - name: AWSAccessSecret
    prompt: What is the AWS Secret Access Key?
    type: SecretInput
    promptIf: !expr "Provider == 'AWS' && !UseAWSCredentialsFromSystem"
    default: !expr "awsCredentials('SecretAccessKey')"

  - name: AWSRegion
    type: Select
    prompt: "Select the AWS region:"
    promptIf: !expr "Provider == 'AWS'"
    options:
      - !expr "awsRegions('ecs')"
    default: !expr "awsRegions('ecs', 0)"

  files:
  - path: xld-k8s-infrastructure.yml
    writeIf: !expr "Service == 'GKE' || Service == 'EKS' || Service == 'AKS'"
  - path: xld-storage-infrastructure.yml
    writeIf: !expr "Service == 'CloudStorage' || Service == 'S3' || Service == 'AzureStorage'"

Go templates

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

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

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 Deploy/Release Blueprint repository URL.
• The XL-CLI configuration file can be updated manually or appropriate command line flags can also be passed when running the command in order to specify a different remote blueprint repository. Please refer to the XL-CLI documentation for detailed configuration and command line flag usage.
• 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 information, see Manage blueprint repositories.

Blueprint answers file

When testing blueprints, or when there are too many blueprint questions to answer through a command line, you can use an answers file to supply responses to blueprint questions. The flags -a (answers) and -s (strict-answers), as described in the XL-CLI documentation. The answers file format is expected to be YAML.

Example answers.yaml:

AppName: TestApp
ClientCert: |
    FshYmQzRUNbYTA4Icc3V7JEgLXMNjcSLY9L1H4XQD79coMBRbbJFtOsp0Yk2btCKCAYLio0S8Jw85W5mgpLkasvCrXO5
    QJGxFvtQc2tHGLj0kNzM9KyAqbUJRe1l40TqfMdscEaWJimtd4oygqVc6y7zW1Wuj1EcDUvMD8qK8FEWfQgm5ilBIldQ
ProvisionCluster: true
AWSAccessKey: accesskey
AWSAccessSecret: accesssecret
DiskSize: 100.0

When using answers files with the --strict-answsers flag, any command line input can be bypassed and blueprints can be fully automated. For more information on how to automate tests for blueprints with answers files and test case files, refer to Blueprint testing.

When an answers file is provided, it will be used in the same order as the command line input. As usual, while preparing a value for the parameter the steps will be:

• If the promptIf field exists, answers are evaluated and based on the boolean result, decided whether or not to continue.
• If the value field is present in the parameter definition, regardless of the answers file value, the value field value is going to be used.
• If the answers file is present and the value parameter is found within, it will be used.
• If none of the above is present and the parameter is not skipped due to a condition, the user will be asked to provide input through the command line if --strict-answers is not enabled.