[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

deploy-guide/source/targethosts-prepare.rst

@@ -133,10 +133,13 @@ Configure CentOS / Rocky
 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
-   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
    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`_.
 
 .. _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
 =======================

doc/source/reference/architecture/security.rst

@@ -108,6 +108,12 @@ the databases that they need to query.
 
 .. _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:
 
 Securing network access to OpenStack services

doc/source/user/security/index.rst

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

doc/source/user/security/non-root.rst

@@ -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