From 59e2b38c80ff223ffe14f8053505af15c8393b37 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 7 May 2020 15:08:39 +0100 Subject: [PATCH] docs: Use proper headers in nova-manage man page This is step one in improving the usability of these docs. The current style makes it impossible to link to individual commands from the built docs. There is a better way. Use headers along with code blocks to show the actual command. This was mostly generated from a find-replace along with some follow-up manual fixes. Change-Id: Icd25006f31c8e34fe33d79779e0577dc78f96a24 Signed-off-by: Stephen Finucane --- doc/source/cli/nova-manage.rst | 1275 +++++++++++++++++++------------- 1 file changed, 745 insertions(+), 530 deletions(-) diff --git a/doc/source/cli/nova-manage.rst b/doc/source/cli/nova-manage.rst index 2cc8d765e92f..a9df805ddbcd 100644 --- a/doc/source/cli/nova-manage.rst +++ b/doc/source/cli/nova-manage.rst @@ -11,6 +11,7 @@ Synopsis nova-manage [ [...]] + Description =========== @@ -30,8 +31,6 @@ commands in that category:: nova-manage db -These sections describe the available categories and arguments for -:program:`nova-manage`. Options ======= @@ -152,658 +151,874 @@ without an argument can be combined after a single dash. specified and Linux platform is used. This option is ignored if :option:`--log-config-append` is set. -Commands -======== -Nova Database -~~~~~~~~~~~~~ +Database Commands +================= -``nova-manage db version`` - Print the current main database version. +db version +---------- -``nova-manage db sync [--local_cell] [VERSION]`` - Upgrade the main database schema up to the most recent version or - ``VERSION`` if specified. By default, this command will also attempt to - upgrade the schema for the cell0 database if it is mapped (see the - ``map_cell0`` or ``simple_cell_setup`` commands for more details on mapping - the cell0 database). If ``--local_cell`` is specified, then only the main - database in the current cell is upgraded. The local database connection is - determined by :oslo.config:option:`database.connection` in the - configuration file, passed to nova-manage using the ``--config-file`` - option(s). This command should be run after ``nova-manage api_db sync``. +.. program:: nova-manage db version - Returns exit code 0 if the database schema was synced successfully, or 1 if - cell0 cannot be accessed. +.. code-block:: shell -``nova-manage db archive_deleted_rows [--max_rows ] [--verbose] [--until-complete] [--before ] [--purge] [--all-cells]`` - 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, - :oslo.config:option:`api_database.connection` is required in the config - file. Specifying ``--verbose`` will print the results of the archive - operation for any tables that were changed. Specifying ``--until-complete`` - will make the command run continuously until all deleted rows are archived. - Use the ``--max_rows`` option, which defaults to 1000, as a batch size for - each iteration (note that the purged API database table records are not - included in this batch size). Specifying ``--before`` will archive only - instances that were deleted before the date provided, and records in other - tables related to those instances. Specifying ``--purge`` will cause a - *full* DB purge to be completed after archival. If a date range is desired - for the purge, then run ``nova-manage db purge --before `` manually - after archiving is complete. Specifying ``--all-cells`` will - cause the process to run against all cell databases. + nova-manage db version - .. note:: +Print the current main database version. - The date argument accepted by the ``--before`` option can be in any - of several formats, including ``YYYY-MM-DD [HH:mm[:ss]]`` and the default - format produced by the ``date`` command, e.g. ``Fri May 24 09:20:11 CDT 2019``. - Date strings containing spaces must be quoted appropriately. Some examples:: +db sync +------- - # Purge shadow table rows older than a specific 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" +.. program:: nova-manage db sync - Relative dates (such as ``yesterday``) are not supported natively. - The ``date`` command can be helpful here:: +.. code-block:: shell - # Archive deleted rows more than one month old - nova-manage db archive_deleted_rows --before "$(date -d 'now - 1 month')" + nova-manage db sync [--local_cell] [VERSION] - **Return Codes** +Upgrade the main database schema up to the most recent version or +``VERSION`` if specified. By default, this command will also attempt to +upgrade the schema for the cell0 database if it is mapped (see the +``map_cell0`` or ``simple_cell_setup`` commands for more details on mapping +the cell0 database). If ``--local_cell`` is specified, then only the main +database in the current cell is upgraded. The local database connection is +determined by :oslo.config:option:`database.connection` in the +configuration file, passed to nova-manage using the ``--config-file`` +option(s). This command should be run after ``nova-manage api_db sync``. - .. list-table:: - :widths: 20 80 - :header-rows: 1 +Returns exit code 0 if the database schema was synced successfully, or 1 if +cell0 cannot be accessed. - * - Return code - - Description - * - 0 - - Nothing was archived. - * - 1 - - Some number of rows were archived. - * - 2 - - Invalid value for ``--max_rows``. - * - 3 - - No connection to the API database could be established using - :oslo.config:option:`api_database.connection`. - * - 4 - - Invalid value for ``--before``. - * - 255 - - An unexpected error occurred. +db archive_deleted_rows +----------------------- - If automating, this should be run continuously while the result is 1, - stopping at 0, or use the ``--until-complete`` option. +.. program:: nova-manage db archive_deleted_rows -``nova-manage db purge [--all] [--before ] [--verbose] [--all-cells]`` - Delete rows from shadow tables. Specifying ``--all`` will delete all data from - all shadow tables. Specifying ``--before`` will delete data from all shadow tables - that is older than the date provided. Specifying ``--verbose`` will - cause information to be printed about purged records. Specifying - ``--all-cells`` will cause the purge to be applied against all cell databases. - For ``--all-cells`` to work, the api database connection information must - be configured. Returns exit code 0 if rows were deleted, 1 if required - arguments are not provided, 2 if an invalid date is provided, 3 if no - data was deleted, 4 if the list of cells cannot be obtained. +.. code-block:: shell - .. note:: + nova-manage db archive_deleted_rows [--max_rows ] [--verbose] + [--until-complete] [--before ] [--purge] [--all-cells] - The date argument accepted by the ``--before`` option can be in any - of several formats, including ``YYYY-MM-DD [HH:mm[:ss]]`` and the default - format produced by the ``date`` command, e.g. ``Fri May 24 09:20:11 CDT 2019``. - Date strings containing spaces must be quoted appropriately. Some examples:: +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, +:oslo.config:option:`api_database.connection` is required in the config +file. Specifying ``--verbose`` will print the results of the archive +operation for any tables that were changed. Specifying ``--until-complete`` +will make the command run continuously until all deleted rows are archived. +Use the ``--max_rows`` option, which defaults to 1000, as a batch size for +each iteration (note that the purged API database table records are not +included in this batch size). Specifying ``--before`` will archive only +instances that were deleted before the date provided, and records in other +tables related to those instances. Specifying ``--purge`` will cause a +*full* DB purge to be completed after archival. If a date range is desired +for the purge, then run ``nova-manage db purge --before `` manually +after archiving is complete. Specifying ``--all-cells`` will +cause the process to run against all cell databases. - # Purge shadow table rows older than a specific 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" +.. note:: - Relative dates (such as ``yesterday``) are not supported natively. - The ``date`` command can be helpful here:: + The date argument accepted by the ``--before`` option can be in any + of several formats, including ``YYYY-MM-DD [HH:mm[:ss]]`` and the default + format produced by the ``date`` command, e.g. ``Fri May 24 09:20:11 CDT 2019``. + Date strings containing spaces must be quoted appropriately. Some examples:: - # Archive deleted rows more than one month old - nova-manage db archive_deleted_rows --before "$(date -d 'now - 1 month')" + # Archive deleted row 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" -``nova-manage db online_data_migrations [--max-count]`` - Perform data migration to update all live data. + Relative dates (such as ``yesterday``) are not supported natively. + The ``date`` command can be helpful here:: - ``--max-count`` controls the maximum number of objects to migrate in a given - call. If not specified, migration will occur in batches of 50 until fully - complete. + # Archive deleted rows more than one month old + nova-manage db archive_deleted_rows --before "$(date -d 'now - 1 month')" - Returns exit code 0 if no (further) updates are possible, 1 if the ``--max-count`` - option was used and some updates were completed successfully (even if others generated - errors), 2 if some updates generated errors and no other migrations were able to take - effect in the last batch attempted, or 127 if invalid input is provided (e.g. - non-numeric max-count). +**Return Codes** - This command should be called after upgrading database schema and nova services on - all controller nodes. If it exits with partial updates (exit status 1) it should - be called again, even if some updates initially generated errors, because some updates - may depend on others having completed. If it exits with status 2, intervention is - required to resolve the issue causing remaining updates to fail. It should be - considered successfully completed only when the exit status is 0. +.. list-table:: + :widths: 20 80 + :header-rows: 1 - For example:: + * - Return code + - Description + * - 0 + - Nothing was archived. + * - 1 + - Some number of rows were archived. + * - 2 + - Invalid value for ``--max_rows``. + * - 3 + - No connection to the API database could be established using + :oslo.config:option:`api_database.connection`. + * - 4 + - Invalid value for ``--before``. + * - 255 + - An unexpected error occurred. - $ 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 | - +---------------------------------------------+--------------+-----------+ +If automating, this should be run continuously while the result is 1, +stopping at 0, or use the ``--until-complete`` option. - In the above example, 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. In the case of 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. +db purge +-------- -Nova API Database -~~~~~~~~~~~~~~~~~ +.. program:: nova-manage db purge -``nova-manage api_db version`` - Print the current API database version. +.. code-block:: shell -``nova-manage api_db sync [VERSION]`` - Upgrade the API database schema up to the most recent version or - ``VERSION`` if specified. This command does not create the API - database, it runs schema migration scripts. The API database connection is - determined by :oslo.config:option:`api_database.connection` in the - configuration file passed to nova-manage. + nova-manage db purge [--all] [--before ] [--verbose] [--all-cells] - In the 18.0.0 Rocky or 19.0.0 Stein release, this command will also upgrade - the optional placement database if ``[placement_database]/connection`` is - configured. +Delete rows from shadow tables. Specifying ``--all`` will delete all data from +all shadow tables. Specifying ``--before`` will delete data from all shadow tables +that is older than the date provided. Specifying ``--verbose`` will +cause information to be printed about purged records. Specifying +``--all-cells`` will cause the purge to be applied against all cell databases. +For ``--all-cells`` to work, the api database connection information must +be configured. Returns exit code 0 if rows were deleted, 1 if required +arguments are not provided, 2 if an invalid date is provided, 3 if no +data was deleted, 4 if the list of cells cannot be obtained. + +.. note:: + + The date argument accepted by the ``--before`` option can be in any + of several formats, including ``YYYY-MM-DD [HH:mm[:ss]]`` and the default + format produced by the ``date`` command, e.g. ``Fri May 24 09:20:11 CDT 2019``. + Date strings containing spaces must be quoted appropriately. Some examples:: + + # Purge shadow table rows older than a specific 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" + + 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 purge --before "$(date -d 'now - 1 month')" + +db online_data_migrations +------------------------- + +.. program:: nova-manage db online_data_migrations + +.. code-block:: shell + + nova-manage db online_data_migrations [--max-count] + +Perform data migration to update all live data. + +``--max-count`` controls the maximum number of objects to migrate in a given +call. If not specified, migration will occur in batches of 50 until fully +complete. + +Returns exit code 0 if no (further) updates are possible, 1 if the ``--max-count`` +option was used and some updates were completed successfully (even if others generated +errors), 2 if some updates generated errors and no other migrations were able to take +effect in the last batch attempted, or 127 if invalid input is provided (e.g. +non-numeric max-count). + +This command should be called after upgrading database schema and nova services on +all controller nodes. If it exits with partial updates (exit status 1) it should +be called again, even if some updates initially generated errors, because some updates +may depend on others having completed. If it exits with status 2, intervention is +required to resolve the issue causing remaining updates to fail. It should be +considered successfully completed only when the exit status is 0. + +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 | + +---------------------------------------------+--------------+-----------+ + +In the above example, 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. In the case of 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. + + +API Database Commands +===================== + +api_db version +-------------- + +.. program:: nova-manage api_db version + +.. code-block:: shell + + nova-manage api_db version + +Print the current API database version. + +api_db sync +----------- + +.. program:: nova-manage api_db sync + +.. code-block:: shell + + nova-manage api_db sync [VERSION] + +Upgrade the API database schema up to the most recent version or +``VERSION`` if specified. This command does not create the API +database, it runs schema migration scripts. The API database connection is +determined by :oslo.config:option:`api_database.connection` in the +configuration file passed to nova-manage. + +In the 18.0.0 Rocky or 19.0.0 Stein release, this command will also upgrade +the optional placement database if ``[placement_database]/connection`` is +configured. + +Returns exit code 0 if the database schema was synced successfully. This +command should be run before ``nova-manage db sync``. - Returns exit code 0 if the database schema was synced successfully. This - command should be run before ``nova-manage db sync``. .. _man-page-cells-v2: -Nova Cells v2 -~~~~~~~~~~~~~ +Cells v2 Commands +================= -``nova-manage cell_v2 simple_cell_setup [--transport-url ]`` - Setup a fresh cells v2 environment. If a ``transport_url`` is not - specified, it will use the one defined by :oslo.config:option:`transport_url` - in the configuration file. Returns 0 if setup is completed - (or has already been done), 1 if no hosts are reporting (and cannot be - mapped) and 1 if the transport url is missing or invalid. +cell_v2 simple_cell_setup +------------------------- -``nova-manage cell_v2 map_cell0 [--database_connection ]`` - Create 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 - :oslo.config:option:`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. Returns 0 if cell0 is - created successfully or already setup. +.. program:: nova-manage cell_v2 simple_cell_setup -``nova-manage cell_v2 map_instances --cell_uuid [--max-count ] [--reset]`` - Map 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. +.. code-block:: shell - 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. + nova-manage cell_v2 simple_cell_setup [--transport-url ] - **Return Codes** +Setup a fresh cells v2 environment. If a ``transport_url`` is not +specified, it will use the one defined by :oslo.config:option:`transport_url` +in the configuration file. Returns 0 if setup is completed +(or has already been done), 1 if no hosts are reporting (and cannot be +mapped) and 1 if the transport url is missing or invalid. - .. list-table:: - :widths: 20 80 - :header-rows: 1 +cell_v2 map_cell0 +----------------- - * - Return code - - Description - * - 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. +.. program:: nova-manage cell_v2 map_cell0 -``nova-manage cell_v2 map_cell_and_hosts [--name ] [--transport-url ] [--verbose]`` - Create a cell mapping to the database connection and message queue - transport url, and map hosts to that cell. The database connection - comes from the :oslo.config:option:`database.connection` defined in the - configuration file passed to nova-manage. If a transport_url is not - specified, it will use the one defined by - :oslo.config:option:`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. Returns 0 on successful - completion, and 1 if the transport url is missing or invalid. +.. code-block:: shell -``nova-manage cell_v2 verify_instance --uuid [--quiet]`` - Verify 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. Returns 0 when the - instance is successfully mapped to a cell, 1 if the instance is not - mapped to a cell (see the ``map_instances`` command), 2 if the cell - mapping is missing (see the ``map_cell_and_hosts`` command if you are - upgrading from a cells v1 environment, and the ``simple_cell_setup`` if - you are upgrading from a non-cells v1 environment), 3 if it is a deleted - instance which has instance mapping, and 4 if it is an archived instance - which still has an instance mapping. + nova-manage cell_v2 map_cell0 [--database_connection ] -``nova-manage cell_v2 create_cell [--name ] [--transport-url ] [--database_connection ] [--verbose] [--disabled]`` - Create a cell mapping to the database connection and message queue - transport url. If a database_connection is not specified, it will use the - one defined by :oslo.config:option:`database.connection` in the - configuration file passed to nova-manage. If a transport_url is not - specified, it will use the one defined by - :oslo.config:option:`transport_url` in the configuration file. The verbose - option will print out the resulting cell mapping uuid. All the cells - created are by default enabled. However passing the ``--disabled`` option - can create a pre-disabled cell, meaning no scheduling will happen to this - cell. The meaning of the various exit codes returned by this command are - explained below: +Create 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 +:oslo.config:option:`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. Returns 0 if cell0 is +created successfully or already setup. - * Returns 0 if the cell mapping was successfully created. - * Returns 1 if the transport url or database connection was missing - or invalid. - * Returns 2 if another cell is already using that transport url and/or - database connection combination. +cell_v2 map_instances +--------------------- -``nova-manage cell_v2 discover_hosts [--cell_uuid ] [--verbose] [--strict] [--by-service]`` - Searches cells, or a single cell, and maps found hosts. This command will - check the database for each cell (or a single one if passed in) and map any - hosts which are not currently mapped. If a host is already mapped, nothing - will be done. You need to re-run this command each time you add a batch of - compute hosts to a cell (otherwise the scheduler will never place instances - there and the API will not list the new hosts). 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 ensure 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). +.. program:: nova-manage cell_v2 map_instances - 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. +.. code-block:: shell - The meaning of the various exit codes returned by this command are - explained below: + nova-manage cell_v2 map_instances --cell_uuid + [--max-count ] [--reset] - * Returns 0 if 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. - * Returns 1 if ``--strict`` is specified and no unmapped hosts were found. - Also returns 1 if an exception was raised while running. - * Returns 2 if the command aborted because of a duplicate host mapping - found. This means the command collided with another running - discover_hosts command or scheduler periodic task and is safe to retry. +Map 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. -``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 - transport URL and database connection with their sensitive details. +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. -``nova-manage cell_v2 delete_cell [--force] --cell_uuid `` - Delete a cell by the given uuid. Returns 0 if the empty cell is found and - deleted successfully or the cell that has hosts is found and the cell, hosts - and the instance_mappings are deleted successfully with ``--force`` option - (this happens if there are no living instances), 1 if a cell with that uuid - could not be found, 2 if host mappings were found for the cell (cell not empty) - without ``--force`` option, 3 if there are instances mapped to the cell - (cell not empty) irrespective of the ``--force`` option, and 4 if there are - instance mappings to the cell but all instances have been deleted in the cell, - again without the ``--force`` option. +**Return Codes** -``nova-manage cell_v2 list_hosts [--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. - If the cell is not found by uuid, this command will return an exit code - of 1. Otherwise, the exit code will be 0. +.. list-table:: + :widths: 20 80 + :header-rows: 1 -``nova-manage cell_v2 update_cell --cell_uuid [--name ] [--transport-url ] [--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 :oslo.config:option:`database.connection` in the configuration - file. If a transport_url is not specified, it will attempt to use the one - defined by :oslo.config:option:`transport_url` in the configuration file. - The meaning of the various exit codes returned by this command are - explained below: + * - Return code + - Description + * - 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. - * If successful, it will return 0. - * If the cell is not found by the provided uuid, it will return 1. - * If the properties cannot be set, it will return 2. - * If the provided transport_url or/and database_connection is/are same as - another cell, it will return 3. - * If an attempt is made to disable and enable a cell at the same time, it - will return 4. - * If an attempt is made to disable or enable cell0 it will return 5. +cell_v2 map_cell_and_hosts +-------------------------- - .. note:: +.. program:: nova-manage cell_v2 map_cell_and_hosts - 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. +.. code-block:: shell - The scheduler will not notice that a cell has been enabled/disabled until - it is restarted or sent the SIGHUP signal. + nova-manage cell_v2 map_cell_and_hosts [--name ] + [--transport-url ] [--verbose] -``nova-manage cell_v2 delete_host --cell_uuid --host `` - Delete a host by the given host name and the given cell uuid. Returns 0 - if the empty host is found and deleted successfully, 1 if a cell with - that uuid could not be found, 2 if a host with that name could not be - found, 3 if a host with that name is not in a cell with that uuid, 4 if - a host with that name has instances (host not empty). +Create a cell mapping to the database connection and message queue +transport url, and map hosts to that cell. The database connection +comes from the :oslo.config:option:`database.connection` defined in the +configuration file passed to nova-manage. If a transport_url is not +specified, it will use the one defined by +:oslo.config:option:`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. Returns 0 on successful +completion, and 1 if the transport url is missing or invalid. - .. note:: +cell_v2 verify_instance +----------------------- - 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. +.. program:: nova-manage cell_v2 verify_instance -Placement -~~~~~~~~~ +.. code-block:: shell + + nova-manage cell_v2 verify_instance --uuid [--quiet] + +Verify 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. Returns 0 when the +instance is successfully mapped to a cell, 1 if the instance is not +mapped to a cell (see the ``map_instances`` command), 2 if the cell +mapping is missing (see the ``map_cell_and_hosts`` command if you are +upgrading from a cells v1 environment, and the ``simple_cell_setup`` if +you are upgrading from a non-cells v1 environment), 3 if it is a deleted +instance which has instance mapping, and 4 if it is an archived instance +which still has an instance mapping. + +cell_v2 create_cell +------------------- + +.. program:: nova-manage cell_v2 create_cell + +.. code-block:: shell + + nova-manage cell_v2 create_cell [--name ] + [--transport-url ] + [--database_connection ] [--verbose] [--disabled] + +Create a cell mapping to the database connection and message queue +transport url. If a database_connection is not specified, it will use the +one defined by :oslo.config:option:`database.connection` in the +configuration file passed to nova-manage. If a transport_url is not +specified, it will use the one defined by +:oslo.config:option:`transport_url` in the configuration file. The verbose +option will print out the resulting cell mapping uuid. All the cells +created are by default enabled. However passing the ``--disabled`` option +can create a pre-disabled cell, meaning no scheduling will happen to this +cell. The meaning of the various exit codes returned by this command are +explained below: + +* Returns 0 if the cell mapping was successfully created. +* Returns 1 if the transport url or database connection was missing + or invalid. +* Returns 2 if another cell is already using that transport url and/or + database connection combination. + +cell_v2 discover_hosts +---------------------- + +.. program:: nova-manage cell_v2 discover_hosts + +.. code-block:: shell + + nova-manage cell_v2 discover_hosts [--cell_uuid ] [--verbose] + [--strict] [--by-service] + +Searches cells, or a single cell, and maps found hosts. This command will +check the database for each cell (or a single one if passed in) and map any +hosts which are not currently mapped. If a host is already mapped, nothing +will be done. You need to re-run this command each time you add a batch of +compute hosts to a cell (otherwise the scheduler will never place instances +there and the API will not list the new hosts). 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 ensure 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. + +The meaning of the various exit codes returned by this command are +explained below: + +* Returns 0 if 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. +* Returns 1 if ``--strict`` is specified and no unmapped hosts were found. + Also returns 1 if an exception was raised while running. +* Returns 2 if the command aborted because of a duplicate host mapping + found. This means the command collided with another running + discover_hosts command or scheduler periodic task and is safe to retry. + +cell_v2 list_cells +------------------ + +.. program:: nova-manage cell_v2 list_cells + +.. code-block:: shell + + 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 +transport URL and database connection with their sensitive details. + +cell_v2 delete_cell +------------------- + +.. program:: nova-manage cell_v2 delete_cell + +.. code-block:: shell + + nova-manage cell_v2 delete_cell [--force] --cell_uuid + +Delete a cell by the given uuid. Returns 0 if the empty cell is found and +deleted successfully or the cell that has hosts is found and the cell, hosts +and the instance_mappings are deleted successfully with ``--force`` option +(this happens if there are no living instances), 1 if a cell with that uuid +could not be found, 2 if host mappings were found for the cell (cell not empty) +without ``--force`` option, 3 if there are instances mapped to the cell +(cell not empty) irrespective of the ``--force`` option, and 4 if there are +instance mappings to the cell but all instances have been deleted in the cell, +again without the ``--force`` option. + +cell_v2 list_hosts +------------------ + +.. program:: nova-manage cell_v2 list_hosts + +.. code-block:: shell + + nova-manage cell_v2 list_hosts [--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. +If the cell is not found by uuid, this command will return an exit code +of 1. Otherwise, the exit code will be 0. + +cell_v2 update_cell +------------------- + +.. program:: nova-manage cell_v2 update_cell + +.. code-block:: shell + + nova-manage cell_v2 update_cell --cell_uuid + [--name ] [--transport-url ] + [--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 :oslo.config:option:`database.connection` in the configuration +file. If a transport_url is not specified, it will attempt to use the one +defined by :oslo.config:option:`transport_url` in the configuration file. +The meaning of the various exit codes returned by this command are +explained below: + +* If successful, it will return 0. +* If the cell is not found by the provided uuid, it will return 1. +* If the properties cannot be set, it will return 2. +* If the provided transport_url or/and database_connection is/are same as + another cell, it will return 3. +* If an attempt is made to disable and enable a cell at the same time, it + will return 4. +* If an attempt is made to disable or enable cell0 it will return 5. + +.. note:: + + 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. + +cell_v2 delete_host +------------------- + +.. program:: nova-manage cell_v2 delete_host + +.. code-block:: shell + + nova-manage cell_v2 delete_host --cell_uuid --host + +Delete a host by the given host name and the given cell uuid. Returns 0 +if the empty host is found and deleted successfully, 1 if a cell with +that uuid could not be found, 2 if a host with that name could not be +found, 3 if a host with that name is not in a cell with that uuid, 4 if +a host with that name has instances (host not empty). + +.. note:: + + 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. + + +Placement Commands +================== .. _heal_allocations_cli: -``nova-manage placement heal_allocations [--max-count ] [--verbose] [--skip-port-allocations] [--dry-run] [--instance ] [--cell `) but the corresponding - allocation is not found then the allocation is created against the - network device resource providers according to the resource request of - that port. It is possible that the missing allocation cannot be created - either due to not having enough resource inventory on the host the instance - resides on or because more than one resource provider could fulfill the - request. In this case the instance needs to be manually deleted or the - port needs to be detached. When nova `supports migrating instances - with guaranteed bandwidth ports`_, migration will heal missing allocations - for these instances. +.. program:: nova-manage placement heal_allocations - Before the allocations for the ports are persisted in placement nova-manage - tries to update each port in neutron to refer to the resource provider UUID - which provides the requested resources. If any of the port updates fail in - neutron or the allocation update fails in placement the command tries to - roll back the partial updates to the ports. If the roll back fails - then the process stops with exit code ``7`` and the admin needs to do the - rollback in neutron manually according to the description in the exit code - section. +.. code-block:: shell - .. _supports migrating instances with guaranteed bandwidth ports: https://specs.openstack.org/openstack/nova-specs/specs/train/approved/support-move-ops-with-qos-ports.html + nova-manage placement heal_allocations [--max-count ] + [--verbose] [--skip-port-allocations] [--dry-run] + [--instance ] [--cell `) but the corresponding +allocation is not found then the allocation is created against the +network device resource providers according to the resource request of +that port. It is possible that the missing allocation cannot be created +either due to not having enough resource inventory on the host the instance +resides on or because more than one resource provider could fulfill the +request. In this case the instance needs to be manually deleted or the +port needs to be detached. When nova `supports migrating instances +with guaranteed bandwidth ports`_, migration will heal missing allocations +for these instances. - Specify ``--verbose`` to get detailed progress output during execution. +Before the allocations for the ports are persisted in placement nova-manage +tries to update each port in neutron to refer to the resource provider UUID +which provides the requested resources. If any of the port updates fail in +neutron or the allocation update fails in placement the command tries to +roll back the partial updates to the ports. If the roll back fails +then the process stops with exit code ``7`` and the admin needs to do the +rollback in neutron manually according to the description in the exit code +section. - Specify ``--dry-run`` to print output but not commit any changes. The - return code should be 4. *(Since 20.0.0 Train)* +.. _supports migrating instances with guaranteed bandwidth ports: https://specs.openstack.org/openstack/nova-specs/specs/train/approved/support-move-ops-with-qos-ports.html - Specify ``--instance`` to process a specific instance given its UUID. If - specified the ``--max-count`` option has no effect. - *(Since 20.0.0 Train)* +There is also a special case handled for instances that *do* have +allocations created before Placement API microversion 1.8 where project_id +and user_id values were required. For those types of allocations, the +project_id and user_id are updated using the values from the instance. - Specify ``--skip-port-allocations`` to 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 does - not use such a feature then the performance impact of querying neutron - ports for each instance can be avoided with this flag. - *(Since 20.0.0 Train)* +Specify ``--max-count`` to control the maximum number of instances to +process. If not specified, all instances in each 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 or 4. - Specify ``--cell`` to process heal allocations within a specific cell. - This is mutually exclusive with the ``--instance`` option. +Specify ``--verbose`` to get detailed progress output during execution. - Specify ``--force`` to forcefully heal single instance allocation. This - option needs to be passed with ``--instance``. +Specify ``--dry-run`` to print output but not commit any changes. The +return code should be 4. *(Since 20.0.0 Train)* - This command requires that the - :oslo.config:option:`api_database.connection` and - :oslo.config:group:`placement` configuration options are set. Placement API - >= 1.28 is required. +Specify ``--instance`` to process a specific instance given its UUID. If +specified the ``--max-count`` option has no effect. +*(Since 20.0.0 Train)* - **Return Codes** +Specify ``--skip-port-allocations`` to 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 does +not use such a feature then the performance impact of querying neutron +ports for each instance can be avoided with this flag. +*(Since 20.0.0 Train)* - .. list-table:: - :widths: 20 80 - :header-rows: 1 +Specify ``--cell`` to process heal allocations within a specific cell. +This is mutually exclusive with the ``--instance`` option. - * - Return code - - Description - * - 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:: +Specify ``--force`` to forcefully heal single instance allocation. This +option needs to be passed with ``--instance``. - $ openstack port unset --binding-profile allocation +This command requires that the +:oslo.config:option:`api_database.connection` and +:oslo.config:group:`placement` configuration options are set. Placement API +>= 1.28 is required. - * - 127 - - Invalid input. - * - 255 - - An unexpected error occurred. +**Return Codes** + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Return code + - Description + * - 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 --binding-profile allocation + + * - 127 + - Invalid input. + * - 255 + - An unexpected error occurred. .. _sync_aggregates_cli: -``nova-manage placement sync_aggregates [--verbose]`` - Mirrors compute host aggregates to resource provider aggregates - in the Placement service. Requires the :oslo.config:group:`api_database` - and :oslo.config:group:`placement` sections of the nova configuration file - to be populated. +placement sync_aggregates +------------------------- - Specify ``--verbose`` to get detailed progress output during execution. +.. program:: nova-manage placement sync_aggregates - .. 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. +.. code-block:: shell - .. versionadded:: Rocky + nova-manage placement sync_aggregates [--verbose] - **Return Codes** +Mirrors compute host aggregates to resource provider aggregates +in the Placement service. Requires the :oslo.config:group:`api_database` +and :oslo.config:group:`placement` sections of the nova configuration file +to be populated. - .. list-table:: - :widths: 20 80 - :header-rows: 1 +Specify ``--verbose`` to get detailed progress output during execution. - * - 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. +.. 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. -``nova-manage placement audit [--verbose] [--delete] [--resource_provider ]`` - Iterates over all the Resource Providers (or just one if you provide the - UUID) and then verifies if the compute allocations are either related to - an existing instance or a migration UUID. - If not, it will tell which allocations are orphaned. +.. versionadded:: Rocky - You can also ask to delete all the orphaned allocations by specifying - ``-delete``. +**Return Codes** - Specify ``--verbose`` to get detailed progress output during execution. +.. list-table:: + :widths: 20 80 + :header-rows: 1 - This command requires that the - :oslo.config:option:`api_database.connection` and - :oslo.config:group:`placement` configuration options are set. Placement API - >= 1.14 is required. + * - 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. - **Return Codes** +placement audit +--------------- - .. list-table:: - :widths: 20 80 - :header-rows: 1 +.. program:: nova-manage placement audit - * - 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 +.. code-block:: shell -libvirt -~~~~~~~ + nova-manage placement audit [--verbose] [--delete] + [--resource_provider ] -``nova-manage libvirt get_machine_type [instance-uuid]`` - Fetch and display the recorded machine type of a libvirt instance. +Iterates over all the Resource Providers (or just one if you provide the +UUID) and then verifies if the compute allocations are either related to +an existing instance or a migration UUID. +If not, it will tell which allocations are orphaned. - **Return Codes** +You can also ask to delete all the orphaned allocations by specifying +``-delete``. - .. list-table:: - :widths: 20 80 - :header-rows: 1 +Specify ``--verbose`` to get detailed progress output during execution. - * - Return code - - Description - * - 0 - - Successfully completed - * - 1 - - An unexpected error occurred - * - 2 - - Unable to find instance or instance mapping - * - 3 - - No machine type found for instance +This command requires that the +:oslo.config:option:`api_database.connection` and +:oslo.config:group:`placement` configuration options are set. Placement API +>= 1.14 is required. -``nova-manage libvirt update_machine_type [instance-uuid] [machine_type] [--force]`` - Set or update the recorded machine type of an instance. +**Return Codes** - The following criteria must also be met when using this command: +.. list-table:: + :widths: 20 80 + :header-rows: 1 - * The instance must have a ``vm_state`` of ``STOPPED``, ``SHELVED`` or - ``SHELVED_OFFLOADED``. + * - 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 - * The machine type is 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``. +Libvirt Commands +================ - * 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``. +libvirt get_machine_type +------------------------ - A ``--force`` flag is provided to skip the above checks but caution - should be taken as this could easily lead to the underlying ABI of the - instance changing when moving between machine types. +.. program:: nova-manage libvirt get_machine_type - **Return Codes** +.. code-block:: shell - .. list-table:: - :widths: 20 80 - :header-rows: 1 + nova-manage libvirt get_machine_type [INSTANCE_UUID] - * - Return code - - Description - * - 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 +Fetch and display the recorded machine type of a libvirt instance. -``nova-manage libvirt list_unset_machine_type [--cell-uuid]`` - List the UUID of any instance without ``hw_machine_type`` set. +**Return Codes** - This command is useful for operators attempting to determine when it is - safe to change the :oslo.config:option:`libvirt.hw_machine_type` option - within an environment. +.. list-table:: + :widths: 20 80 + :header-rows: 1 - **Return Codes** + * - Return code + - Description + * - 0 + - Successfully completed + * - 1 + - An unexpected error occurred + * - 2 + - Unable to find instance or instance mapping + * - 3 + - No machine type found for instance - .. list-table:: - :widths: 20 80 - :header-rows: 1 +libvirt update_machine_type +--------------------------- + +.. program:: nova-manage libvirt update_machine_type + +.. code-block:: shell + + nova-manage libvirt update_machine_type \ + [INSTANCE_UUID] [MACHINE_TYPE] [--force] + +Set or update the recorded machine type of an instance. + +The following criteria must also be met when using this command: + +* The instance must have a ``vm_state`` of ``STOPPED``, ``SHELVED`` or + ``SHELVED_OFFLOADED``. + +* The machine type is 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``. + +A ``--force`` flag is provided to skip the above checks but caution +should be taken as this could easily lead to the underlying ABI of the +instance changing when moving between machine types. + +**Return Codes** + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Return code + - Description + * - 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 +------------------------------- + +.. program:: nova-manage libvirt list_unset_machine_type + +.. code-block:: shell + + nova-manage libvirt list_unset_machine_type [--cell-uuid ] + +List the UUID of any instance without ``hw_machine_type`` set. + +This command is useful for operators attempting to determine when it is +safe to change the :oslo.config:option:`libvirt.hw_machine_type` option +within an environment. + +**Return Codes** + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Return code + - Description + * - 0 + - Completed successfully, no instances found without hw_machine_type + * - 1 + - An unexpected error occurred + * - 2 + - Unable to find cell mapping + * - 3 + - Instances found without hw_machine_type set - * - Return code - - Description - * - 0 - - Completed successfully, no instances found without hw_machine_type - * - 1 - - An unexpected error occurred - * - 2 - - Unable to find cell mapping - * - 3 - - Instances found without hw_machine_type set See Also ======== * :nova-doc:`OpenStack Nova <>` + Bugs ====