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

DevOps as Code uses a declarative YAML format to construct specifications that can be executed by XL Deploy and XL Release using the XL CLI. This topic provides a reference for the XebiaLabs DevOps as Code YAML file structure for each available kind for XL Deploy and XL Release. It also includes information on using the Spec section of the YAML file which provides the details of the configuration.

YAML file fields

XebiaLabs YAML files include a common set of root fields and a kind field that identifies the type of YAML file.

Root fields

Field name Description
apiVersion XebiaLabs API (xl-deploy/v1, xl-release/v1, or xl/v1) and XL CLI version (v1, v2 and so on)
kind See Kind fields for details
spec Specifications based on kind. See the Spec section for details
metadata Used to define a list of other YAML files to import and home directories

Kind fields

Product Kind Description
XL Deploy Applications Deployment packages containing the physical files (artifacts) that comprise a version of an application
XL Deploy Infrastructure Servers, databases and middleware to which you deploy your applications
XL Deploy Environments Specific infrastructure (e.g., Dev, QA, Production) to which you deploy your applications.
XL Deploy Configuration Configuration details such as credentials, policies, notifications and triggers
XL Deploy Deployment Starts a deployment using the details in the spec section
XL Deploy Permissions Global and directory-level permissions for roles (version 8.6 or higher)
XL Deploy Roles Roles to which global and directory-level permissions can be assigned (version 8.6 or higher)
XL Deploy Users Users that can be assigned to roles (version 8.6 or higher)
XL Release Templates Used to model the release flow process. Can include configuration details and have multiple spec sections
XL Release Release Creates and starts a release from a XL Release template
XL Release Permissions Specify global and directory-level permissions for users and roles (version 8.6 or higher)
XL Release Users Users that can be assigned to roles (version 8.6 or higher)
XL Release Roles Roles that can be assigned global permissions (version 8.6 or higher)
All Import Used to list multiple YAML files for sequential execution
All Blueprint Blueprints YAML files are created from templates that streamline the provisioning process using standardized configurations built on best practices

Spec section

The spec section of the XebiaLabs YAML file has unique fields available depending on the YAML file’s kind. Due to the scope, complexity and flexibility of this section, the best way for you to understand the capabilities and constructs used in this section is to:

  • Review YAML generated from existing configurations - You can use the XL CLI generate command to generate YAML files for specific kinds from existing configurations or new configurations that you create in XL Deploy and XL Release.
  • Use YAML snippets - You can choose from a list of useful, customizable snippets to get started when writing a YAML file. See the YAML snippets reference for DevOps as Code
  • Utilize the Visual Studio Code extension - If you are using the Visual Studio Code editor, XebiaLabs provides an extension that adds YAML support for the XebiaLabs DevOps Platform to Visual Studio Code. The extension adds the following features:

    • Syntax highlighting
    • Code completion
    • Code validation
    • Code formatting
    • Code snippets
    • Context documentation

    To install the extension, and for more details on the supported features, search for “DevOps as Code by XebiaLabs” in the Visual Studio Code Marketplace.

Review YAML generated from existing configurations

If you have existing applications and pipelines configured in XL Deploy and XL Release, you can get started with DevOps as Code by using the xl generate command to generate YAML files with details from these existing configurations. Because the resulting YAML files and syntax represent familiar constructs used in your development environment, you can use the information as a starting point to extend and expand your own YAML files, helping to bootstrap your transition to an “as code” development and release model.

Here are a few simple XL CLI command line examples to generate YAML files from your existing configurations.

Generate a YAML file from an XL Deploy Application configuration

To generate a YAML file for an existing Application configuration from XL Deploy:

xl generate -s xl-deploy -p Applications/myapp -f tmp/myapplication.yaml

The resulting YAML file might look like:

apiVersion: xl-deploy/v1
kind: Applications
spec:
- name: Applications/App
  type: udm.Application
  lastVersion: '1.0'
  children:
  - name: '1.0'
    type: udm.DeploymentPackage
    deployables:
    - name: file
      type: file.File
      targetPath: /tmp
      file: !file artifacts/Applications/App/1.0/file/enhanced-buzz-9180-1421871254-19.webp

Generate a YAML file for an XL Deploy Infrastructure configuration

To generate a YAML file for an existing Infrastructure configuration from XL Deploy:

xl generate -s xl-deploy -p Infrastructure -f tmp/myinfra.yaml

The resulting YAML file might look like:

apiVersion: xl-deploy/v1
kind: Infrastructure
spec:
- name: Infrastructure/localhost
  type: overthere.LocalHost
  os: UNIX

Generate a YAML file for an XL Deploy Environment configuration

To generate a YAML file for an existing Infrastructure configuration from XL Deploy:

xl generate -s xl-deploy -p Environment -f tmp/myenvironment.yaml

The resulting YAML file might look like:

apiVersion: xl-deploy/v1
kind: Environments
spec:
- name: Environments/localEnv
  type: udm.Environment
  members:
  - Infrastructure/localhost

Generate a YAML file for an XL Release Template configuration

To generate a YAML file for an existing Template configuration from XL Release:

xl generate -s xl-release -p Pipeline -f /tmp/mypipeline.yaml

The resulting YAML file might look like:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: MyTemplate
  type: xlrelease.Release
  scheduledStartDate: 2018-10-25T07:00:00Z
  phases:
  - name: My Phase
    type: xlrelease.Phase
    tasks:
    - name: My Task
      type: xlrelease.Task
    color: #0099CC

Handling special boolean characters

The characters Y, N, 1, and 0 by themselves in a string-type field will be interpreted as boolean values by the YAML specification if they are not enclosed in quotes. This could result in unexpected behavior when applying a file in XL Deploy or XL Release, if the fields are not correctly declared.

For example, if you create a template with the name Y without enclosing it in quotes, then use xl apply to generate the template, the template name will be created as true. To avoid this outcome, in the YAML file you should always ensure that the characters above are enclosed in quotes in the form “Y”.

Note that if you use xl generate for fields already in XL Deploy or XL Release with the characters above, they will automatically be generated with quotations to avoid this outcome.