diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index ee14729e2b..5114e0e3a5 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -37,7 +37,7 @@ Note that this is independent from the use of a virtual environment for remote execution, which is described in :kolla-ansible-doc:`Virtual Environments `. -#. For Ubuntu, update the package index. +#. For Debian or Ubuntu, update the package index. .. code-block:: console @@ -51,37 +51,23 @@ execution, which is described in sudo dnf install python3-devel libffi-devel gcc openssl-devel python3-libselinux - For Ubuntu, run: + For Debian or Ubuntu, run: .. code-block:: console - sudo apt-get install python-dev libffi-dev gcc libssl-dev python-selinux python-setuptools + sudo apt-get install python3-dev libffi-dev gcc libssl-dev Install dependencies using a virtual environment ------------------------------------------------ If not installing Kolla Ansible in a virtual environment, skip this section. -#. Install the virtualenv package. - - For CentOS or RHEL 8, run: - - .. code-block:: console - - sudo dnf install python3-virtualenv - - For Ubuntu, run: - - .. code-block:: console - - sudo apt-get install python-virtualenv - #. Create a virtual environment and activate it: .. code-block:: console - virtualenv /path/to/virtualenv - source /path/to/virtualenv/bin/activate + python3 -m venv /path/to/venv + source /path/to/venv/bin/activate The virtual environment should be activated before running any commands that depend on packages installed in it. @@ -97,7 +83,7 @@ If not installing Kolla Ansible in a virtual environment, skip this section. .. code-block:: console - pip install ansible + pip install 'ansible<2.10' Install dependencies not using a virtual environment ---------------------------------------------------- @@ -110,13 +96,13 @@ If installing Kolla Ansible in a virtual environment, skip this section. .. code-block:: console - sudo easy_install pip + sudo dnf install python3-pip - For Ubuntu, run: + For Debian or Ubuntu, run: .. code-block:: console - sudo apt-get install python-pip + sudo apt-get install python3-pip #. Ensure the latest version of pip is installed: @@ -131,14 +117,22 @@ If installing Kolla Ansible in a virtual environment, skip this section. .. code-block:: console - sudo yum install ansible + sudo dnf install ansible - For Ubuntu, run: + For Debian or Ubuntu, run: .. code-block:: console sudo apt-get install ansible + .. note:: + + If the installed Ansible version does not meet the requirements, one can + use pip: ``sudo pip install -U 'ansible<2.10'``. + Beware system package upgrades might interfere with that so it + is recommended to uninstall the system package first. One might be better + off with the virtual environment method to avoid this pitfall. + Install Kolla-ansible ~~~~~~~~~~~~~~~~~~~~~ @@ -172,7 +166,7 @@ Install Kolla-ansible for deployment or evaluation .. code-block:: console - cp -r /path/to/virtualenv/share/kolla-ansible/etc_examples/kolla/* /etc/kolla + cp -r /path/to/venv/share/kolla-ansible/etc_examples/kolla/* /etc/kolla If not using a virtual environment on CentOS or RHEL, run: @@ -193,7 +187,7 @@ Install Kolla-ansible for deployment or evaluation .. code-block:: console - cp /path/to/virtualenv/share/kolla-ansible/ansible/inventory/* . + cp /path/to/venv/share/kolla-ansible/ansible/inventory/* . If not using a virtual environment on CentOS or RHEL, run: @@ -329,9 +323,12 @@ than one node, edit ``multinode`` inventory: .. note:: - Ubuntu might not come with python pre-installed. That will cause - errors in ping module. To quickly install python with ansible you - can run ``ansible -i multinode all -m raw -a "apt-get -y install python-dev"`` + Distributions might not come with Python pre-installed. That will cause + errors in the ``ping`` module. To quickly install Python with Ansible you + can run: for Debian or Ubuntu: + ``ansible -i multinode all -m raw -a "apt-get -y install python3"``, + and for CentOS or RHEL: + ``ansible -i multinode all -m raw -a "dnf -y install python3"``. Kolla passwords --------------- @@ -384,7 +381,7 @@ There are a few options that are required to deploy Kolla-Ansible: Choices are: binary - using repositories like apt or yum + using repositories like apt or dnf source using raw source archives, git repositories or local source directory diff --git a/doc/source/user/virtual-environments.rst b/doc/source/user/virtual-environments.rst index 8af28527f9..1cea330831 100644 --- a/doc/source/user/virtual-environments.rst +++ b/doc/source/user/virtual-environments.rst @@ -4,9 +4,9 @@ Virtual Environments ==================== -Python `virtual environments `_ provide -a mechanism for isolating python packages from the system site packages, and -other virtual environments. Kolla-ansible largely avoids this problem by +Python `virtual environments `_ +provide a mechanism for isolating python packages from the system site packages +and other virtual environments. Kolla-ansible largely avoids this problem by deploying services in Docker containers, however some python dependencies must be installed both on the Ansible control host and the target hosts. @@ -18,20 +18,13 @@ python virtual environment on the Ansible control host. For example: .. code-block:: console - virtualenv /path/to/venv + python3 -m venv /path/to/venv source /path/to/venv/bin/activate pip install -U pip pip install kolla-ansible + pip install 'ansible<2.10' deactivate -It may be advantageous to also install Ansible in the virtual environment. - -.. code-block:: console - - source /path/to/venv/bin/activate - (venv) pip install ansible - (venv) deactivate - To use the virtual environment, it should first be activated: .. code-block:: console