265 lines
7.0 KiB
ReStructuredText
265 lines
7.0 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
===============================
|
|
Hosts (os-hosts) (DEPRECATED)
|
|
===============================
|
|
|
|
.. warning::
|
|
|
|
The ``os-hosts`` API is deprecated as of the 2.43 microversion. Requests
|
|
made with microversion >= 2.43 will result in a 404 error. To list and show
|
|
host details, use the :ref:`os-hypervisors` API. To enable or disable a
|
|
service, use the :ref:`os-services` API. There is no replacement for the
|
|
`shutdown`, `startup`, `reboot`, or `maintenance_mode` actions as those are
|
|
system-level operations which should be outside of the control of the
|
|
compute service.
|
|
|
|
Manages physical hosts. Some virt drivers do not support all host
|
|
functions. For more information, see `nova virt support
|
|
matrix <https://docs.openstack.org/nova/latest/user/support-matrix.html>`__
|
|
|
|
Policy defaults enable only users with the administrative role to perform
|
|
all os-hosts related operations. Cloud providers can change these permissions
|
|
through the ``policy.json`` file.
|
|
|
|
List Hosts
|
|
==========
|
|
|
|
.. rest_method:: GET /os-hosts
|
|
|
|
Lists hosts.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: unauthorized(401), forbidden(403)
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- hosts: hosts
|
|
- zone: host_zone
|
|
- host_name: host_name_body
|
|
- service: host_service
|
|
|
|
**Example List Hosts**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-hosts/hosts-list-resp.json
|
|
:language: javascript
|
|
|
|
Show Host Details
|
|
=================
|
|
|
|
.. rest_method:: GET /os-hosts/{host_name}
|
|
|
|
Shows details for a host.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host_name: host_name
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host: host_resource_array
|
|
- resource: host_resource
|
|
- resource.project: host_project
|
|
- resource.cpu: host_cpu
|
|
- resource.memory_mb: host_memory_mb
|
|
- resource.disk_gb: host_disk_gb
|
|
- resource.host: host_name_body
|
|
|
|
**Example Show Host Details**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-resp.json
|
|
:language: javascript
|
|
|
|
Update Host status
|
|
==================
|
|
|
|
.. rest_method:: PUT /os-hosts/{host_name}
|
|
|
|
Enables, disables a host or put a host in maintenance or normal mode.
|
|
|
|
.. warning::
|
|
|
|
Putting a host into maintenance mode is only implemented by the XenServer
|
|
compute driver and it has been reported that it does not actually evacuate
|
|
all of the guests from the host, it just sets a flag in the Xen management
|
|
console, and is therefore useless. There are other APIs that allow you to do
|
|
the same thing which are supported across all compute drivers, which would be
|
|
disabling a service and then migrating the instances off that host. See the
|
|
`Operations Guide <https://wiki.openstack.org/wiki/OpsGuide/Compute_Node_Failures_and_Maintenance>`_
|
|
for more information on maintenance.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), NotImplemented(501)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host_name: host_name
|
|
- status: host_status_body_in
|
|
- maintenance_mode: host_maintenance_mode_in
|
|
|
|
**Example Enable Host: JSON request**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-hosts/host-put-maintenance-req.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host: host_name_body
|
|
- status: host_status_body
|
|
- maintenance_mode: host_maintenance_mode
|
|
|
|
**Example Enable Host**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-hosts/host-put-maintenance-resp.json
|
|
:language: javascript
|
|
|
|
Reboot Host
|
|
===========
|
|
|
|
.. rest_method:: GET /os-hosts/{host_name}/reboot
|
|
|
|
Reboots a host.
|
|
|
|
.. warning::
|
|
|
|
This is only supported by the XenServer and Hyper-v drivers. The backing
|
|
drivers do no orchestration of dealing with guests in the nova database when
|
|
performing a reboot of the host. The nova-compute service for that host may
|
|
be temporarily disabled by the service group health check which would take it
|
|
out of scheduling decisions, and the guests would be down, but the periodic
|
|
task which checks for unexpectedly stopped instances runs in the nova-compute
|
|
service, which might be dead now so the nova API would show the instances as
|
|
running when in fact they are actually stopped. This API is also not tested
|
|
in a live running OpenStack environment. Needless to say, it is not
|
|
recommended to use this API and it is deprecated as of the 2.43 microversion.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), NotImplemented(501)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host_name: host_name
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host: host_name_body
|
|
- power_action: host_power_action
|
|
|
|
**Example Reboot Host: JSON response**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-reboot.json
|
|
:language: javascript
|
|
|
|
Shut Down Host
|
|
==============
|
|
|
|
.. rest_method:: GET /os-hosts/{host_name}/shutdown
|
|
|
|
Shuts down a host.
|
|
|
|
.. warning::
|
|
|
|
This is only supported by the XenServer and Hyper-v drivers. The backing
|
|
drivers do no orchestration of dealing with guests in the nova database when
|
|
performing a shutdown of the host. The nova-compute service for that host may
|
|
be temporarily disabled by the service group health check which would take it
|
|
out of scheduling decisions, and the guests would be down, but the periodic
|
|
task which checks for unexpectedly stopped instances runs in the nova-compute
|
|
service, which might be dead now so the nova API would show the instances as
|
|
running when in fact they are actually stopped. This API is also not tested
|
|
in a live running OpenStack environment. Needless to say, it is not
|
|
recommended to use this API and it is deprecated as of the 2.43 microversion.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), NotImplemented(501)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host_name: host_name
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host: host_name_body
|
|
- power_action: host_power_action
|
|
|
|
**Example Shut Down Host**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-shutdown.json
|
|
:language: javascript
|
|
|
|
Start Host
|
|
==========
|
|
|
|
.. rest_method:: GET /os-hosts/{host_name}/startup
|
|
|
|
Starts a host.
|
|
|
|
.. warning::
|
|
|
|
This is not implemented by any in-tree compute drivers and therefore will
|
|
always fail with a `501 NotImplemented` error. Needless to say, it is not
|
|
recommended to use this API and it is deprecated as of the 2.43 microversion.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), NotImplemented(501)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host_name: host_name
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- host: host_name_body
|
|
- power_action: host_power_action
|
|
|
|
**Example Start Host**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-hosts/host-get-startup.json
|
|
:language: javascript
|