WORKFLOWS.md 5.83 KB
Newer Older
1 2
These docs show how to populate an example workflow in Tower
and how to automate the creation or copying of workflows.
AlanCoding's avatar
AlanCoding committed
3

4 5 6 7
## Normal CRUD

Workflows and workflow nodes can be managed as normal tower-cli resources.

AlanCoding's avatar
AlanCoding committed
8 9
### Workflow Creation

10
Create an empty workflow:
AlanCoding's avatar
AlanCoding committed
11
```
12 13 14 15 16 17
tower-cli workflow create --name="workflow1" --organization="Default" --description="example description"
```

Check the existing workflows with the standard list or get commands.
```
tower-cli workflow list --description-on
AlanCoding's avatar
AlanCoding committed
18 19 20 21 22
```

### Node Creation

Create nodes inside the workflow
23
These all become "root" nodes and will spawn jobs on workflow launch
AlanCoding's avatar
AlanCoding committed
24
without any dependencies on other nodes.
25
These commands create 2 root nodes.
AlanCoding's avatar
AlanCoding committed
26
```
27 28
tower-cli node create -W workflow1 --job-template="Hello World"
tower-cli node create -W workflow1 --job-template="Hello World"
AlanCoding's avatar
AlanCoding committed
29 30 31 32
```

List the nodes inside of the workflow
```
33
tower-cli node list -W workflow1
AlanCoding's avatar
AlanCoding committed
34 35 36 37 38
```

### Node Association

From the list command, you can find the ids of nodes you want to link
39 40 41
`assocate_success_node` will cause the 2nd node to run on success of the
first node. The following command causes node 2 to run on the event of
successful completion of node 1.
AlanCoding's avatar
AlanCoding committed
42
```
43
tower-cli node assocate_success_node 1 2
AlanCoding's avatar
AlanCoding committed
44 45
```

46 47 48 49 50
This operation is only possible when node 2 is a root node.
See the Tower documentation for the limitations on the types of node
connections allowed.

Auto-creation of the success node, only knowing the parent node id:
AlanCoding's avatar
AlanCoding committed
51
```
52
tower-cli node assocate_success_node 8 --job-template="Hello world"
AlanCoding's avatar
AlanCoding committed
53 54
```

55 56 57 58
Corresponding disassociate commands are also available. Disassociating
a node from another node will make it a root node.

## Node Network Bulk Management
59 60

To print out a YAML representation of the nodes of a workflow, you can
61
use the following command. JSON format is also allowed.
62 63

```
64
tower-cli workflow schema workflow1
65 66
```

67
Here, "workflow1" is the name of the workflow.
AlanCoding's avatar
AlanCoding committed
68

69
### Creating/updating a Schema Definition
70

71
To bulk-create or buld-update a workflow node network, use the workflow schema command.
72
The schema is JSON or YAML content, and can be passed in the CLI
73 74 75
argument, or pointed to a file. The schema is passed as a second positional
argument, where the first argument references the workflow.

AlanCoding's avatar
AlanCoding committed
76
```
77
tower-cli workflow schema workflow2 @schema.yml
AlanCoding's avatar
AlanCoding committed
78 79
```

80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
The schema can be provided without using a file:

```
tower-cli workflow schema workflow2 '[{"job_template": "Hello world"}]'
```

The Schema definition defines the hierarchy structure that connects the nodes.
Names, as well as other valid parameters for node creation, are acceptable
inside of the node's entry inside the schema definition.

Links must be declared as a list under a key that starts with "success",
"failure", or "always". The following is an example of a valid schema
definition.

Example `schema.yml` file:

AlanCoding's avatar
AlanCoding committed
96
```yaml
97
- job_template: Hello world
98 99 100 101 102 103 104 105 106
  failure:
  - inventory_source: AWS servers (AWS servers - 42)
  success:
  - project: Ansible Examples
    always:
    - job_template: Echo variable
      success:
      - job_template: Scan localhost

AlanCoding's avatar
AlanCoding committed
107
```
108 109 110 111 112 113 114 115

This style may be useful to apply in a script to create a workflow
network with a tower-cli command after the constituent resources like
the job templates and projects were created by preceding
tower-cli commands.

### Differences with Machine Formatted Schemas

116 117 118 119
After writing a workflow schema, you may notice differences
in how tower-cli subsequently echos the schema definition back to you.
The following is what tower-cli might return after
writing the above example.
120 121 122 123 124 125 126 127 128 129 130 131 132 133

```yaml
- failure_nodes:
  - inventory_source: 42
  job_template: 45
  success_nodes:
  - always_nodes:
    - job_template: 55
      success_nodes:
      - job_template: 44
    project: 40

```

134
Note that the root node data starts with "failure_nodes", instead
135 136 137
of the name of the job template. This will not impact functionality, and
manually changing the order will not impact functionality either.

138
Although this format is harder to read, it does the same thing
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
as the previous schema. The ability to both echo and create schemas can
be used to copy the contents of one workflow to another.

As an example, consider 2 workflows. The first has a name "workflow1", and
has its node network populated. The second is named "workflow2" and is empty.
The following commands will copy the structure from the first to the second.

```bash
tower-cli workflow schema workflow1 > schema.yml
tower-cli workflow schema workflow2 @schema.yml
```

### Idempotence

The workflow schema feature populates the workflow node network based on the
154 155
hierarchy structure. Before creating each node, it attempts to find an
existing node with the specified properties in that location in the
156 157 158
tree, and will not create a new node if it exists. Also, if an existing node
has no correspondence in the schema, the entire sub-tree based on that node will
be deleted.
159

160 161 162
Thus, after running the schema command, the resulting workflow topology will always
be exactly the same as what is specified in the given schema file. To continue with
the previous example, subsequent invocations of:
163 164 165 166 167 168

```bash
tower-cli workflow schema workflow2 @schema.yml
tower-cli workflow schema workflow2 @schema.yml
```

169 170
should not change the network of workflow2, since `schema.yml` file itself remains
unchanged. However
171

172 173 174 175 176
```bash
tower-cli workflow schema workflow2 @new_schema.yml
```

will modify topology of workflow2 to exactly the same as what is specified in `new_schema.yml`.
177 178 179 180 181 182

## Launching Workflow Jobs

Use the workflow_job resource to launch workflow jobs.
This supports the use of extra_vars, which can contain answers to
survey questions.
183 184 185 186
The `--monitor` and `--wait` flag are available to poll the server
until workflow job reaches a completed status. The `--monitor` option
will print rolling updates of the jobs that ran as part of the workflow.
Here is an example of using those features:
187 188

```
189
tower-cli workflow_job launch -W "echo Hello World" -e a=1 --monitor
190
```