Work with the YAML format for Deploy

This topic provides information about how to work with the YAML format for Deploy.

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. It also includes information on using the Spec section of the YAML file which provides the details of the configuration.

YAML file fields

Deploy 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	Digital.ai API (xl-deploy/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
Deploy	Import	Used to list multiple YAML files for sequential execution
Deploy	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 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.

• 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, Digital.ai 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 information on the supported features, search for "DevOps as Code by Digital.ai" in the Visual Studio Code Marketplace.

Review YAML generated from existing configurations

If you have existing applications and pipelines configured in Deploy, 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

YAML Validation for Environment Creation

The Deploy validates infrastructure members and dictionaries referenced in YAML files. For example,

apiVersion: xl-deploy/v1
kind: Environments
spec:
- name: Environments/env1
  type: udm.Environment
  members: 
  - Infrastructure/infra1
  dictionaries:
  - Environments/directory/dictionary
  failOnMissingCiRefs: false

In the provided YAML specification:

• When failOnMissingCiRefs is set to false:
  • The system skips validation for non-existent CIs.
  • Missing CIs are created, and the deployment proceeds without any error message.

Note: By default the failOnMissingCiRefs is set to false.

• When failOnMissingCiRefs is set to true:
  • The system verifies the existence of all the CIs defined in the YAML.
  • If any CI is missing or does not exist, the deployment fails, and an error message is displayed, listing the missing CIs.

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