You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
python-tempestconf/doc/source/user/usage.rst

466 lines
14 KiB

=====
Usage
=====
To install ``python-tempestconf`` follow our `Installation Guide`_
.. _Installation Guide: ../install/installation.html
For a successful execution of ``python-tempestconf`` a user needs to do one
of the following:
* source OpenStack RC file before running :command:`discover-tempest-config`
command, see `Examples of usage with sourced credentials`_
* use ``clouds.yaml`` file and take advantage of ``os-client-config`` support
and use a named cloud, see `Examples of usage with a named cloud`_
If a user doesn't use ``--create``, no resources, which require admin
credentials, are created. See `Resources`_ section.
Examples of usage with sourced credentials
------------------------------------------
**All of the examples** in this section mentioned below **use** the following
step **as a prerequisite**:
* Source your OpenStack RC file containing the cloud credentials. Let's say
you have an overcloud_rc file with the following content:
.. code-block:: shell-session
$ 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 sourced by:
.. code-block:: shell-session
$ source overcloud_rc
.. note::
Thanks to
`os-client-config <https://docs.openstack.org/os-client-config/latest/index.html>`_
support, ``python-tempestconf`` is able to read cloud credentials from
the shell environment, which means, they **don't need** to be
explicitly passed via CLI.
Override values
+++++++++++++++
Override values can be useful when a user wants to set a key-value pair in
generated ``tempest.conf`` from one of the two following reasons:
* ``python-tempestconf`` is **not** able to discover it and therefore set the
desired
key-value pair in ``tempest.conf`` by itself
* ``python-tempestconf`` is able to discover it, but a user wants to set it
differently
Values specified as overrides will be set to tempest.conf no matter if they
were discovered or not. If a section or a key don't exist, they will be
created.
In the following example we make the tool to print debugging information, we
set that ``tempest.conf`` will be written to ``etc/`` directory and we pass
some override values.
.. code-block:: shell-session
:emphasize-lines: 4-6
$ discover-tempest-config \
--debug \
--out etc/tempest.conf \
auth.tempest_roles Member \
identity.username MyOverrideUsername \
section.key MyValue
The generated ``tempest.conf`` will look like:
.. code-block:: shell-session
$ cat etc/tempest.conf
<omitted some content>
[auth]
tempest_roles = Member
<omitted some content>
[identity]
username = MyOverrideUsername
<omitted some content>
[section]
key = value
<omitted some content>
Prevent some key-value pairs to be set in tempest.conf
++++++++++++++++++++++++++++++++++++++++++++++++++++++
A user can define key-value pairs which are not wanted to be written to the
generated ``tempest.conf``. This can be useful in case when
``python-tempestconf`` discovers something which is not wanted by a user to
have in ``tempest.conf``. If the option is used, ``python-tempestconf`` will
make sure that the defined values are not written to tempest.conf no matter
if they were discovered or not.
.. code-block:: shell-session
$ discover-tempest-config \
--remove section1.key1 \
--remove section2.key2=value \
--remove section3.key3=value1,value2
In the following case **all** api_extensions will be removed and
``tempest.conf`` will **not contain** the api_extensions key under
compute-feature-enabled section.
.. code-block:: shell-session
$ discover-tempest-config \
--remove compute-feature-enabled.api_extensions
In the following case **only** NMN api extension will be removed from the
api_extensions list.
.. code-block:: shell-session
$ discover-tempest-config \
--remove compute-feature-enabled.api_extensions=NMN
In the following case only NMN **and** OS-EXT-IPS api extensions will be
removed.
.. code-block:: shell-session
$ discover-tempest-config \
--remove compute-feature-enabled.api_extensions=NMN,OS-EXT-IPS
.. note::
``--remove`` option will remove even values set as `overrides`_
.. _overrides: ./usage.html#override-values
.. note::
This argument's functionality is opposite to ``--append`` one, see
`Append values to tempest.conf`_
Append values to tempest.conf
+++++++++++++++++++++++++++++
In a case when ``python-tempestconf`` is not able to discover some wanted
api_extensions, you can make ``python-tempestconf`` append any extensions
by using ``--append`` argument.
The following will make ``python-tempestconf`` append my_ext extension to
compute-feature-enabled.api_extensions and tag and tag-ext extensions to
network-feature-enabled.api_extensions.
.. code-block:: shell-session
$ discover-tempest-config \
--append compute-feature-enabled.api_extensions=my_ext \
--append network-feature-enabled.api_extensions=tag,tag-ext
.. note::
This argument's functionality is opposite to ``--remove`` one, see
`Prevent some key-value pairs to be set in tempest.conf`_
Usage with tempest accounts file
++++++++++++++++++++++++++++++++
To read more about ``accounts.yaml`` file and how to generate it follow these
links:
* `what is accounts.yaml? <https://docs.openstack.org/tempest/latest/configuration.html#pre-provisioned-credentials>`_
* `how to generate it? <https://docs.openstack.org/tempest/latest/account_generator.html>`_
When ``--test-accounts`` argument is used, ``python-tempestconf`` will not
write any credentials to generated ``tempest.conf`` file, it will add a
**test_accounts_file** key to **auth** section with value equal to the path
provided by the ``--test-accounts`` argument. Also **use_dynamic_credentials**
under **auth** section will be set to False as
`tempest documentation <https://docs.openstack.org/tempest/latest/configuration.html#pre-provisioned-credentials>`_
suggests.
This argument can be useful when a user doesn't want to store credentials in
``tempest.conf``, f.e: the user want's to share the ``tempest.conf``.
If you already have the file created, you can run
:command:`discover-tempest-config` command with ``--test-accounts`` argument:
.. code-block:: shell-session
:emphasize-lines: 3
$ discover-tempest-config \
--out etc/tempest.conf \
--test-accounts /path/to/my/accounts.yaml
The generated ``tempest.conf`` will look like:
.. code-block:: shell-session
$ cat etc/tempest.conf
<omitted some content>
[auth]
test_accounts_file = /path/to/my/accounts.yaml
use_dynamic_credentials = False
<omitted some content>
non-admin argument
++++++++++++++++++
If your credentials are **non-admin ones**, which means that you are
**not allowed** to create any resources in your cloud, then please specify
``--non-admin`` argument. When this argument is used, ``python-tempestconf``
will **not create** any resources.
.. code-block:: shell-session
:emphasize-lines: 4
$ discover-tempest-config \
-v \
--debug \
--non-admin
Examples of usage with a named cloud
------------------------------------
``python-tempestconf`` supports
`os-client-config <https://git.openstack.org/openstack/os-client-config>`__
so instead of sourcing an OpenStack RC file a user can use clouds.yml file.
Location where this file should be stored and syntax which is used to define
it can be found
`here <https://docs.openstack.org/os-client-config/latest/user/configuration.html#config-files>`__
Let's say there is a ``clouds.yaml`` file located in ``/etc/openstack/`` with
the following content:
.. code-block:: shell-session
$ 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'
Then if you use ``--os-cloud`` argument you can run
:command:`discover-tempest-config` **without** setting any OS_* environment
variable (for example by sourcing any OpenStack RC file).
``--os-cloud`` specifies one of the cloud names located in the ``clouds.yaml``
file.
.. code-block:: shell-session
:emphasize-lines: 3
$ discover-tempest-config \
--debug \
--os-cloud devstack
So the call from `non-admin argument`_ section would for example look like:
.. code-block:: shell-session
:emphasize-lines: 5
$ discover-tempest-config \
-v \
--debug \
--non-admin \
--os-cloud devstack
The call from `Usage with tempest accounts file`_ section would for example
look like:
.. code-block:: shell-session
:emphasize-lines: 2
$ discover-tempest-config \
--os-cloud devstack \
--out etc/tempest.conf \
--test-accounts /path/to/my/accounts.yaml
Resources
---------
Without specifying ``--create`` argument, no resources which require admin
credentials are crated during the ``python-tempestconf`` execution. For the
documentation on how to use ``--create`` argument see `Admin User Guide`_
.. _Admin User Guide: ../admin/admin_usage.html
This affects these types of resources:
* users
* images
* flavors
Users
+++++
For a successful execution of Tempest at least two users need to be created
(the default concurrency is 2). Therefor ``python-tempestconf`` looks for
the following two users:
* the user who started ``python-tempestconf``
* the alt user defined by:
* identity.alt_username
* identity.alt_password
* identity.alt_project_name
.. note::
These values are set by default, have a look at `default values`_ which
``python-tempestconf`` sets to a ``tempest.conf``
.. _default values: ./default.html
If the users are not found, they can't be created, so
:command:`discover-tempest-config` ends with an exception.
Images
++++++
Any user can create an image, therefore ``--create`` argument doesn't have to
be used in order to have created images, necessary for tempest execution, by
``python-tempestconf``.
However, when non-admin credentials are used, the created images will have
**community** visibility. It's because users without admin credentials can't
create a public image and private images are not visible for other users -
tempest tests **would fail** finding the image, because they are usually run
under a **different user.**
When admin credentials are used, the images are created as public ones.
``--image`` argument is used to specify an image which will be uploaded
to glance and used later by tempest tests for booting VMs.
The following example will upload ``/my/path/to/myImage.img`` image to glance
twice. First **compute.image_ref** will be equal to the ID of the uploaded
image. Then the image is uploaded to glance again and but
**compute.image_alt_ref** is set to that corresponding ID:
.. code-block:: shell-session
$ discover-tempest-config \
--os-cloud myCloud \
--image /my/path/to/myImage.img
In the following example, an `override`_ value is used to set
**compute.image_ref**, which means that the image specified by ``--image`` is
uploaded and only **compute.image_alt_ref** is set to the ID of newly created
image.
.. _override: ./usage.html#override-values
.. code-block:: shell-session
$ discover-tempest-config \
--os-cloud myCloud \
compute.image_ref 2eb9f6c9-bd32-427d-850d-c3bb3cfaaa87
.. note::
``python-tempestconf`` checks by image name, if it is already present
in glance and only in case it's not present there, will upload the
image.
.. note::
If the image ID specified as an override is not found, the image where
``--image`` points to is used.
If ``--image`` is not defined, the default image (see `CLI options`_)
is chosen to be uploaded.
.. _CLI options: ../cli/cli_options.html
Flavors
+++++++
``python-tempestconf`` looks by default for these two flavors:
* *m1.nano* with 64 MB of RAM, which will be set as **compute.flavor_ref**
* *m1.micro* with 128 MB of RAM, which will be set as
**compute.flavor_alt_ref**
If a user used ``--flavor-min-mem`` argument, ``python-tempestconf`` will look
for these two flavors:
* *custom*
* *custom_alt*
.. note::
``python-tempestconf`` looks for flavors by name, so if a user has had
a flavor with name *custom*/*custom_alt* already created, those flavors'
IDs will be set as **compute.flavor_ref**/**compute.flavor_ref_alt**
without checking if theirs RAM size is equal to the one specified by
``--flavor-min-mem``.
If they are not found and ``--create`` argument is not used, the tool will try
to auto discover two smallest flavors available in the system. If at least two
flavors are not found, the tool ends with an exception.
If two flavors are found, their IDs will be set to ``tempest.conf``, see the
following example:
.. code-block:: shell-session
$ discover-tempest-config \
--out etc/tempest.conf
The generated tempest.conf will look like:
.. code-block:: ini
$ cat etc/tempest.conf
<omitted some content>
[compute]
# typically an ID of the smaller flavor found
flavor_ref = <ID_1>
# typically an ID of the bigger flavor found
flavor_alt_ref = <ID_2>
<omitted some content>
In the following example, an `override`_ option specifies **compute.flavor_ref**
ID, which if it's found, the tool continues with looking for a **m1.micro**
flavor to be set as **compute.flavor_alt_ref** as was explained above.
.. code-block:: shell-session
$ discover-tempest-config \
--out etc/tempest.conf \
compute.flavor_ref 123
.. note::
If the **compute.flavor_ref** ID is not found, the tool ends with an
exception.