Add modify-images role

We use virt-customize for many tasks. Instead of having these tasks
all being implemented in different ways across the various roles,
we can instead have a utility role for that purpose. This allows
us to keep the implementation uniform across those tasks and
provides a single place to fix issues with our virt-customize
implementation.

New roles in quickstart-extras will be expected to use this role
for any virt-customize tasks. Eventually, we will want to port
existing virt-customize tasks to use this new role as well.

Change-Id: I6dcb398e17f20a4a2f862873067d92b1b520748c

roles/modify-image/README.md

@@ -0,0 +1,79 @@
+modify-image
+============
+
+An Ansible role for modifying an image via the libguestfs tool, virt-customize.
+The role requires an image and a script to run inside of that image via
+virt-customize. It also has paramaters for how much memory and cpu to give
+the virt-customize VM, and a list of artifacts to copy out of the VM after
+running the script. The script will always produce a log of the same name as
+the script with .log appended. This can be extracted via the
+`modify_image_extract_list` variable.
+
+Requirements
+------------
+
+* [libguestfs](http://libguestfs.org/)
+
+Role Variables
+--------------
+
+* `image_to_modify` -- the image that virt-customize will operate on
+* `modify_script` -- the script that will be run inside the image
+* `modify_image_extract_list` -- list of artifacts to extract after the image
+   is modified
+* `modify_image_working_dir` -- directory containing image and script. This is
+   also where extracted files and logs will end up.
+* `modify_image_vc_ram` -- amount of RAM to give the virt-customize VM (in MB)
+* `modify_image_vc_cpu` -- number of CPUs to give the virt-customize VM
+* `modify_image_vc_verbose` -- whether to run virt-customize with verbose flag
+* `modify_image_vc_trace` -- whether to run virt-customize with trace flag
+
+Example Usage
+-------------
+
+```yaml
+---
+- name: |
+    Run a script inside an image via virt-customize without extracting anything
+  hosts: virthost
+  vars:
+    image_to_modify: "{{ working_dir }}/undercloud.qcow2"
+    modify_script: "{{ working_dir }}/undercloud_convert.sh"
+  roles:
+    - modify-image
+
+- name: Run a script inside an image and extract the log from the script
+  hosts: virthost
+  vars:
+    image_to_modify: "{{ working_dir }}/undercloud.qcow2"
+    modify_script: "{{ working_dir }}/undercloud_convert.sh"
+    modify_image_extract_list:
+      - /tmp/builder.log
+  roles:
+    - modify-image
+
+- name: Run a script inside an image that needs to have lots of resources
+  hosts: virthost
+  vars:
+    image_to_modify: "{{ working_dir }}/undercloud.qcow2"
+    modify_script: "{{ working_dir }}/undercloud_convert.sh"
+    modify_image_vc_cpu: 8
+    modify_image_vc_ram: 16384
+  roles:
+    - modify-image
+
+- name: Run a script inside an image with virt-customize in verbose mode
+  hosts: virthost
+  vars:
+    image_to_modify: "{{ working_dir }}/undercloud.qcow2"
+    modify_script: "{{ working_dir }}/undercloud_convert.sh"
+    modify_image_verbose: true
+  roles:
+    - modify-image
+
+```
+
+License
+-------
+
+Apache

roles/modify-image/defaults/main.yml

@@ -0,0 +1,26 @@
+---
+
+# These variable do not have a default because there is no sane default. The
+# role will fail immediately if either is not specified.
+# image_to_modify:
+# modify_script:
+
+# The extract list defaults to empty list
+modify_image_extract_list: []
+
+# By default we use the global working directory for modifying images
+modify_image_working_dir: "{{ working_dir }}"
+
+# virt-customize defaults
+# vc_args can be used to pass any arbitrary arguments to virt-customize
+vc_args: ""
+
+# the other "vc" vars below are converted to the correct virt-customize args,
+# and are provided for convenience.
+
+# ram and cpu are not set by default to take libguestfs defaults by default
+# modify_image_vc_ram:
+# modify_image_vc_cpu:
+modify_image_vc_verbose: false
+modify_image_vc_trace: false
+

roles/modify-image/meta/main.yml

@@ -0,0 +1,2 @@
+dependencies:
+  - extras-common

roles/modify-image/tasks/main.yml

@@ -0,0 +1,50 @@
+---
+
+- name: make sure an image and script are provided
+  fail:
+    msg:
+        "In order to use this role image_to_modify and modify_script must be
+         provided."
+  when: image_to_modify is not defined or modify_script is not defined
+
+- name: ensure libguestfs is installed
+  yum: name=libguestfs-tools-c state=latest
+  become: true
+
+- name: virt-customize args --> memory
+  set_fact: vc_args="{{ vc_args }} -m {{ modify_image_vc_ram }}"
+  when: modify_image_vc_ram is defined
+
+- name: virt-customize args --> cpu
+  set_fact: vc_args="{{ vc_args }} --smp {{ modify_image_vc_cpu }}"
+  when: modify_image_vc_cpu is defined
+
+- name: virt-customize args --> verbose output
+  set_fact: vc_args="{{ vc_args }} -v"
+  when: modify_image_vc_verbose|bool
+
+- name: virt-customize args --> trace/debug output
+  set_fact: vc_args="{{ vc_args }} -x"
+  when: modify_image_vc_trace|bool
+
+- name: Run virt-customize on the provided image
+  shell: virt-customize {{ vc_args }}
+         -a {{ image_to_modify }}
+         --run {{ modify_script }}
+         > {{ modify_script }}.log 2>&1
+  environment:
+    LIBGUESTFS_BACKEND: direct
+  args:
+    chdir: "{{ modify_image_working_dir }}"
+
+- name: Extract artifacts from the image
+  shell: virt-copy-out
+         -a {{ image_to_modify }}
+         {{ item }}
+         {{ modify_image_working_dir }}
+  environment:
+      LIBGUESTFS_BACKEND: direct
+  args:
+      chdir: "{{ modify_image_working_dir }}"
+  with_items: "{{ modify_image_extract_list }}"
+