From adb6d7b001e7d3a53e8022158254defae0ba5919 Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Mon, 16 Jul 2018 11:40:13 +0200 Subject: [PATCH] Document integration of the tool Document and show example how to integrate python-tempetsconf with a different project. Change-Id: I3757d298653dfb243d1b710759f9550a9e27c8a7 Story: 2002703 Task: 22574 --- doc/source/index.rst | 5 +- doc/source/install/installation.rst | 7 + doc/source/user/import.rst | 193 ++++++++++++++++++++++++++++ doc/source/user/index.rst | 1 + 4 files changed, 203 insertions(+), 3 deletions(-) create mode 100644 doc/source/user/import.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 756f1f6b..24ae6561 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,7 +9,8 @@ Welcome to python-tempestconf's documentation! python-tempestconf is a tool for automatic generation of tempest configuration based on user's cloud. -Contents: +Content: +-------- .. toctree:: :maxdepth: 2 @@ -19,8 +20,6 @@ Contents: user/index contributor/index -Indices and tables -================== * :ref:`genindex` * :ref:`search` diff --git a/doc/source/install/installation.rst b/doc/source/install/installation.rst index ff3c2cb5..4070a2c4 100644 --- a/doc/source/install/installation.rst +++ b/doc/source/install/installation.rst @@ -44,3 +44,10 @@ RPM Installation (RDO) $ sudo yum install openstack-tempest + +Pip installation +---------------- + +Install `python-tempestconf` via pip as follows:: + + $ pip install python-tempestconf diff --git a/doc/source/user/import.rst b/doc/source/user/import.rst new file mode 100644 index 00000000..afaa82c3 --- /dev/null +++ b/doc/source/user/import.rst @@ -0,0 +1,193 @@ +======================================= +Use python-tempestconf as Python module +======================================= + +`python-tempestconf` can be imported and used from a different Python project. + +.. warning:: + + The import of config_tempest is possible only when the tool is installed + from **master branch** or via pip, however, **python-tempestconf-2.0.0. + or newer has to be installed**. + +Installation +++++++++++++ + +See our `Install Guide`_ on how to install `python-tempestconf`. + +.. _Install Guide: ../install/installation.html + +Import +++++++ + +Import python-tempestconf in your project as follows: + +.. code-block:: Python + + from config_tempest import main as tempestconf + +python-tempestconf needs cloud credentials in order to create a tempest +configuration file. There is a helper method for obtaining cloud credentials +which uses +`os-client-config `_ +for parsing the cloud for credentials. + +The following example shows how to get cloud credentials and how to pass it to +the configuration tool: + +.. code-block:: Python + + # The following call will return a dict containing cloud credentials, + # for example: + # >>> tempestconf.get_cloud_creds(args_namespace) + # { + # 'username': 'demo', + # 'project_name': 'demo', + # 'user_domain_name': 'Default', + # 'auth_url': 'http://172.16.52.8:5000/v3', + # 'password': 'f0921edc3c2b4fc8', + # 'project_domain_name': 'Default' + # } + cloud_creds = tempestconf.get_cloud_creds(args_namespace) + + # Then the configuration step can be run using: + tempestconf.config_tempest(cloud_creds=cloud_creds) + +.. note:: + + If `args_namespace` contains **--os-cloud** argument, the `get_cloud_creds` + method returns cloud credentials related to that cloud, otherwise, returns + credentials of the current cloud (according to the sourced credentials). + + +List of arguments which may be passed to `config_tempest` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + * cloud_creds + * create + * create_accounts_file + * debug + * deployer_input + * image_disk_format + * image_path + * network_id + * non_admin + * os_cloud + * out + * overrides + * remove + * test_accounts + * verbose + +.. note:: + + For detailed description of the options see our `CLI documentation`_ + + .. _CLI documentation: ../cli/cli_options.html + + +Example implementation +++++++++++++++++++++++ + +1. Save following code snippet as `example.py`: + + .. code-block:: Python + + import argparse + from config_tempest import main as tempestconf + + parser = argparse.ArgumentParser(description='Example implementation.') + args = parser.parse_args() + + # gets credentials of the current cloud according to + # the sourced credentials + cloud_creds = tempestconf.get_cloud_creds(args) + + tempestconf.config_tempest(non_admin=True, + out='./etc/tempest.conf', + cloud_creds=cloud_creds) + +2. Source your OpenStack RC file containing the cloud credentials. Let's say + you have a overcloud_rc file with the following content: + + .. code-block:: Bash + + $ cat overcloud_rc + unset OS_SERVICE_TOKEN + export OS_USERNAME=demo + export OS_PASSWORD='password' + export OS_AUTH_URL=http://172.16.52.15/identity/v3 + export PS1='[\u@\h \W(keystone_demo)]\$ ' + export OS_PROJECT_NAME=demo + export OS_USER_DOMAIN_NAME=default + export OS_PROJECT_DOMAIN_NAME=default + export OS_IDENTITY_API_VERSION=3 + + Then it can be source by: + + .. code-block:: Bash + + $ source overcloud_rc + + +3. Run the `example.py`: + + .. code-block:: Bash + + $ python example.py + + +Example implementation with a named cloud ++++++++++++++++++++++++++++++++++++++++++ + +1. Let's say there is a `clouds.yaml` file located in `/etc/openstack/` with + the following content: + + .. code-block:: Bash + + $ cat /etc/openstack/clouds.yaml + clouds: + devstack: + auth: + auth_url: http://172.16.52.15/identity/v3 + password: password + project_domain_id: default + project_name: demo + user_domain_id: default + username: demo + identity_api_version: '3' + region_name: RegionOne + volume_api_version: '2' + + +2. Save following code snippet as an `example.py`: + + .. code-block:: Python + + import argparse + from config_tempest import main as tempestconf + + parser = argparse.ArgumentParser(description='Example implementation.') + # Let's add an os_cloud option which will be passed + # to config_tempest later. + parser.add_argument('--os-cloud', help='Name of a named cloud.') + args = parser.parse_args() + + # gets credentials to the devstack cloud + cloud_creds = tempestconf.get_cloud_creds(args) + + tempestconf.config_tempest(non_admin=True, + out='./etc/tempest.conf', + cloud_creds=cloud_creds) + +3. Run the `example.py`: + + .. code-block:: Bash + + $ python example.py --os-cloud devstack + + .. note:: + + In this example you **don't need** to source cloud credentials. The + credentials are obtained from the `/etc/openstack/clouds.yaml` + thanks to `--os-cloud` argument. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 03dde542..a45b25cb 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -6,3 +6,4 @@ Usage :includehidden: usage + import