From f37eb32a93ae9e4bc04cd5cd4e07012fb6bb5a57 Mon Sep 17 00:00:00 2001 From: Dmitriy Rabotyagov Date: Wed, 11 Oct 2023 20:25:03 +0200 Subject: [PATCH] [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 | 10 +- .../reference/architecture/security.rst | 6 ++ doc/source/user/security/index.rst | 1 + doc/source/user/security/non-root.rst | 99 +++++++++++++++++++ 4 files changed, 113 insertions(+), 3 deletions(-) create mode 100644 doc/source/user/security/non-root.rst diff --git a/deploy-guide/source/targethosts-prepare.rst b/deploy-guide/source/targethosts-prepare.rst index f175ad4944..001bbb3368 100644 --- a/deploy-guide/source/targethosts-prepare.rst +++ b/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 ======================= diff --git a/doc/source/reference/architecture/security.rst b/doc/source/reference/architecture/security.rst index 69f4bb0eab..f3264fda00 100644 --- a/doc/source/reference/architecture/security.rst +++ b/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 `. + + +.. _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 diff --git a/doc/source/user/security/index.rst b/doc/source/user/security/index.rst index 7c725cd902..0b32f9ed91 100644 --- a/doc/source/user/security/index.rst +++ b/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 diff --git a/doc/source/user/security/non-root.rst b/doc/source/user/security/non-root.rst new file mode 100644 index 0000000000..08275a60fe --- /dev/null +++ b/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: `` in user_variables.yml + b. Define the following environment variable: + + .. code-block:: shell-session + + export ANSIBLE_REMOTE_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 ` + +.. _Ansible privilege escalation: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html