Adds tripleo_get_hash ansible module, example play & updates README

This adds tripleo_get_hash python module for use with ansible as well
as an example_playbook.yaml. The default config path is changed from
/etc/ to /usr/local/etc. Includes updates to the README

Change-Id: I18c46de71031ca1dd3f1a4f75df651ced12ebff1

tripleo-get-hash/README.md

@@ -3,9 +3,9 @@
 ## What is tripleo-get-hash
 
 This utility is meant for use by TripleO deployments, particularly in zuul
-continuous integration jobs. Given an RDO named tag, such as 'current-tripleo'
+continuous integration jobs. Given an [RDO named tag](https://docs.openstack.org/tripleo-docs/latest/ci/stages-overview.html#rdo-dlrn-promotion-criteria),
-or 'tripleo-ci-testing' [1] it will return the hash information, including
+such as 'current-tripleo' or 'tripleo-ci-testing' it will return the hash
-the commit, distro and full hashes where available.
+information, including the commit, distro and full hashes where available.
 
 It includes a simple command line interface. If you clone the source you can
 try it out of the box without installation invoking it as a module:
@@ -20,20 +20,32 @@ try it out of the box without installation invoking it as a module:
 
 ## Quick start
 
+#### Install using setup.py
+
+Installation using python setup.py requires sudo, because the python source
+is installed at /usr/local/lib/python.
+
 ```
-python setup.py install
+sudo python setup.py install
 ```
 The tripleo-get-hash utility uses a yaml configuration file named 'config.yaml'.
 If you install this utility using setup.py as above, the configuration file
-is placed in /etc:
+is placed in /usr/local/etc:
 ```
-     /etc/tripleo_get_hash/config.yaml
+     /usr/local/etc/tripleo_get_hash/config.yaml
 ```
-Alternatively if you are running from a checked out version of the repo and
-invoking as a module (see examples above) the config.yaml in the repo checkout
-is used instead.
 
-After installation you can invoke tripleo-get-hash in /usr/local/bin/:
+#### Install using pip
+
+You can also install using python pip - you can see the
+[tripleo-get-hash module here](https://pypi.org/project/tripleo-get-hash/)
+
+```
+    pip install tripleo-get-hash --user
+```
+
+After installation you can invoke tripleo-get-hash --help to see the various
+options:
 ```
      tripleo-get-hash --help
 ```
@@ -45,5 +57,30 @@ instead you are instantiating TripleOHashInfo objects in code, you can create
 the objects passing an existing 'config' dictionary. Note this has to contain
 all of constants.CONFIG_KEYS to avoid explosions.
 
+## Ansible Module
 
-[1] https://docs.openstack.org/tripleo-docs/latest/ci/stages-overview.html#rdo-dlrn-promotion-criteria
+The tripleo-get-hash utility can be invoked from ansible using the
+[tripleo_get_hash.py](https://opendev.org/openstack/tripleo-repos/src/branch/master/tripleo-get-hash/tripleo_get_hash.py) ansible module from the source tree.
+If you install tripleo-get-hash using python setup.py, the module will be
+installed for you at /usr/share/ansible/plugins/modules/ and is ready to use.
+Otherwise you will need to copy this file to somewhere that your ansible
+installation can find it. It is required that you install tripleo-get-hash either
+via pip or via setup.py before you can use the ansible module.
+
+See the [example playbook](https://opendev.org/openstack/tripleo-repos/src/branch/master/tripleo-get-hash/example_playbook.yaml) included here for examples of
+usage. You can also test the ansible module is available and working correctly
+from the bash shell:
+
+```
+$ ansible localhost -m tripleo_get_hash -a "component=compute release=victoria"
+localhost | SUCCESS => {
+    "changed": false,
+    "commit_hash": "e954a56fec69637ebd671643d41bb0ecc85a2656",
+    "distro_hash": "de7baf4889fba4d42ac39c9e912c42e38abb5193",
+    "dlrn_url": "https://trunk.rdoproject.org/centos8-victoria/component/compute/current-tripleo/commit.yaml",
+    "error": "",
+    "extended_hash": "None",
+    "full_hash": "e954a56fec69637ebd671643d41bb0ecc85a2656_de7baf48",
+    "success": true
+}
+```

tripleo-get-hash/example_playbook.yaml

@@ -0,0 +1,40 @@
+---
+- name: Example usage for tripleo-get-hash python module
+  hosts: localhost
+  tasks:
+    - name: get component-ci-testing for victoria compute component
+      tripleo_get_hash:
+        os_version: centos8       # default: centos8
+        release: victoria         # default: master
+        component: compute        # default: None
+        tag: component-ci-testing   # default: current-tripleo
+      register: component_ci_testing_victoria_compute
+
+    - debug:
+        msg: "Centos8 component-ci-testing victoria compute component: {{ component_ci_testing_victoria_compute['full_hash'] }}"
+
+    - debug:
+        var: component_ci_testing_victoria_compute
+
+    - name: get centos7 tripleo-ci-testing for train
+      tripleo_get_hash:
+        os_version: centos7
+        release: train
+        tag: tripleo-ci-testing
+      register: centos7_tripleo_ci_testing_train
+
+    - debug:
+        msg: "Centos7 current-tripleo train: {{ centos7_tripleo_ci_testing_train['full_hash'] }}"
+
+    - debug:
+        var: centos7_tripleo_ci_testing_train
+
+    - name: get current-tripleo centos8 for master branch
+      tripleo_get_hash:
+      register: centos8_current_tripleo_master
+
+    - debug:
+        msg: "Centos8 current-tripleo master: {{ centos8_current_tripleo_master['full_hash'] }}"
+
+    - debug:
+        var: centos8_current_tripleo_master

tripleo-get-hash/setup.cfg

@@ -2,7 +2,7 @@
 name = tripleo-get-hash
 author = Marios Andreou
 author_email = marios@redhat.com
-description = Get the tripleo build hash for a known RDO named tag.
+description = Get the tripleo build hash for a known RDO named tag. See https://opendev.org/openstack/tripleo-repos/src/branch/master/tripleo-get-hash/README.md#what-is-tripleo-get-hash for more information.
 long_description = file: README.md LICENSE
 long_description_content_type = text/markdown
 url = https://opendev.org/openstack/tripleo-repos/src/branch/master/tripleo-get-hash
@@ -29,4 +29,5 @@ console_scripts =
     tripleo-get-hash = tripleo_get_hash.__main__:cli_entrypoint
 
 [options.data_files]
-    /etc/tripleo_get_hash/ = config.yaml
+    /usr/local/etc/tripleo_get_hash/ = config.yaml
+    /usr/share/ansible/plugins/modules/ = tripleo_get_hash.py

tripleo-get-hash/tripleo_get_hash.py

@@ -0,0 +1,139 @@
+#!/usr/bin/python
+#   Copyright 2021 Red Hat, Inc.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License"); you may
+#   not use this file except in compliance with the License. You may obtain
+#   a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#   License for the specific language governing permissions and limitations
+#   under the License.
+#
+
+from tripleo_get_hash.tripleo_hash_info import TripleOHashInfo
+from ansible.module_utils.basic import AnsibleModule
+
+DOCUMENTATION = r'''
+---
+module: tripleo_get_hash
+
+short_description: Resolve rdo named tag to commit, full and distro hashes
+
+version_added: "2.9"
+
+description:
+
+options:
+    os_version:
+        description: The operating system and version to fetch hashes for
+        required: false
+        type: str
+        default: centos8
+    release:
+        description: The release of OpenStack you want the hash info for
+        required: false
+        type: str
+        default: master
+    component:
+        description: The tripleo-ci component you are interested in
+        required: false
+        type: str
+        default: None
+    tag:
+        description: The named tag to fetch
+        required: false
+        type: str
+        default: current-tripleo
+
+author:
+    - Marios Andreou (@marios)
+'''
+
+EXAMPLES = r'''
+- name: Get the latest hash info for victoria centos8 tripleo component
+  tripleo_get_hash:
+    os_version: centos8
+    release: victoria
+    component: tripleo
+'''
+
+RETURN = r'''
+full_hash:
+    description: The full hash that identifies the build
+    type: str
+    returned: always
+    sample: 'f47f1db5af04ddd1ab4cc3ccadf95884d335b3f3_92f50ace'
+distro_hash:
+    description: The distro hash
+    type: str
+    returned: when available
+    sample: '92f50acecd0a218936b7163e8362e75913b62af2'
+commit_hash:
+    description: The commit hash
+    type: str
+    returned: when available
+    sample: 'f47f1db5af04ddd1ab4cc3ccadf95884d335b3f3'
+extended_hash:
+    description: The extended hash
+    type: str
+    returned: when available
+    sample: 'f47f1db5af04ddd1ab4cc3ccadf95884d335b3f3'
+dlrn_url:
+    description: The dlrn server url from which hash info was collected.
+    type: str
+    returned: always
+    sample: 'https://trunk.rdoproject.org/centos8-master/current-tripleo/delorean.repo.md5'  # noqa E501
+'''
+
+
+def run_module():
+    result = dict(
+        success=False,
+        changed=False,
+        error="",
+    )
+
+    argument_spec = dict(
+        os_version=dict(type='str', required=False, default='centos8'),
+        release=dict(type='str', required=False, default='master'),
+        component=dict(type='str', required=False, default=None),
+        tag=dict(type='str', required=False, default='current-tripleo'),
+    )
+
+    module = AnsibleModule(
+        argument_spec,
+        supports_check_mode=False
+    )
+
+    try:
+
+        os_version = module.params.get('os_version')
+        release = module.params.get('release')
+        component = module.params.get('component')
+        tag = module.params.get('tag')
+
+        hash_result = TripleOHashInfo(os_version, release, component, tag)
+        result['commit_hash'] = hash_result.commit_hash
+        result['distro_hash'] = hash_result.distro_hash
+        result['full_hash'] = hash_result.full_hash
+        result['extended_hash'] = hash_result.extended_hash
+        result['dlrn_url'] = hash_result.dlrn_url
+        result['success'] = True
+    except Exception as exc:
+        result['error'] = str(exc)
+        result['msg'] = "Error something went wrong fetching hash info"
+        module.fail_json(**result)
+
+    module.exit_json(**result)
+
+
+def main():
+    run_module()
+
+
+if __name__ == '__main__':
+    main()

tripleo-get-hash/tripleo_get_hash/constants.py

@@ -30,4 +30,4 @@ CONFIG_KEYS = [
 This is the path that we expect to find the system installed config.yaml.
 The path is specified in [options.data_files] of the project setup.cfg.
 """
-CONFIG_PATH = '/etc/tripleo_get_hash/config.yaml'
+CONFIG_PATH = '/usr/local/etc/tripleo_get_hash/config.yaml'

tripleo-get-hash/tripleo_get_hash/tripleo_hash_info.py

@@ -103,7 +103,7 @@ class TripleOHashInfo:
         result_config = {}
         config_path = ''
         local_config = _resolve_local_config_path()
-        # If we can read /etc/tripleo_get_hash/config.yaml then use that
+        # prefer const.CONFIG_PATH then local_config
         if _check_read_file(const.CONFIG_PATH):
             config_path = const.CONFIG_PATH
         elif local_config: