Add the ability to generate an ARA report only on job failure

This changes the 'ara_generate_html' toggle to provide three options:
- true (always generate a report)
- false (never generate a report)
- 'failure' (only generate a report on failure, based on zuul_success)

This defaults to true and can be changed on a job basis.

Change-Id: I9a6a3c999b7656b1f5b25b0cb6c2baa63d7857b2

roles/emit-ara-html/README.rst

@@ -5,6 +5,12 @@ Have ARA generate html logs if ARA and ARA data are both present.
 .. zuul:rolevar:: ara_generate_html
 
    Whether to generate a static ARA HTML report or not.
+   Possible values:
+
+   - ``true`` (always generate a report)
+   - ``false`` (never generate a report)
+   - ``failure`` (only generate a report on failure)
+
    Defaults to ``true``.
 
 .. zuul:rolevar:: ara_compress_html

roles/emit-ara-html/defaults/main.yaml

@@ -1,4 +1,8 @@
 # Whether to generate a static ARA HTML report or not
+# Possible values:
+#   - true (always)
+#   - false (never)
+#   - 'failure' (only on failure)
 ara_generate_html: true
 
 # Whether to compress the ARA HTML output or not

roles/emit-ara-html/tasks/main.yaml

@@ -17,15 +17,21 @@
   register: ara_command_type
   when: ara_db_stat.stat.exists
 
-- name: Generate ARA html output
-  command: "ara generate html {{ zuul.executor.log_root }}/ara"
-  ignore_errors: yes
-  when:
+- when:
     - ara_command_type | succeeded
     - not ara_command_type | skipped
-    - ara_generate_html | bool
+  block:
+    # Always generate (true), never (false) or only on failure ('failure')
+    # Additionally cover for edge cases where zuul_success might be undefined
+    - name: Generate ARA html output
+      command: "ara generate html {{ zuul.executor.log_root }}/ara"
+      ignore_errors: yes
+      when: ara_generate_html | bool or
+            (ara_generate_html == 'failure' and not zuul_success | default(false) | bool)
+      register: ara_generated
 
-- name: Compress ARA html output
-  command: gzip --recursive --best {{ zuul.executor.log_root }}/ara
-  ignore_errors: yes
-  when: ara_compress_html | bool
+    - name: Compress ARA html output
+      command: gzip --recursive --best {{ zuul.executor.log_root }}/ara
+      ignore_errors: yes
+      when:
+        - not ara_generated | skipped