# ansible-role-refstack-client

## About
It's an ansible playbook for running [refstack-client](https://opendev.org/openinfra/refstack-client).
It can be useful in automation where this role can be included in other playbooks.
The role is importable to [Infrared](https://github.com/redhat-openstack/infrared.git) as an infrared
plugin, so right after Infrared deploys an environment, this role can be executed to ensure the
deployment is working by passing refstack tests.

## Required Role Variables
| Variable name                | Required | Default                                                             | Type   | Description                                                                      |
|------------------------------|----------|---------------------------------------------------------------------|--------|---------------------------------------------------------------------------------------------------------|
| private_key_path             | if upload_results is True         | None                                       | String | Results are uploaded to the corresponding account.                                                      |
| source_admin_credentials     | only if accounts_path not defined | None                                       | String | File or command to be sourced for admin credentials which will be used for accounts.yaml generation.    |
| source_credentials           | True     | None                                                                | String | File or command to be sourced: keystonerc_demo/openrc demo demo. These creds will be used to run refstack tests.|

## Optional Role Variables

| Variable name                | Required | Default                                                             | Type   | Description                                                                      |
|------------------------------|----------|---------------------------------------------------------------------|--------|---------------------------------------------------------------------------------------------------------|
| accounts_path                | False    | None                                                                | String | Path to a tempest accounts file which will be used in tempest.conf generation step.                     |
| additional_tempestconf_params| False    | None                                                                | String | Additional arguments to pass for discover-tempest-config tool.                                          |
| deployer_input               | False    | None                                                                | String | Pat to a deployer input file which will be used in tempest.conf generation step.                        |
| dest_dir *                   | False    | pwd                                                                 | String | Local directory where the artifact files will be stored.                                                |
| download_artifacts           | False    | False                                                               | Bool   | Whether artifacts should be downloaded to the host or not. They will be downloaded to dest_dir location.|
| guideline                    | False    | 2021.11                                                             | String | Specific refstack guideline.                                                                            |
| private_key_path_src *       | False    | None                                                                | String | If defined, the key defined by the param is copied to the targeted machine to private_key_path location.|
| refstack_client_source       | False    | ~/.refstack-client                                                  | String | Destination where refstack-client will be cloned only if the dir doesn't exist or it's empty, otherwise it will be used as is.|
| tempestconf_source           | False    | None                                                                | String | A path to python-tempestconf's source. If not defined, refstack-client's default is applied.            |
| refstack_client_version      | False    | HEAD                                                                | String | Version of refstack-client cloned from git.                                                             |
| server                       | False    | https://refstack.openstack.org/api                                  | String | Server url where the results will be uploaded to if upload_results is True.                             |
| refstack_target_programs     | False    | ['platform', 'compute', 'object', 'dns', 'orchestration', 'shared_file_system'] | List | The tests within the specified target programs will be executed.                              |
| tempest_account_concurrency  | False    | 3                                                                   | Int    | A concurrency accounts.yaml file is generated with by tempest.                                          |
| tempest_config_path          | False    | None                                                                | String | Destination of tempest configuration file to be used for running refstack tests.                        |
| tempest_tag                  | False    | refstack-client's default                                           | String | Tempest will be cloned and checkouted to this specific tag.                                             |
| test_list                    | False    | None                                                                | String | A path or an URL to a test list text file containing specific test cases.                               |
| upload_results               | False    | False                                                               | Bool   | Whether results should be uploaded to the server or not.                                                |
| url_cirros_image             | False    | https://download.cirros-cloud.net/0.5.2/cirros-0.5.2-x86_64-disk.img| String | A path or a link to a cirros image.                                                                     |

**\* it's a local path, the path on a machine, the playbook is executed from**

## Example
To run the role from the repository:
```
$ git clone https://opendev.org/openinfra/ansible-role-refstack-client.git
$ cd ansible-role-refstack-client
$ mkdir roles && ln -s $(pwd) roles/ansible-role-refstack-client
```
Then create a `playbook.yaml`:
```
---
- hosts: localhost
  vars:
    source_credentials: ~/overcloudrc
    source_admin_credentials: ~/overcloudrc_admin
    upload_results: True
    private_key_path: ~/.ssh/id_rsa
  roles:
    - ansible-role-refstack-client
```
And run it:
```
$ ansible-playbook playbook.yaml
```


## Usage with Infrared

Run the following steps to run the plugin:
1. Install infrared and add ansible-role-refstack-client plugin by providing the url to this repo:
    ```
    (infrared)$ ir plugin add https://opendev.org/openinfra/ansible-role-refstack-client.git --src-path infrared_plugin
    ```
2. You can verify that the plugin is imported by:
    ```
    (infrared)$ ir plugin list
    ```
4. Run the plugin:
    ```
    (infrared)$ ir ansible-role-refstack-client
    ```

### Example
```
(infrared)$ ir ansible-role-refstack-client \
                 --source_credentials /home/stack/overcloudrc \
                 --source_admin_credentials /home/stack/overcloudrc \
                 --deployer_input /home/stack/ir-tempest-deployer-input.conf \
                 --upload_results true \
                 --private_key_path /home/stack/refstack_key \
                 --private_key_path_src $(pwd)/refstack_key
```

In the example above `tempest_config_path` is not defined, so `source_admin_credentials` is a required parameter
because the role will try to generate an `accounts.yaml` before generating a `tempest.conf`.