Update python_venv_build role docs

This patch fixes a few errors and updates the README to
describe the role's purpose and process in more detail.

Change-Id: I5d30ba7a4c56dde6f1504639135f7f66560c4791
This commit is contained in:
Jesse Pretorius 2019-03-20 10:21:16 +00:00 committed by Jesse Pretorius (odyssey4me)
parent eb167317c2
commit 403e2b3cc5
1 changed files with 103 additions and 8 deletions

View File

@ -2,7 +2,7 @@
Team and repository tags
========================
.. image:: https://governance.openstack.org/tc/badges/openstack-ansible-python_venv_build.svg
.. image:: https://governance.openstack.org/tc/badges/ansible-role-python_venv_build.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
.. Change things from this point on
@ -11,7 +11,8 @@ Team and repository tags
OpenStack-Ansible python_venv_build
===================================
This Ansible role prepares a python venv for use in OpenStack-Ansible.
This Ansible role prepares a python venv for use within the OpenStack-Ansible
project, but it may be used for other projects as well.
The role requires the following to be present prior to execution:
@ -22,18 +23,112 @@ The role requires the following to be present prior to execution:
Use-cases
~~~~~~~~~
This role is built to cater to the following use-cases:
This role is built for the following use-cases:
# Execute a build against a build host, then serve the venvs from a web
server.
# Execute a build against the first host in a group, then serving the
venvs from the deployment host.
1. Using a build host (a.k.a. repo server):
* Build `python wheels`_ on a repo server with a given list of python
packages.
* Prepare a requirements.txt and constraints.txt file on the repo server,
and use them to ensure that the build and installation processes are
both consistent and idempotent.
* On the build host, install the distribution packages required at build
time.
* On any number of target hosts, create a virtualenv and install these
built wheels into it using the pip ``--find-links`` option.
* On any number of target hosts, install the distribution packages required
at run time.
* Re-use previously built wheels to speed up any subsequent builds..
2. Not using a build host:
* On any number of target hosts, create a virtualenv, then locally install
the distribution packages required at build and run time, then locally
compile and install the given list of python packages.
* This negates the need for a repo server, but takes longer due to the
increased number of dependencies to install and the compilation happening
on every target host.
* The only situation where a build host provides no benefit is where there
is only a single target host (with no containers) and none of the packages
installed into the venv will be used again for any other venvs built by
this role on the same host.
It may be useful to review the `Python Build/Install Process Simplification`_
specification to understand the background that led to the creation of this
role.
.. _python wheels: https://pythonwheels.com
.. _Python Build/Install Process Simplification: https://specs.openstack.org/openstack/openstack-ansible-specs/specs/queens/python-build-install-simplification.html
Process
~~~~~~~
1. Pre-requisites are checked.
2. If wheel building is enabled, and there is a repo server in the environment,
then the following happens on the repo server:
a. The distribution packages required to execute the python wheel compile
are installed.
b. A set of requirements and source-constraints for the venv are compiled
for pip to use when building the wheels. These are also used to determine
whether there are changes to either for the purpose of idempotence.
c. The python wheels are compiled, and an install-time constraints file is
created. The install-time constraints file has the list of python
packages with their versions - this differs from the source-constraints
which may contain git SHA's.
3. The installation of the python packages then commences on the target hosts:
a. If the wheel build was enabled:
i. Only the distribution packages required at runtime by the python
packages are installed.
ii. A python venv is created at ``venv_install_destination_path``.
iii. The requirements and constraints files for the venv are prepared in
the venv path.
iv. The python packages are installed from the wheels on the repo server
using pip's ``--find-links`` option to ensure that they are preferred
above the default pypi index.
v. If there are any ``venv_packages_to_symlink`` then the appropriate
python libraries installed into the system from those packages will be
symlinked into the virtualenv. This provides for python libraries
which have a tight coupling with C bindings which may not be portable
as a wheel.
b. If the wheel build was *not* enabled:
i. The distribution packages required for compiling and at runtime by the
python packages are installed.
ii. A python venv is created at ``venv_install_destination_path``.
iii. The requirements and constraints files for the venv are prepared in
the venv path. The constraints file in this case would contain the
same content as the source-constraints file on the repo server where
there is one.
iv. The python packages are installed from the default pip index. During
the installation pip will do a git clone and build from it for any
packages that have a git SHA as a constraint.
v. If there are any ``venv_packages_to_symlink`` then the appropriate
python libraries installed into the system from those packages will be
symlinked into the virtualenv. This provides for python libraries which
have a tight coupling with C bindings which may not be portable as a
wheel.
4. If any ``venv_facts_when_changed`` are set, then they are implemented on
the target host in ``/etc/ansible/facts.d``.
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../defaults/main.yml
:language: yaml
:start-after: under the License.
References
~~~~~~~~~~
Documentation for the project can be found at:
https://docs.openstack.org/openstack-ansible-python_venv_build/latest/
https://docs.openstack.org/ansible-role-python_venv_build/latest/
The project home is at:
http://launchpad.net/openstack-ansible