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

This reference includes some useful snippets to get started when writing DevOps as Code YAML files that can be applied to XL Deploy and XL Release.

XL Deploy YAML snippets

This section includes some useful snippets to get started when writing YAML files to apply to XL Deploy.

Create infrastructure

Use the Infrastructure kind to set up servers and cloud / container endpoints. You can specify a list of servers in the spec section.

apiVersion: xl-deploy/v1
kind: Infrastructure
spec:
- name: Infrastructure/Apache  host
  type: overthere.SshHost
  os: UNIX
  address: tomcat-host.local
  username: tomcatuser
- name: Infrastructure/local-docker
  type: docker.Engine
  dockerHost: http://dockerproxy:2375
- name: aws
  type: aws.Cloud
  accesskey: YOUR ACCESS KEY
  accessSecret: YOUR SECRET

Create environments with dictionary

Create environments and dictionaries.

apiVersion: xl-deploy/v1
kind: Environments
spec:
- name: AWS Dictionary
  type: udm.Dictionary
  entries:
    region: eu-west-1
    username: aws-user
- name: AWS
  type: udm.Environment
  members:
  - ~Infrastructure/aws
  dictionaries:
  - ~Environments/AWS Dictionary

Create a deployment package with an artifact

Creates a deployment package for a war file:

apiVersion: xl-deploy/v1
kind: Applications
spec:
- name: Applications/MyApp
  type: udm.Application
  lastVersion: "1.0"
  children:
  - name: "1.0"
    type: udm.DeploymentPackage
    deployables:
    - name: Server
      type: jee.War
      file: !file server.war

Group multiple YAML files

Groups YAML files for sequential execution:

apiVersion: xl/v1
kind: Import
metadata:
 imports:
   - create/create-homes.yaml
   - create/create-files.yaml
   - create/create-docker.yaml
   - create/create-k8s.yaml

Define home directories

Use -home to indicate home directories:

apiVersion: xl-deploy/v1
kind: Environments
metadata:
 Environments-home: Environments/XL
 Configuration-home: Configuration/XL
 Infrastructure-home: Infrastructure/XL
spec:
 - directory: k8s
   children:
     - name: Local
       type: udm.Environment
       triggers:
         - ~Configuration/t1
         - Configuration/XL/t2
       members:
         - ~Infrastructure/k8s/Minukube/default
       dictionaries:
         - ../../dict2
 - name: dict
   type: udm.Dictionary
   entries:
     user: admin
     password: qwerty
   encryptedEntries:
     user: admin
     password: qwerty
 - name: dict2
   type: udm.Dictionary

Permissions

As of version 8.6, you can specify permissions-related details in YAML. This section includes YAML snippets for users, roles and global permissions.

Users

Create new users and passwords:

---
apiVersion: xl-deploy/v1
kind: Users
spec:
- username: admin
- username: chris_smith
- password: !value pass1
- username: jay_albert
- password: test
- username: sue_perez
- password: test

Roles

Create roles (Leaders and Developers) and assign users to each role:

---
apiVersion: xl-deploy/v1
kind: Roles
spec:
- name: Leaders
  principals:
  - jay_albert
- name: Developers
  principals:
  - ron_vallee
  - sue_perez

Global permissions

Assign global permissions to roles:

---
apiVersion: xl-deploy/v1
kind: Permissions
spec:
- directory: Applications/docker
  roles:
    - role: Leaders
      permissions:
        - controltask#execute
    - role: Developers
      permissions:
        - controltask#execute
        - generate#dsl
        - deploy#initial
- global:
  - role: Leaders
    permissions:
    - report#view
    - task#assign
  - role: Developers
    permissions:
    - task#skip_step
    - admin
    - login
    - task#takeover
    - task#preview_step
    - report#view
    - discovery
    - controltask#execute
    - task#assign
    - task#view
    - task#move_step
    - security#edit

XL Release YAML snippets

This section includes some useful snippets to get started when writing YAML files to apply to XL Release.

Create a Shared Configuration item

Set up a reusable server connection in Shared Configuration like this:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: XL Deploy
  type: xldeploy.XLDeployServer
  url: http://xl-deploy:4516
  username: !value XL_DEPLOY_USERNAME
  password: !value XL_DEPLOY_PASSWORD

Templates

Create a template

Here is a basic template with one manual task:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: Sample release
  type: xlrelease.Release
  phases:
  - name: DEV
    type: xlrelease.Phase
    tasks:
    - name: Do something
      type: xlrelease.Task

Create a folder structure

Create nested folders using the directory construct. You can create templates directly under the directory.

apiVersion: xl-release/v1
kind: Templates
spec:
- directory: My folder
  children:
  - directory: Subfolder
    children:
    - name: My subtemplate
      type: xlrelease.Release

Folders will be created if they don’t already exist.

Create a template in an existing folder

If a folder is already present, you can create a template in it with this snippet:

apiVersion: xl-release/v1
kind: Templates
metadata:
  home: My folder
spec:
- name: My template
  type: xlrelease.Release

Set descriptions in Markdown

The most convenient way to set a Markdown description is by using the | construct from YAML:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: My template
  type: xlrelease.Release
  description: |
    This is the standard release process. See our wiki <link>

Template properties

Here is a template with various properties:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: My template
  type: xlrelease.Release
  description: |
    This is the standard release process. See our wiki <link>
  scheduledStartDate: 2018-11-01T08:00:00Z
  scriptUsername: admin
  scriptUserPassword: admin
  tags:
  - Standard release

Variable usage

Variables are defined at the template level and can be referenced in tasks with the ${...} syntax. Here is an example:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: My release template
  type: xlrelease.Release
  variables:
  - key: version   # Define ${version} variable
    label: Version
    description: The version of this release
    type: xlrelease.StringVariable
    requiresValue: true
    showOnReleaseStart: true
  phases:
  - name: DEV
    type: xlrelease.Phase
    tasks:
    - name: Develop ${version}  # Use ${version} variable
      type: xlrelease.Task

Here is a list of examples for all variable types:

  variables:
  - key: stringVariable
    type: xlrelease.StringVariable
    value: Hello world
  - key: passwordVariable
    type: xlrelease.PasswordStringVariable
  - key: booleanVariable
    type: xlrelease.BooleanVariable
    value: true
  - key: numberVariable
    type: xlrelease.IntegerVariable
    value: 42
  - key: listVariable
    type: xlrelease.ListStringVariable
    value:
    - One
    - Two
    - Three
  - key: mapVariable
    type: xlrelease.MapStringStringVariable
    value:
      1: I
      2: II
      3: III
  - key: setVariable
    type: xlrelease.SetStringVariable
    value:
    - Apples
    - Pears
    - Oranges
  - key: listBoxVariable
    type: xlrelease.StringVariable
    valueProvider:
      type: xlrelease.ListOfStringValueProviderConfiguration
      values:
      - One
      - Two
      - Three

All task properties you can set on any task

Here is an overview of properties you can set on a task:

    tasks:
    - name: My task
      type: xlrelease.Task
      description: |
        **Markdown** description.
      owner: admin
      team: Release Admin
      scheduledStartDate: 2018-11-01T08:00:00Z
      dueDate: 2018-11-01T10:00:00Z
      plannedDuration: 7200
      delayDuringBlackout: true
      flagStatus: ATTENTION_NEEDED  # Possible values: OK, ATTENTION_NEEDED, AT_RISK
      flagComment: This task fails often
      tags:
      - Task tag
      watchers:
      - admin

Parallel and Sequential groups

Here is an example of Parallel and Sequential groups:

    tasks:
    - name: Parallel execution
      type: xlrelease.ParallelGroup
      tasks:
      - name: Task 1a
        type: xlrelease.Task
      - name: Task 1b
        type: xlrelease.Task
    - name: Sequential execution
      type: xlrelease.SequentialGroup
      tasks:
      - name: Task 1
        type: xlrelease.Task
      - name: Task 2
        type: xlrelease.Task

Use a failure handler

Use this construct to skip a task when it fails:

    tasks:
    - name: Deploy to DEV
      type: xldeploy.Deploy
      taskFailureHandlerEnabled: true
      taskRecoverOp: SKIP_TASK

This snippet runs a script that tries the task three times before it fails:

    tasks:
    - name: Try 3 times
      type: xlrelease.Task
      taskFailureHandlerEnabled: true
      taskRecoverOp: RUN_SCRIPT
      failureHandler: |
        if (releaseVariables['attempt'] < 3):
          releaseVariables['attempt'] = releaseVariables['attempt'] + 1
          taskApi.retryTask(getCurrentTask().getId(), "Retrying task from failure handler.")
        else:
          taskApi.skipTask(getCurrentTask().getId(), "Skipped task from failure handler.")

Create a Python and Groovy script tasks

These snippets will create Script tasks. Use the YAML | construct for the script section.

Jython script:

    tasks:
    - name: Sleep in Jython
      type: xlrelease.ScriptTask
      script: |
        import time
        time.sleep(5)

Groovy script:

    tasks:
    - name: Sleep in Groovy
      type: xlrelease.GroovyScriptTask
      script: |
        sleep(5000)

Create release task

The create release task starts a release. You do not need to define the output variable in the variable section as it will be created automatically.

    tasks:
    - name: Sub release
      type: xlrelease.CreateReleaseTask
      newReleaseTitle: My subrelease
      templateId: My template
      folderId: My folder/Subfolder
      templateVariables:
      - key: version
        value: 1.0
        type: xlrelease.StringVariable

Gate task with conditions

Add conditions to a Gate task like this: <!— source: YAML

apiVersion: xl-release/v1 kind: Templates metadata: home: My folder spec:

  • name: Gate conditions type: xlrelease.Release phases:
    • name: DEV type: xlrelease.Phase –> source: YAML ``` tasks:
      • name: Verify before deployment type: xlrelease.GateTask conditions:
        • name: Application is tested type: xlrelease.GateCondition
        • name: Environment is available type: xlrelease.GateCondition checked: true ```

Connect XL Release to XL Deploy

Set up a connection from XL Release to XL Deploy using this snippet:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: XL Deploy
  type: xldeploy.XLDeployServer
  url: http://xl-deploy:4516
  username: !value XL_DEPLOY_USERNAME
  password: !value XL_DEPLOY_PASSWORD

Simple XL Deploy deployment task

Here is a simple example of a task that triggers a deployment in XL Deploy:

    tasks:
    - name: Deploy REST-o-rant
      type: xldeploy.Deploy
      server: XL Deploy
      deploymentPackage:  rest-o-rant-api-docker/1.1
      deploymentEnvironment: Environments/Local Docker Engine

Note: The names correspond to items defined in an XL Deploy server so you must have a Shared Configuration object called XL Deploy already defined in XL Release.

Permissions

As of version 8.6, you can specify permissions-related details in YAML. This section includes YAML snippets for users, roles and global permissions.

User permissions

Create a new user and password:

---
apiVersion: xl-release/v1
kind: Users
spec:
- username: tim_ellis
  name: tim ellis
  email: tellis@company.com
  password: changeme
  enabled: true

Roles

Create roles (Leaders and Developers) and assign users to each role:

apiVersion: xl-release/v1
kind: Roles
spec:
- name: Leaders
  principals:
  - jay_albert
- name: Developers
  principals:
  - chris_smith
  - sue_perez

Global permissions

Assign global permissions to roles:

---
apiVersion: xl-release/v1
kind: Permissions
spec:
- global:
  - role: Leaders
    permissions:
    - template#create
    - reports#view
    - admin
    - security#edit
  - role: Developers
    permissions:
    - release#create
    - global_variables#edit
    - dashboard#create
    - folder#create_top_level

Folder permissions

Here is an example of folder permissions given to a folder named MyFolder.

---
apiVersion: xl-release/v1
kind: Permissions
spec:
- directory: MyFolder
  teams:
  - name: MyTeam
    roles:
    - Managers
    - Developers
    - Sysadmin
    permissions:
    - template#create_release
    - release#abort
  - name: Release Admin
    users:
    - admin
    permissions:
    - release#edit_precondition
    - release#edit
    - release#reassign_task
    - release#edit_security
    - release#view
    - release#lock_task
    - release#start
    - release#edit_blackout
    - release#edit_failure_handler
    - folder#view
    - release#abort
    - release#edit_task
  - name: Template Owner
    users:
    - admin
    permissions:
    - template#edit
    - template#lock_task
    - template#view
    - folder#view
    - template#edit_triggers
    - template#edit_precondition
    - template#edit_security
    - template#create_release
    - template#edit_failure_handler
  - name: Folder Owner
    users:
    - admin
    permissions:
    - group#edit
    - folder#edit_configuration
    - folder#view
    - dashboard#edit
    - folder#edit_security
    - folder#edit
    - dashboard#view
    - group#view

Releases

Create a release

Create a release based on a template directly from YAML using the Release kind:

apiVersion: xl-release/v1
kind: Release
spec:
  name: My folder/My release
  template: My release template
  variables:
    version: '1.0'