Add a BuildRequest object

In order to maintain the API contract when using cells we need to store enough information to fulfill an instance show request.

Problem description

When an API request is made to build an instance there is a certain response contract that we need to honor. This means that we need to have stored certain information from the request such as image, flavor, name, uuid, etc… In a cellsv2 setup this poses a challenge because that would currently be stored in the instance table, but we don’t know which cell instance table to put it in yet.

Use Cases

  • Operators want to partition their deployments into cells for scaling, failure domain, and buildout reasons. When partitioned, we need to maintain the current API contract.

Project Priority

Cellsv2 is a priority for Liberty.

Proposed change

A new object will be added which will have a RequestSpec object as a field, and all additional details needed for an instance show as other fields.

A new table will be added to the api database to store the fields which are not in the RequestSpec.


The RequestSpec object could be expanded to hold all of this data. That would bloat an object whose purpose is to inform scheduling decisions with unnecessary data for that task.

An instance table could be added to the api database. This is similar to what’s being proposed here, but could lead to confusion because of its temporary nature. The BuildRequest object will look much like an instance, but it will be clear that it’s not actually the instance.

Data model impact

A new table will be added to the ‘nova_api’ database for storing the BuildRequest fields. The table will need to store things like availability_zone, power_state, task_state, uuid, key_name, metadata, security_groups, etc… These items will be stored as a versioned dict of the fields necessary.

The table will look like::

CREATE TABLE `build_request` (
  `created_at` datetime DEFAULT NULL,
  `updated_at` datetime DEFAULT NULL,
  `instance_uuid` varchar(36) NOT NULL,
  `project_id` varchar(255) NOT NULL,
  `request_obj` text NOT NULL

instance_uuid and project_id would be indexed.

Once the instance has been written to a cell database this entry should be deleted as the show request can then be fulfilled from the instance table. This means that this data is short lived so future changes can be made with few concerns about backwards compatibility.

REST API impact


Security impact


Notifications impact


Other end user impact


Performance Impact

An additional database write will be incurred.

Other deployer impact

Instances that have not been scheduled yet will exist in this new table. Deployers will need to be aware of this to aid proper debugging.

Developer impact




Primary assignee:


Other contributors:


Work Items

  • Add BuildRequest object

  • Add new table to api database

  • Have nova-api write BuildRequest info to this table

  • After the instance has been created in the cell database (covered in the scheduler interaction spec) remove this database row.




Since this is designed to be an internal re-architecting of Nova with no user visible changes the current suite of Tempest or functional tests should suffice. At some point we will want to look at how to test multiple cells or potentially exposing the concept of a cell in the API and we will tackle testing requirements then.

Documentation Impact

Documentation will be written describing the flow of an instance build and how this affects it.