4d0aab16ec
This does a few things: 1. Fixes the "migration_status" wording since that does not exist and could be confused as a field on the server resource which it is not, it is referring to the migration resource status. 2. Fixes the RESIZED status mention since that is not a real server status, it probably meant VERIFY_RESIZE (RESIZED is the name of the nova.compute.vm_states variable used in the code to set the VERIFY_RESIZE status in the API). 3. Adds words about options to correct the server status from ERROR after confirmResize fails, the most obvious being an admin resetting the server status to ACTIVE or the user hard rebooting the server. Change-Id: I7de257ad78031d137616d724bee3fa1cbf40d6fa Related-Bug: #1821594
251 lines
7.2 KiB
ReStructuredText
251 lines
7.2 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
==========================================================
|
|
Servers - run an administrative action (servers, action)
|
|
==========================================================
|
|
|
|
Enables administrators to perform an action on a server. Specify the
|
|
action in the request body.
|
|
|
|
You can inject network information into, migrate, live-migrate,
|
|
reset networking on, reset the state of a server,
|
|
and evacuate a server from a failed host to a new host.
|
|
|
|
|
|
Inject Network Information (injectNetworkInfo Action)
|
|
=====================================================
|
|
|
|
.. rest_method:: POST /servers/{server_id}/action
|
|
|
|
Injects network information into a server.
|
|
|
|
Specify the ``injectNetworkInfo`` action in the request body.
|
|
|
|
Policy defaults enable only users with the administrative role to
|
|
perform this operation. Cloud providers can change these permissions
|
|
through the ``policy.json`` file.
|
|
|
|
.. warning:: There is very limited support on this API, For more information,
|
|
see `nova virt support matrix
|
|
<https://docs.openstack.org/nova/latest/user/support-matrix.html>`__
|
|
|
|
Normal response codes: 202
|
|
|
|
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- server_id: server_id_path
|
|
- injectNetworkInfo: injectNetworkInfo
|
|
|
|
**Example Inject Network Information (injectNetworkInfo Action)**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-inject-network-info.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
If successful, this method does not return content in the response body.
|
|
|
|
|
|
Migrate Server (migrate Action)
|
|
===============================
|
|
|
|
.. rest_method:: POST /servers/{server_id}/action
|
|
|
|
Migrates a server to a host.
|
|
|
|
Specify the ``migrate`` action in the request body.
|
|
|
|
Up to microversion 2.55, the scheduler chooses the host.
|
|
Starting from microversion 2.56, the ``host`` parameter is available
|
|
to specify the destination host. If you specify ``null`` or don't specify
|
|
this parameter, the scheduler chooses a host.
|
|
|
|
**Asynchronous Postconditions**
|
|
|
|
The server goes to a ``VERIFY_RESIZE`` status, ``RESIZED`` VM status,
|
|
and ``finished`` migration status after a successful cold migration
|
|
and then must be confirmed or reverted. If you set the
|
|
``resize_confirm_window`` option of the Compute service to a positive integer
|
|
value, the Compute service automatically confirms the migrate operation
|
|
after the set interval in seconds.
|
|
|
|
Policy defaults enable only users with the administrative role to
|
|
perform this operation. Cloud providers can change these permissions
|
|
through the ``policy.json`` file.
|
|
|
|
Normal response codes: 202
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
|
itemNotFound(404), conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- server_id: server_id_path
|
|
- migrate: migrate
|
|
- host: host_migration_2_56
|
|
|
|
**Example Migrate Server (migrate Action) (v2.1)**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-migrate-server/migrate-server.json
|
|
:language: javascript
|
|
|
|
**Example Migrate Server (migrate Action) (v2.56)**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-migrate-server/v2.56/migrate-server.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
If successful, this method does not return content in the response body.
|
|
|
|
|
|
Live-Migrate Server (os-migrateLive Action)
|
|
===========================================
|
|
|
|
.. rest_method:: POST /servers/{server_id}/action
|
|
|
|
Live-migrates a server to a new host without rebooting.
|
|
|
|
Specify the ``os-migrateLive`` action in the request body.
|
|
|
|
Use the ``host`` parameter to specify the destination host. If
|
|
this param is ``null``, the scheduler chooses a host. If a scheduled host
|
|
is not suitable to do migration, the scheduler tries up to
|
|
``migrate_max_retries`` rescheduling attempts.
|
|
|
|
Starting from API version 2.25, the ``block_migration`` parameter could be
|
|
to ``auto`` so that nova can decide value of block_migration during live
|
|
migration.
|
|
|
|
Policy defaults enable only users with the administrative role to
|
|
perform this operation. Cloud providers can change these permissions
|
|
through the ``policy.json`` file.
|
|
|
|
Starting from REST API version 2.34 pre-live-migration checks are done
|
|
asynchronously, results of these checks are available in ``instance-actions``.
|
|
Nova responds immediately, and no pre-live-migration checks are returned.
|
|
The instance will not immediately change state to ``ERROR``, if a failure of
|
|
the live-migration checks occurs.
|
|
|
|
Starting from API version 2.68, the ``force`` parameter is no longer accepted
|
|
as this could not be meaningfully supported by servers with complex resource
|
|
allocations.
|
|
|
|
Normal response codes: 202
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
|
itemNotFound(404), conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- server_id: server_id_path
|
|
- os-migrateLive: os-migrateLive
|
|
- host: host_migration
|
|
- block_migration: block_migration
|
|
- block_migration: block_migration_2_25
|
|
- disk_over_commit: disk_over_commit
|
|
- force: force_live_migrate
|
|
|
|
**Example Live-Migrate Server (os-migrateLive Action)**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-migrate-server/v2.30/live-migrate-server.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
If successful, this method does not return content in the response body.
|
|
|
|
|
|
Reset Networking On A Server (resetNetwork Action)
|
|
==================================================
|
|
|
|
.. rest_method:: POST /servers/{server_id}/action
|
|
|
|
Resets networking on a server.
|
|
|
|
.. note::
|
|
|
|
Only the XenServer driver implements this feature and only if the guest
|
|
has the XenAPI agent in the targeted server.
|
|
|
|
Specify the ``resetNetwork`` action in the request body.
|
|
|
|
Policy defaults enable only users with the administrative role to
|
|
perform this operation. Cloud providers can change these permissions
|
|
through the ``policy.json`` file.
|
|
|
|
Normal response codes: 202
|
|
|
|
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
|
|
conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- server_id: server_id_path
|
|
- resetNetwork: resetNetwork
|
|
|
|
**Example Reset Networking On A Server (resetNetwork Action)**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-reset-network.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
If successful, this method does not return content in the response body.
|
|
|
|
.. _os-resetState:
|
|
|
|
Reset Server State (os-resetState Action)
|
|
=========================================
|
|
|
|
.. rest_method:: POST /servers/{server_id}/action
|
|
|
|
Resets the state of a server.
|
|
|
|
Specify the ``os-resetState`` action and the ``state`` in the request body.
|
|
|
|
Policy defaults enable only users with the administrative role to
|
|
perform this operation. Cloud providers can change these permissions
|
|
through the ``policy.json`` file.
|
|
|
|
Normal response codes: 202
|
|
|
|
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- server_id: server_id_path
|
|
- os-resetState: os-resetState
|
|
- os-resetState.state: os-resetState_state
|
|
|
|
**Example Reset Server State (os-resetState Action)**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-reset-server-state.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
If successful, this method does not return content in the response body.
|