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 - Name resolver option(s), can be callable receiving all arguments in a tuple
28 - Timeout (e.g. L{TMO_NORMAL}), or callback receiving all arguments in a
29 tuple to calculate timeout
30 - List of arguments as tuples
33 - Argument kind used for encoding/decoding
34 - Description for docstring (can be C{None})
36 - Custom body encoder (e.g. for preparing per-node bodies)
37 - Return value wrapper (e.g. for deserializing into L{objects}-based objects)
38 - Short call description for docstring
42 from ganeti import utils
43 from ganeti import objects
46 # Guidelines for choosing timeouts:
47 # - call used during watcher: timeout of 1min, _TMO_URGENT
48 # - trivial (but be sure it is trivial) (e.g. reading a file): 5min, _TMO_FAST
49 # - other calls: 15 min, _TMO_NORMAL
50 # - special calls (instance add, etc.): either _TMO_SLOW (1h) or huge timeouts
51 TMO_URGENT = 60 # one minute
52 TMO_FAST = 5 * 60 # five minutes
53 TMO_NORMAL = 15 * 60 # 15 minutes
54 TMO_SLOW = 3600 # one hour
58 SINGLE = "single-node"
61 ACCEPT_OFFLINE_NODE = object()
63 # Constants for encoding/decoding
72 ED_FINALIZE_EXPORT_DISKS,
74 ED_BLOCKDEV_RENAME) = range(1, 12)
78 """Converts list of calls to dictionary.
81 return utils.SequenceToDict(calls)
84 def _MigrationStatusPostProc(result):
85 """Post-processor for L{rpc.RpcRunner.call_instance_get_migration_status}.
88 if not result.fail_msg and result.payload is not None:
89 result.payload = objects.MigrationStatus.FromDict(result.payload)
93 def _BlockdevFindPostProc(result):
94 """Post-processor for L{rpc.RpcRunner.call_blockdev_find}.
97 if not result.fail_msg and result.payload is not None:
98 result.payload = objects.BlockDevStatus.FromDict(result.payload)
102 def _BlockdevGetMirrorStatusPostProc(result):
103 """Post-processor for L{rpc.RpcRunner.call_blockdev_getmirrorstatus}.
106 if not result.fail_msg:
107 result.payload = map(objects.BlockDevStatus.FromDict, result.payload)
111 def _BlockdevGetMirrorStatusMultiPreProc(node, args):
112 """Prepares the appropriate node values for blockdev_getmirrorstatus_multi.
115 # there should be only one argument to this RPC, already holding a
116 # node->disks dictionary, we just need to extract the value for the
118 assert len(args) == 1
119 return [args[0][node]]
122 def _BlockdevGetMirrorStatusMultiPostProc(result):
123 """Post-processor for L{rpc.RpcRunner.call_blockdev_getmirrorstatus_multi}.
126 if not result.fail_msg:
127 for idx, (success, status) in enumerate(result.payload):
129 result.payload[idx] = (success, objects.BlockDevStatus.FromDict(status))
134 def _OsGetPostProc(result):
135 """Post-processor for L{rpc.RpcRunner.call_os_get}.
138 if not result.fail_msg and isinstance(result.payload, dict):
139 result.payload = objects.OS.FromDict(result.payload)
143 def _ImpExpStatusPostProc(result):
144 """Post-processor for import/export status.
146 @rtype: Payload containing list of L{objects.ImportExportStatus} instances
147 @return: Returns a list of the state of each named import/export or None if
148 a status couldn't be retrieved
151 if not result.fail_msg:
154 for i in result.payload:
158 decoded.append(objects.ImportExportStatus.FromDict(i))
160 result.payload = decoded
165 def _TestDelayTimeout((duration, )):
166 """Calculate timeout for "test_delay" RPC.
169 return int(duration + 5)
172 _FILE_STORAGE_CALLS = [
173 ("file_storage_dir_create", SINGLE, None, TMO_FAST, [
174 ("file_storage_dir", None, "File storage directory"),
175 ], None, None, "Create the given file storage directory"),
176 ("file_storage_dir_remove", SINGLE, None, TMO_FAST, [
177 ("file_storage_dir", None, "File storage directory"),
178 ], None, None, "Remove the given file storage directory"),
179 ("file_storage_dir_rename", SINGLE, None, TMO_FAST, [
180 ("old_file_storage_dir", None, "Old name"),
181 ("new_file_storage_dir", None, "New name"),
182 ], None, None, "Rename file storage directory"),
186 ("storage_list", MULTI, None, TMO_NORMAL, [
187 ("su_name", None, None),
188 ("su_args", None, None),
189 ("name", None, None),
190 ("fields", None, None),
191 ], None, None, "Get list of storage units"),
192 ("storage_modify", SINGLE, None, TMO_NORMAL, [
193 ("su_name", None, None),
194 ("su_args", None, None),
195 ("name", None, None),
196 ("changes", None, None),
197 ], None, None, "Modify a storage unit"),
198 ("storage_execute", SINGLE, None, TMO_NORMAL, [
199 ("su_name", None, None),
200 ("su_args", None, None),
201 ("name", None, None),
203 ], None, None, "Executes an operation on a storage unit"),
207 ("instance_info", SINGLE, None, TMO_URGENT, [
208 ("instance", None, "Instance name"),
209 ("hname", None, "Hypervisor type"),
210 ], None, None, "Returns information about a single instance"),
211 ("all_instances_info", MULTI, None, TMO_URGENT, [
212 ("hypervisor_list", None, "Hypervisors to query for instances"),
214 "Returns information about all instances on the given nodes"),
215 ("instance_list", MULTI, None, TMO_URGENT, [
216 ("hypervisor_list", None, "Hypervisors to query for instances"),
217 ], None, None, "Returns the list of running instances on the given nodes"),
218 ("instance_reboot", SINGLE, None, TMO_NORMAL, [
219 ("inst", ED_INST_DICT, "Instance object"),
220 ("reboot_type", None, None),
221 ("shutdown_timeout", None, None),
222 ], None, None, "Returns the list of running instances on the given nodes"),
223 ("instance_shutdown", SINGLE, None, TMO_NORMAL, [
224 ("instance", ED_INST_DICT, "Instance object"),
225 ("timeout", None, None),
226 ], None, None, "Stops an instance"),
227 ("instance_balloon_memory", SINGLE, None, TMO_NORMAL, [
228 ("instance", ED_INST_DICT, "Instance object"),
229 ("memory", None, None),
230 ], None, None, "Modify the amount of an instance's runtime memory"),
231 ("instance_run_rename", SINGLE, None, TMO_SLOW, [
232 ("instance", ED_INST_DICT, "Instance object"),
233 ("old_name", None, None),
234 ("debug", None, None),
235 ], None, None, "Run the OS rename script for an instance"),
236 ("instance_migratable", SINGLE, None, TMO_NORMAL, [
237 ("instance", ED_INST_DICT, "Instance object"),
238 ], None, None, "Checks whether the given instance can be migrated"),
239 ("migration_info", SINGLE, None, TMO_NORMAL, [
240 ("instance", ED_INST_DICT, "Instance object"),
242 "Gather the information necessary to prepare an instance migration"),
243 ("accept_instance", SINGLE, None, TMO_NORMAL, [
244 ("instance", ED_INST_DICT, "Instance object"),
245 ("info", None, "Result for the call_migration_info call"),
246 ("target", None, "Target hostname (usually an IP address)"),
247 ], None, None, "Prepare a node to accept an instance"),
248 ("instance_finalize_migration_dst", SINGLE, None, TMO_NORMAL, [
249 ("instance", ED_INST_DICT, "Instance object"),
250 ("info", None, "Result for the call_migration_info call"),
251 ("success", None, "Whether the migration was a success or failure"),
252 ], None, None, "Finalize any target-node migration specific operation"),
253 ("instance_migrate", SINGLE, None, TMO_SLOW, [
254 ("instance", ED_INST_DICT, "Instance object"),
255 ("target", None, "Target node name"),
256 ("live", None, "Whether the migration should be done live or not"),
257 ], None, None, "Migrate an instance"),
258 ("instance_finalize_migration_src", SINGLE, None, TMO_SLOW, [
259 ("instance", ED_INST_DICT, "Instance object"),
260 ("success", None, "Whether the migration succeeded or not"),
261 ("live", None, "Whether the user requested a live migration or not"),
262 ], None, None, "Finalize the instance migration on the source node"),
263 ("instance_get_migration_status", SINGLE, None, TMO_SLOW, [
264 ("instance", ED_INST_DICT, "Instance object"),
265 ], None, _MigrationStatusPostProc, "Report migration status"),
266 ("instance_start", SINGLE, None, TMO_NORMAL, [
267 ("instance_hvp_bep", ED_INST_DICT_HVP_BEP, None),
268 ("startup_paused", None, None),
269 ], None, None, "Starts an instance"),
270 ("instance_os_add", SINGLE, None, TMO_1DAY, [
271 ("instance_osp", ED_INST_DICT_OSP, None),
272 ("reinstall", None, None),
273 ("debug", None, None),
274 ], None, None, "Starts an instance"),
278 ("import_start", SINGLE, None, TMO_NORMAL, [
279 ("opts", ED_OBJECT_DICT, None),
280 ("instance", ED_INST_DICT, None),
281 ("component", None, None),
282 ("dest", ED_IMPEXP_IO, "Import destination"),
283 ], None, None, "Starts an import daemon"),
284 ("export_start", SINGLE, None, TMO_NORMAL, [
285 ("opts", ED_OBJECT_DICT, None),
286 ("host", None, None),
287 ("port", None, None),
288 ("instance", ED_INST_DICT, None),
289 ("component", None, None),
290 ("source", ED_IMPEXP_IO, "Export source"),
291 ], None, None, "Starts an export daemon"),
292 ("impexp_status", SINGLE, None, TMO_FAST, [
293 ("names", None, "Import/export names"),
294 ], None, _ImpExpStatusPostProc, "Gets the status of an import or export"),
295 ("impexp_abort", SINGLE, None, TMO_NORMAL, [
296 ("name", None, "Import/export name"),
297 ], None, None, "Aborts an import or export"),
298 ("impexp_cleanup", SINGLE, None, TMO_NORMAL, [
299 ("name", None, "Import/export name"),
300 ], None, None, "Cleans up after an import or export"),
301 ("export_info", SINGLE, None, TMO_FAST, [
302 ("path", None, None),
303 ], None, None, "Queries the export information in a given path"),
304 ("finalize_export", SINGLE, None, TMO_NORMAL, [
305 ("instance", ED_INST_DICT, None),
306 ("snap_disks", ED_FINALIZE_EXPORT_DISKS, None),
307 ], None, None, "Request the completion of an export operation"),
308 ("export_list", MULTI, None, TMO_FAST, [], None, None,
309 "Gets the stored exports list"),
310 ("export_remove", SINGLE, None, TMO_FAST, [
311 ("export", None, None),
312 ], None, None, "Requests removal of a given export"),
316 ("x509_cert_create", SINGLE, None, TMO_NORMAL, [
317 ("validity", None, "Validity in seconds"),
318 ], None, None, "Creates a new X509 certificate for SSL/TLS"),
319 ("x509_cert_remove", SINGLE, None, TMO_NORMAL, [
320 ("name", None, "Certificate name"),
321 ], None, None, "Removes a X509 certificate"),
325 ("bdev_sizes", MULTI, None, TMO_URGENT, [
326 ("devices", None, None),
328 "Gets the sizes of requested block devices present on a node"),
329 ("blockdev_create", SINGLE, None, TMO_NORMAL, [
330 ("bdev", ED_OBJECT_DICT, None),
331 ("size", None, None),
332 ("owner", None, None),
333 ("on_primary", None, None),
334 ("info", None, None),
335 ], None, None, "Request creation of a given block device"),
336 ("blockdev_wipe", SINGLE, None, TMO_SLOW, [
337 ("bdev", ED_OBJECT_DICT, None),
338 ("offset", None, None),
339 ("size", None, None),
341 "Request wipe at given offset with given size of a block device"),
342 ("blockdev_remove", SINGLE, None, TMO_NORMAL, [
343 ("bdev", ED_OBJECT_DICT, None),
344 ], None, None, "Request removal of a given block device"),
345 ("blockdev_pause_resume_sync", SINGLE, None, TMO_NORMAL, [
346 ("disks", ED_OBJECT_DICT_LIST, None),
347 ("pause", None, None),
348 ], None, None, "Request a pause/resume of given block device"),
349 ("blockdev_assemble", SINGLE, None, TMO_NORMAL, [
350 ("disk", ED_OBJECT_DICT, None),
351 ("owner", None, None),
352 ("on_primary", None, None),
354 ], None, None, "Request assembling of a given block device"),
355 ("blockdev_shutdown", SINGLE, None, TMO_NORMAL, [
356 ("disk", ED_OBJECT_DICT, None),
357 ], None, None, "Request shutdown of a given block device"),
358 ("blockdev_addchildren", SINGLE, None, TMO_NORMAL, [
359 ("bdev", ED_OBJECT_DICT, None),
360 ("ndevs", ED_OBJECT_DICT_LIST, None),
362 "Request adding a list of children to a (mirroring) device"),
363 ("blockdev_removechildren", SINGLE, None, TMO_NORMAL, [
364 ("bdev", ED_OBJECT_DICT, None),
365 ("ndevs", ED_OBJECT_DICT_LIST, None),
367 "Request removing a list of children from a (mirroring) device"),
368 ("blockdev_close", SINGLE, None, TMO_NORMAL, [
369 ("instance_name", None, None),
370 ("disks", ED_OBJECT_DICT_LIST, None),
371 ], None, None, "Closes the given block devices"),
372 ("blockdev_getsize", SINGLE, None, TMO_NORMAL, [
373 ("disks", ED_OBJECT_DICT_LIST, None),
374 ], None, None, "Returns the size of the given disks"),
375 ("drbd_disconnect_net", MULTI, None, TMO_NORMAL, [
376 ("nodes_ip", None, None),
377 ("disks", ED_OBJECT_DICT_LIST, None),
378 ], None, None, "Disconnects the network of the given drbd devices"),
379 ("drbd_attach_net", MULTI, None, TMO_NORMAL, [
380 ("nodes_ip", None, None),
381 ("disks", ED_OBJECT_DICT_LIST, None),
382 ("instance_name", None, None),
383 ("multimaster", None, None),
384 ], None, None, "Connects the given DRBD devices"),
385 ("drbd_wait_sync", MULTI, None, TMO_SLOW, [
386 ("nodes_ip", None, None),
387 ("disks", ED_OBJECT_DICT_LIST, None),
389 "Waits for the synchronization of drbd devices is complete"),
390 ("blockdev_grow", SINGLE, None, TMO_NORMAL, [
391 ("cf_bdev", ED_OBJECT_DICT, None),
392 ("amount", None, None),
393 ("dryrun", None, None),
394 ], None, None, "Request a snapshot of the given block device"),
395 ("blockdev_export", SINGLE, None, TMO_1DAY, [
396 ("cf_bdev", ED_OBJECT_DICT, None),
397 ("dest_node", None, None),
398 ("dest_path", None, None),
399 ("cluster_name", None, None),
400 ], None, None, "Export a given disk to another node"),
401 ("blockdev_snapshot", SINGLE, None, TMO_NORMAL, [
402 ("cf_bdev", ED_OBJECT_DICT, None),
403 ], None, None, "Export a given disk to another node"),
404 ("blockdev_rename", SINGLE, None, TMO_NORMAL, [
405 ("devlist", ED_BLOCKDEV_RENAME, None),
406 ], None, None, "Request rename of the given block devices"),
407 ("blockdev_find", SINGLE, None, TMO_NORMAL, [
408 ("disk", ED_OBJECT_DICT, None),
409 ], None, _BlockdevFindPostProc,
410 "Request identification of a given block device"),
411 ("blockdev_getmirrorstatus", SINGLE, None, TMO_NORMAL, [
412 ("disks", ED_OBJECT_DICT_LIST, None),
413 ], None, _BlockdevGetMirrorStatusPostProc,
414 "Request status of a (mirroring) device"),
415 ("blockdev_getmirrorstatus_multi", MULTI, None, TMO_NORMAL, [
416 ("node_disks", ED_NODE_TO_DISK_DICT, None),
417 ], _BlockdevGetMirrorStatusMultiPreProc,
418 _BlockdevGetMirrorStatusMultiPostProc,
419 "Request status of (mirroring) devices from multiple nodes"),
423 ("os_diagnose", MULTI, None, TMO_FAST, [], None, None,
424 "Request a diagnose of OS definitions"),
425 ("os_validate", MULTI, None, TMO_FAST, [
426 ("required", None, None),
427 ("name", None, None),
428 ("checks", None, None),
429 ("params", None, None),
430 ], None, None, "Run a validation routine for a given OS"),
431 ("os_get", SINGLE, None, TMO_FAST, [
432 ("name", None, None),
433 ], None, _OsGetPostProc, "Returns an OS definition"),
437 ("node_has_ip_address", SINGLE, None, TMO_FAST, [
438 ("address", None, "IP address"),
439 ], None, None, "Checks if a node has the given IP address"),
440 ("node_info", MULTI, None, TMO_URGENT, [
442 "Names of the volume groups to ask for disk space information"),
444 "Names of the hypervisors to ask for node information"),
445 ], None, None, "Return node information"),
446 ("node_verify", MULTI, None, TMO_NORMAL, [
447 ("checkdict", None, None),
448 ("cluster_name", None, None),
449 ], None, None, "Request verification of given parameters"),
450 ("node_volumes", MULTI, None, TMO_FAST, [], None, None,
451 "Gets all volumes on node(s)"),
452 ("node_demote_from_mc", SINGLE, None, TMO_FAST, [], None, None,
453 "Demote a node from the master candidate role"),
454 ("node_powercycle", SINGLE, ACCEPT_OFFLINE_NODE, TMO_NORMAL, [
455 ("hypervisor", None, "Hypervisor type"),
456 ], None, None, "Tries to powercycle a node"),
460 ("lv_list", MULTI, None, TMO_URGENT, [
461 ("vg_name", None, None),
462 ], None, None, "Gets the logical volumes present in a given volume group"),
463 ("vg_list", MULTI, None, TMO_URGENT, [], None, None,
464 "Gets the volume group list"),
465 ("bridges_exist", SINGLE, None, TMO_URGENT, [
466 ("bridges_list", None, "Bridges which must be present on remote node"),
467 ], None, None, "Checks if a node has all the bridges given"),
468 ("etc_hosts_modify", SINGLE, None, TMO_NORMAL, [
470 "Mode to operate; currently L{constants.ETC_HOSTS_ADD} or"
471 " L{constants.ETC_HOSTS_REMOVE}"),
472 ("name", None, "Hostname to be modified"),
473 ("ip", None, "IP address (L{constants.ETC_HOSTS_ADD} only)"),
474 ], None, None, "Modify hosts file with name"),
475 ("drbd_helper", MULTI, None, TMO_URGENT, [], None, None, "Gets DRBD helper"),
476 ("run_oob", SINGLE, None, TMO_NORMAL, [
477 ("oob_program", None, None),
478 ("command", None, None),
479 ("remote_node", None, None),
480 ("timeout", None, None),
481 ], None, None, "Runs out-of-band command"),
482 ("hooks_runner", MULTI, None, TMO_NORMAL, [
483 ("hpath", None, None),
484 ("phase", None, None),
486 ], None, None, "Call the hooks runner"),
487 ("iallocator_runner", SINGLE, None, TMO_NORMAL, [
488 ("name", None, "Iallocator name"),
489 ("idata", None, "JSON-encoded input string"),
490 ], None, None, "Call an iallocator on a remote node"),
491 ("test_delay", MULTI, None, _TestDelayTimeout, [
492 ("duration", None, None),
493 ], None, None, "Sleep for a fixed time on given node(s)"),
494 ("hypervisor_validate_params", MULTI, None, TMO_NORMAL, [
495 ("hvname", None, "Hypervisor name"),
496 ("hvfull", None, "Parameters to be validated"),
497 ], None, None, "Validate hypervisor params"),
501 "RpcClientDefault": \
502 _Prepare(_IMPEXP_CALLS + _X509_CALLS + _OS_CALLS + _NODE_CALLS +
503 _FILE_STORAGE_CALLS + _MISC_CALLS + _INSTANCE_CALLS +
504 _BLOCKDEV_CALLS + _STORAGE_CALLS),
505 "RpcClientJobQueue": _Prepare([
506 ("jobqueue_update", MULTI, None, TMO_URGENT, [
507 ("file_name", None, None),
508 ("content", ED_COMPRESS, None),
509 ], None, None, "Update job queue file"),
510 ("jobqueue_purge", SINGLE, None, TMO_NORMAL, [], None, None,
512 ("jobqueue_rename", MULTI, None, TMO_URGENT, [
513 ("rename", None, None),
514 ], None, None, "Rename job queue file"),
516 "RpcClientBootstrap": _Prepare([
517 ("node_start_master_daemons", SINGLE, None, TMO_FAST, [
518 ("no_voting", None, None),
519 ], None, None, "Starts master daemons on a node"),
520 ("node_activate_master_ip", SINGLE, None, TMO_FAST, [
521 ("master_params", ED_OBJECT_DICT, "Network parameters of the master"),
522 ("use_external_mip_script", None,
523 "Whether to use the user-provided master IP address setup script"),
525 "Activates master IP on a node"),
526 ("node_stop_master", SINGLE, None, TMO_FAST, [], None, None,
527 "Deactivates master IP and stops master daemons on a node"),
528 ("node_deactivate_master_ip", SINGLE, None, TMO_FAST, [
529 ("master_params", ED_OBJECT_DICT, "Network parameters of the master"),
530 ("use_external_mip_script", None,
531 "Whether to use the user-provided master IP address setup script"),
533 "Deactivates master IP on a node"),
534 ("node_change_master_netmask", SINGLE, None, TMO_FAST, [
535 ("old_netmask", None, "The old value of the netmask"),
536 ("netmask", None, "The new value of the netmask"),
537 ("master_ip", None, "The master IP"),
538 ("master_netdev", None, "The master network device"),
539 ], None, None, "Change master IP netmask"),
540 ("node_leave_cluster", SINGLE, None, TMO_NORMAL, [
541 ("modify_ssh_setup", None, None),
543 "Requests a node to clean the cluster information it has"),
544 ("master_info", MULTI, None, TMO_URGENT, [], None, None,
545 "Query master info"),
546 ("version", MULTI, None, TMO_URGENT, [], None, None, "Query node version"),
548 "RpcClientConfig": _Prepare([
549 ("upload_file", MULTI, None, TMO_NORMAL, [
550 ("file_name", ED_FILE_DETAILS, None),
551 ], None, None, "Upload a file"),
552 ("write_ssconf_files", MULTI, None, TMO_NORMAL, [
553 ("values", None, None),
554 ], None, None, "Write ssconf files"),