4 # Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Google Inc.
6 # This program is free software; you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation; either version 2 of the License, or
9 # (at your option) any later version.
11 # This program is distributed in the hope that it will be useful, but
12 # WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 # General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with this program; if not, write to the Free Software
18 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 """RPC definitions for communication between master and node daemons.
23 RPC definition fields:
26 - L{SINGLE} for single-node calls, L{MULTI} for multi-node
27 - Timeout (e.g. L{TMO_NORMAL}), or callback receiving all arguments in a
28 tuple to calculate timeout
29 - List of arguments as tuples
32 - Argument kind used for encoding/decoding
33 - Description for docstring (can be C{None})
35 - Return value wrapper (e.g. for deserializing into L{objects}-based objects)
36 - Short call description for docstring
40 from ganeti import utils
41 from ganeti import objects
44 # Guidelines for choosing timeouts:
45 # - call used during watcher: timeout of 1min, _TMO_URGENT
46 # - trivial (but be sure it is trivial) (e.g. reading a file): 5min, _TMO_FAST
47 # - other calls: 15 min, _TMO_NORMAL
48 # - special calls (instance add, etc.): either _TMO_SLOW (1h) or huge timeouts
49 TMO_URGENT = 60 # one minute
50 TMO_FAST = 5 * 60 # five minutes
51 TMO_NORMAL = 15 * 60 # 15 minutes
52 TMO_SLOW = 3600 # one hour
56 SINGLE = "single-node"
59 # Constants for encoding/decoding
68 ED_FINALIZE_EXPORT_DISKS,
70 ED_BLOCKDEV_RENAME) = range(1, 12)
74 """Converts list of calls to dictionary.
77 return utils.SequenceToDict(calls)
80 def _MigrationStatusPostProc(result):
81 """Post-processor for L{rpc.RpcRunner.call_instance_get_migration_status}.
84 if not result.fail_msg and result.payload is not None:
85 result.payload = objects.MigrationStatus.FromDict(result.payload)
89 def _BlockdevFindPostProc(result):
90 """Post-processor for L{rpc.RpcRunner.call_blockdev_find}.
93 if not result.fail_msg and result.payload is not None:
94 result.payload = objects.BlockDevStatus.FromDict(result.payload)
98 def _BlockdevGetMirrorStatusPostProc(result):
99 """Post-processor for L{rpc.RpcRunner.call_blockdev_getmirrorstatus}.
102 if not result.fail_msg:
103 result.payload = map(objects.BlockDevStatus.FromDict, result.payload)
107 def _BlockdevGetMirrorStatusMultiPostProc(result):
108 """Post-processor for L{rpc.RpcRunner.call_blockdev_getmirrorstatus_multi}.
111 if not result.fail_msg:
112 for idx, (success, status) in enumerate(result.payload):
114 result.payload[idx] = (success, objects.BlockDevStatus.FromDict(status))
119 def _OsGetPostProc(result):
120 """Post-processor for L{rpc.RpcRunner.call_os_get}.
123 if not result.fail_msg and isinstance(result.payload, dict):
124 result.payload = objects.OS.FromDict(result.payload)
128 def _ImpExpStatusPostProc(result):
129 """Post-processor for import/export status.
131 @rtype: Payload containing list of L{objects.ImportExportStatus} instances
132 @return: Returns a list of the state of each named import/export or None if
133 a status couldn't be retrieved
136 if not result.fail_msg:
139 for i in result.payload:
143 decoded.append(objects.ImportExportStatus.FromDict(i))
145 result.payload = decoded
150 def _TestDelayTimeout((duration, )):
151 """Calculate timeout for "test_delay" RPC.
154 return int(duration + 5)
157 _FILE_STORAGE_CALLS = [
158 ("file_storage_dir_create", SINGLE, TMO_FAST, [
159 ("file_storage_dir", None, "File storage directory"),
160 ], None, "Create the given file storage directory"),
161 ("file_storage_dir_remove", SINGLE, TMO_FAST, [
162 ("file_storage_dir", None, "File storage directory"),
163 ], None, "Remove the given file storage directory"),
164 ("file_storage_dir_rename", SINGLE, TMO_FAST, [
165 ("old_file_storage_dir", None, "Old name"),
166 ("new_file_storage_dir", None, "New name"),
167 ], None, "Rename file storage directory"),
171 ("storage_list", MULTI, TMO_NORMAL, [
172 ("su_name", None, None),
173 ("su_args", None, None),
174 ("name", None, None),
175 ("fields", None, None),
176 ], None, "Get list of storage units"),
177 ("storage_modify", SINGLE, TMO_NORMAL, [
178 ("su_name", None, None),
179 ("su_args", None, None),
180 ("name", None, None),
181 ("changes", None, None),
182 ], None, "Modify a storage unit"),
183 ("storage_execute", SINGLE, TMO_NORMAL, [
184 ("su_name", None, None),
185 ("su_args", None, None),
186 ("name", None, None),
188 ], None, "Executes an operation on a storage unit"),
192 ("instance_info", SINGLE, TMO_URGENT, [
193 ("instance", None, "Instance name"),
194 ("hname", None, "Hypervisor type"),
195 ], None, "Returns information about a single instance"),
196 ("all_instances_info", MULTI, TMO_URGENT, [
197 ("hypervisor_list", None, "Hypervisors to query for instances"),
198 ], None, "Returns information about all instances on the given nodes"),
199 ("instance_list", MULTI, TMO_URGENT, [
200 ("hypervisor_list", None, "Hypervisors to query for instances"),
201 ], None, "Returns the list of running instances on the given nodes"),
202 ("instance_reboot", SINGLE, TMO_NORMAL, [
203 ("inst", ED_INST_DICT, "Instance object"),
204 ("reboot_type", None, None),
205 ("shutdown_timeout", None, None),
206 ], None, "Returns the list of running instances on the given nodes"),
207 ("instance_shutdown", SINGLE, TMO_NORMAL, [
208 ("instance", ED_INST_DICT, "Instance object"),
209 ("timeout", None, None),
210 ], None, "Stops an instance"),
211 ("instance_run_rename", SINGLE, TMO_SLOW, [
212 ("instance", ED_INST_DICT, "Instance object"),
213 ("old_name", None, None),
214 ("debug", None, None),
215 ], None, "Run the OS rename script for an instance"),
216 ("instance_migratable", SINGLE, TMO_NORMAL, [
217 ("instance", ED_INST_DICT, "Instance object"),
218 ], None, "Checks whether the given instance can be migrated"),
219 ("migration_info", SINGLE, TMO_NORMAL, [
220 ("instance", ED_INST_DICT, "Instance object"),
222 "Gather the information necessary to prepare an instance migration"),
223 ("accept_instance", SINGLE, TMO_NORMAL, [
224 ("instance", ED_INST_DICT, "Instance object"),
225 ("info", None, "Result for the call_migration_info call"),
226 ("target", None, "Target hostname (usually an IP address)"),
227 ], None, "Prepare a node to accept an instance"),
228 ("instance_finalize_migration_dst", SINGLE, TMO_NORMAL, [
229 ("instance", ED_INST_DICT, "Instance object"),
230 ("info", None, "Result for the call_migration_info call"),
231 ("success", None, "Whether the migration was a success or failure"),
232 ], None, "Finalize any target-node migration specific operation"),
233 ("instance_migrate", SINGLE, TMO_SLOW, [
234 ("instance", ED_INST_DICT, "Instance object"),
235 ("target", None, "Target node name"),
236 ("live", None, "Whether the migration should be done live or not"),
237 ], None, "Migrate an instance"),
238 ("instance_finalize_migration_src", SINGLE, TMO_SLOW, [
239 ("instance", ED_INST_DICT, "Instance object"),
240 ("success", None, "Whether the migration succeeded or not"),
241 ("live", None, "Whether the user requested a live migration or not"),
242 ], None, "Finalize the instance migration on the source node"),
243 ("instance_get_migration_status", SINGLE, TMO_SLOW, [
244 ("instance", ED_INST_DICT, "Instance object"),
245 ], _MigrationStatusPostProc, "Report migration status"),
246 ("instance_start", SINGLE, TMO_NORMAL, [
247 ("instance_hvp_bep", ED_INST_DICT_HVP_BEP, None),
248 ("startup_paused", None, None),
249 ], None, "Starts an instance"),
250 ("instance_os_add", SINGLE, TMO_1DAY, [
251 ("instance_osp", ED_INST_DICT_OSP, None),
252 ("reinstall", None, None),
253 ("debug", None, None),
254 ], None, "Starts an instance"),
258 ("import_start", SINGLE, TMO_NORMAL, [
259 ("opts", ED_OBJECT_DICT, None),
260 ("instance", ED_INST_DICT, None),
261 ("component", None, None),
262 ("dest", ED_IMPEXP_IO, "Import destination"),
263 ], None, "Starts an import daemon"),
264 ("export_start", SINGLE, TMO_NORMAL, [
265 ("opts", ED_OBJECT_DICT, None),
266 ("host", None, None),
267 ("port", None, None),
268 ("instance", ED_INST_DICT, None),
269 ("component", None, None),
270 ("source", ED_IMPEXP_IO, "Export source"),
271 ], None, "Starts an export daemon"),
272 ("impexp_status", SINGLE, TMO_FAST, [
273 ("names", None, "Import/export names"),
274 ], _ImpExpStatusPostProc, "Gets the status of an import or export"),
275 ("impexp_abort", SINGLE, TMO_NORMAL, [
276 ("name", None, "Import/export name"),
277 ], None, "Aborts an import or export"),
278 ("impexp_cleanup", SINGLE, TMO_NORMAL, [
279 ("name", None, "Import/export name"),
280 ], None, "Cleans up after an import or export"),
281 ("export_info", SINGLE, TMO_FAST, [
282 ("path", None, None),
283 ], None, "Queries the export information in a given path"),
284 ("finalize_export", SINGLE, TMO_NORMAL, [
285 ("instance", ED_INST_DICT, None),
286 ("snap_disks", ED_FINALIZE_EXPORT_DISKS, None),
287 ], None, "Request the completion of an export operation"),
288 ("export_list", MULTI, TMO_FAST, [], None, "Gets the stored exports list"),
289 ("export_remove", SINGLE, TMO_FAST, [
290 ("export", None, None),
291 ], None, "Requests removal of a given export"),
295 ("x509_cert_create", SINGLE, TMO_NORMAL, [
296 ("validity", None, "Validity in seconds"),
297 ], None, "Creates a new X509 certificate for SSL/TLS"),
298 ("x509_cert_remove", SINGLE, TMO_NORMAL, [
299 ("name", None, "Certificate name"),
300 ], None, "Removes a X509 certificate"),
304 ("bdev_sizes", MULTI, TMO_URGENT, [
305 ("devices", None, None),
306 ], None, "Gets the sizes of requested block devices present on a node"),
307 ("blockdev_create", SINGLE, TMO_NORMAL, [
308 ("bdev", ED_OBJECT_DICT, None),
309 ("size", None, None),
310 ("owner", None, None),
311 ("on_primary", None, None),
312 ("info", None, None),
313 ], None, "Request creation of a given block device"),
314 ("blockdev_wipe", SINGLE, TMO_SLOW, [
315 ("bdev", ED_OBJECT_DICT, None),
316 ("offset", None, None),
317 ("size", None, None),
319 "Request wipe at given offset with given size of a block device"),
320 ("blockdev_remove", SINGLE, TMO_NORMAL, [
321 ("bdev", ED_OBJECT_DICT, None),
322 ], None, "Request removal of a given block device"),
323 ("blockdev_pause_resume_sync", SINGLE, TMO_NORMAL, [
324 ("disks", ED_OBJECT_DICT_LIST, None),
325 ("pause", None, None),
326 ], None, "Request a pause/resume of given block device"),
327 ("blockdev_assemble", SINGLE, TMO_NORMAL, [
328 ("disk", ED_OBJECT_DICT, None),
329 ("owner", None, None),
330 ("on_primary", None, None),
332 ], None, "Request assembling of a given block device"),
333 ("blockdev_shutdown", SINGLE, TMO_NORMAL, [
334 ("disk", ED_OBJECT_DICT, None),
335 ], None, "Request shutdown of a given block device"),
336 ("blockdev_addchildren", SINGLE, TMO_NORMAL, [
337 ("bdev", ED_OBJECT_DICT, None),
338 ("ndevs", ED_OBJECT_DICT_LIST, None),
339 ], None, "Request adding a list of children to a (mirroring) device"),
340 ("blockdev_removechildren", SINGLE, TMO_NORMAL, [
341 ("bdev", ED_OBJECT_DICT, None),
342 ("ndevs", ED_OBJECT_DICT_LIST, None),
343 ], None, "Request removing a list of children from a (mirroring) device"),
344 ("blockdev_close", SINGLE, TMO_NORMAL, [
345 ("instance_name", None, None),
346 ("disks", ED_OBJECT_DICT_LIST, None),
347 ], None, "Closes the given block devices"),
348 ("blockdev_getsize", SINGLE, TMO_NORMAL, [
349 ("disks", ED_OBJECT_DICT_LIST, None),
350 ], None, "Returns the size of the given disks"),
351 ("drbd_disconnect_net", MULTI, TMO_NORMAL, [
352 ("nodes_ip", None, None),
353 ("disks", ED_OBJECT_DICT_LIST, None),
354 ], None, "Disconnects the network of the given drbd devices"),
355 ("drbd_attach_net", MULTI, TMO_NORMAL, [
356 ("nodes_ip", None, None),
357 ("disks", ED_OBJECT_DICT_LIST, None),
358 ("instance_name", None, None),
359 ("multimaster", None, None),
360 ], None, "Connects the given DRBD devices"),
361 ("drbd_wait_sync", MULTI, TMO_SLOW, [
362 ("nodes_ip", None, None),
363 ("disks", ED_OBJECT_DICT_LIST, None),
364 ], None, "Waits for the synchronization of drbd devices is complete"),
365 ("blockdev_grow", SINGLE, TMO_NORMAL, [
366 ("cf_bdev", ED_OBJECT_DICT, None),
367 ("amount", None, None),
368 ("dryrun", None, None),
369 ], None, "Request a snapshot of the given block device"),
370 ("blockdev_export", SINGLE, TMO_1DAY, [
371 ("cf_bdev", ED_OBJECT_DICT, None),
372 ("dest_node", None, None),
373 ("dest_path", None, None),
374 ("cluster_name", None, None),
375 ], None, "Export a given disk to another node"),
376 ("blockdev_snapshot", SINGLE, TMO_NORMAL, [
377 ("cf_bdev", ED_OBJECT_DICT, None),
378 ], None, "Export a given disk to another node"),
379 ("blockdev_rename", SINGLE, TMO_NORMAL, [
380 ("devlist", ED_BLOCKDEV_RENAME, None),
381 ], None, "Request rename of the given block devices"),
382 ("blockdev_find", SINGLE, TMO_NORMAL, [
383 ("disk", ED_OBJECT_DICT, None),
384 ], _BlockdevFindPostProc,
385 "Request identification of a given block device"),
386 ("blockdev_getmirrorstatus", SINGLE, TMO_NORMAL, [
387 ("disks", ED_OBJECT_DICT_LIST, None),
388 ], _BlockdevGetMirrorStatusPostProc,
389 "Request status of a (mirroring) device"),
390 ("blockdev_getmirrorstatus_multi", MULTI, TMO_NORMAL, [
391 ("node_disks", ED_NODE_TO_DISK_DICT, None),
392 ], _BlockdevGetMirrorStatusMultiPostProc,
393 "Request status of (mirroring) devices from multiple nodes"),
397 ("os_diagnose", MULTI, TMO_FAST, [], None,
398 "Request a diagnose of OS definitions"),
399 ("os_validate", MULTI, TMO_FAST, [
400 ("required", None, None),
401 ("name", None, None),
402 ("checks", None, None),
403 ("params", None, None),
404 ], None, "Run a validation routine for a given OS"),
405 ("os_get", SINGLE, TMO_FAST, [
406 ("name", None, None),
407 ], _OsGetPostProc, "Returns an OS definition"),
411 ("node_has_ip_address", SINGLE, TMO_FAST, [
412 ("address", None, "IP address"),
413 ], None, "Checks if a node has the given IP address"),
414 ("node_info", MULTI, TMO_URGENT, [
416 "Name of the volume group to ask for disk space information"),
417 ("hypervisor_type", None,
418 "Name of the hypervisor to ask for memory information"),
419 ], None, "Return node information"),
420 ("node_verify", MULTI, TMO_NORMAL, [
421 ("checkdict", None, None),
422 ("cluster_name", None, None),
423 ], None, "Request verification of given parameters"),
424 ("node_volumes", MULTI, TMO_FAST, [], None, "Gets all volumes on node(s)"),
425 ("node_demote_from_mc", SINGLE, TMO_FAST, [], None,
426 "Demote a node from the master candidate role"),
427 ("node_powercycle", SINGLE, TMO_NORMAL, [
428 ("hypervisor", None, "Hypervisor type"),
429 ], None, "Tries to powercycle a node"),
433 ("lv_list", MULTI, TMO_URGENT, [
434 ("vg_name", None, None),
435 ], None, "Gets the logical volumes present in a given volume group"),
436 ("vg_list", MULTI, TMO_URGENT, [], None, "Gets the volume group list"),
437 ("bridges_exist", SINGLE, TMO_URGENT, [
438 ("bridges_list", None, "Bridges which must be present on remote node"),
439 ], None, "Checks if a node has all the bridges given"),
440 ("etc_hosts_modify", SINGLE, TMO_NORMAL, [
442 "Mode to operate; currently L{constants.ETC_HOSTS_ADD} or"
443 " L{constants.ETC_HOSTS_REMOVE}"),
444 ("name", None, "Hostname to be modified"),
445 ("ip", None, "IP address (L{constants.ETC_HOSTS_ADD} only)"),
446 ], None, "Modify hosts file with name"),
447 ("drbd_helper", MULTI, TMO_URGENT, [], None, "Gets DRBD helper"),
448 ("run_oob", SINGLE, TMO_NORMAL, [
449 ("oob_program", None, None),
450 ("command", None, None),
451 ("remote_node", None, None),
452 ("timeout", None, None),
453 ], None, "Runs out-of-band command"),
454 ("hooks_runner", MULTI, TMO_NORMAL, [
455 ("hpath", None, None),
456 ("phase", None, None),
458 ], None, "Call the hooks runner"),
459 ("iallocator_runner", SINGLE, TMO_NORMAL, [
460 ("name", None, "Iallocator name"),
461 ("idata", None, "JSON-encoded input string"),
462 ], None, "Call an iallocator on a remote node"),
463 ("test_delay", MULTI, _TestDelayTimeout, [
464 ("duration", None, None),
465 ], None, "Sleep for a fixed time on given node(s)"),
466 ("hypervisor_validate_params", MULTI, TMO_NORMAL, [
467 ("hvname", None, "Hypervisor name"),
468 ("hvfull", None, "Parameters to be validated"),
469 ], None, "Validate hypervisor params"),
473 "RpcClientDefault": \
474 _Prepare(_IMPEXP_CALLS + _X509_CALLS + _OS_CALLS + _NODE_CALLS +
475 _FILE_STORAGE_CALLS + _MISC_CALLS + _INSTANCE_CALLS +
476 _BLOCKDEV_CALLS + _STORAGE_CALLS),
477 "RpcClientJobQueue": _Prepare([
478 ("jobqueue_update", MULTI, TMO_URGENT, [
479 ("file_name", None, None),
480 ("content", ED_COMPRESS, None),
481 ], None, "Update job queue file"),
482 ("jobqueue_purge", SINGLE, TMO_NORMAL, [], None, "Purge job queue"),
483 ("jobqueue_rename", MULTI, TMO_URGENT, [
484 ("rename", None, None),
485 ], None, "Rename job queue file"),
487 "RpcClientBootstrap": _Prepare([
488 ("node_start_master_daemons", SINGLE, TMO_FAST, [
489 ("no_voting", None, None),
490 ], None, "Starts master daemons on a node"),
491 ("node_activate_master_ip", SINGLE, TMO_FAST, [
492 ("master_params", ED_OBJECT_DICT, "Network parameters of the master"),
493 ("use_external_mip_script", None,
494 "Whether to use the user-provided master IP address setup script"),
496 "Activates master IP on a node"),
497 ("node_stop_master", SINGLE, TMO_FAST, [], None,
498 "Deactivates master IP and stops master daemons on a node"),
499 ("node_deactivate_master_ip", SINGLE, TMO_FAST, [
500 ("master_params", ED_OBJECT_DICT, "Network parameters of the master"),
501 ("use_external_mip_script", None,
502 "Whether to use the user-provided master IP address setup script"),
504 "Deactivates master IP on a node"),
505 ("node_change_master_netmask", SINGLE, TMO_FAST, [
506 ("old_netmask", None, "The old value of the netmask"),
507 ("netmask", None, "The new value of the netmask"),
508 ("master_ip", None, "The master IP"),
509 ("master_netdev", None, "The master network device"),
510 ], None, "Change master IP netmask"),
511 ("node_leave_cluster", SINGLE, TMO_NORMAL, [
512 ("modify_ssh_setup", None, None),
513 ], None, "Requests a node to clean the cluster information it has"),
514 ("master_info", MULTI, TMO_URGENT, [], None, "Query master info"),
515 ("version", MULTI, TMO_URGENT, [], None, "Query node version"),
517 "RpcClientConfig": _Prepare([
518 ("upload_file", MULTI, TMO_NORMAL, [
519 ("file_name", ED_FILE_DETAILS, None),
520 ], None, "Upload a file"),
521 ("write_ssconf_files", MULTI, TMO_NORMAL, [
522 ("values", None, None),
523 ], None, "Write ssconf files"),