openshift_version: improve messaging

This role often provides the first failure messages when users'
inventory parameters are not going to work out. So, make sure the task
names and messages are informative to someone who may not have very much
context for what this role does.

1 files changed, 38 insertions, 18 deletions

diff --git a/roles/openshift_version/tasks/main.yml b/roles/openshift_version/tasks/main.yml
index c3d001bb4..fa9b20e92 100644
--- a/roles/openshift_version/tasks/main.yml
+++ b/roles/openshift_version/tasks/main.yml
@@ -7,8 +7,13 @@
 # Block attempts to install origin without specifying some kind of version information.
 # This is because the latest tags for origin are usually alpha builds, which should not
 # be used by default. Users must indicate what they want.
-- fail:
-    msg: "Must specify openshift_release or openshift_image_tag in inventory to install origin. (suggestion: add openshift_release=\"1.2\" to inventory)"
+- name: Abort when we cannot safely guess what Origin image version the user wanted
+  fail:
+    msg: |-
+      To install a containerized Origin release, you must set openshift_release or
+      openshift_image_tag in your inventory to specify which version of the OpenShift
+      component images to use. You may want the latest (usually alpha) releases or
+      a more stable release. (Suggestion: add openshift_release="x.y" to inventory.)
   when:
   - is_containerized | bool
   - openshift.common.deployment_type == 'origin'
@@ -27,7 +32,10 @@
   when: openshift_release is defined
 
 # Verify that the image tag is in a valid format
-- block:
+- when:
+  - openshift_image_tag is defined
+  - openshift_image_tag != "latest"
+  block:
 
   # Verifies that when the deployment type is origin the version:
   # - starts with a v
@@ -35,12 +43,14 @@
   # It also allows for optional trailing data which:
   # - must start with a dash
   # - may contain numbers, letters, dashes and dots.
-  - name: Verify Origin openshift_image_tag is valid
+  - name: (Origin) Verify openshift_image_tag is valid
+    when: openshift.common.deployment_type == 'origin'
     assert:
       that:
       - "{{ openshift_image_tag|match('(^v?\\d+\\.\\d+\\.\\d+(-[\\w\\-\\.]*)?$)') }}"
-      msg: "openshift_image_tag must be in the format v#.#.#[-optional.#]. Examples: v1.2.3, v3.5.1-alpha.1"
-    when: openshift.common.deployment_type == 'origin'
+      msg: |-
+        openshift_image_tag must be in the format v#.#.#[-optional.#]. Examples: v1.2.3, v3.5.1-alpha.1
+        You specified openshift_image_tag={{ openshift_image_tag }}
 
   # Verifies that when the deployment type is openshift-enterprise the version:
   # - starts with a v
@@ -48,16 +58,14 @@
   # It also allows for optional trailing data which:
   # - must start with a dash
   # - may contain numbers
-  - name: Verify Enterprise openshift_image_tag is valid
+  - name: (Enterprise) Verify openshift_image_tag is valid
+    when: openshift.common.deployment_type == 'openshift-enterprise'
     assert:
       that:
       - "{{ openshift_image_tag|match('(^v\\d+\\.\\d+[\\.\\d+]*(-\\d+)?$)') }}"
-      msg: "openshift_image_tag must be in the format v#.#[.#[.#]]. Examples: v1.2, v3.4.1, v3.5.1.3, v1.2-1, v1.2.3-4"
-    when: openshift.common.deployment_type == 'openshift-enterprise'
-
-  when:
-  - openshift_image_tag is defined
-  - openshift_image_tag != "latest"
+      msg: |-
+        openshift_image_tag must be in the format v#.#[.#[.#]]. Examples: v1.2, v3.4.1, v3.5.1.3, v1.2-1, v1.2.3-4
+        You specified openshift_image_tag={{ openshift_image_tag }}
 
 # Make sure we copy this to a fact if given a var:
 - set_fact:
@@ -119,30 +127,42 @@
 
 - fail:
     msg: openshift_version role was unable to set openshift_version
+  name: Abort if openshift_version was not set
   when: openshift_version is not defined
 
 - fail:
     msg: openshift_version role was unable to set openshift_image_tag
+  name: Abort if openshift_image_tag was not set
   when: openshift_image_tag is not defined
 
 - fail:
     msg: openshift_version role was unable to set openshift_pkg_version
+  name: Abort if openshift_pkg_version was not set
   when: openshift_pkg_version is not defined
 
 - fail:
-    msg: "No OpenShift version available, please ensure your systems are fully registered and have access to appropriate yum repositories."
+    msg: "No OpenShift version available; please ensure your systems are fully registered and have access to appropriate yum repositories."
+  name: Abort if openshift_pkg_version was not set
   when:
   - not is_containerized | bool
   - openshift_version == '0.0'
 
-# We can't map an openshift_release to full rpm version like we can with containers, make sure
+# We can't map an openshift_release to full rpm version like we can with containers; make sure
 # the rpm version we looked up matches the release requested and error out if not.
-- fail:
-    msg: "Detected OpenShift version {{ openshift_version }} does not match requested openshift_release {{ openshift_release }}. You may need to adjust your yum repositories, inventory, or run the appropriate OpenShift upgrade playbook."
+- name: For an RPM install, abort when the release requested does not match the available version.
   when:
   - not is_containerized | bool
   - openshift_release is defined
-  - not openshift_version.startswith(openshift_release) | bool
+  assert:
+    that:
+    - openshift_version.startswith(openshift_release) | bool
+    msg: |-
+      You requested openshift_release {{ openshift_release }}, which is not matched by
+      the latest OpenShift RPM we detected as {{ openshift.common.service_type }}-{{ openshift_version }}
+      on host {{ inventory_hostname }}.
+      We will only install the latest RPMs, so please ensure you are getting the release
+      you expect. You may need to adjust your Ansible inventory, modify the repositories
+      available on the host, or run the appropriate OpenShift upgrade playbook.
 
 # The end result of these three variables is quite important so make sure they are displayed and logged:
 - debug: var=openshift_release