code.grnet.gr Git - ganeti-local/blob - doc/design-device-uuid-name.rst

   1 ==========================================
   2 Design for adding UUID and name to devices
   3 ==========================================
   4
   5 .. contents:: :depth: 4
   6
   7 This is a design document about adding UUID and name to instance devices
   8 (Disks/NICs) and the ability to reference them by those identifiers.
   9
  10
  11 Current state and shortcomings
  12 ==============================
  13
  14 Currently, the only way to refer to a device (Disk/NIC) is by its index
  15 inside the VM (e.g. gnt-instance modify --disk 2:remove).
  16
  17 Using indices as identifiers has the drawback that addition/removal of a
  18 device results in changing the identifiers(indices) of other devices and
  19 makes the net effect of commands depend on their strict ordering. A
  20 device reference is not absolute, meaning an external entity controlling
  21 Ganeti, e.g., over RAPI, cannot keep permanent identifiers for referring
  22 to devices, nor can it have more than one outstanding commands, since
  23 their order of execution is not guaranteed.
  24
  25
  26 Proposed Changes
  27 ================
  28
  29 To be able to reference a device in a unique way, we propose to extend
  30 Disks and NICs by assigning to them a UUID and a name. The UUID will be
  31 assigned by Ganeti upon creation, while the name will be an optional
  32 user parameter. Renaming a device will also be supported.
  33
  34 Commands (e.g. `gnt-instance modify`) will be able to reference each
  35 device by its index, UUID, or name. To be able to refer to devices by
  36 name, we must guarantee that device names are unique. Unlike other
  37 objects (instances, networks, nodegroups, etc.), NIC and Disk objects
  38 will not have unique names across the cluster, since they are still not
  39 independent entities, but rather part of the instance object. This makes
  40 global uniqueness of names hard to achieve at this point. Instead their
  41 names will be unique at instance level.
  42
  43 Apart from unique device names, we must also guarantee that a device
  44 name can not be the UUID of another device. Also, to remove ambiguity
  45 while supporting both indices and names as identifiers, we forbid purely
  46 numeric device names.
  47
  48
  49 Implementation Details
  50 ======================
  51
  52 Modify OpInstanceSetParams to accept not only indexes, but also device
  53 names and UUIDs. So, the accepted NIC and disk modifications will have
  54 the following format:
  55
  56 identifier:action,key=value
  57
  58 where, from now on, identifier can be an index (-1 for the last device),
  59 UUID, or name and action should be add, modify, or remove.
  60
  61 Configuration Changes
  62 ~~~~~~~~~~~~~~~~~~~~~
  63
  64 Disk and NIC config objects get two extra slots:
  65
  66 - uuid
  67 - name
  68
  69 Instance Queries
  70 ~~~~~~~~~~~~~~~~~
  71
  72 We will extend the query mechanism to expose names and UUIDs of NICs and
  73 Disks.
  74
  75 Hook Variables
  76 ~~~~~~~~~~~~~~
  77
  78 We will expose the name of NICs and Disks to the hook environment of
  79 instance-related operations:
  80
  81 ``INSTANCE_NIC%d_NAME``
  82 ``INSTANCE_DISK%d_NAME``
  83
  84 .. vim: set textwidth=72 :
  85 .. Local Variables:
  86 .. mode: rst
  87 .. fill-column: 72
  88 .. End: