From 812c0521ddf3a9c00289c500951c241ec0a2cbd7 Mon Sep 17 00:00:00 2001
From: "Gael Chamoulaud (Strider)" <gchamoul@redhat.com>
Date: Tue, 9 Feb 2021 09:42:12 +0100
Subject: [PATCH] Add new tripleo-latest-packages-version playbook

This patch adds a new TripleO specific playbook which will call the
check_latest_packages_version role hosted in validations-common. This
playbook will test if the python3-tripleoclient package is at its latest
version on the Undercloud before starting an upgrade.

Note1: The check-latest-packages-versions validation hosted in
validations-common will be refactored to only test non TripleO packages.

Note2: The documentation automation has been modified to point to the
external role official documentation.

Depends-on: 07c1e0f9b892be3494c99ba21a614e92c8c366bc

Signed-off-by: Gael Chamoulaud (Strider) <gchamoul@redhat.com>
Signed-off-by: Jiri Podivin <jpodivin@redhat.com>
Change-Id: I606f650029dd4daad7dc7aac248c388130e9d503
(cherry picked from commit eb21b9d24f30144ebbb6dabe1a46f23de2bc8e11)
---
 doc/source/_exts/generate_validations_doc.py  | 48 +++++++++++++++----
 .../tripleo-latest-packages-version.yaml      | 15 ++++++
 2 files changed, 54 insertions(+), 9 deletions(-)
 create mode 100644 playbooks/tripleo-latest-packages-version.yaml

diff --git a/doc/source/_exts/generate_validations_doc.py b/doc/source/_exts/generate_validations_doc.py
index 977b5af04..97b6b2752 100644
--- a/doc/source/_exts/generate_validations_doc.py
+++ b/doc/source/_exts/generate_validations_doc.py
@@ -25,6 +25,7 @@ DEFAULT_METADATA = {
 
 
 def get_validation_metadata(validation, key):
+    """Returns metadata dictionary"""
     try:
         return validation['vars']['metadata'][key]
     except KeyError:
@@ -32,11 +33,11 @@ def get_validation_metadata(validation, key):
 
 
 def get_include_role(validation):
+    """Returns Included Role"""
     try:
         if 'tasks' in validation:
             return validation['tasks'][0]['include_role']['name']
-        else:
-            return validation['roles'][0]
+        return validation['roles'][0]
     except KeyError:
         return list()
 
@@ -50,6 +51,7 @@ def get_remaining_metadata(validation):
 
 
 def get_validation_parameters(validation):
+    """Returns parameters"""
     try:
         return {k: v for k, v in validation['vars'].items()
                 if k != 'metadata'}
@@ -58,6 +60,7 @@ def get_validation_parameters(validation):
 
 
 def build_summary(group, validations):
+    """Creates validations documentation contents by group"""
     entries = [
         "* :ref:`{}`: {}".format(group + '_' + validation['id'],
                                  validation['name'])
@@ -73,7 +76,29 @@ def format_dict(my_dict):
                     for key, value in my_dict.items()])
 
 
-def build_detail(group, validations):
+def role_doc_entry(role_name, local_roles):
+    """Generates Documentation entry
+
+    If the included role isn't hosted on tripleo-validations, we point to the
+    validations-common role documentation. Otherwise, it generates a classical
+    local toctree.
+    """
+    local_role_doc = (".. toctree::\n\n"
+                      "   roles/role-{}".format(role_name))
+    doc_base_url = "https://docs.openstack.org/validations-common/latest/roles"
+    external_role = \
+        ("- `{role} <{baseurl}/role-{role}.html>`_ "
+         "from `openstack/validations-common "
+         "<https://opendev.org/openstack/validations-common>`_"
+         "".format(role=role_name,
+                   baseurl=doc_base_url))
+
+    if role_name not in local_roles:
+        return external_role
+    return local_role_doc
+
+
+def build_detail(group, validations, local_roles):
     entries = ['{}\n{}\n'.format(group, len(group) * '=')]
     entries = entries + [
         """.. _{label}:
@@ -92,10 +117,7 @@ def build_detail(group, validations):
 
 Role documentation
 
-.. toctree::
-
-   roles/role-{roles}
-
+{roledoc}
 """
         .format(label=(group + '_' + validation['id']),
                 title=validation['id'],
@@ -105,7 +127,8 @@ Role documentation
                 groups=', '.join(validation['groups']),
                 hosts=validation['hosts'],
                 parameters=format_dict(validation['parameters']),
-                roles=validation['roles']
+                roles=validation['roles'],
+                roledoc=role_doc_entry(validation['roles'], local_roles)
                 )
         for validation in validations]
     with open('doc/source/validations-{}-details.rst'.format(group), 'w') as f:
@@ -155,10 +178,17 @@ def get_groups():
     return groups, contents
 
 
+def get_local_roles(path):
+    """Returns a list of local Ansible Roles"""
+    return next(os.walk(path))[1]
+
+
 def setup(app):
     group_name, group_info = get_groups()
     build_groups_detail(group_info)
 
+    local_roles = get_local_roles(os.path.abspath('roles'))
+
     validations = []
     for validation_path in sorted(glob('playbooks/*.yaml')):
         with open(validation_path) as f:
@@ -182,5 +212,5 @@ def setup(app):
         validations_in_group = [validation for validation
                                 in validations
                                 if group in validation['groups']]
-        build_detail(group, validations_in_group)
+        build_detail(group, validations_in_group, local_roles)
         build_summary(group, validations_in_group)
diff --git a/playbooks/tripleo-latest-packages-version.yaml b/playbooks/tripleo-latest-packages-version.yaml
new file mode 100644
index 000000000..86a2a40a5
--- /dev/null
+++ b/playbooks/tripleo-latest-packages-version.yaml
@@ -0,0 +1,15 @@
+---
+- hosts: undercloud
+  gather_facts: false
+  vars:
+    metadata:
+      name: Check if latest version of TripleO packages is installed
+      description: |
+        Make sure a list of TripleO packages are at its latest version
+        before starting an upgrade.
+      groups:
+        - pre-upgrade
+    packages_list:
+      - python3-tripleoclient
+  roles:
+    - check_latest_packages_version