nova/doc/source/admin/compute-node-identification.rst

Compute Node Identification

Nova requires that compute nodes maintain a constant and consistent identity during their lifecycle. With the exception of the ironic driver, starting in the 2023.1 release, this is achieved by use of a file containing the node unique identifier that is persisted on disk. Prior to 2023.1, a combination of the compute node's hostname and the :oslo.confighost value in the configuration file were used.

The 2023.1 and later compute node identification file must remain unchanged during the lifecycle of the compute node. Changing the value or removing the file will result in a failure to start and may require advanced techniques for recovery. The file is read once at nova-compute` startup, at which point it is validated for formatting and the corresponding node is located or created in the database.

Note

Even after 2023.1, the compute node's hostname may not be changed after the initial registration with the controller nodes, it is just not used as the primary method for identification.

The behavior of nova-compute is different when using the ironic driver, as the (UUID-based) identity and mapping of compute nodes to compute manager service hosts is dynamic. In that case, no single node identity is maintained by the compute host and thus no identity file is read or written. Thus none of the sections below apply to hosts with :oslo.configcompute_driver set to ironic.

Self-provisioning of the node identity

By default, nova-compute will automatically generate and write a UUID to disk the first time it starts up, and will use that going forward as its stable identity. Using the :oslo.configstate_path (which is /var/lib/nova on most systems), a compute_id file will be created with a generated UUID.

Since this file (and it's parent directory) is writable by nova, it may be desirable to move this to one of the other locations that nova looks for the identification file.

Deployment provisioning of the node identity

In addition to the location mentioned above, nova will also search the parent directories of any config file in use (either the defaults or provided on the command line) for a compute_id file. Thus, a deployment tool may, on most systems, pre-provision the node's UUID by writing one to /etc/nova/compute_id.

The contents of the file should be a single UUID in canonical textual representation with no additional whitespace or other characters. The following should work on most Linux systems:

$ uuidgen > /etc/nova/compute_id

Note

Do not execute the above command blindly in every run of a deployment tool, as that will result in overwriting the compute_id file each time, which will prevent nova from working properly.

Upgrading from pre-2023.1

Before release 2023.1, nova-compute only used the hostname (combined with :oslo.confighost, if set) to identify its compute node objects in the database. When upgrading from a prior release, the compute node will perform a one-time migration of the hostname-matched compute node UUID to the compute_id file in the :oslo.configstate_path location.

Note

It is imperative that you allow the above migration to run and complete on compute nodes that are being upgraded. Skipping this step by pre-provisioning a compute_id file before the upgrade will not work and will be equivalent to changing the compute node UUID after it has already been created once.