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
Jesse Pretorius (odyssey4me)
parent
eb167317c2
commit
403e2b3cc5
111
README.rst
111
README.rst
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user