Tasks

Overview

There are many Task Types available, including scripts added directly, scripts and templates from the Library section, recipes, playbooks, salt states, puppet agent installs, and http (api) calls. Tasks are primarily created for use in Workflows, but a single Task can be executed on an existing instance via Actions > Run Task.

Role Permissions

The User Role Permission ‘Provisioning: Tasks FULL’ is required to create, edit and delete tasks.

Tasks Types that can execute locally against the Morpheus Appliance have an additional Role Permission: Tasks - Script Engines. Script Engine Task Types will be hidden for users without Tasks - Script Engines role permissions.

Common Options

When creating a Task, the required and optional inputs will vary significantly by the Task type. However, there are options which are common to Tasks of all types.

Target Options

When creating a Task, users can select a target to perform the execution. Some Task types allow for any of the three execution targets listed below and some will limit the user to two or just one. The table in the next section lists the available execution targets for each Task type.

  • Resource: A Morpheus-managed Instance or server is selected to execute the Task

  • Local: The Task is executed by the Morpheus appliance node

  • Remote: The user specifies a remote box which will execute the Task

Execute Options

  • Retryable: When marked, this Task can be configured to be retried in the event of failure

  • Retry Count: The maximum number of times the Task will be retried when there is a failure

  • Retry Delay: The length of time (in seconds) Morpheus will wait to retry the Task

  • Allow Custom Config: When marked, a text area is provided at Task execution time to allow the user to pass extra variables or specify extra configuration. See the next section for an example.

Allow Custom Config

When “Allow Custom Config” is marked on a Task, the user is shown a text area for custom configuration when the Task is executed manually from the Tasks List Page. If the Task is to be part of an Operational Workflow, mark the same box on the Workflow rather than on the Task to see the text area at execution time. This text area is inside the “Advanced Options” section, which must be expanded in order to reveal the text area. Within the text area, add a JSON map of key-value pairs which can be resolved within your automation scripts. This could be used to pass extra variables that aren’t always needed in the script or for specifying extra configuration.

Example JSON Map:

{"key1": "value1",
"key2": "value2",
"os": "linux",
"foo": "bar"}

When the Task is executed, these extra variables would be resolved where called into the script such as in the following simple BASH script example:

echo "<%=customOptions.os%>"
echo "<%=customOptions.foo%>"

The above example would result in the following output:

linux
bar

Task Types

Available Task Types

Task Type

Task Description

Source Options

Execute Target Options

Configuration Requirements

Role Permissions Requirements

ansible

Ansible

Runs an Ansible playbook. Ansible Integration required

Ansible Repo (Git)

Local, Resource

Existing Ansible Integration

Provisioning: Tasks

ansibletower

Ansible Tower

Relays Ansible calls to Ansible Tower

Tower Integration

Local, Remote, Resource

Existing Ansible Tower Integration

Provisioning: Tasks

chef

Chef bootstrap

Executes Chef bootstrap and run list. Chef Integration required

Chef Server

Resource

Existing Chef Integration

Provisioning: Tasks

email

Email

Send an email from a Workflow

Task Content

Local

SMTP Configured

Provisioning: Tasks

groovy

Groovy script

Executes Groovy Script locally (on Morpheus app node)

Local, Repository, Url

Local

None

Provisioning: Tasks, Tasks - Script Engines

http

HTTP

Executes REST call for targeting external API’s.

Local

Local

None

Provisioning: Tasks

javascript

Javascript

Executes Javascript locally (on Morpheus app node)

Local

Local

None

Provisioning: Tasks, Tasks - Script Engines

jruby

jRuby Scirpt

Executes Ruby script locally (on Morpheus app node)

Local, Repository, Url

Local

None

Provisioning: Tasks, Tasks - Script Engines

libraryscript

Library Script

Creates a Task from an existing Library Script (Library > Templates > Script Templates)

Library Script

Resource

Existing Library Script

Provisioning: Tasks

template

Library Template

Creates a Task from an existing Library Template (Library > Templates > Spec Templates)

Library Template

Resource

Existing Library Templates

Provisioning: Tasks

powershell

PowerShell Script

Execute PowerShell Script on the Target Resource

Local, Repository, Url

Remote, Resource, Local

None

Provisioning: Tasks

puppet

Puppet Agent Install

Executes Puppet Agent bootstrap, writes puppet.conf and triggers agent checkin. Puppet Integration required

Puppet Master

Resource

Existing Puppet Integration

Provisioning: Tasks

python

Python Script

Executes Python Script locally

Local, Repository, Url

Local

virtualenv installed on Appliance Nodes

Provisioning: Tasks, Tasks - Script Engines

restart

Restart

Restarts target VM/Host/Container and confirms startup status before executing next task in Workflow

System

Resource

None

Provisioning: Tasks

shellscript

Shell Script

Executes Bash script on the target resource

Local, Repository, Url

Local, Remote, Resource

None

Provisioning: Tasks

vro

vRealize Orchestrator Workflow

Executes vRO Workflow on the Target Resource

vRO Integration

Local, Resource

Existing vRO Integration

Provisioning: Tasks

wa

Write Attributes

Add arbitrary values to the Attributes map of the target resource

N/A

Local

Provide map of values as valid JSON

Provisioning: Tasks

Task Configuration

  • Ansible Playbook

    ansible

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • ANSIBLE REPO: Select existing Ansible Integration

    • GIT REF: Specify tag or branch (Option, blank assumes default)

    • PLAYBOOK: Name of playbook to execute, both playbook and playbook.yml format supported

    • TAGS: Enter comma separated tags to filter executed tasks by (ie --tags)

    • SKIP TAGS: Enter comma separated tags to run the playbook without matching tagged tasks (ie --skip-tags)

    Important

    Using different Git Refs for multiple Ansible Tasks in same Workflow is not supported. Git Refs can vary between Workflows, but Tasks in each Workflow must use the same Git Ref.

  • Ansible Tower Job

    ansibletower

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • TOWER INTEGRATION: Select an existing Ansible Tower integration

    • INVENTORY: Select an existing Inventory, when bootstrapping an Instance, Morpheus will add the Instance to the Inventory

    • GROUP: Enter a group name, when bootstrapping an Instance, Morpheus will add the Instance to the Group if it exists. If it does not exist, Morpheus will create the Group

    • JOB TEMPLATE: Select an existing job template to associate with the Task

    • SCM OVERRIDE: If needed, specify an SCM branch other than that specified on the template

    • EXECUTE MODE: Select Limit to Instance (template is executed only on Instance provisioned), Limit to Group (template is executed on all hosts in the Group), Run for all (template is executed on all hosts in the Inventory), or Skip Execution (to skip execution of the template on the Instance provisioned)

  • Chef bootstrap

    chef

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • CHEF SERVER: Select existing Chef integration

    • ENVIRONMENT: Populate Chef environment, or leave as _default

    • RUN LIST: Enter Run List, eg role[web]

    • DATA BAG KEY: Enter data bag key (will be masked upon save)

    • DATA BAG KEY PATH: Enter data bag key path, eg /etc/chef/databag_secret

    • NODE NAME: Defaults to Instance name, configurable

    • NODE ATTRIBUTES: Specify attributes inside the {}

  • Groovy script

    groovy

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • CONTENT: Contents of the Groovy script if not sourcing it from a repository

  • Email

    email

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • SOURCE: Choose local to draft or paste the email directly into the Task. Choose Repository or URL to bring in a template from a Git repository or another outside source

    • EMAIL ADDRESS: Email addresses can be entered literally or Morpheus automation variables can be injected, such as <%=instance.createdByEmail%>

    • SUBJECT: The subject line of the email, Morpheus automation variables can be injected into the subject field

    • CONTENT: The body of the email is HTML. Morpheus automation variables can be injected into the email body when needed

    • SKIP WRAPPED EMAIL TEMPLATE: The Morpheus-styled email template is ignored and only HTML in the Content field is used

    Tip

    To whitelabel email sent from Tasks, select SKIP WRAPPED EMAIL TEMPLATE and use an HTML template with your own CSS styling

  • HTTP (API)

    http

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • URL: An HTTP or HTTPS URL as the HTTP Task target

    • HTTP METHOD: GET (default), POST, PUT, PATCH, HEAD, or DELETE

    • AUTH USER: Username for username/password authentication

    • PASSWORD: Password for username/password authentication

    • BODY: Request Body

    • HTTP HEADERS: Enter requests headers, examples below:

    Authorization

    Bearer token

    Content-Type

    application/json

    • IGNORE SSL ERRORS: Mark when making REST calls to systems without a trusted SSL certificate

  • Javascript

    javascript

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • SCRIPT: Javascript contents to execute

  • jRuby Script

    jruby

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • CONTENT: Contents of the jRuby script is entered here if it’s not being called in from an outside source

  • Library Script

    libraryscript

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • SCRIPT: Search for an existing script in the typeahead field

  • Library Template

    template

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • TEMPLATE: Search for an existing template in the typeahead field

  • Powershell Script

    powershell

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • ELEVATED SHELL: Run script with administrator privileges

    • IP ADDRESS: IP address of the PowerShell Task target

    • PORT: SSH port for PowerShell Task target (5985 default)

    • USERNAME: Username for PowerShell Task target

    • PASSWORD: Password for PowerShell Task target

    • Content: Enter script to execute if not calling the script in from an outside source

    Note

    Setting the execution target to local requires Powershell to be installed on the Morpheus appliance box(es). Microsoft Documentation contains installation instructions for all major Linux distributions and versions.

  • Puppet Agent Install

    puppet

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • PUPPET MASTER: Select Puppet Master from an existing Puppet integration

    • PUPPET NODE NAME: Enter Puppet node name. Variables supported eg. <%= instance.name %>

    • PUPPET ENVIRONMENT: Enter Puppet environment, eg. production

  • Python Script

    python

    Important

    Beginning with Morpheus version 4.2.1, Python Tasks use virtual environments. For this reason, virtualenv must be installed on your appliances in order to work with Python Tasks. See the information below for more detailed steps to install virtualenv on your Morpheus appliance node(s).

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • CONTENT: Python script to execute is entered here if not pulled in from an outside repository

    • COMMAND ARGUMENTS: Optional arguments passed into the Python script. Variables supported eg. <%= instance.name %>

    • ADDITIONAL PACKAGES: Additional packages to be installed after requirements.txt (if detected). Expected format for additional packages: ‘packageName==x.x.x packageName2==x.x.x’, the version must be specified

    • PYTHON BINARY: Optional binary to override the default Python binary


    Enterprise Proxy Considerations

    Additional considerations must be made in enterprise proxy environments where Python Tasks are run with additional package download requirements. These additional packages are downloaded using pip and may not obey global Morpheus proxy rules. To deal with this, create or edit the pip configuration file at /etc/pip.conf. Your configuration should include something like the following:

    [global]
    proxy = http://some-proxy-ip.com:8087
    

    For more information, review the Pip documentation on using proxy servers here.

    CentOS 7 / Python 2.7 (RHEL system Python)

    With a fresh install of Morpheus on a default build of CentOS 7, Python Tasks will not function due to the missing requirement of virtualenv.

    If you attempt to run a python task, you will get an error similar to the following:

    Task Execution Failed on Attempt 1
    sudo: /tmp/py-8ae51ebf-749c-4354-b6e4-11ce541afad5/bin/python: command not found
    

    In order to run Morpheus Python Tasks in CentOS 7, install virtualenv: yum install python-virtualenv

    If you require python3, you can specify the binary to be used while building the virtual environment. In a default install, do the following: yum install python3. Then, in your Morpheus Python Task, specify the binary in the PYTHON BINARY field as “/bin/python3”. This will build a virtual environment in /tmp using the python3 binary, which is equivalent to making a virtual environment like so: virtualenv ~/venv -p /bin/python3.

    If you wish to install additional Python packages into the virtual environment, put them in pip format and space-separated into the ADDITIONAL PACKAGES field on the Python Task. Use the help text below the field to ensure correct formatting.

    CentOS 8 and Python

    In CentOS 8, Python is not installed by default. There is a platform-python but that should not be used for anything in userland. The error message with a default install of CentOS 8 will be similar to this:

    Task Execution Failed on Attempt 1
    sudo: /tmp/py-cffc9a8f-c40d-451d-956e-d6e9185ade33/bin/python: command not found
    

    The default virtualenv for CentOS 8 is the python3 variety, for Morpheus to use Python Tasks, do the following: yum install python3-virtualenv

    If Python2 is required, do the following: yum install python2 and specify /bin/python2 as the PYTHON BINARY in your Morpheus Task.

    This will build a virtualenv in /tmp using the python2 binary, which is equivalent to making a virtualenv like so: virtualenv ~/venv -p /bin/python2

    If you wish to install additional Python packages into the virtual environment, put them in pip format and space-separated into the ADDITIONAL PACKAGES field on the Python Task. Use the help text below the field to ensure correct formatting.

  • Restart

    restart

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

  • Shell Script

    shellscript

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • SUDO: Mark the box to run the script as sudo

    • CONTENT: Script to execute is entered here if not pulled in from an outside repository


    Tip

    When the EXECUTE TARGET option is set to “Local” (in other words, the Task is run on the appliance itself), two additional fields are revealed: GIT REPO and GIT REF. Use GIT REPO to set the PWD shell variable (identifies the current working directory) to the locally cached repository (ex. /var/opt/morpheus-node/morpheus-local/repo/git/76fecffdf1fe96516e90becdab9de) and GIT REF to identify the Git branch the Task should be run from if the default (typically main or master) shouldn’t be used. If these options are not set, the working folder will be /opt/morpheus/lib/tomcat/temp which would not allow scripts to reference file paths relative to the repository (if needed).

  • vRealize Orchestrator Workflow

    vro

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • RESULT TYPE: Single Value, Key/Value Pairs, or JSON

    • vRO INTEGRATION: Select an existing vRO integration

    • WORKFLOW: Select a vRO workflow from the list synced from the selected integration

    • PARAMETER BODY (JSON):

  • Write Attributes

    wa

    • NAME: Name of the Task

    • CODE: Unique code name for API, CLI, and variable references

    • ATTRIBUTES: A JSON map of arbitrary values to write to the attributes property of the target resource


    Tip

    This is often useful for storing values from one phase of a Provisioning Workflow for access in another phase. See the video demo below for a complete example.


Task Management

Adding Tasks

  1. Select Automation from within the Library menu

  2. On the Tasks tab, click the Add button

  3. From the New Task Wizard input a name for the task

  4. Select the type of task from from the type dropdown

  5. Input the appropriate configuration details. These will vary signficiantly based on the selected Task type. More details on each Task type are contained in the preceding sections.

  6. Once done, click SAVE CHANGES

Tip

When writing a Task config, it’s often necessary to reference Morpheus variables which pertain to the specific Instance the Task is being run against. Morpheus includes a pop-out column along the right side of the Add/Edit Task modal which lists available variables. Click and drag the relevant variable into the config area and Morpheus will automatically fill in the variable call formatted for the currently chosen Task type. See the screenshot below.

../../_images/taskvars.png

Editing Tasks

  1. Select Automation from within the Library menu

  2. Click the pencil icon (✎) on the row of the task you wish to edit

  3. Modify Task as needed

  4. Once done, click SAVE CHANGES

Deleting Tasks

  1. Select Automation from within the Library menu

  2. Click the trash icon (🗑) on the row of the Task you wish to delete

Task Results

Overview

Using Task results, the output from any preceding Tasks within the same Workflow phase is available to be called into additional Tasks. The results are stored on the results variable. Since results are available to all Tasks, we can use results from any or all prior Tasks so long as they are executed within the same provision phase.

In script type tasks, if a RESULT TYPE is set, Morpheus will store the output on the results variable. It’s important to understand that the result type indicates the format of the Task output Morpheus should expect. Morpheus will parse that output into a Groovy map which can be retrieved and further parsed by resolving the results variable. If the RESULT TYPE is incorrectly set, Morpheus may not be able to store the Task results correctly. Jump to the section on Script Config Examples to see how script results are processed in various example cases.

Results Types

  • Single Value

    Entire task output is stored in <%=results.taskCode%> or <%=results["Task Name"]%> variable.

  • Key/Value pairs

    Expects key=value,key=value output. Entire task output is available with <%=results.taskCode%> or <%=results["Task Name"]%> variable (output inside []). Individual Values are available with <%=results.taskCode.key%> variables.

  • JSON

    Expects key:value,key:value json formatted output. Entire task output is available with <%=results.taskCode%> or <%=results["Task Name"]%> variable (output inside []). Individual Values are available with <%=results.taskCode.key%> variables.

Important

The entire output of a script is treated as results, not just the last line. Ensure formatting is correct for the appropriate result type. For example, if Results Type is json and the output is not fully json compatible, the result would not return properly.

Important

Task results are not supported for Library Script task types

Script Config Examples

Single Value using Task Code
Source Task Config
  • NAME: Var Code (single)

  • CODE: singleExample

  • RESULT TYPE: Single Value

  • SCRIPT: echo "string value"

Source Task Output: string value

Results Task Config (using task code in variable)
  • NAME: N/A

  • CODE: N/A

  • RESULT TYPE: N/A

  • SCRIPT: echo "single: <%=results.singleExample%>"

Results Task Output: single: string value

Single Value using Task Name
Source Task Config
NAME

Var Code

CODE

none

RESULT TYPE

Single Value

SCRIPT

echo "string value"

Source Task Output

string value

Results Task using task name in variable
Results Task Script

echo "task name: <%=results["Var Code"]%>"

Results Task Output

task name: test value

Key/Value Pairs
Source Task Config
NAME

Var Code (keyval)

CODE

keyvalExample

RESULT TYPE

Key/Value pairs

SCRIPT

echo "flash=bang,ping=pong"

Source Task Output

flash=bang,ping=pong

Results Task for all results
Results Task Script

echo "keyval: <%=results.keyvalExample%>"

Results Task Output

keyval: [flash:bang, ping:pong]

Results Task for a single value)
Results Task Script

echo "keyval value: <%=results.keyvalExample.flash%>"

Results Task Output

keyval value: bang

JSON
Source Task Config
NAME

Var Code (json)

CODE

jsonExample

RESULT TYPE

JSON

SCRIPT

echo "{\"ping\":\"pong\",\"flash\":\"bang\"}"

Source Task Output

{"ping":"pong","flash":"bang"}

Results Task for all results
Results Task Script

echo "json: <%=results.jsonExample%>"

Results Task Output

json: [ping:pong, flash:bang]

Results Task for a single value
Results Task Script

echo "json value: <%=results.jsonExample.ping%>"

Results Task Output

json value: pong

Multiple Task Results
Results Task Script
echo "single: <%=results.singleExample%>"
echo "task name: <%=results["Var Code"]%>"
echo "keyval: <%=results.keyvalExample%>"
echo "keyval value: <%=results.keyval.flash%>"
echo "json: <%=results.jsonExample%>"
echo "json value: <%=results.jsonExample.ping%>"
Results Task Output
single: string value
task name: string value
keyval: [flash:bang, ping:pong]
keyval value: bang
json: [ping:pong, flash:bang]
json value: pong

Workflow Config

Add one or multiple tasks with Results Type configured to a workflow, and the results will be available to all tasks in the same phase of the workflow via the <%=results.variables%> during the workflow execution.

  • Task Results are only available to tasks in the same workflow phase

  • Task Results are only available during workflow execution