root / doc / design-2.0-commandline-parameters.rst @ cd55576a
History | View | Annotate | Download (9.1 kB)
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-3.0 |
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. |
263 |
|