Files
045d883772108c722e2a483a6e6b3239d4518a05
nova /api-ref /source /os-services.inc

356 lines
9.2 KiB
PHP
Raw Normal View History

.. -*- rst -*-
.. _os-services:
================================
Compute services (os-services)
================================
Lists all running Compute services in a region, enables or disables
scheduling for a Compute service and deletes a Compute service.
For an overview of Compute services, see `OpenStack
api-ref: add a note in DELETE /os-services about deleting computes As seen in I2717274bb1bd370870acbf58c03dc59cee30cc5e, if an operator deletes a nova-compute service via the API but fails to stop the actual nova-compute process, the API will delete the services table and compute_nodes table records, but the nova-compute process will hit the 'update_available_resource' periodic task and re-create the compute node record, which at that point is orphaned since it does not have an associated nova-compute service. Restarting the nova-compute service _should_ recreate the service table record for that host and then the user could attempt to delete the service and compute node record again via this API, but it's better to not have to find this out the hard way. So this change adds a simple reminder that the nova-compute process on the host should be stopped before deleting the compute service. While in here, the link to the install guide about the various compute services is also fixed. Change-Id: I68f2074814c3ae890888a5c75fd2870bb99f0e08 Related-Bug: #1646255
2018年03月15日 16:05:46 -04:00
Compute <https://docs.openstack.org/nova/latest/install/get-started-compute.html>`__.
List Compute Services
=====================
.. rest_method:: GET /os-services
Lists all running Compute services.
Provides details why any services were disabled.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- binary: binary_query
- host: host_query_service
Response
--------
.. rest_parameters:: parameters.yaml
- services: services
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
- id: service_id_body_2_52
- id: service_id_body_2_53
- binary: binary
- disabled_reason: disabled_reason_body
- host: host_name_body
- state: service_state
- status: service_status
- updated_at: updated
- zone: OS-EXT-AZ:availability_zone
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
- forced_down: forced_down_2_11
**Example List Compute Services**
.. literalinclude:: ../../doc/api_samples/os-services/v2.11/services-list-get-resp.json
:language: javascript
Disable Scheduling For A Compute Service
========================================
.. rest_method:: PUT /os-services/disable
Disables scheduling for a Compute service.
Specify the service by its host name and binary name.
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
**Example Disable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- host: host_name_body
- status: service_status
**Example Disable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-resp.json
:language: javascript
Disable Scheduling For A Compute Service and Log Disabled Reason
================================================================
.. rest_method:: PUT /os-services/disable-log-reason
Disables scheduling for a Compute service and logs information to the Compute
service table about why a Compute service was disabled.
Specify the service by its host name and binary name.
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
- disabled_reason: disabled_reason_body
**Example Disable Scheduling For A Compute Service and Log Disabled Reason**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- disabled_reason: disabled_reason_body
- host: host_name_body
- status: service_status
**Example Disable Scheduling For A Compute Service and Log Disabled Reason**
.. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-resp.json
:language: javascript
Enable Scheduling For A Compute Service
=======================================
.. rest_method:: PUT /os-services/enable
Enables scheduling for a Compute service.
Specify the service by its host name and binary name.
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
**Example Enable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- host: host_name_body
- status: service_status
**Example Enable Scheduling For A Compute Service**
.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-resp.json
:language: javascript
Update Forced Down
==================
.. rest_method:: PUT /os-services/force-down
Set or unset ``forced_down`` flag for the service. ``forced_down`` is a manual
override to tell nova that the service in question has been fenced manually by
the operations team (either hard powered off, or network unplugged). That
signals that it is safe to proceed with ``evacuate`` or other operations that
nova has safety checks to prevent for hosts that are up.
.. warning::
Setting a service forced down without completely fencing it will likely
result in the corruption of VMs on that host.
Action ``force-down`` available as of microversion 2.11.
Specify the service by its host name and binary name.
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
.. note:: Starting with microversion 2.53 this API is superseded by
``PUT /os-services/{service_id}``.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- host: host_name_body
- binary: binary
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
- forced_down: forced_down_2_11
**Example Update Forced Down**
.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- binary: binary
- host: host_name_body
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
- forced_down: forced_down_2_11
|
**Example Update Forced Down**
.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-resp.json
:language: javascript
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
Update Compute Service
======================
.. rest_method:: PUT /os-services/{service_id}
Update a compute service to enable or disable scheduling, including recording a
reason why a compute service was disabled from scheduling. Set or unset the
``forced_down`` flag for the service.
This API is available starting with microversion 2.53.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- service_id: service_id_path_2_53_no_version
- status: service_status_2_53_in
- disabled_reason: disabled_reason_2_53_in
- forced_down: forced_down_2_53_in
**Example Disable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-disable-log-put-req.json
:language: javascript
**Example Enable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-enable-put-req.json
:language: javascript
**Example Update Forced Down (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-force-down-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- service: service
- id: service_id_body_2_53_no_version
- binary: binary
- disabled_reason: disabled_reason_body
- host: host_name_body
- state: service_state
- status: service_status
- updated_at: updated
- zone: OS-EXT-AZ:availability_zone
- forced_down: forced_down_2_53_out
**Example Disable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-disable-log-put-resp.json
:language: javascript
**Example Enable Scheduling For A Compute Service (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-enable-put-resp.json
:language: javascript
**Example Update Forced Down (v2.53)**
.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-force-down-put-resp.json
:language: javascript
Delete Compute Service
======================
.. rest_method:: DELETE /os-services/{service_id}
api-ref: add a note in DELETE /os-services about deleting computes As seen in I2717274bb1bd370870acbf58c03dc59cee30cc5e, if an operator deletes a nova-compute service via the API but fails to stop the actual nova-compute process, the API will delete the services table and compute_nodes table records, but the nova-compute process will hit the 'update_available_resource' periodic task and re-create the compute node record, which at that point is orphaned since it does not have an associated nova-compute service. Restarting the nova-compute service _should_ recreate the service table record for that host and then the user could attempt to delete the service and compute node record again via this API, but it's better to not have to find this out the hard way. So this change adds a simple reminder that the nova-compute process on the host should be stopped before deleting the compute service. While in here, the link to the install guide about the various compute services is also fixed. Change-Id: I68f2074814c3ae890888a5c75fd2870bb99f0e08 Related-Bug: #1646255
2018年03月15日 16:05:46 -04:00
Deletes a service. If it's a ``nova-compute`` service, then the
corresponding host will be removed from all the host aggregates as well.
Block deleting compute services which are hosting instances This change makes "DELETE /os-services/{service_id}" fail with a 409 response when attempting to delete a nova-compute service which is still hosting instances. Deleting a compute service also results in deleting the related compute_nodes table entry for that service host. The compute node resource provider in placement is tied to the compute node via the UUID, and if we allow deleting the compute service and node then the resource provider for that node is effectively orphaned in Placement, along with the instances which have allocations against that resource provider. Furthermore, restarting the compute service will create a new service and compute_nodes record, and the compute node would have a new UUID and resource provider. This will affect scheduling for that host since Placement will be reporting it as having available capacity which in reality is not accurate. A release note is included for the (justified) behavior change in the API. A new microversion should not be required for this since admins should not have to opt out of broken behavior. Since this API did not previously expect to return a 409 response, the "expected_errors" decorator is updated and again, should not require a microversion per the guidelines: https://docs.openstack.org/nova/latest/contributor/microversions.html#when-a-microversion-is-not-needed Change-Id: I0bd63b655ad3d3d39af8d15c781ce0a45efc8e3a Closes-Bug: #1763183
2018年04月11日 18:00:39 -04:00
Attempts to delete a ``nova-compute`` service which is still hosting instances
will result in a 409 HTTPConflict response. The instances will need to be
migrated or deleted before a compute service can be deleted.
api-ref: add a note in DELETE /os-services about deleting computes As seen in I2717274bb1bd370870acbf58c03dc59cee30cc5e, if an operator deletes a nova-compute service via the API but fails to stop the actual nova-compute process, the API will delete the services table and compute_nodes table records, but the nova-compute process will hit the 'update_available_resource' periodic task and re-create the compute node record, which at that point is orphaned since it does not have an associated nova-compute service. Restarting the nova-compute service _should_ recreate the service table record for that host and then the user could attempt to delete the service and compute node record again via this API, but it's better to not have to find this out the hard way. So this change adds a simple reminder that the nova-compute process on the host should be stopped before deleting the compute service. While in here, the link to the install guide about the various compute services is also fixed. Change-Id: I68f2074814c3ae890888a5c75fd2870bb99f0e08 Related-Bug: #1646255
2018年03月15日 16:05:46 -04:00
.. important:: Be sure to stop the actual ``nova-compute`` process on the
physical host *before* deleting the service with this API.
Failing to do so can lead to the running service re-creating
orphaned **compute_nodes** table records in the database.
Normal response codes: 204
Block deleting compute services which are hosting instances This change makes "DELETE /os-services/{service_id}" fail with a 409 response when attempting to delete a nova-compute service which is still hosting instances. Deleting a compute service also results in deleting the related compute_nodes table entry for that service host. The compute node resource provider in placement is tied to the compute node via the UUID, and if we allow deleting the compute service and node then the resource provider for that node is effectively orphaned in Placement, along with the instances which have allocations against that resource provider. Furthermore, restarting the compute service will create a new service and compute_nodes record, and the compute node would have a new UUID and resource provider. This will affect scheduling for that host since Placement will be reporting it as having available capacity which in reality is not accurate. A release note is included for the (justified) behavior change in the API. A new microversion should not be required for this since admins should not have to opt out of broken behavior. Since this API did not previously expect to return a 409 response, the "expected_errors" decorator is updated and again, should not require a microversion per the guidelines: https://docs.openstack.org/nova/latest/contributor/microversions.html#when-a-microversion-is-not-needed Change-Id: I0bd63b655ad3d3d39af8d15c781ce0a45efc8e3a Closes-Bug: #1763183
2018年04月11日 18:00:39 -04:00
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
Use uuid for id in os-services API This patch introduces a new microversion to identify services by uuid instead of id, to ensure uniqueness across cells. GET /os-services returns uuid in the id field, and uuid must be provided to delete a service with DELETE /os-services/{service_uuid}. The old PUT /os-services/* APIs are now capped and replaced with a new PUT /os-services/{service_uuid} which takes a uuid path parameter to uniquely identify the service to update. It also restricts updates to nova-compute services only, since disabling or forcing-down a non-compute service like nova-scheduler doesn't make sense as it doesn't do anything. The new update() method in this microversion also avoids trying to re-use the existing private action methods like _enable and _disable since those are predicated on looking up the service by host/binary, are confusing to follow for code flow, and just don't really make sense with a pure PUT resource update method. Part of blueprint service-hyper-uuid-in-api Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad
2017年07月18日 13:54:47 -04:00
- service_id: service_id_path_2_52
- service_id: service_id_path_2_53
Response
--------
If successful, this method does not return content in the response body.