20. Workflows¶

Workflows allow you to configure a sequence of disparate job templates that may or may not share inventory, playbooks, or permissions. However, workflows have ‘admin’ and ‘execute’ permissions, similar to job templates. A workflow accomplishes the task of tracking the full set of jobs that were part of the release process as a single unit.

Note

Workflows are only available to those with Enterprise-level licenses.

Job templates are linked together using a graph-like structure called nodes. Job template nodes are associated with job templates. A job template can be a part of different workflows or used multiple times in the same workflow. A copy of the graph structure is saved to a workflow job when you launch the workflow.

As the workflow runs, jobs are spawned from the node’s linked template. Nodes linking to a job template which has prompt-driven fields (job_type, job_tags, skip_tags, limit) can contain those fields, and will not be prompted on launch. Job templates with promptable credential and/or inventory, WITHOUT defaults, will not be available for inclusion in a workflow.

A node can have only one parent and can only have children that is linked to a state of success, failure, or always. If always, then the state is neither success or failure. States apply at the node level, not at the workflow job template level. A workflow job will be marked as successful unless it is canceled or encounters an error.

If you attempt to launch a workflow job template that has the following missing pieces, the user interface will notify you as a warning but will still proceed:

Job template deleted from the node
A prompted field is provided, but the job template is not set to prompt on launch for the field

If you launch from the API, running a get command displays a list of warnings and highlights missing components. The basic workflow for a workflow job template is illustrated below.

It is possible to launch several workflows simultaneously, and set a schedule for when to launch them. You can set notifications on workflows, such as when a job completes, similar to that of job templates.

20.1. Extra Variables¶

Also similar to job templates, workflows use surveys to specify variables to be used in the playbooks in the workflow, called extra_vars. Survey variables are combined with extra_vars defined on the workflow job template, and saved to the workflow job extra_vars. extra_vars in the workflow job are combined with job template variables when spawning jobs within the workflow.

Workflows utilize the same behavior (hierarchy) of variable precedence as Job Templates with the exception of three additional variables. Refer to the Ansible Tower Variable Precedence Hierarchy in the Extra Variables section of the Job Templates chapter of this guide. The three additional variables include:

_images/Architecture-Tower_Variable_Precedence_Hierarchy-Workflows.png

In addition to the workflow extra_vars, jobs ran as part of a workflow can inherit variables in the artifacts dictionary of a parent job in the workflow (also combining with ancestors further upstream in its branch). These can be defined by the set_stats Ansible module, version 2.2.2 or later.

If you use the set_stats module in your playbook, you can produce results that can be consumed downstream by another job, for example, notify users as to the success or failure of an integration run. In this example, there are two playbooks that can be combined in a workflow to exercise artifact passing:

invoke_set_stats.yml: first playbook in the workflow:

- hosts: localhost
tasks:
  - name: "Artifact integration test results to the web"
    local_action: 'shell curl -F "file=@integration_results.txt" https://file.io'
    register: result

  - name: "Artifact URL of test results to Tower Workflows"
    set_stats:
      data:
        integration_results_url:  "{{ (result.stdout|from_json).link }}"

use_set_stats.yml: second playbook in the workflow

- hosts: localhost
tasks:
  - name: "Get test results from the web"
    uri:
      url: "{{ integration_results_url }}"
      return_content: true
    register: results


  - name: "Output test results"
    debug:
      msg: "{{ results.content }}"

The set_stats module processes this workflow as follows:

The contents of an integration results (example: integration_results.txt below) is first uploaded to the web.

the tests are passing!

Through the invoke_set_stats playbook, set_stats is then invoked to artifact the URL of the uploaded integration_results.txt into the Ansible variable “integration_results_url”.
The second playbook in the workflow consumes the Ansible extra variable “integration_results_url”. It calls out to the web using the uri module to get the contents of the file uploaded by the previous Job Template Job. Then, it simply prints out the contents of the gotten file.

Note

For artifacts to work, keep the default setting, per_host = False in the set_stats module.

20.2. Workflow States¶

The workflow job can have the following states (no Failed state):

Waiting
Running
Success (finished)
Cancel
Error

In the workflow scheme, canceling a job cancels the branch, while canceling the workflow job cancels the entire workflow. Deleting a job template does not delete the job node, but will indicate that is it invalid by displaying in the user interface, a broken link in the workflow, which prompts for correction without adverse impact to the structure of the workflow.

20.3. Role-Based Access Controls¶

To edit and delete a workflow job template, you must have the admin role. To create a workflow job template, you must be an organization admin or a system admin. However, you can run a workflow job template that contains job templates you don’t have permissions for. Similar to projects, organization admins can create a blank workflow and then grant an admin_role to a low-level user, after which they can go about delegating more access and building the graph. You must have execute access to a job template to add it to a workflow job template.

Other tasks such as the ability to make a duplicate copy and re-launch a workflow can also be performed, depending on what kinds of permissions are granted to a particular user. Generally, you should have permissions to all the resources used in a workflow (like job templates) before relaunching or making a copy.

For more information on performing the tasks described in this section, refer to the Ansible Tower Administration Guide.