Import design doc for commandline arguments

Reviewed-by: iustinp

diff --git a/doc/design-2.0-commandline-parameters.rst b/doc/design-2.0-commandline-parameters.rst
new file mode 100644 (file)
index 0000000..76e9b96
--- /dev/null
+++ b/doc/design-2.0-commandline-parameters.rst
@@ -0,0 +1,263 @@
+Ganeti 2.0 commandline arguments
+================================
+
+.. contents::
+
+Objective
+---------
+
+Ganeti 2.0 introduces several new features as well as new ways to
+handle instance ressources like disks or network interfaces. This
+requires some noticable changes in the way commandline arguments are
+handled.
+
+- extend and modify commandline syntax to support new features
+- ensure consistent patterns in commandline arguments to reduce cognitive load
+
+Background
+----------
+
+Ganeti 2.0 introduces several changes in handling instances ressources
+such as disks and network card as well as some new features. Due to
+these changes, the commandline syntax needs to be changed
+significantly since the existing commandline syntax is not able to
+cover the changes.
+
+Overview
+--------
+
+Changes for Ganeti 2.0 that require changes for the commandline
+syntax, in no particular order:
+
+- flexible instance disk handling: support a variable number of disks
+  with varying properties per instance,
+- flexible instance network interface handling: support a variable
+  number of network interfaces with varying properties per instance
+- multiple hypervisors: multiple hypervisors can be active on the same
+  cluster, each supporting different parameters,
+- support for device type CDROM (via ISO image)
+
+Detailed Design
+---------------
+
+There are several areas of Ganeti where the commandline arguments will change:
+
+- Cluster configuration
+
+  - cluster initialization
+  - cluster default configuration
+
+- Instance configuration
+
+  - handling of network cards for instances,
+  - handling of disks for instances,
+  - handling of CDROM devices and
+  - handling of hypervisor specific options.
+
+Notes about device removal/addition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To avoid problems with device location changes (e.g. second network
+interface of the instance becoming the first or third and the like)
+the list of network/disk devices is treated as a stack, i.e. devices
+can only be added/removed at the end of the list of devices of each
+class (disk or network) for each instance.
+
+gnt-instance commands
+~~~~~~~~~~~~~~~~~~~~~
+
+The commands for gnt-instance will be modified and extended to allow
+for the new functionality:
+
+- the add command will be extended to support the new device and
+  hypervisor options,
+- the modify command continues to handle all modifications to
+  instances, but will be extended with new arguments for handling
+  devices.
+
+Network Device Options
+~~~~~~~~~~~~~~~~~~~~~~
+
+The generic format of the network device option is:
+
+  --net $DEVNUM[:$OPTION=$VALUE][,$OPTION=VALUE]
+
+:$DEVNUM: device number, unsigned integer, starting at 0,
+:$OPTION: device option, string,
+:$VALUE: device option value, string.
+
+Currently, the following device options will be defined (open to
+further changes):
+
+:mac: MAC address of the network interface, accepts either a valid
+  MAC address or the string 'auto'. If 'auto' is specified, a new MAC
+  address will be generated randomly. If the mac device option is not
+  specified, the default value 'auto' is assumed.
+:bridge: network bridge the network interface is connected
+  to. Accepts either a valid bridge name (the specified bridge must
+  exist on the node(s)) as string or the string 'auto'. If 'auto' is
+  specified, the default brigde is used. If the bridge option is not
+  specified, the default value 'auto' is assumed.
+
+Disk Device Options
+~~~~~~~~~~~~~~~~~~~
+
+The generic format of the disk device option is:
+
+  --disk $DEVNUM:[$OPTION=$VALUE][,$OPTION=VALUE]
+
+:$DEVNUM: device number, unsigned integer, starting at 0,
+:$OPTION: device option, string,
+:$VALUE: device option value, string.
+
+Currently, the following device options will be defined (open to
+further changes):
+
+:size: size of the disk device, either a positive number, specifying
+  the disk size in mebibytes, or a number followed by a magnitude suffix
+  (M for megabytes, G for gigabytes). Also accepts the string 'auto' in
+  which case the default disk size will be used. If the size option is
+  not specified, 'auto' is assumed. This option is not valid for all
+  disk layout types.
+:access: access mode of the disk device, a single letter, valid values
+  are:
+
+  - w: read/write access to the disk device or
+  - r: read-only access to the disk device.
+
+  If the access mode is not specified, the default mode of read/write
+  access will be configured.
+:path: path to the image file for the disk device, string. No default
+  exists. This option is not valid for all disk layout types.
+
+Adding devices
+~~~~~~~~~~~~~~
+
+To add devices to an already existing instance, use the device type
+specific option to gnt-instance modify. Currently, there are two
+device type specific options supported:
+
+:--net: for network interface cards
+:--disk: for disk devices
+
+The syntax to the device specific options is similiar to the generic
+device options, but instead of specifying a device number like for
+gnt-instance add, you specify the magic string add. The new device
+will always be appended at the end of the list of devices of this type
+for the specified instance, e.g. if the instance has disk devices 0,1
+and 2, the newly added disk device will be disk device 3.
+
+Example: gnt-instance modify --net add:mac=auto test-instance
+
+Removing devices
+~~~~~~~~~~~~~~~~
+
+Removing devices from and instance is done via gnt-instance
+modify. The same device specific options as for adding instances are
+used. Instead of a device number and further device options, only the
+magic string remove is specified. It will always remove the last
+device in the list of devices of this type for the instance specified,
+e.g. if the instance has disk devices 0, 1, 2 and 3, the disk device
+number 3 will be removed.
+
+Example: gnt-instance modify --net remove test-instance
+
+Modifying devices
+~~~~~~~~~~~~~~~~~
+
+Modifying devices is also done with device type specific options to
+the gnt-instance modify command. There are currently two device type
+options supported:
+
+:--net: for network interface cards
+:--disk: for disk devices
+
+The syntax to the device specific options is similiar to the generic
+device options. The device number you specify identifies the device to
+be modified.
+
+Example: gnt-instance modify --disk 2:access=r
+
+Hypervisor Options
+~~~~~~~~~~~~~~~~~~
+
+Ganeti 2.0 will support more than one hypervisor. Different
+hypervisors have various options that only apply to a specific
+hypervisor. Those hypervisor specific options are treated specially
+via the --hypervisor option. The generic syntax of the hypervisor
+option is as follows:
+
+  --hypervisor $HYPERVISOR:$OPTION=$VALUE[,$OPTION=$VALUE]
+
+:$HYPERVISOR: symbolic name of the hypervisor to use, string,
+  has to match the supported hypervisors. Example: xen-3.0
+
+:$OPTION: hypervisor option name, string
+:$VALUE: hypervisor option value, string
+
+The hypervisor option for an instance can be set on instance creation
+time via the gnt-instance add command. If the hypervisor for an
+instance is not specified upon instance creation, the default
+hypervisor will be used.
+
+Modifying hypervisor parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The hypervisor parameters of an existing instance can be modified
+using --hypervisor option of the gnt-instance modify command. However,
+the hypervisor type of an existing instance can not be changed, only
+the particular hypervisor specific option can be changed. Therefore,
+the format of the option parameters has been simplified to omit the
+hypervisor name and only contain the comma separated list of
+option-value pairs.
+
+Example: gnt-instance modify --hypervisor
+cdrom=/srv/boot.iso,boot_order=cdrom:network test-instance
+
+gnt-cluster commands
+~~~~~~~~~~~~~~~~~~~~
+
+The command for gnt-cluster will be extended to allow setting and
+changing the default parameters of the cluster:
+
+- The init command will be extend to support the defaults option to
+  set the cluster defaults upon cluster initialization.
+- The modify command will be added to modify the cluster
+  parameters. It will support the --defaults option to change the
+  cluster defaults.
+
+Cluster defaults
+
+The generic format of the cluster default setting option is:
+
+  --defaults $OPTION=$VALUE[,$OPTION=$VALUE]
+
+:$OPTION: cluster default option, string,
+:$VALUE: cluster default option value, string.
+
+Currently, the following cluster default options are defined (open to
+further changes):
+
+:hypervisor: the default hypervisor to use for new instances,
+  string. Must be a valid hypervisor known to and supported by the
+  cluster.
+:disksize: the disksize for newly created instance disks, where
+  applicable. Must be either a positive number, in which case the unit
+  of megabyte is assumed, or a positive number followed by a supported
+  magnitude symbol (M for megabyte or G for gigabyte).
+:bridge: the default network bridge to use for newly created instance
+  network interfaces, string. Must be a valid bridge name of a bridge
+  existing on the node(s).
+
+Hypervisor cluster defaults
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The generic format of the hypervisor clusterwide default setting option is:
+
+  --hypervisor-defaults $HYPERVISOR:$OPTION=$VALUE[,$OPTION=$VALUE]
+
+:$HYPERVISOR: symbolic name of the hypervisor whose defaults you want
+  to set, string
+:$OPTION: cluster default option, string,
+:$VALUE: cluster default option value, string.
+