Version: Release 22.3

YAML Snippets Reference in Release

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

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

Create a Shared Configuration item

Set up a reusable server connection in Shared Configuration:

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

Manage templates

Create a template

Create 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

note

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:

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

Set descriptions in Markdown

Set a Markdown description 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

Define template 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:

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 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 a 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
      template: My template
      folder: My folder/Subfolder
      templateVariables:
      - key: version
        value: 1.0
        type: xlrelease.StringVariable

Gate task with conditions

Add conditions to a Gate task like this:

    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 Release to Deploy

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

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

Simple Deploy deployment task

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

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

note

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

Manage permissions

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

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'

Source tag for adding file values to a property

The !source tag followed by a file path takes the contents of a file in the specified location and adds it as the value of a property in the form of a string. This can be useful for example if you have a long description which is more convenient to store in an external file, or if you want to store a script separately and add it to a property such as a script action. If the file cannot be found, it will return an error.

apiVersion: xl-release/v1
kind: Templates
spec:
- directory: AsCode
  children:
  - template: As Code child release
    description: !source text/description.md
    variables:
    - type: xlrelease.StringVariable
      key: version
      label: release version
      description: this variable contains the version of the release
    phases:
    - phase: Child release phase 1
      tasks:
      - scripty
      type: xlrelease.GroovyScriptTask
      owner: admin
      script: !source script/some_script.py

Blackouts, special days, and environment reservations

Blackouts and special days

Create blackout periods or set special days:

apiVersion: xl-release/v1
kind: Templates
spec:
- calendar:
  - type: xlrelease.ReleaseCalendar
    blackouts:
    - type: xlrelease.Blackout
      label: blackout1
      startDate: 2021-01-22T00:00:00+01:00
      endDate: 2021-01-22T18:59:59+01:00
    - type: xlrelease.Blackout
      label: blackout2
      startDate: 2021-01-22T19:00:00+01:00
      endDate: 2021-01-22T19:59:59+01:00
    specialDays:
    - type: xlrelease.SpecialDay
      label: specialDay1
      startDate: 2021-01-22T00:00:00+01:00
      endDate: 2021-01-22T23:59:59+01:00
      color: '#febb4c'

Environment reservations

Create environment reservations:

apiVersion: xl-release/v1
kind: Environments
spec:
  reservations:
  - environment: Prod1
    applications:
    - PerClinic
    startDate: 2021-01-18T11:54:14.968+01:00
    endDate: 2021-01-20T14:54:14.969+01:00

note

Adding blackouts and reservations through as-code is append-only.

Create a Shared Configuration item​

Manage templates​

Create a template​

Create a folder structure​

Create a template in an existing folder​

Set descriptions in Markdown​

Template properties​

Variable usage​

All task properties you can set on any task​

Parallel and Sequential groups​

Use a failure handler​

Create Python and Groovy script tasks​

Create a release task​

Gate task with conditions​

Connect Release to Deploy​

Simple Deploy deployment task​

Manage permissions​

User permissions​

Roles​

Global permissions​

Folder permissions​

Create a release​

Source tag for adding file values to a property​

Blackouts, special days, and environment reservations​

Blackouts and special days​

Environment reservations​

Create a Shared Configuration item

Manage templates

Create a template

Create a folder structure

Create a template in an existing folder

Set descriptions in Markdown

Template properties

Variable usage

All task properties you can set on any task

Parallel and Sequential groups

Use a failure handler

Create Python and Groovy script tasks

Create a release task

Gate task with conditions

Connect Release to Deploy

Simple Deploy deployment task

Manage permissions

User permissions

Roles

Global permissions

Folder permissions

Create a release

Source tag for adding file values to a property

Blackouts, special days, and environment reservations

Blackouts and special days

Environment reservations