docs/development/manuals/get-valid-server-state.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 ======================
   5 Get valid server state
   6 ======================
   7
   8 Related Blueprints:
   9 ===================
  10
  11 https://blueprints.launchpad.net/nova/+spec/get-valid-server-state
  12
  13 Problem description
  14 ===================
  15
  16 Previously when the owner of a VM has queried his VMs, he has not received
  17 enough state information, states have not changed fast enough in the VIM and
  18 they have not been accurate in some scenarios. With this change this gap is now
  19 closed.
  20
  21 A typical case is that, in case of a fault of a host, the user of a high
  22 availability service running on top of that host, needs to make an immediate
  23 switch over from the faulty host to an active standby host. Now, if the compute
  24 host is forced down [1] as a result of that fault, the user has to be notified
  25 about this state change such that the user can react accordingly. Similarly,
  26 a change of the host state to "maintenance" should also be notified to the
  27 users.
  28
  29 What is changed
  30 ===============
  31
  32 A new ``host_status`` parameter is added to the ``/servers/{server_id}`` and
  33 ``/servers/detail`` endpoints in microversion 2.16. By this new parameter
  34 user can get additional state information about the host.
  35
  36 ``host_status`` possible values where next value in list can override the
  37 previous:
  38
  39 - ``UP`` if nova-compute is up.
  40 - ``UNKNOWN`` if nova-compute status was not reported by servicegroup driver
  41   within configured time period. Default is within 60 seconds,
  42   but can be changed with ``service_down_time`` in nova.conf.
  43 - ``DOWN`` if nova-compute was forced down.
  44 - ``MAINTENANCE`` if nova-compute was disabled. MAINTENANCE in API directly
  45   means nova-compute service is disabled. Different wording is used to avoid
  46   the impression that the whole host is down, as only scheduling of new VMs
  47   is disabled.
  48 - Empty string indicates there is no host for server.
  49
  50 ``host_status`` is returned in the response in case the policy permits. By
  51 default the policy is for admin only in Nova policy.json::
  52
  53   "os_compute_api:servers:show:host_status": "rule:admin_api"
  54
  55 For an NFV use case this has to also be enabled for the owner of the VM::
  56
  57   "os_compute_api:servers:show:host_status": "rule:admin_or_owner"
  58
  59 REST API examples:
  60 ==================
  61
  62 Case where nova-compute is enabled and reporting normally::
  63
  64     GET /v2.1/{tenant_id}/servers/{server_id}
  65
  66     200 OK
  67     {
  68       "server": {
  69         "host_status": "UP",
  70         ...
  71       }
  72     }
  73
  74 Case where nova-compute is enabled, but not reporting normally::
  75
  76     GET /v2.1/{tenant_id}/servers/{server_id}
  77
  78     200 OK
  79     {
  80       "server": {
  81         "host_status": "UNKNOWN",
  82         ...
  83       }
  84     }
  85
  86 Case where nova-compute is enabled, but forced_down::
  87
  88     GET /v2.1/{tenant_id}/servers/{server_id}
  89
  90     200 OK
  91     {
  92       "server": {
  93         "host_status": "DOWN",
  94         ...
  95       }
  96     }
  97
  98 Case where nova-compute is disabled::
  99
 100     GET /v2.1/{tenant_id}/servers/{server_id}
 101
 102     200 OK
 103     {
 104       "server": {
 105         "host_status": "MAINTENANCE",
 106         ...
 107       }
 108     }
 109
 110 Host Status is also visible in python-novaclient::
 111
 112   +-------+------+--------+------------+-------------+----------+-------------+
 113   | ID    | Name | Status | Task State | Power State | Networks | Host Status |
 114   +-------+------+--------+------------+-------------+----------+-------------+
 115   | 9a... | vm1  | ACTIVE | -          | RUNNING     | xnet=... | UP          |
 116   +-------+------+--------+------------+-------------+----------+-------------+
 117
 118 Links:
 119 ======
 120
 121 [1] Manual for OpenStack NOVA API for marking host down
 122 http://artifacts.opnfv.org/doctor/docs/manuals/mark-host-down_manual.html
 123
 124 [2] OpenStack compute manual page
 125 http://developer.openstack.org/api-ref-compute-v2.1.html#compute-v2.1