NOVA-MANAGE(1)

📦
version 34.0.0 · 12 versions
, in ubuntu stonking

👑 NOVA-MANAGE(1)

okay bestie, welcome to nova-manage, the manual page for the nova management tool 💖 — the command-line queen that runs the admin side of OpenStack Compute. Sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

nova-manage — the management tool for the OpenStack Compute services. it's giving "I run the cloud" energy and honestly? it does. 👑

🌸 SYNOPSIS 🌸

nova-manage <category> [<action> [<options>...]]

🦋 DESCRIPTION 🦋

nova-manage controls cloud computing instances by managing various admin-only aspects of Nova. so like, this is not the casual-user tool, this is the "I have root and I know things" tool. iykyk. 💅

the standard pattern for executing a nova-manage command is, literally:

nova-manage <category> <command> [<args>]

run it with no arguments at all and it'll show you a list of available command categories:

nova-manage

and you can also run with a category argument like db to see a list of all commands in that category:

nova-manage db

main character energy: categories are the vibe, commands are the plot. 🌈

🎀 OPTIONS 🎀

these options apply to all commands and may be given in any order, before or after commands. individual commands may provide additional options. options without an argument can be combined after a single dash. (yes, that's a real little shortcut, no cap.)

  • -h, --help — show a help message and exit. the classic. 🫶
  • --config-dir <dir> — path to a config directory to pull *.conf files from. this file set is sorted, so as to provide a predictable parse order if individual options are over-ridden. the set is parsed after the file(s) specified via previous --config-file arguments, hence over-ridden options in the directory take precedence. ⚠️ this option must be set from the command-line.
  • --config-file <path> — path to a config file to use. multiple config files can be specified, with values in later files taking precedence. defaults to None. this option must be set from the command-line.
  • --log-config-append <path>, --log-config <path>, --log_config <path> — the name of a logging configuration file. this file is appended to any existing logging configuration files. for details about logging configuration files, see the Python logging module documentation. note that when logging configuration files are used then all logging configuration is set in the configuration file and other logging configuration options are ignored (for example, --log-date-format). 💀
  • --log-date-format <format> — defines the format string for %(asctime)s in log records. default: None. this option is ignored if --log-config-append is set.
  • --log-dir <dir>, --logdir <dir> — the base directory used for relative log_file paths. this option is ignored if --log-config-append is set.
  • --log-file PATH, --logfile <path> — name of log file to send logging output to. if no default is set, logging will go to stderr as defined by use_stderr. this option is ignored if --log-config-append is set.
  • --syslog-log-facility SYSLOG_LOG_FACILITY — syslog facility to receive log lines. this option is ignored if --log-config-append is set.
  • --use-journal — enable journald for logging. if running in a systemd environment you may wish to enable journal support. doing so will use the journal native protocol which includes structured metadata in addition to log messages. this option is ignored if --log-config-append is set.
  • --nouse-journal — the inverse of --use-journal. 🙃
  • --use-json — use JSON formatting for logging. this option is ignored if --log-config-append is set.
  • --nouse-json — the inverse of --use-json.
  • --use-syslog — use syslog for logging. existing syslog format is DEPRECATED and will be changed later to honor RFC5424. this option is ignored if --log-config-append is set.
  • --nouse-syslog — the inverse of --use-syslog.
  • --watch-log-file — uses logging handler designed to watch file system. when log file is moved or removed this handler will open a new log file with specified path instantaneously. it makes sense only if --log-file option is specified and Linux platform is used. this option is ignored if --log-config-append is set.
  • --nowatch-log-file — the inverse of --watch-log-file.
  • --debug, -d — if enabled, the logging level will be set to DEBUG instead of the default INFO level. turn it on when you want to see everything 👀
  • --nodebug — the inverse of --debug.
  • --post-mortem — allow post-mortem debugging.
  • --nopost-mortem — the inverse of --post-mortem.
  • --version — show program's version number and exit. ✨

💜 DATABASE COMMANDS 💜

🌸 db version

nova-manage db version

print the current main database version. that's it, that's the whole thing, she's simple and she ate. 💅

🦋 db sync

nova-manage db sync [--local_cell] [VERSION]

upgrade the main database schema up to the most recent version, or up to VERSION if specified. by default, this command will also attempt to upgrade the schema for the cell0 database if it is mapped. if --local_cell is specified, then only the main database in the current cell is upgraded. the local database connection is determined by database.connection <#database.connection> in the configuration file, passed to nova-manage using the --config-file option(s).

refer to the nova-manage cells_v2 map_cell0 or nova-manage cells_v2 simple_cell_setup commands for more details on mapping the cell0 database. 🗺️

⚠️ this command should be run after nova-manage api_db sync. order matters, bestie, don't skip steps.

Options

  • --local_cell — only sync db in the local cell: do not attempt to fan-out to all cells.

Return codes

  • 0 — successfully synced database schema. 🎉
  • 1 — failed to access cell0. 😭

Changed in version 20.0.0: (Train)

removed support for the legacy --version <version> argument.

Changed in version 24.0.0: (Xena)

migrated versioning engine to alembic. the optional VERSION argument is now expected to be an alembic-based version. sqlalchemy-migrate-based versions will be rejected. no old-school versions allowed, periodt.

🎀 db archive_deleted_rows

nova-manage db archive_deleted_rows [--max_rows <rows>] [--verbose]
  [--until-complete] [--before <date>] [--purge] [--all-cells] [--task-log]
  [--sleep]

move deleted rows from production tables to shadow tables. note that the corresponding rows in the instance_mappings, request_specs and instance_group_member tables of the API database are purged when instance records are archived and thus, api_database.connection <#api_database.connection> is required in the config file. yes, you literally need the API DB connection for this. 🔥

if automating, this should be run continuously while the result is 1, stopping at 0, or use the --until-complete option.

Changed in version 24.0.0: (Xena)

added --task-log, --sleep options.

Options

  • --max_rows <rows> — maximum number of deleted rows to archive. defaults to 1000. note that this number does not include the corresponding rows, if any, that are removed from the API database for deleted instances.
  • --before <date> — archive rows that have been deleted before <date>. accepts date strings in the default format output by the date command, as well as YYYY-MM-DD[HH:mm:ss]. for example:
# Purge shadow table rows older than a specific date
nova-manage db archive_deleted_rows --before 2015-10-21
# or
nova-manage db archive_deleted_rows --before "Oct 21 2015"
# Times are also accepted
nova-manage db archive_deleted_rows --before "2015-10-21 12:00"

note that relative dates (such as yesterday) are not supported natively. the date command can be helpful here:

# Archive deleted rows more than one month old
nova-manage db archive_deleted_rows --before "$(date -d 'now - 1 month')"
  • --verbose — print how many rows were archived per table. numbers!! we love numbers ✨
  • --until-complete — run continuously until all deleted rows are archived. use --max_rows as a batch size for each iteration.
  • --purge — purge all data from shadow tables after archive completes. dramatic. 💀
  • --all-cells — run command across all cells.
  • --task-log — also archive task_log table records. note that task_log records are never deleted, so archiving them will move all of the task_log records up to now into the shadow tables. it is recommended to also specify the --before option to avoid races for those consuming task_log record data via the /os-instance_usage_audit_log <https://docs.openstack.org/api-ref/compute/#server-usage-audit-log-os-instance-usage-audit-log> API (example: Telemetry).
  • --sleep — the amount of time in seconds to sleep between batches when --until-complete is used. defaults to 0.

okay that's the first chunk, there's more coming, don't go anywhere 💖

✨ Return codes ✨

Ok bestie, here's the little decoder ring for what this command hands back to you:

  • 0 — Nothing was archived. Crickets. Zero. Nada. 💀
  • 1 — Some number of rows were archived. We did something! 🎉
  • 2 — Invalid value for --max_rows.
  • 3 — No connection to the API database could be established using api_database.connection.
  • 4 — Invalid value for --before.
  • 255 — An unexpected error occurred. 🫠

🧹 db purge

nova-manage db purge [--all] [--before <date>] [--verbose] [--all-cells]

This one deletes rows from the shadow tables. Just yeets them. Gone. 🗑️

Heads up though: for --all-cells to actually work, the API database connection information must be configured. No config, no vibes.

Added in version 18.0.0: (Rocky)

Options

  • --all — Purge all the rows in the shadow tables. Every last one. No crumbs left. 💅
  • --before <date> — Deletes archived rows that were deleted from Nova before <date>. It accepts date strings in the default format that the date command spits out, plus YYYY-MM-DD[HH:mm:ss]. For example:
# Purge shadow table rows deleted before specified date
nova-manage db purge --before 2015-10-21
# or
nova-manage db purge --before "Oct 21 2015"
# Times are also accepted
nova-manage db purge --before "2015-10-21 12:00"

Also important: relative dates (like yesterday) are not supported natively. That's literally why the date command exists, bestie — let it do the math for you:

# Archive deleted rows more than one month old
nova-manage db purge --before "$(date -d 'now - 1 month')"
  • --verbose — Prints out info about the purged records. So you can see exactly what got deleted. Nosy but valid.
  • --all-cells — Run against all cell databases. All of them. Every single one. 🌈

Return codes

  • 0 — Rows were deleted. Success slay. ✅
  • 1 — Required arguments were not provided. You forgot something, bestie. 😭
  • 2 — Invalid value for --before.
  • 3 — Nothing was purged.
  • 4 — No connection to the API database could be established using api_database.connection.

🔄 db online_data_migrations

nova-manage db online_data_migrations [--max-count <count>]

Performs data migration to update all live data. Live! Real-time! Main character energy. ✨

The way this works: you call this command after upgrading the database schema and the nova services on all controller nodes. If it exits with partial updates (exit status 1) you should call it again — even if some updates initially generated errors — because some updates may depend on others having already completed. It's a whole chain, iykyk.

If it exits with status 2, intervention is required to resolve the issue causing the remaining updates to fail. Like, a human has to get involved. 🙈

It should be considered successfully completed only when the exit status is 0. Periodt.

For example:

$ nova-manage db online_data_migrations
Running batches of 50 until complete
2 rows matched query migrate_instances_add_request_spec, 0 migrated
2 rows matched query populate_queued_for_delete, 2 migrated
+---------------------------------------------+--------------+-----------+
|                  Migration                  | Total Needed | Completed |
+---------------------------------------------+--------------+-----------+
|         create_incomplete_consumers         |      0       |     0     |
|      migrate_instances_add_request_spec     |      2       |     0     |
|       migrate_quota_classes_to_api_db       |      0       |     0     |
|        migrate_quota_limits_to_api_db       |      0       |     0     |
|          migration_migrate_to_uuid          |      0       |     0     |
|     populate_missing_availability_zones     |      0       |     0     |
|          populate_queued_for_delete         |      2       |     2     |
|                populate_uuids               |      0       |     0     |
+---------------------------------------------+--------------+-----------+

So in that example up there, the migrate_instances_add_request_spec migration found two candidate records but did not need to perform any kind of data migration for either of them. And for the populate_queued_for_delete migration, two candidate records were found which did require a data migration. Since --max-count defaults to 50 and only two records were migrated with no more candidates remaining, the command completed successfully with exit code 0. Ate and left no crumbs. 👑

Added in version 13.0.0: (Mitaka)

Options

  • --max-count <count> — Controls the maximum number of objects to migrate in a given call. If you don't specify it, migration will occur in batches of 50 until fully complete.

Return codes

  • 0 — No (further) updates are possible. Done done.
  • 1 — Some updates were completed successfully. Note that not all updates may have succeeded, so like... call it again. fr fr.
  • 2 — Some updates generated errors and no other migrations were able to take effect in the last batch attempted. 🚨 Intervention time.
  • 127 — Invalid input was provided.

🦋 db ironic_compute_node_move

nova-manage db ironic_compute_node_move --ironic-node-uuid <uuid> --destination-host <host>

Moves ironic nodes — plus any instances attached to them — between nova-compute services. Relocation era. 📦

This is genuinely useful when you're migrating away from using peer_list and multiple hash ring balanced nova-compute servers, over to the new ironic shard system. Glow up.

Here's the order of operations, and yes it matters, bestie:

First you must turn off the nova-compute service that currently manages the Ironic host. Second, you mark that nova-compute service as forced down via the Nova API. Third, you make sure the new nova-compute service is correctly configured to target the appropriate shard (and optionally also a conductor group). Finally — and this is the fun part — most Ironic nodes should now move to the new service on their own, but any Ironic nodes that have instances on them will need to be manually moved to their new Ironic service by using this nova-manage command. 🙋‍♀️

Added in version 28.0.0: (2023.2 Bobcat)

Options

  • --ironic-node-uuid <uuid> — The Ironic node uuid to be moved (which is also the Nova compute node uuid and the uuid of the corresponding resource provider in Placement). One uuid, three identities. Multitasking icon. 🎀

Note that the Nova compute service that currently manages this Ironic node must first be marked a "forced down" via the Nova API — in a similar way to a down hypervisor that is about to have its VMs evacuated to a replacement hypervisor.

  • --destination-host <host> — Destination ironic nova-compute service CONF.host. That's where we're going. 🚀

✨ API DATABASE COMMANDS ✨

💅 api_db version 💅

nova-manage api_db version

Prints the current API database version. That's it, that's the whole vibe. 👑

✨ Added in version 2015.1.0: (Kilo)

💖 api_db sync 💖

nova-manage api_db sync [VERSION]

Upgrades the API database schema up to the most recent version, or to VERSION if you pass one. Important: this command does not create the API database — it just runs the schema migration scripts. The API database connection is determined by api_database.connection <#api_database.connection> in the configuration file passed to nova-manage.

Bestie, run this before nova-manage db sync, okay? Order matters. 💅

✨ Added in version 2015.1.0: (Kilo)

🌀 Changed in version 18.0.0: (Rocky) — Added support for upgrading the optional placement database if [placement_database]/connection is configured.

🌀 Changed in version 20.0.0: (Train) — Removed support for upgrading the optional placement database, since placement is now a separate project. Also removed support for the legacy --version <version> argument.

🌀 Changed in version 24.0.0: (Xena) — Migrated the versioning engine to alembic. The optional VERSION argument is now expected to be an alembic-based version. sqlalchemy-migrate-based versions will be rejected. 🚫

🦋 CELLS V2 COMMANDS 🦋

🌸 cell_v2 simple_cell_setup 🌸

nova-manage cell_v2 simple_cell_setup [--transport-url <transport_url>]

Sets up a fresh cells v2 environment. If --transport-url is not specified, it will use the one defined by transport_url <#DEFAULT.transport_url> in the configuration file. Fresh start, clean slate, main character energy. ✨

✨ Added in version 14.0.0: (Newton)

🎀 Options 🎀

  • --transport-url <transport_url> — The transport url for the cell message queue.

🎀 Return codes 🎀

  • 0 — Setup is completed.
  • 1 — No hosts are reporting, meaning none can be mapped, or if the transport URL is missing or invalid.

💜 cell_v2 map_cell0 💜

nova-manage cell_v2 map_cell0 [--database_connection <database_connection>]

Creates a cell mapping to the database connection for the cell0 database. If a database_connection is not specified, it will use the one defined by database.connection <#database.connection> in the configuration file passed to nova-manage. The cell0 database is used for instances that have not been scheduled to any cell. This generally applies to instances that have encountered an error before they have been scheduled. So it's like the waiting room for sad little instances. 🥺

✨ Added in version 14.0.0: (Newton)

🎀 Options 🎀

  • --database_connection <database_connection> — The database connection URL for cell0. This is optional. If not provided, a standard database connection will be used based on the main database connection from nova configuration.

🎀 Return codes 🎀

  • 0 — cell0 is created successfully or has already been set up.

🧚 cell_v2 map_instances 🧚

nova-manage cell_v2 map_instances --cell_uuid <cell_uuid>
  [--max-count <max_count>] [--reset]

Maps instances to the provided cell. Instances in the nova database will be queried from oldest to newest and mapped to the provided cell. A --max-count can be set on the number of instance to map in a single run. Repeated runs of the command will start from where the last run finished, so it is not necessary to increase --max-count to finish. A --reset option can be passed which will reset the marker, thus making the command start from the beginning, as opposed to the default behavior of starting from where the last run finished.

If --max-count is not specified, all instances in the cell will be mapped in batches of 50. If you have a large number of instances, consider specifying a custom value and run the command until it exits with 0. So satisfying when it finally hits zero. 😭

✨ Added in version 12.0.0: (Liberty)

🎀 Options 🎀

  • --cell_uuid <cell_uuid> — Unmigrated instances will be mapped to the cell with the UUID provided.
  • --max-count <max_count> — Maximum number of instances to map. If not set, all instances in the cell will be mapped in batches of 50. If you have a large number of instances, consider specifying a custom value and run the command until it exits with 0.
  • --reset — The command will start from the beginning as opposed to the default behavior of starting from where the last run finished.

🎀 Return codes 🎀

  • 0 — All instances have been mapped.
  • 1 — There are still instances to be mapped.
  • 127 — Invalid value for --max-count.
  • 255 — An unexpected error occurred.

🌈 cell_v2 map_cell_and_hosts 🌈

nova-manage cell_v2 map_cell_and_hosts [--name <cell_name>]
  [--transport-url <transport_url>] [--verbose]

Creates a cell mapping to the database connection and message queue transport URL, and maps hosts to that cell. The database connection comes from the database.connection <#database.connection> defined in the configuration file passed to nova-manage. If --transport-url is not specified, it will use the one defined by transport_url <#DEFAULT.transport_url> in the configuration file. This command is idempotent (can be run multiple times), and the verbose option will print out the resulting cell mapping UUID. So go ahead, run it again, it's not mad. 💖

✨ Added in version 13.0.0: (Mitaka)

🎀 Options 🎀

  • --transport-url <transport_url> — The transport url for the cell message queue.
  • --name <cell_name> — The name of the cell.
  • --verbose — Output the cell mapping uuid for any newly mapped hosts.

🎀 Return codes 🎀

  • 0 — Successful completion.
  • 1 — The transport url is missing or invalid.

💫 cell_v2 verify_instance 💫

nova-manage cell_v2 verify_instance --uuid <instance_uuid> [--quiet]

Verifies instance mapping to a cell. This command is useful to determine if the cells v2 environment is properly setup, specifically in terms of the cell, host, and instance mapping records required. It's like a vibe check for your cells. ✅

✨ Added in version 14.0.0: (Newton)

🎀 Options 🎀

  • --uuid <instance_uuid> — The instance UUID to verify.
  • --quiet — Do not print anything.

✨ Return codes ✨

okay so if you're running this against an instance (iykyk), here's what the exit code is telling you:

  • 0 — 🎉 the instance was successfully mapped to a cell. we love to see it.
  • 1 — the instance is not mapped to a cell. go look at the map_instances command, bestie.
  • 2 — the cell mapping is missing. 💀 so if you're upgrading from a cells v1 environment, hit up the map_cell_and_hosts command; and if you're upgrading from a non-cells v1 environment, you want the simple_cell_setup command.
  • 3 — this is a deleted instance that still has an instance mapping just hanging around. awkward.
  • 4 — this is an archived instance that still has an instance mapping. also awkward. ✨

🦋 cell_v2 create_cell 🦋

nova-manage cell_v2 create_cell [--name <cell_name>]
  [--transport-url <transport_url>]
  [--database_connection <database_connection>] [--verbose] [--disabled]

so this one creates a cell mapping to the database connection + message queue transport URL. real "let's make this official" energy. 💖

if a database_connection isn't specified, it'll use the one defined by database.connection in the configuration file that was passed to nova-manage. and if --transport-url isn't specified, it uses the one defined by transport_url in the configuration file. the --verbose option will print out the resulting cell mapping UUID, which is lowkey satisfying ngl. all the cells you create are enabled by default. however — passing the --disabled option can create a pre-disabled cell, meaning no scheduling will happen to this cell at all. it's giving "we built the room but nobody's allowed in yet." 🙈

Added in version 15.0.0: (Ocata)

Changed in version 18.0.0: (Rocky)

  • Added --disabled option.

🌸 Options 🌸

  • --name <cell_name> — the name of the cell. give it a cute one.
  • --database_connection <database_connection> — the database URL for the cell database. 🔥
  • --transport-url <transport_url> — the transport url for the cell message queue.
  • --verbose — output the UUID of the created cell. (so you can screenshot it, obviously.)
  • --disabled — create a pre-disabled cell.

✨ Return codes ✨

  • 0 — the cell mapping was successfully created. slay. 💅
  • 1 — the transport URL or database connection was missing or invalid. 😭
  • 2 — another cell is already using the provided transport URL and/or database connection combination. not the duplication, bestie.

🎀 cell_v2 discover_hosts 🎀

nova-manage cell_v2 discover_hosts [--cell_uuid <cell_uuid>] [--verbose]
  [--strict] [--by-service]

okay so this searches cells — or just a single cell — and maps found hosts. it'll check the database for each cell (or a single one if you passed it in) and map any hosts that aren't currently mapped. if a host is already mapped, nothing happens. no drama. 🫶

the thing everyone forgets: you need to re-run this command every single time you add a batch of compute hosts to a cell. otherwise the scheduler will never place instances there, and the API won't list the new hosts. so like. re-run it. don't make me say it again. 😭

if --strict is specified, the command will only return 0 if an unmapped host was discovered and mapped successfully. if --by-service is specified, this command will look in the appropriate cell(s) for any nova-compute services and make sure there are host mappings for them. this is less efficient and is only necessary when using compute drivers that may manage zero or more actual compute nodes at any given time (currently only ironic).

⚠️ This command should be run once after all compute hosts have been deployed and should not be run in parallel. When run in parallel, the commands will collide with each other trying to map the same hosts in the database at the same time. 💀

Added in version 14.0.0: (Newton)

Changed in version 16.0.0: (Pike)

  • Added --strict option.

Changed in version 18.0.0: (Rocky)

  • Added --by-service option.

🌈 Options 🌈

  • --cell_uuid <cell_uuid> — if provided, only this cell will be searched for new hosts to map. one cell only, keep it focused. ✨
  • --verbose — provide detailed output when discovering hosts. spill the tea.
  • --strict — considered successful (exit code 0) only when an unmapped host is discovered. any other outcome is considered a failure (non-zero exit code).
  • --by-service — discover hosts by service instead of compute node.

✨ Return codes ✨

  • 0 — hosts were successfully mapped, or no hosts needed to be mapped. if --strict is specified, returns 0 only if an unmapped host was discovered and mapped. 👑
  • 1 — if --strict is specified and no unmapped hosts were found. also returns 1 if an exception was raised while running. 😭
  • 2 — the command was aborted because of a duplicate host mapping found. this means the command collided with another running discover_hosts command or a scheduler periodic task — and it is safe to retry. phew. 🙏

🧚 cell_v2 list_cells 🧚

nova-manage cell_v2 list_cells [--verbose]

by default, the cell name, UUID, disabled state, masked transport URL, and database connection details are shown. use the --verbose option to see the transport URL and database connection with their sensitive details. 👀 (yes that means passwords. careful who's looking over your shoulder.)

Added in version 15.0.0: (Ocata)

Changed in version 18.0.0: (Rocky)

  • Added the disabled column to output.

⭐ Options ⭐

  • --verbose — show sensitive details, such as passwords. 🙈

✨ Return codes ✨

  • 0 — success. that's it. that's the list. 💖

🍓 cell_v2 delete_cell 🍓

nova-manage cell_v2 delete_cell [--force] --cell_uuid <cell_uuid>

delete a cell by the given UUID. it's giving spring cleaning but for your database. 🧹✨

Added in version 15.0.0: (Ocata)

💜 Options 💜

  • --force — delete hosts and instance_mappings that belong to the cell as well. (this is the "and take everything with you" button, so maybe double-check the UUID first, bestie. 😭)
  • --cell_uuid <cell_uuid> — the UUID of the cell to delete.

✨ Return codes ✨

okay so for the command we were just talking about, here's what those return codes actually mean, bestie:

  • 0 — An empty cell was found and deleted successfully, or a cell that has hosts was found and the cell, hosts and the instance_mappings were deleted successfully with the --force option (this happens if there are no living instances). slay 💅
  • 1 — A cell with the provided UUID could not be found. 😭
  • 2 — Host mappings were found for the cell, meaning the cell is not empty, and the --force option was not provided. 🙈
  • 3 — There are active instances mapped to the cell (cell not empty). 💀
  • 4 — There are (inactive) instances mapped to the cell and the --force option was not provided. 😬

🦋 cell_v2 list_hosts 🦋

nova-manage cell_v2 list_hosts [--cell_uuid <cell_uuid>]

Lists the hosts in one or all v2 cells. By default hosts in all v2 cells are listed. Use the --cell_uuid option to list hosts in a specific cell.

Added in version 17.0.0: (Queens) — periodt. ✨

Options

  • --cell_uuid <cell_uuid> — The UUID of the cell. (like, which cell are we peeking into? 👀)

Return codes

  • 0 — Success. 🎉
  • 1 — The cell indicated by --cell_uuid was not found. 😭

👑 cell_v2 update_cell 👑

nova-manage cell_v2 update_cell --cell_uuid <cell_uuid>
  [--name <cell_name>] [--transport-url <transport_url>]
  [--database_connection <database_connection>] [--disable] [--enable]

Updates the properties of a cell by the given uuid. If a database_connection is not specified, it will attempt to use the one defined by database.connection in the configuration file. If a transport_url is not specified, it will attempt to use the one defined by transport_url in the configuration file.

Updating the transport_url or database_connection fields on a running system will NOT result in all nodes immediately using the new values. Use caution when changing these values. 😬
The scheduler will not notice that a cell has been enabled/disabled until it is restarted or sent the SIGHUP signal. 🫠

Added in version 16.0.0: (Pike)

Changed in version 18.0.0: (Rocky) — added --enable, --disable options. iconic. 💖

Options

  • --cell_uuid <cell_uuid> — The UUID of the cell to update.
  • --name <cell_name> — Set the cell name.
  • --transport-url <transport_url> — Set the cell transport_url. Note that running nodes will not see the change until restarted or the SIGHUP signal is sent.
  • --database_connection <database_connection> — Set the cell database_connection. Note that running nodes will not see the change until restarted or the SIGHUP signal is sent.
  • --disable — Disables the cell. Note that the scheduling will be blocked to this cell until it is enabled and the nova-scheduler service is restarted or the SIGHUP signal is sent.
  • --enable — Enables the cell. Note that the nova-scheduler service will not see the change until it is restarted or the SIGHUP signal is sent.

Return codes

  • 0 — Success. ✨
  • 1 — The cell was not found by the provided UUID. 😭
  • 2 — The specified properties could not be set. 😬
  • 3 — The provided --transport-url or/and --database_connection parameters were same as another cell. 🙈
  • 4 — An attempt was made to disable and enable a cell at the same time. 💀
  • 5 — An attempt was made to disable or enable cell0. 🚫

🌸 cell_v2 delete_host 🌸

nova-manage cell_v2 delete_host --cell_uuid <cell_uuid> --host <host>

Delete a host by the given host name and the given cell UUID.

Added in version 17.0.0: (Queens)

The scheduler caches host-to-cell mapping information so when deleting a host the scheduler may need to be restarted or sent the SIGHUP signal. 🧠

Options

  • --cell_uuid <cell_uuid> — The UUID of the cell.
  • --host <host> — The host to delete.

Return codes

  • 0 — The empty host was found and deleted successfully
  • 1 — A cell with the specified UUID could not be found.
  • 2 — A host with the specified name could not be found
  • 3 — The host with the specified name is not in a cell with the specified UUID.
  • 4 — The host with the specified name has instances (host not empty). 💀

✨ PLACEMENT COMMANDS ✨

🌸 placement heal_allocations

nova-manage placement heal_allocations [--max-count <max_count>]
  [--verbose] [--skip-port-allocations] [--dry-run]
  [--instance <instance_uuid>] [--cell <cell_uuid>] [--force]

Okay bestie, sit down for this one because it's a whole saga. 💅

So here's the vibe: this command goes through every non-cell0 cell and hunts down instances that are missing their allocations in the Placement service AND aren't out here going through a task state transition. For every single victim—sorry, *instance*—it finds, it creates allocations against that instance's compute node resource provider, based on the flavor that instance has. Iconic. 🎀

Note: Nested allocations are only partially supported, bestie. Nested allocations that happen because Neutron ports have QoS policies? Those have been supported since 20.0.0 (Train). Slay. But nested allocations from vGPU or Cyborg device profile requests in the flavor? Not supported. 😭 Also—and this is important—if you're out here using provider.yaml files on compute hosts to define extra resources, and those resources live on child resource providers, then instances using those resources are not supported either. Sorry babe.

Also, if the instance has any port attached that comes with a resource request (like Quality of Service (QoS): Guaranteed Bandwidth, you know the one), but the corresponding allocation just… isn't there? Then the allocation gets created against the network device resource providers according to that port's resource request. 💖

But plot twist: sometimes that missing allocation genuinely can't be created. Maybe there's not enough resource inventory on the host the instance lives on, or maybe more than one resource provider could fulfill the request (messy). In that case? The instance needs to be manually deleted, or the port needs to be detached. No shortcuts. When nova supports migrating instances with guaranteed bandwidth ports (that's the Train spec if you're curious), migration will heal missing allocations for these instances. Until then? Manual it is. 💅

Okay now the drama of persistence: before those port allocations get persisted in placement, nova-manage tries to update each port in neutron to refer to the resource provider UUID that provides the requested resources. But—if any of those port updates fail in neutron, or the allocation update fails in placement, the command tries to roll back the partial updates to the ports. And if the roll back fails? The process stops with exit code 7 and you, the admin, have to do the rollback in neutron manually according to the description in the exit code section. Good luck bestie, you got this. 🫶

There's also a special case handled for instances that do have allocations created before Placement API microversion 1.8, back when project_id and user_id values were required. For those types of allocations, project_id and user_id get updated using the values from the instance. Nostalgia. 🌸

This command requires that the api_database.connection and placement configuration options are set. Placement API >= 1.28 is required. No skipping. ✨

Added in version 18.0.0: (Rocky)

Changed in version 20.0.0: (Train) — Added --dry-run, --instance, and --skip-port-allocations options.

Changed in version 21.0.0: (Ussuri) — Added --cell option.

Changed in version 22.0.0: (Victoria) — Added --force option.

Changed in version 25.0.0: (Yoga) — Added support for healing port allocations if the port-resource-request-groups neutron API extension is enabled, and therefore ports can request multiple groups of resources, e.g. by using both guaranteed minimum bandwidth and guaranteed minimum packet rate QoS policy rules. Ate. 💅

🎀 Options

  • --max-count <max_count> — Maximum number of instances to process. If you don't specify it, all instances in each cell get mapped in batches of 50. Have a large number of instances? Consider specifying a custom value and running the command until it exits with 0 or 4.
  • --verbose — Provide verbose output during execution. Because sometimes you want all the tea. 👑
  • --dry-run — Runs the command and prints output but does not commit any changes. The return code should be 4.
  • --instance <instance_uuid> — UUID of a specific instance to process. If you specify this, --max-count has no effect. Mutually exclusive with --cell.
  • --skip-port-allocations — Skip the healing of the resource allocations of bound ports. E.g. healing bandwidth resource allocation for ports having minimum QoS policy rules attached. If your deployment doesn't use such a feature, then the performance impact of querying neutron ports for each instance can be avoided with this flag. Speedrun. ✨
  • --cell <cell_uuid> — Heal allocations within a specific cell. Mutually exclusive with --instance.
  • --force — Force heal allocations. Requires the --instance argument.

🦋 Return codes

  • 0 — Command completed successfully and allocations were created. 🎉
  • 1 — --max-count was reached and there are more instances to process.
  • 2 — Unable to find a compute node record for a given instance. 💀
  • 3 — Unable to create (or update) allocations for an instance against its compute node resource provider.
  • 4 — Command completed successfully but no allocations were created.
  • 5 — Unable to query ports from neutron.
  • 6 — Unable to update ports in neutron.
  • 7 — Cannot roll back neutron port updates. Manual steps needed. The error message will indicate which neutron ports need to be changed to clean up binding:profile of the port:
$ openstack port unset <port_uuid> --binding-profile allocation
  • 127 — Invalid input. 🙈
  • 255 — An unexpected error occurred. 😭
└─────────────┴───────────────────────────────────────────────────────────────────────────┘

and that's a wrap on that table, bestie 💅 onto the next ones!

placement sync_aggregates

ok so this one is all about aggregates, and the synopsis is giving very simple, very demure:

nova-manage placement sync_aggregates [--verbose]

What it actually does? It mirrors compute host aggregates to resource provider aggregates in the Placement service. Yes, it's literally copying your aggregate vibe over to the other side. 🦋

BUT — and hear me out — it needs the api_database and placement sections of the nova configuration file to be populated first. Like, actually populated. Not just sitting there empty. No config, no sync, no slay. 😭

Throw in --verbose if you want detailed progress output while it's running, so you can sit there and watch each lil step like it's a reality TV finale. 👑

⚠️ Note: Depending on the size of your deployment and the number of compute hosts in aggregates, this command could cause a non-negligible amount of traffic to the placement service, and therefore is recommended to be run during maintenance windows. She is NOT a peak-traffic girly. Please respect her boundaries. 🙈

Added in version 18.0.0: (Rocky) ✨

Options

  • --verbose — Provide verbose output during execution.

Return codes

┌─────────────┬────────────────────────────┐
│ Return code │ Description                │
├─────────────┼────────────────────────────┤
│ 0           │ Successful run             │
├─────────────┼────────────────────────────┤
│ 1           │ A host was found with more │
│             │ than one matching compute  │
│             │ node record                │
├─────────────┼────────────────────────────┤
│ 2           │ An unexpected error        │
│             │ occurred while working     │
│             │ with the placement API     │
├─────────────┼────────────────────────────┤
│ 3           │ Failed updating provider   │
│             │ aggregates in placement    │
├─────────────┼────────────────────────────┤
│ 4           │ Host mappings not found    │
│             │ for one or more host       │
│             │ aggregate members          │
├─────────────┼────────────────────────────┤
│ 5           │ Compute node records not   │
│             │ found for one or more      │
│             │ hosts                      │
├─────────────┼────────────────────────────┤
│ 6           │ Resource provider not      │
│             │ found by uuid for a given  │
│             │ host                       │
├─────────────┼────────────────────────────┤
│ 255         │ An unexpected error        │
│             │ occurred.                  │
└─────────────┴────────────────────────────┘

placement audit

and NOW we get to the detective of the family 🔍 the audit. Here's how you call her:

nova-manage placement audit [--verbose] [--delete]
  [--resource_provider <uuid>]

The way this works: she iterates over all the Resource Providers — or just one, if you're feeling specific and you hand her the UUID — and then she verifies whether the compute allocations are either related to an existing instance or a migration UUID. If they're not related to either? She will straight up tell you which allocations are orphaned. Exposed. Called out. No cap. 💀

This command requires that the api_database.connection and placement configuration options are set. Also, Placement API >= 1.14 is required — so check your version before you come crying to her. 😭

Added in version 21.0.0: (Ussuri) 🌈

Options

  • --verbose — Provide verbose output during execution.
  • --resource_provider <provider_uuid> — UUID of a specific resource provider to verify.
  • --delete — Deletes orphaned allocations that were found.

Return codes

┌─────────────┬───────────────────────────┐
│ Return code │ Description               │
├─────────────┼───────────────────────────┤
│ 0           │ No orphaned allocations   │
│             │ were found                │
├─────────────┼───────────────────────────┤
│ 1           │ An unexpected error       │
│             │ occurred                  │
├─────────────┼───────────────────────────┤
│ 3           │ Orphaned allocations were │
│             │ found                     │
├─────────────┼───────────────────────────┤
│ 4           │ All found orphaned        │
│             │ allocations were deleted  │
├─────────────┼───────────────────────────┤
│ 127         │ Invalid input             │
└─────────────┴───────────────────────────┘

💾 volume_attachment get_connector 💾

nova-manage volume_attachment get_connector

okay so this one is literally just showing you the host connector for this compute host 👑 define the vibe of your connection, bestie.

and when you hit it with the --json switch? it dumps a JSON string with all the connector info for the current host 🌸 save that bad boy to a file and you can feed it straight into the nova-manage volume_attachment refresh command later. it's giving "i prepared ahead of time and that's why i'm the moment" ✨

Added in version 24.0.0: (Xena) 🦋

Return codes 💅

  • 0 — Success 🎀
  • 1 — An unexpected error occurred 😭

🔍 volume_attachment show 🔍

nova-manage volume_attachment show [INSTANCE_UUID] [VOLUME_ID]

this spills ALL the tea on the volume attachment between VOLUME_ID and INSTANCE_UUID 💖 like, are they actually attached or is it complicated? this tells you fr fr.

Added in version 24.0.0: (Xena) 🦋

Return codes 💅

  • 0 — Success 🎀
  • 1 — An unexpected error occurred 😭
  • 2 — Instance not found 🙈
  • 3 — Instance is not attached to volume 💀

🔄 volume_attachment refresh 🔄

nova-manage volume_attachment refresh [INSTANCE_UUID] [VOLUME_ID] [CONNECTOR_PATH]

refreshes the connection info tied to a given volume attachment 🌈 glow-up for your connection data.

now listen bestie, because the vibes gotta be right for this to work: the instance must be attached to the volume, must have a vm_state of stopped, and must not be locked 🔒 no exceptions, no cap.

CONNECTOR_PATH is the path to a JSON-formatted file holding the up-to-date connector info for the compute that's currently hosting the instance 🫶 and you generate that file with the nova-manage volume_attachment get_connector command. it's a whole little pipeline and honestly? iconic.

Added in version 24.0.0: (Xena) 🦋

Return codes 💅

  • 0 — Success 🎀
  • 1 — An unexpected error occurred 😭
  • 2 — Connector path does not exist 🕳️
  • 3 — Failed to open connector path 🙈
  • 4 — Instance does not exist 💀
  • 5 — Instance state invalid (must be stopped and unlocked) 🔒
  • 6 — Volume is not attached to the instance 😬
  • 7 — Connector host is not correct 🚫

✨ LIBVIRT COMMANDS ✨

okay bestie, this is the libvirt corner of nova-manage, and it's giving "I need to know what machine type my instances are living in" energy 💅

🖥️ libvirt get_machine_type

nova-manage libvirt get_machine_type [INSTANCE_UUID]

So like… this one fetches and shows you the recorded machine type of a libvirt instance, and you point at which instance you mean with INSTANCE_UUID. That's it. That's the whole job. ✨

Added in version 23.0.0: (Wallaby)

🎀 Return codes

  • 0 — Successfully completed 🫶
  • 1 — An unexpected error occurred 😭
  • 2 — Unable to find instance or instance mapping 💀
  • 3 — No machine type found for instance 🙈

🔧 libvirt update_machine_type

nova-manage libvirt update_machine_type \
    [INSTANCE_UUID] [MACHINE_TYPE] [--force]

This one sets or updates the recorded machine type of instance INSTANCE_UUID to the machine type MACHINE_TYPE. Glow-up for your instance's machine type, fr fr ✨

But bestie, there are criteria that have to be met when you use this command, no cap:

  • The instance must have a vm_state of STOPPED, SHELVED or SHELVED_OFFLOADED. 😴
  • The machine type must be supported. The supported list includes alias and versioned types of pc, pc-i440fx, pc-q35, q35, virt or s390-ccw-virtio. 👑
  • The update will not move the instance between underlying machine types. For example, pc to q35. 🚫
  • The update will not move the instance between an alias and versioned machine type or vice versa. For example, pc to pc-1.2.3 or pc-1.2.3 to pc. 🚫

There's a --force flag provided to skip all of those checks above, but caution should be taken because this could easily lead to the underlying ABI of the instance changing when moving between machine types. Like, that's not a cute little oopsie, that's a real ABI-changing situation 💀

Added in version 23.0.0: (Wallaby)

✨ Options

  • --force — Skip machine type compatibility checks and force machine type update. (use responsibly bestie 🫶)

🎀 Return codes

  • 0 — Update completed successfully 🎉
  • 1 — An unexpected error occurred 😭
  • 2 — Unable to find instance or instance mapping 💀
  • 3 — The instance has an invalid vm_state 🙈
  • 4 — The proposed update of the machine type is invalid 🚫
  • 5 — The provided machine type is unsupported 🧚

📋 libvirt list_unset_machine_type

nova-manage libvirt list_unset_machine_type [--cell-uuid <cell-uuid>]

Lists the UUID of any instance that doesn't have hw_machine_type set. Basically "who here is missing their machine type, raise your hand" 🙋

This command is useful for operators trying to figure out when it's safe to change the libvirt.hw_machine_type <#libvirt.hw_machine_type> option within an environment. iykyk 🫶

Added in version 23.0.0: (Wallaby)

✨ Options

  • --cell_uuid <cell_uuid> — The UUID of the cell to list instances from.

🎀 Return codes

  • 0 — Completed successfully, no instances found without hw_machine_type set ✨
  • 1 — An unexpected error occurred 😭
  • 2 — Unable to find cell mapping 💀
  • 3 — Instances found without hw_machine_type set 👀

🌸 IMAGE PROPERTY COMMANDS 🌸

💖 image_property show 💖

nova-manage image_property show [INSTANCE_UUID] [IMAGE_PROPERTY]

Bestie, this one goes and fetches the recorded image property IMAGE_PROPERTY of whatever instance INSTANCE_UUID points at, then displays it for you. Show and tell, literally. ✨

Added in version 25.0.0: (Yoga)

🎀 Return codes 🎀

  • 0 — Successfully completed 💅
  • 1 — An unexpected error occurred 😭
  • 2 — Unable to find instance or instance mapping 🙈
  • 3 — No image property found for instance 💀

🦋 image_property set 🦋

nova-manage image_property set \
    [INSTANCE_UUID] [--property] [IMAGE_PROPERTY]=[VALUE]

This sets (or updates, if it's already there) the recorded image property IMAGE_PROPERTY on the instance INSTANCE_UUID, and gives it the value VALUE. Glow up for image props, no cap. ✨

You have to meet these criteria when you use this command:

  • The instance must have a vm_state of STOPPED, SHELVED or SHELVED_OFFLOADED.

This command is lowkey iconic for operators who need to update stored instance image properties that have become invalidated by a change of instance machine type, for example. 👑

Added in version 25.0.0: (Yoga)

⭐ Options ⭐

  • --property — The image property to set, using the format name=value. For example: --property hw_disk_bus=virtio --property hw_cdrom_bus=sata.

🎀 Return codes 🎀

  • 0 — Update completed successfully 💅
  • 1 — An unexpected error occurred 😭
  • 2 — Unable to find instance or instance mapping 🙈
  • 3 — The instance has an invalid vm_state 💀
  • 4 — The provided image property name is invalid 🚫
  • 5 — The provided image property value is invalid 🚫

🌈 LIMITS COMMANDS 🌈

👑 limits migrate_to_unified_limits 👑

nova-manage limits migrate_to_unified_limits [--project-id <project-id>]
[--region-id <region-id>] [--verbose] [--dry-run] [--quiet]
[--no-embedded-flavor-scan]

Okay so this is the big one: it migrates quota limits from the Nova database to unified limits in Keystone. Moving day, but for quotas. 🚚✨

This command is useful for operators migrating from legacy quotas to unified limits. The limits get migrated by copying them out of the Nova database and into Keystone, by creating them using the Keystone API.

The Nova configuration file that nova-manage is using must have a keystone_authtoken section that contains authentication settings, otherwise the Keystone API calls will not succeed. Here's an example, bestie:

[keystone_authtoken]
project_domain_name = Default
project_name = service
user_domain_name = Default
username = nova
auth_url = http://127.0.0.1/identity
auth_type = password
password = <password>

By default, in Keystone policy configuration, access to create, update, and delete in the unified limits API is restricted to callers with the admin role. So you're gonna need to make sure that the user configured under keystone_authtoken has the necessary role and scope. No role, no limits, periodt. 💅

Warning: ⚠️ The limits migrate_to_unified_limits command will create limits only for resources that exist in the legacy quota system, and any resource that does not have a unified limit in Keystone will use a quota limit of 0. 😭 For resource classes that are allocated by the placement service and have no default limit set, you will need to create default limits manually. The most common example is class:DISK_GB. All Nova API requests that need to allocate DISK_GB will fail quota enforcement until a default limit for it is set in Keystone. 💀 See the unified limits documentation about creating limits using the OpenStackClient.
Added in version 28.0.0: (2023.2 Bobcat)
Changed in version 31.0.0: (2025.1 Epoxy)

Added flavor scanning for resource classes missing limits, along with the --quiet and --no-embedded-flavor-scan options. 🔥

⭐ Options ⭐

  • --project-id <project-id> — The project ID for which to migrate quota limits.
  • --region-id <region-id> — The region ID for which to migrate quota limits.
  • --verbose — Provide verbose output during execution.
  • --dry-run — Show what limits would be created without actually creating them. Flavors will still be scanned for resource classes missing limits.
  • --quiet — Do not output anything during execution. 🤫
  • --no-embedded-flavor-scan — Do not scan instances embedded flavors for resource classes missing limits.

🎀 Return codes 🎀

  • 0 — Command completed successfully 💅
  • 1 — An unexpected error occurred 😭
  • 2 — Failed to connect to the database 🙈
  • 3 — Missing registered limits were identified 🚫

🫶 SEE ALSO 🫶

  • nova-policy(1)
  • nova-status(1)

🐛 BUGS 🐛

💜 Author 💜

openstack@lists.openstack.org

2010-present, OpenStack Foundation

aaaand that's a wrap on the whole entire page, bestie!! 🎉✨ you made it to the end, which is giving main character energy fr fr. this one's from 34.0.0, dated Oct 01, 2026, and it's NOVA-MANAGE(1) — go forth and manage your nova like the icon you are. 💅👑🦋

📦 where this page comes from