Change Bifrost Python upper-constraints source

Users can override the upper-constraints.txt by setting the source of
openstack-base in kolla-build.conf.

However, bifrost-base Dockerfile so far doesn't pass overridden
upper-constraints file to Bifrost install playbook resulting the
playbook not acknowledging it and just use upstream one.

This change sets the source of Bifrost upper-constraints to use
upper-constraints of openstack-base for consistency among all Kolla
images

With this, change the environment variable UPPER_CONSTRAINTS_FILE is
only affecting kolla-toolbox image.
Therefore, moved UPPER_CONSTRATINS_FILE variable example to the
``kolla_toolbox_pip_conf`` block of kolla-toolbox Dockerfile.

Additionally, updated 'Python packages build options' section of
documentation to represent latest method of changing Python package
related options (including this change).

Change-Id: I0a9c782ca1177ef84e4323cb1e5bfac0fb3f383c

1 files changed, 63 insertions, 5 deletions

diff --git a/doc/source/admin/image-building.rst b/doc/source/admin/image-building.rst
index aad3c33a3..02abb19b9 100644
--- a/doc/source/admin/image-building.rst
+++ b/doc/source/admin/image-building.rst
@@ -320,11 +320,69 @@ Python packages build options
 
 The block ``base_pip_conf`` in the ``base`` Dockerfile can be used to provide
 the PyPI build customisation options via the standard environment variables
-like ``PIP_INDEX_URL``, ``PIP_TRUSTED_HOST``, etc. Also here can be provided
-the standard environment variable ``UPPER_CONSTRAINTS_FILE`` used for building
-the ``bifrost_deploy`` container when PyPI upper-constraints needs to be
-overridden. Also this variable would be used in the ``kolla-toolbox`` if
-provided instead of the defaults.
+like ``PIP_INDEX_URL``, ``PIP_TRUSTED_HOST``, etc.
+
+To override PYPI upper-constraints of all OpenStack images, you can
+define the source location of openstack-base. in ``kolla-build.conf``.
+
+Upstream repository of `openstack-base (requirements) <https://opendev.org/openstack/requirements>`__
+has a source of
+`upper constraints file <https://opendev.org/openstack/requirements/src/branch/master/upper-constraints.txt>`__.
+
+Make a fork or clone the repository then customise ``upper-constraints.txt``
+and define the location of ``openstack-base`` in ``kolla_build.conf``.
+
+.. path /etc/kolla/kolla-build.conf
+.. code-block:: ini
+
+   # These examples use upstream openstack-base as a demonstration
+   # To use custom openstack-base, make changes accordingly
+
+   # Using git source
+   [openstack-base]
+   type = git
+   location = https://opendev.org/openstack/requirements
+   reference = master
+
+   # Using URL source
+   [openstack-base]
+   type = url
+   location = https://tarballs.opendev.org/openstack/requirements/requirements-master.tar.gz
+
+   # Using local source
+   [openstack-base]
+   type = local
+   location = /home/kolla/src/requirements
+
+To remove or change the version of specific Python packages in
+``openstack-base`` upper-constraints, you can use the block
+``openstack_base_override_upper_constraints`` in your template file,
+for example, ``template-overrides.j2``:
+
+.. code-block:: jinja
+
+   {% block openstack_base_override_upper_constraints %}
+   RUN {{ macros.upper_constraints_version_change("sqlparse", "0.4.4", "0.5.0") }}
+   RUN {{ macros.upper_constraints_remove("reno") }}
+   {% endblock %}
+
+``kolla-toolbox`` image needs different approach as it does not uses
+``openstack-base`` as a base image.
+A variable ``UPPER_CONSTRAINTS_FILE`` is set in the
+Dockerfile of ``kolla-toolbox``.
+To change variable, add the following contents to the
+``kolla_toolbox_pip_conf`` block in your template file, for example,
+``template-overrides.j2``:
+
+.. code-block:: jinja
+
+   {% block kolla_toolbox_pip_conf %}
+   ENV UPPER_CONSTRAINTS_FILE=https://releases.openstack.org/constraints/upper/master
+   {% endblock %}
+
+.. note::
+
+   ``UPPER_CONSTRAINTS_FILE`` must be a valid URL to the file
 
 Plugin functionality
 --------------------