Restore V3 Diagnostics info
bp restore-vm-diagnostics APIImpact Change-Id: I1b775c565012931aec09a6ac11ad14d8fcdcd857
This commit is contained in:
Sergey Nikitin
committed by
Matt Riedemann
Matt Riedemann
parent
49db85ff55
commit
f4a70090a0
303
specs/ocata/approved/restore-vm-diagnostics.rst
Normal file
303
specs/ocata/approved/restore-vm-diagnostics.rst
Normal file
@@ -0,0 +1,303 @@
|
|||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
===================================
|
||||||
|
Restore standardised VM Diagnostics
|
||||||
|
===================================
|
||||||
|
|
||||||
|
https://blueprints.launchpad.net/nova/+spec/restore-vm-diagnostics
|
||||||
|
|
||||||
|
Currently there is no defined format for VM diagnostics. This BP will ensure
|
||||||
|
that all of the drivers that provide VM diagnostics will have a consistent
|
||||||
|
format.
|
||||||
|
|
||||||
|
**NOTE:** VM diagnostic spec was implemented in Juno but only for API v3 [1]_.
|
||||||
|
After that V3 API was removed. This spec will restore API part of VM
|
||||||
|
diagnostic BP. All other parts of BP (e.g. compute API part, virt drivers part)
|
||||||
|
weren't removed with v3 API.
|
||||||
|
|
||||||
|
Problem description
|
||||||
|
===================
|
||||||
|
|
||||||
|
Now VM diagnostics are a 'blob' of data returned by each hypervisor. The
|
||||||
|
goal here is to have a formal definition of what output should be returned, if
|
||||||
|
possible, by the drivers supporting the API.
|
||||||
|
|
||||||
|
Use Cases
|
||||||
|
---------
|
||||||
|
|
||||||
|
Diagnostic information from all virt drivers will have the same format.
|
||||||
|
It will help to use this information and it will help to get rid of need to
|
||||||
|
know from what virt driver you got diagnostic information.
|
||||||
|
|
||||||
|
Proposed change
|
||||||
|
===============
|
||||||
|
|
||||||
|
Add an API microversion that will standardise response of getting
|
||||||
|
VM diagnostics info request [2]_. This microversion is **admin-only** by
|
||||||
|
default. The access is driven by policy. The microversion will use a virt
|
||||||
|
driver method that returns a predefined structure. It was already
|
||||||
|
implemented::
|
||||||
|
|
||||||
|
get_instance_diagnostics(self, instance)
|
||||||
|
|
||||||
|
This method returns information as an object class. A diagnostics
|
||||||
|
model class will be instantiated and populated by the virt drivers. A field
|
||||||
|
that is not populated by the driver will return a default value set in the
|
||||||
|
aforementioned class. After getting object class from the method we will build
|
||||||
|
a response in the API layer by getting fields from this object.
|
||||||
|
|
||||||
|
The table below has the key and the description of the value returned:
|
||||||
|
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| Key | Description |
|
||||||
|
+========================+===================================================+
|
||||||
|
| state | A string enum denoting the current state of |
|
||||||
|
| | the VM. Possible values are: 'pending', 'running',|
|
||||||
|
| | 'paused', 'shutdown', 'crashed', 'suspended' |
|
||||||
|
| | (String) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| driver | A string denoting the driver on which the VM is |
|
||||||
|
| | running. Examples may be: 'libvirt', 'xenapi', |
|
||||||
|
| | 'hyperv' and 'vmwareapi' (String) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| hypervisor | A string denoting the hypervisor on which the VM |
|
||||||
|
| | is running. Examples for libvirt driver may be: |
|
||||||
|
| | 'qemu', 'kvm' or 'xen'. (String) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| hypervisor_os | A string denoting the hypervisor OS (String) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| uptime | The amount of time in seconds that the VM has |
|
||||||
|
| | been running (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| num_cpus | The number of vCPUs (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| num_nics | The number of vNICS (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| num_disks | The number of disks (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| cpu_details | An array of details (a dictionary) per vCPU (see |
|
||||||
|
| | below) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| nic_details | An array of details (a dictionary) per vNIC (see |
|
||||||
|
| | below) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| disk_details | An array of details (a dictionary) per disk (see |
|
||||||
|
| | below) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| memory_details | A dictionary of memory details (see below) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| config_drive | Indicates if the config drive is supported on |
|
||||||
|
| | the instance (Boolean) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
|
||||||
|
Note: If the virt driver is unable to provide a specific field then this field
|
||||||
|
will be reported as 'None' in the diagnostics.
|
||||||
|
|
||||||
|
The cpu details is an array of dictionaries per each virtual CPU.
|
||||||
|
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| Key | Description |
|
||||||
|
+========================+===================================================+
|
||||||
|
| id | CPU ID (String) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| time | CPU Time in nano seconds (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
|
||||||
|
The network details is an array of dictionaries per each virtual NIC.
|
||||||
|
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| Key | Description |
|
||||||
|
+========================+===================================================+
|
||||||
|
| mac_address | Mac address of the interface (String) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| rx_octets | Received octets (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| rx_errors | Received errors (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| rx_drop | Received packets dropped (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| rx_packets | Received packets (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| tx_octets | Transmitted Octets (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| tx_errors | Transmit errors (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| tx_drop | Transmit dropped packets (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| tx_packets | Transmit packets (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
|
||||||
|
The disk details is an array of dictionaries per each virtual disk.
|
||||||
|
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| Key | Description |
|
||||||
|
+========================+===================================================+
|
||||||
|
| read_bytes | Disk reads in bytes (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| read_requests | Read requests (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| write_bytes | Disk writes in bytes (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| write_requests | Write requests (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| errors_count | Disk errors (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
|
||||||
|
The memory details is a dictionary.
|
||||||
|
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| Key | Description |
|
||||||
|
+========================+===================================================+
|
||||||
|
| maximum | Amount of memory provisioned for the VM in MB |
|
||||||
|
| | (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
| used | Amount of memory that is currently used by the |
|
||||||
|
| | guest operating system and its applications in MB |
|
||||||
|
| | (Integer) |
|
||||||
|
+------------------------+---------------------------------------------------+
|
||||||
|
|
||||||
|
Below is an example of the dictionary data returned by the fake driver::
|
||||||
|
|
||||||
|
{'state': 'running',
|
||||||
|
'driver': 'fake-driver',
|
||||||
|
'hypervisor_os': 'fake-os',
|
||||||
|
'hypervisor': 'fake-hypervisor',
|
||||||
|
'uptime': 7,
|
||||||
|
'num_cpus': 1,
|
||||||
|
'num_vnics': 1,
|
||||||
|
'num_disks': 1,
|
||||||
|
'cpu_details': [{'id': '0',
|
||||||
|
'time': 1024}],
|
||||||
|
'nic_details': [{'mac_address': '00:00:00:00:00:00',
|
||||||
|
'rx_octets': 0,
|
||||||
|
'rx_errors': 0,
|
||||||
|
'rx_drop': 0,
|
||||||
|
'rx_packets': 0,
|
||||||
|
'tx_octets': 0,
|
||||||
|
'tx_errors': 0,
|
||||||
|
'tx_drop': 0,
|
||||||
|
'tx_packets': 0}],
|
||||||
|
'disk_details': [{'read_bytes':0,
|
||||||
|
'read_requests': 0,
|
||||||
|
'write_bytes': 0,
|
||||||
|
'write_requests': 0,
|
||||||
|
'errors_count': 0}],
|
||||||
|
'memory_details': {'maximum': 512, 'used': 256}}
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
------------
|
||||||
|
|
||||||
|
Continue with the same format that the current API has. This is problematic as
|
||||||
|
we are unable to build common user interface that can query VM states,
|
||||||
|
for example in tempest.
|
||||||
|
|
||||||
|
Data model impact
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
REST API impact
|
||||||
|
---------------
|
||||||
|
|
||||||
|
A new microversion will be added which will use already merged parts of VM
|
||||||
|
diagnostic BP. This microversion will change response of getting
|
||||||
|
VM diagnostics info request [2]_. This microversion is **admin-only** by
|
||||||
|
default. The access is driven by policy.
|
||||||
|
|
||||||
|
Security impact
|
||||||
|
---------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Notifications impact
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Other end user impact
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Performance Impact
|
||||||
|
------------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Other deployer impact
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
It will make life easier - deployers will be able to get better insight into
|
||||||
|
the state of VM and be able to troubleshoot.
|
||||||
|
|
||||||
|
Developer impact
|
||||||
|
----------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Assignee(s)
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Primary assignee:
|
||||||
|
Sergey Nikitin - snikitin
|
||||||
|
|
||||||
|
Work Items
|
||||||
|
----------
|
||||||
|
|
||||||
|
Most of virt drivers support get_instance_diagnostics() method:
|
||||||
|
|
||||||
|
* libvirt support (Done)
|
||||||
|
|
||||||
|
* XenAPI support (Partially)
|
||||||
|
|
||||||
|
* VMware support (Partially)
|
||||||
|
|
||||||
|
* Hyper-V support (In progress) [3]_
|
||||||
|
|
||||||
|
* Ironic support (Not started)
|
||||||
|
|
||||||
|
The work items in this case will be:
|
||||||
|
|
||||||
|
* Complete XenAPI support
|
||||||
|
|
||||||
|
* Complete VMware support
|
||||||
|
|
||||||
|
* Add VM diagnostics microversion API
|
||||||
|
|
||||||
|
* Restore and modify existing tempest tests
|
||||||
|
|
||||||
|
* Add support for the python-novaclient
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Testing
|
||||||
|
=======
|
||||||
|
|
||||||
|
Tempest already has tests for VM diagnostics, but they are skipped because
|
||||||
|
API part of this spec was removed from Nova with V3 API [4]_. These tests
|
||||||
|
should be restored and modified.
|
||||||
|
|
||||||
|
Documentation Impact
|
||||||
|
====================
|
||||||
|
|
||||||
|
Docs needed for new API microversion. These docs will describe new output
|
||||||
|
of getting VM diagnostics info response.
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. [1] https://specs.openstack.org/openstack/nova-specs/specs/juno/implemented/v3-diagnostics.html
|
||||||
|
.. [2] http://developer.openstack.org/api-ref/compute/#show-server-diagnostics
|
||||||
|
.. [3] https://blueprints.launchpad.net/nova/+spec/hyperv-vm-diagnostics
|
||||||
|
.. [4] https://bugs.launchpad.net/nova/+bug/1240043
|
||||||
Reference in New Issue
Block a user