From 325c2b0a96e4064595392dd36fe83fcee6f563f2 Mon Sep 17 00:00:00 2001 From: Julia Kreger Date: Tue, 6 Feb 2024 14:09:40 -0800 Subject: [PATCH] docs: augment admin troubleshooting docs for system scope context Change-Id: I55d94e40e0cc11106b8f0622355db0011e811622 --- doc/source/admin/troubleshooting.rst | 91 ++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/doc/source/admin/troubleshooting.rst b/doc/source/admin/troubleshooting.rst index 341f5891b9..e8c64b8a4c 100644 --- a/doc/source/admin/troubleshooting.rst +++ b/doc/source/admin/troubleshooting.rst @@ -1148,3 +1148,94 @@ i.e. a larger value to enable conductors to have time between running syncs. merger will result in a slightly more performant implementation, which may necessitate re-evaluation and tuning of the ``[pxe_filter]sync_period`` parameter. + +Some or all of my baremetal nodes disappeared! Help?! +===================================================== + +If you just upgraded, and this has occured: + +#) Don't Panic +#) Don't try to re-enroll the nodes. They should still be there, + you just can't see them at the moment. + +Over the past few years, Ironic and OpenStack project as a whole has been +working to improve the model of Role Based Access Control. For users of +Ironic, this means an extended role based access control model allowing +delineation of nodes and the ability for projects to both self-manage. + +The result is that users inside of a project are only permitted to see +baremetal nodes, through the ``owner`` and ``lessee`` field, which has +been granted access to the project. + +However, as with any complex effort, there can be hiccups, and you have +encountered one. Specifically that based upon large scale operator feedback, +Ironic kept logic behind System scoped user usage, which OpenStack largely +avoided due to concerns over effort. + +As such, you have a couple different paths you can take, and your ideal +path is also going to vary upon your model of usage and comfort level. +We recommend reading the rest of this answer section before taking any +further action. + +A good starting point is obtaining a ``system`` scoped account with an +``admin`` or ``member`` role. Either of those roles will permit a node's +``owner`` or ``lessee`` fields to be changed. Executing +``baremetal node list`` commands with this account should show you all +baremetal nodes accross all projects. Alternatively, If you just want to +enable the legacy RBAC policies temporarily to change the fields, that is also +an option, although not encouraged, and can be done utilizing the +``[oslo_policy] enforce_scope`` and ``[oslo_policy] enforce_new_defaults`` +settings. + +System Scoped Accounts +---------------------- + +A ``system`` scoped account is one which has access and authority over the +whole of the of an OpenStack deployment. A simplified way to think of +this is when deployed, a username and password is utilized to "bootstrap" +keystone. The rights granted to that user are inherently a system scoped +``admin`` role level of access. You can use this level of access to +check the status, or run additional commands. + +In this example below, which if successful, should return a list of all +baremetal nodes known to Ironic, once the executing user supplies the +valid password. In this case the "admin" account keystone was +bootstrapped with. As a minor note, you will not be able to have +any "OS_*" enviornment variables loaded into your current +command shell, including "OS_CLOUD" for this command to be successful. + +.. code-block:: console + + $ openstack --os-username=admin --os-user-domain-name=default --os-system-scope all baremetal node list + +You can alternatively issue a `system-scoped token `_ +and re-use further commands with that token, or even generate a new system +scoped account with a role of ``member``. + +Changing/Assigning an Owner +--------------------------- + +Ironic performs matching based upon Project ID. The owner field can be set +to a project's ID value, which allows baremetal nodes to be visible. + +.. code-block:: console + + $ PROJECT_ID=$(openstack project show -c id -f value $PROJECT_NAME) + $ baremetal node set --owner $PROJECT_ID $NODE_UUID_OR_NAME + +Why am I only seeing *some* of the nodes? +----------------------------------------- + +During the Zed development cycle of Ironic, Ironic added an option which +defaulted to True, which enabled project scoped ``admin`` users to be able +to create their own baremetal nodes without needing higher level acccess. +This default enabled option, ``[api] project_admin_can_manage_own_nodes``, +automatically stamps the requestor's project ID on to a baremetal node if an +``owner`` is not otherwise specified upon creation. Obviously, this can +create a mixed perception if an operator never paid attention to the ``owner`` +field before now. + +If your bare metal management processes require that full machine management +is made using a project scoped account, please configure an appropriate +node ``owner`` for the nodes which need to be managed. Ironic recognizes +this is going to vary based upon processes and preferences.