Enable and document tags for all tasks

This commit modifies the main playbook, quickstart.yml, to have a tag
for each task declared (where it was missing).
It also adds documentation on how to use specific tags to interact with
the setup from a developer/user point of view.
Docs is still WIP, needs to be completed with extras integration and
examples (See Depends-On).

Depends-On: https://review.openstack.org/#/c/473491/
Change-Id: Ibb9900c4f8cf7c7028619ca29d288b67fb5ddc7d

ci-scripts/usbkey/quickstart.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-DEFAULT_OPT_TAGS="untagged,provision,environment,undercloud-scripts,overcloud-scripts"
+DEFAULT_OPT_TAGS="untagged,provision,environment,undercloud-inventory,overcloud-scripts"
 
 : ${OPT_BOOTSTRAP:=0}
 : ${OPT_SYSTEM_PACKAGES:=0}

doc/source/getting-started.rst

@@ -104,6 +104,153 @@ Example::
 
     bash quickstart.sh -R master --no-clone --tags all --nodes config/nodes/1ctlr_1comp.yml -I --teardown none -p quickstart-extras-validate.yml $VIRTHOST
 
+Using tags to atomically execute specific phases of the deployment
+------------------------------------------------------------------
 
+Developers and testers may be interested in only running discrete tasks in an
+atomic fashion. Ansible offers an additional powerful way to control the flow
+of execution via ansible tags.
+A TripleO-Quickstart with TripleO-Quickstart-Extras deployment can be driven
+with tags by using the main playbook ``quickstart-extras.yml``, which contains
+the four playbooks mentioned above.
+The specific tags that help users to control the workflow are:
 
+  * In ``quickstart.yml``:
 
+    * provision
+    * environment
+    * libvirt
+    * undercloud-inventory
+
+  * In ``quickstart-extras-undercloud.yml``:
+
+    * freeipa-setup
+    * undercloud-setup
+    * undercloud-deploy
+
+  * In ``quickstart-extras-overcloud-prep.yml``:
+
+    * overcloud-prep-config
+    * overcloud-prep-containers
+    * overcloud-prep-images
+    * overcloud-prep-flavors
+    * overcloud-prep-network
+    * overcloud-ssl
+
+  * In ``quickstart-extras-overcloud.yml``:
+
+    * overcloud-deploy
+    * overcloud-inventory
+    * overcloud-check
+
+  * In ``quickstart-extras-validate.yml``:
+
+    * overcloud-validate
+
+For example, a user may want to only provision their environment:::
+
+    $HOMEDIR/tripleo-quickstart/quickstart.sh \
+      --bootstrap \
+      --no-clone \
+      --working-dir $WORKDIR \
+      --config $HOMEDIR/workdir/config.yml \
+      --nodes  $HOMEDIR/workdir/nodes.yml \
+      --playbook quickstart-extras.yml \
+      --teardown "all" \
+      --tags "provision" \
+      --release master \
+      $VIRTHOST
+
+The option ``--tags "provision"`` will execute JUST the provision task on the
+``$VIRTHOST`` machine so that a developer, for example, will be able to act on
+the ``undercloud.cow2`` image placed in this path:::
+
+    [root@VIRTHOST ~]# ls -la /var/cache/tripleo-quickstart/images/
+    total 11889496
+    drwxrwxr-x. 2 stack stack       4096 12 giu 12.42 .
+    drwxrwxr-x. 3 stack stack         20 30 mag 10.46 ..
+    -rw-rw-r--. 1 stack stack 2891579392 12 giu 12.42 0d2952297e7c562b7e82739e0ad162e9.qcow2
+    lrwxrwxrwx. 1 stack stack         75 12 giu 12.42 latest-undercloud.qcow2 -> /var/cache/tripleo-quickstart/images/0d2952297e7c562b7e82739e0ad162e9.qcow2
+
+Then it is possible to continue the deployment, but the command line must be
+different, it must contain options to preserve what was made before.
+Like this:::
+
+    $HOMEDIR/tripleo-quickstart/quickstart.sh \
+      --retain-inventory \
+      --teardown none \
+      --ansible-debug \
+      --no-clone \
+      --working-dir /path/to/workdir \
+      --config /path/to/config.yml \
+      --nodes /path/to/nodes.yml \
+      --playbook quickstart-extras.yml \
+      --release master \
+      --tags "environment" \
+      $VIRTHOST
+
+The two main options here are ``--retain-inventory`` which keep all the
+previously generated configurations (hosts and ssh files) and
+``--teardown none`` which will preserve any previously created virtual machine.
+At this point we will be able to list virtual machines as unprivileged user
+stack on the ``$VIRTHOST``:::
+
+    [stack@had-05 ~]$ virsh list
+     Id    Name                           State
+    ----------------------------------------------------
+
+It is also possible to use more than a tag in a single run, like in this case:::
+
+    $HOMEDIR/tripleo-quickstart/quickstart.sh \
+      --retain-inventory \
+      --teardown none \
+      --working-dir /path/to/workdir \
+      --config /path/to/config.yml \
+      --nodes /path/to/nodes.yml \
+      --playbook quickstart-extras.yml \
+      --release $RELEASE \
+      --tags "libvirt,undercloud-inventory" \
+      $VIRTHOST
+
+In which basically we move on with the deployment, launching the libvirt setup
+on the remote host that will deploy the undercloud virtual machine and get its
+IP address to be able to include it inside the inventory.
+At the end of these steps we will have all the virtual machines prepared, with
+the undercloud already running:::
+
+    [stack@had-05 ~]$ virsh list --all
+     Id    Name                           State
+    ----------------------------------------------------
+     2     undercloud                     running
+     -     compute_0                      shut off
+     -     compute_1                      shut off
+     -     control_0                      shut off
+     -     control_1                      shut off
+     -     control_2                      shut off
+
+And in addition the ``hosts`` file inside the working directory will be
+populated with the new data coming from the newly installed undercloud machine,
+making us able to access it like this:::
+
+    ssh -F /path/to/workdir/ssh.config.ansible undercloud
+
+At this point we're able to proceed with the undercloud configuration part,
+following the same approach and using the tags that are relevant to this
+specific phase. Looking at ``quickstart-extras-undercloud.yml`` playbook the
+tags for our purpose are ``undercloud-setup`` and ``undercloud-deploy``, so
+the command line will be:::
+
+    $HOMEDIR/tripleo-quickstart/quickstart.sh \
+      --retain-inventory \
+      --teardown none \
+      --working-dir /path/to/workdir \
+      --config /path/to/config.yml \
+      --nodes /path/to/nodes.yml \
+      --playbook quickstart-extras.yml \
+      --release $RELEASE \
+      --tags "undercloud-setup,undercloud-deploy" \
+      $VIRTHOST
+
+While the command ends, the user will be able to act on the undercloud and
+then when, everything is ready on his side, proceed with the further steps at
+the same, atomic, way.

playbooks/quickstart.yml

@@ -43,6 +43,8 @@
 - name:  Setup undercloud, overcloud, and supplemental vms
   hosts: virthost
   gather_facts: yes
+  tags:
+    - libvirt
   roles:
     - libvirt/setup
 
@@ -51,7 +53,7 @@
   hosts: localhost
   gather_facts: yes
   tags:
-    - undercloud-scripts
+    - undercloud-inventory
   roles:
     - tripleo-inventory
 

quickstart.sh

@@ -5,7 +5,7 @@
 # or even ansible modules
 LANG=C
 
-DEFAULT_OPT_TAGS="untagged,provision,environment,undercloud-scripts,overcloud-scripts,undercloud-install,undercloud-post-install,tripleoui-validate"
+DEFAULT_OPT_TAGS="untagged,provision,environment,libvirt,undercloud-inventory,overcloud-scripts,undercloud-install,undercloud-post-install,tripleoui-validate"
 ZUUL_CLONER=/usr/zuul-env/bin/zuul-cloner
 
 : ${OPT_BOOTSTRAP:=0}

releasenotes/notes/tags_for_all_tasks-7797e4ba6492794e.yaml

@@ -0,0 +1,13 @@
+---
+features:
+  - |
+    Tags were added in all the playbooks so that it is possible to control
+    atomically the flow of the entire process.
+    The *DEFAULT_OPT_TAGS* variable used in quickstart.sh has been changed to
+    reflect all the available tags, which are *untagged*, *provision*,
+    *environment*, *libvirt*, *undercloud-inventory*, *overcloud-scripts*,
+    *undercloud-install* and *undercloud-post-install*.
+deprecations:
+  - |
+    The old tag named *undercloud-scripts* has been replaced with the more
+    self-explaining *undercloud-inventory*.