[doc] Add documentation on running as non-root

Right now our documentation assumes that users must run
OpenStack-Ansible as root users. With that it's not a
strict requirement and there is a pretty much
straightforward way on running playbooks as non-root
user by leveraging Ansibles' `become`.

Depends-On: https://review.opendev.org/c/openstack/ansible-role-python_venv_build/+/897948
Change-Id: I426c78157a17fd4524e48437c6f632a8551223d0
This commit is contained in:
Dmitriy Rabotyagov 2023-10-11 20:25:03 +02:00
parent 76e0f9ae31
commit f37eb32a93
4 changed files with 113 additions and 3 deletions

View File

@ -133,10 +133,13 @@ Configure CentOS / Rocky
Configure SSH keys Configure SSH keys
================== ==================
Ansible uses SSH to connect the deployment host and target hosts. Ansible uses SSH to connect the deployment host and target hosts. You can
either use ``root`` user or any other user that is allowed to escalate
privileges through `Ansible become`_ (like adding user to sudoers).
For more details, please reffer to the `Running as non-root`_.
#. Copy the contents of the public key file on the deployment host to #. Copy the contents of the public key file on the deployment host to
the ``/root/.ssh/authorized_keys`` file on each target host. the ``~/.ssh/authorized_keys`` file on each target host.
#. Test public key authentication from the deployment host to each target #. Test public key authentication from the deployment host to each target
host by using SSH to connect to the target host from the deployment host. host by using SSH to connect to the target host from the deployment host.
@ -148,7 +151,8 @@ For more information about how to generate an SSH key pair, as well as best
practices, see `GitHub's documentation about generating SSH keys`_. practices, see `GitHub's documentation about generating SSH keys`_.
.. _GitHub's documentation about generating SSH keys: https://help.github.com/articles/generating-ssh-keys/ .. _GitHub's documentation about generating SSH keys: https://help.github.com/articles/generating-ssh-keys/
.. _Ansible become: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html
.. _Running as non-root: https://docs.openstack.org/openstack-ansible/latest/user/security/non-root.rst
Configuring the storage Configuring the storage
======================= =======================

View File

@ -108,6 +108,12 @@ the databases that they need to query.
.. _principle of least privilege: https://en.wikipedia.org/wiki/Principle_of_least_privilege .. _principle of least privilege: https://en.wikipedia.org/wiki/Principle_of_least_privilege
You can also run OpenStack-Ansible with non-root user by leveraging the
`Ansible privilege escalation`_ method. For more details, please reffer to
the :doc:`running as non-root </user/security/non-root>`.
.. _Ansible privilege escalation: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html
.. _least-access-openstack-services: .. _least-access-openstack-services:
Securing network access to OpenStack services Securing network access to OpenStack services

View File

@ -14,3 +14,4 @@ For understanding security design, please see
.. include:: security-headers.rst .. include:: security-headers.rst
.. include:: security-txt.rst .. include:: security-txt.rst
.. include:: hardening.rst .. include:: hardening.rst
.. include:: non-root.rst

View File

@ -0,0 +1,99 @@
Running as non-root user
========================
Deployers do not have to use ``root`` user accounts on deploy or target hosts.
This approach works out of the box by leveraging `Ansible privilege escalation`_.
Deploment hosts
~~~~~~~~~~~~~~~
You can avoid usage of the ``root`` user on a deployment by following these
guidelines:
#. Clone OpenStack-Ansible repository to home user directory. It means, that
instead of ``/opt/openstack-ansible`` repository will be in
``~/openstack-ansible``.
#. Use custom path for ``/etc/openstack_deploy`` directory. You can place
OpenStack-Ansible configuration directory inside user home directory.
For that you will need to define the following environment variable:
.. code-block:: shell-session
export OSA_CONFIG_DIR="${HOME}/openstack_deploy"
#. If you want to keep basic ansible logging, you need either to create
``/openstack/log/ansible-logging/`` directory and allow user to write there,
or define the following environment variable:
.. code-block:: shell-session
export ANSIBLE_LOG_PATH="${HOME}/ansible-logging/ansible.log"
.. note::
You can also add the environment variable to ``user.rc`` file inside
openstack_deploy folder (``${OSA_CONFIG_DIR}/user.rc``). ``user.rc`` file
is sourced each time you run ``openstack-ansible`` binary.
#. Initial bootstrap of OpenStack-Ansible using ./scripts/bootstrap-ansible.sh
script still should be done either as the ``root`` user or escalate
privileges using ``sudo`` or ``su``.
Destination hosts
~~~~~~~~~~~~~~~~~
It is also possible to use non-root user for Ansible authentication on
destination hosts. However, this user must be able to escalate privileges
using `Ansible privilege escalation`_.
.. note::
You can add environment variables from that section to ``user.rc`` file
inside openstack_deploy folder (``${OSA_CONFIG_DIR}/user.rc``). ``user.rc``
file is sourced each time you run ``openstack-ansible`` binary.
There are also couple of additional things which you might want to consider:
#. Provide ``--become`` flag each time your run a playbook or ad-hoc command.
Alternatively, you can define the following environment variable:
.. code-block:: shell-session
export ANSIBLE_BECOME="True"
#. Override Ansible temporary path if LXC containers are used. The ansible
connection from the physical host to the LXC container passes
environment variables from the host. This means that Ansible attempts to
use the same temporary folder in the LXC container as it would on the host,
relative to the non-root user ${HOME} directory. This will not exist inside
the container and another path must be used instead.
You can do that following in multiple ways:
a. Define ``ansible_remote_tmp: /tmp`` in user_variables.yml
b. Define the following environment variable:
.. code-block:: shell-session
export ANSIBLE_LOCAL_TEMP="/tmp"
#. Define the user that will be used for for connections from the deploy
host to the ansible target hosts. In case the user is the same for all
hosts in your deployment, you can do it in one of following ways:
a. Define ``ansible_user: <USER>`` in user_variables.yml
b. Define the following environment variable:
.. code-block:: shell-session
export ANSIBLE_REMOTE_USER="<USER>"
If the user differs from host to host, you can leverage group_vars or
host_vars. More information on how to use that can be found in the
:doc:`overrides guide </reference/configuration/using-overrides>`
.. _Ansible privilege escalation: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html