==================
Node Multi-Tenancy
==================

This guide explains the steps needed to enable node multi-tenancy. This
feature enables non-admins to perform API actions on nodes, limited by
policy configuration. The Bare Metal service supports two kinds of
non-admin users:

* Owner: owns specific nodes and performs administrative actions on them
* Lessee: receives temporary and limited access to a node

Setting the Owner and Lessee
============================

Non-administrative access to a node is controlled through a node's ``owner``
or ``lessee`` attribute::

  baremetal node set --owner 080925ee2f464a2c9dce91ee6ea354e2  node-7
  baremetal node set --lessee 2a210e5ff114c8f2b6e994218f51a904  node-10

Ironic's API automatically grants visibility and access to these nodes
when a user request comes in with a "project" scope, i.e. credentials
which indicate the user is in a user within a project.

In older versions of Ironic, this functionality had to be manually configured
and then set via custom policies, but now it is automatically available
in modern versions of Ironic.

Trust Model
===========

The ``owner`` and ``lessee`` fields imply very different levels of trust:

* An ``owner`` project is a delegated administrator of the hardware. With
  the default policies, its users holding the ``member`` role can, among
  other things, update the node's BMC address and credentials, access the
  serial console, run arbitrary cleaning and service steps, and lease the
  node to other projects. In many environments, the owning project may
  also have physical access to the nodes, and Ironic does not fully
  isolate the nodes of one owner from the nodes of another owner.

* A ``lessee`` project is a user of the hardware, and may be a completely
  untrusted customer. The ``lessee`` field may also be populated
  automatically and non-interactively when a node is deployed, as
  controlled by :oslo.config:option:`conductor.automatic_lessee_source`.
  The default policies largely limit lessees to using the node, rather
  than administering it (lessee ``admin`` users can still reprovision it
  and run cleaning and service steps), and prevent them from viewing
  sensitive node fields.

.. warning::
   Setting a project as a node's ``owner`` grants elevated access to
   *all* members of that project. It is highly advisable to use a
   dedicated project with strictly limited membership to own nodes.

See the :ref:`trust model description <secure-rbac-trust-model>` in
:doc:`/admin/secure-rbac` for details of exactly what access each field
grants with the default policies.
