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