Work with the YAML format

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

YAML file fields

Deploy/Release 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
Deploy Applications Deployment packages containing the physical files (artifacts) that comprise a version of an application
Deploy Infrastructure Servers, databases and middleware to which you deploy your applications
Deploy Environments Specific infrastructure (e.g., Dev, QA, Production) to which you deploy your applications.
Deploy Configuration Configuration details such as credentials, policies, notifications and triggers
Deploy Deployment Starts a deployment using the details in the spec section
Deploy Permissions Global and directory-level permissions for roles
Deploy Roles Roles to which global and directory-level permissions can be assigned
Deploy Users Users that can be assigned to roles
Release Templates Used to model the release flow process. Can include configuration details and have multiple spec sections
Release Release Creates and starts a release from a Release template
Release Permissions Specify global and directory-level permissions for users and roles
Release Users Users that can be assigned to roles
Release Roles Roles that can be assigned global permissions
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 Deploy/Release 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 Deploy and 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 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 Deploy and 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 Deploy Application configuration

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

xl generate 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 Deploy Infrastructure configuration

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

xl generate 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 Deploy Environment configuration

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

xl generate 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 Release Template configuration

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

xl generate 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 Deploy or 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 Deploy or Release with the characters above, they will automatically be generated with quotations to avoid this outcome.