code.grnet.gr Git - ganeti-local/blob - doc/design-2.0-commandline-parameters.rst

   1 Ganeti 2.0 commandline arguments
   2 ================================
   3
   4 .. contents::
   5
   6 Objective
   7 ---------
   8
   9 Ganeti 2.0 introduces several new features as well as new ways to
  10 handle instance resources like disks or network interfaces. This
  11 requires some noticable changes in the way commandline arguments are
  12 handled.
  13
  14 - extend and modify commandline syntax to support new features
  15 - ensure consistent patterns in commandline arguments to reduce cognitive load
  16
  17 Background
  18 ----------
  19
  20 Ganeti 2.0 introduces several changes in handling instances resources
  21 such as disks and network cards as well as some new features. Due to
  22 these changes, the commandline syntax needs to be changed
  23 significantly since the existing commandline syntax is not able to
  24 cover the changes.
  25
  26 Overview
  27 --------
  28
  29 Design changes for Ganeti 2.0 that require changes for the commandline
  30 syntax, in no particular order:
  31
  32 - flexible instance disk handling: support a variable number of disks
  33   with varying properties per instance,
  34 - flexible instance network interface handling: support a variable
  35   number of network interfaces with varying properties per instance
  36 - multiple hypervisors: multiple hypervisors can be active on the same
  37   cluster, each supporting different parameters,
  38 - support for device type CDROM (via ISO image)
  39
  40 Detailed Design
  41 ---------------
  42
  43 There are several areas of Ganeti where the commandline arguments will change:
  44
  45 - Cluster configuration
  46
  47   - cluster initialization
  48   - cluster default configuration
  49
  50 - Instance configuration
  51
  52   - handling of network cards for instances,
  53   - handling of disks for instances,
  54   - handling of CDROM devices and
  55   - handling of hypervisor specific options.
  56
  57 Notes about device removal/addition
  58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  59
  60 To avoid problems with device location changes (e.g. second network
  61 interface of the instance becoming the first or third and the like)
  62 the list of network/disk devices is treated as a stack, i.e. devices
  63 can only be added/removed at the end of the list of devices of each
  64 class (disk or network) for each instance.
  65
  66 gnt-instance commands
  67 ~~~~~~~~~~~~~~~~~~~~~
  68
  69 The commands for gnt-instance will be modified and extended to allow
  70 for the new functionality:
  71
  72 - the add command will be extended to support the new device and
  73   hypervisor options,
  74 - the modify command continues to handle all modifications to
  75   instances, but will be extended with new arguments for handling
  76   devices.
  77
  78 Network Device Options
  79 ~~~~~~~~~~~~~~~~~~~~~~
  80
  81 The generic format of the network device option is:
  82
  83   --net $DEVNUM[:$OPTION=$VALUE][,$OPTION=VALUE]
  84
  85 :$DEVNUM: device number, unsigned integer, starting at 0,
  86 :$OPTION: device option, string,
  87 :$VALUE: device option value, string.
  88
  89 Currently, the following device options will be defined (open to
  90 further changes):
  91
  92 :mac: MAC address of the network interface, accepts either a valid
  93   MAC address or the string 'auto'. If 'auto' is specified, a new MAC
  94   address will be generated randomly. If the mac device option is not
  95   specified, the default value 'auto' is assumed.
  96 :bridge: network bridge the network interface is connected
  97   to. Accepts either a valid bridge name (the specified bridge must
  98   exist on the node(s)) as string or the string 'auto'. If 'auto' is
  99   specified, the default brigde is used. If the bridge option is not
 100   specified, the default value 'auto' is assumed.
 101
 102 Disk Device Options
 103 ~~~~~~~~~~~~~~~~~~~
 104
 105 The generic format of the disk device option is:
 106
 107   --disk $DEVNUM[:$OPTION=$VALUE][,$OPTION=VALUE]
 108
 109 :$DEVNUM: device number, unsigned integer, starting at 0,
 110 :$OPTION: device option, string,
 111 :$VALUE: device option value, string.
 112
 113 Currently, the following device options will be defined (open to
 114 further changes):
 115
 116 :size: size of the disk device, either a positive number, specifying
 117   the disk size in mebibytes, or a number followed by a magnitude suffix
 118   (M for mebibytes, G for gibibytes). Also accepts the string 'auto' in
 119   which case the default disk size will be used. If the size option is
 120   not specified, 'auto' is assumed. This option is not valid for all
 121   disk layout types.
 122 :access: access mode of the disk device, a single letter, valid values
 123   are:
 124
 125   - w: read/write access to the disk device or
 126   - r: read-only access to the disk device.
 127
 128   If the access mode is not specified, the default mode of read/write
 129   access will be configured.
 130 :path: path to the image file for the disk device, string. No default
 131   exists. This option is not valid for all disk layout types.
 132
 133 Adding devices
 134 ~~~~~~~~~~~~~~
 135
 136 To add devices to an already existing instance, use the device type
 137 specific option to gnt-instance modify. Currently, there are two
 138 device type specific options supported:
 139
 140 :--net: for network interface cards
 141 :--disk: for disk devices
 142
 143 The syntax to the device specific options is similiar to the generic
 144 device options, but instead of specifying a device number like for
 145 gnt-instance add, you specify the magic string add. The new device
 146 will always be appended at the end of the list of devices of this type
 147 for the specified instance, e.g. if the instance has disk devices 0,1
 148 and 2, the newly added disk device will be disk device 3.
 149
 150 Example: gnt-instance modify --net add:mac=auto test-instance
 151
 152 Removing devices
 153 ~~~~~~~~~~~~~~~~
 154
 155 Removing devices from and instance is done via gnt-instance
 156 modify. The same device specific options as for adding instances are
 157 used. Instead of a device number and further device options, only the
 158 magic string remove is specified. It will always remove the last
 159 device in the list of devices of this type for the instance specified,
 160 e.g. if the instance has disk devices 0, 1, 2 and 3, the disk device
 161 number 3 will be removed.
 162
 163 Example: gnt-instance modify --net remove test-instance
 164
 165 Modifying devices
 166 ~~~~~~~~~~~~~~~~~
 167
 168 Modifying devices is also done with device type specific options to
 169 the gnt-instance modify command. There are currently two device type
 170 options supported:
 171
 172 :--net: for network interface cards
 173 :--disk: for disk devices
 174
 175 The syntax to the device specific options is similiar to the generic
 176 device options. The device number you specify identifies the device to
 177 be modified.
 178
 179 Example: gnt-instance modify --disk 2:access=r
 180
 181 Hypervisor Options
 182 ~~~~~~~~~~~~~~~~~~
 183
 184 Ganeti 2.0 will support more than one hypervisor. Different
 185 hypervisors have various options that only apply to a specific
 186 hypervisor. Those hypervisor specific options are treated specially
 187 via the --hypervisor option. The generic syntax of the hypervisor
 188 option is as follows:
 189
 190   --hypervisor $HYPERVISOR:$OPTION=$VALUE[,$OPTION=$VALUE]
 191
 192 :$HYPERVISOR: symbolic name of the hypervisor to use, string,
 193   has to match the supported hypervisors. Example: xen-pvm
 194
 195 :$OPTION: hypervisor option name, string
 196 :$VALUE: hypervisor option value, string
 197
 198 The hypervisor option for an instance can be set on instance creation
 199 time via the gnt-instance add command. If the hypervisor for an
 200 instance is not specified upon instance creation, the default
 201 hypervisor will be used.
 202
 203 Modifying hypervisor parameters
 204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 205
 206 The hypervisor parameters of an existing instance can be modified
 207 using --hypervisor option of the gnt-instance modify command. However,
 208 the hypervisor type of an existing instance can not be changed, only
 209 the particular hypervisor specific option can be changed. Therefore,
 210 the format of the option parameters has been simplified to omit the
 211 hypervisor name and only contain the comma separated list of
 212 option-value pairs.
 213
 214 Example: gnt-instance modify --hypervisor
 215 cdrom=/srv/boot.iso,boot_order=cdrom:network test-instance
 216
 217 gnt-cluster commands
 218 ~~~~~~~~~~~~~~~~~~~~
 219
 220 The command for gnt-cluster will be extended to allow setting and
 221 changing the default parameters of the cluster:
 222
 223 - The init command will be extend to support the defaults option to
 224   set the cluster defaults upon cluster initialization.
 225 - The modify command will be added to modify the cluster
 226   parameters. It will support the --defaults option to change the
 227   cluster defaults.
 228
 229 Cluster defaults
 230
 231 The generic format of the cluster default setting option is:
 232
 233   --defaults $OPTION=$VALUE[,$OPTION=$VALUE]
 234
 235 :$OPTION: cluster default option, string,
 236 :$VALUE: cluster default option value, string.
 237
 238 Currently, the following cluster default options are defined (open to
 239 further changes):
 240
 241 :hypervisor: the default hypervisor to use for new instances,
 242   string. Must be a valid hypervisor known to and supported by the
 243   cluster.
 244 :disksize: the disksize for newly created instance disks, where
 245   applicable. Must be either a positive number, in which case the unit
 246   of megabyte is assumed, or a positive number followed by a supported
 247   magnitude symbol (M for megabyte or G for gigabyte).
 248 :bridge: the default network bridge to use for newly created instance
 249   network interfaces, string. Must be a valid bridge name of a bridge
 250   existing on the node(s).
 251
 252 Hypervisor cluster defaults
 253 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 254
 255 The generic format of the hypervisor clusterwide default setting option is:
 256
 257   --hypervisor-defaults $HYPERVISOR:$OPTION=$VALUE[,$OPTION=$VALUE]
 258
 259 :$HYPERVISOR: symbolic name of the hypervisor whose defaults you want
 260   to set, string
 261 :$OPTION: cluster default option, string,
 262 :$VALUE: cluster default option value, string.