serializer: Remove JSON indentation and dict key sorting
[ganeti-local] / lib / rpc_defs.py
1 #
2 #
3
4 # Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Google Inc.
5 #
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.
10 #
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.
15 #
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
19 # 02110-1301, USA.
20
21 """RPC definitions for communication between master and node daemons.
22
23 RPC definition fields:
24
25   - Name as string
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
30
31     - Name as string
32     - Argument kind used for encoding/decoding
33     - Description for docstring (can be C{None})
34
35   - Return value wrapper (e.g. for deserializing into L{objects}-based objects)
36   - Short call description for docstring
37
38 """
39
40 from ganeti import utils
41 from ganeti import objects
42
43
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
53 TMO_4HRS = 4 * 3600
54 TMO_1DAY = 86400
55
56 SINGLE = "single-node"
57 MULTI = "multi-node"
58
59 # Constants for encoding/decoding
60 (ED_OBJECT_DICT,
61  ED_OBJECT_DICT_LIST,
62  ED_INST_DICT,
63  ED_INST_DICT_HVP_BEP,
64  ED_NODE_TO_DISK_DICT,
65  ED_INST_DICT_OSP,
66  ED_IMPEXP_IO,
67  ED_FILE_DETAILS,
68  ED_FINALIZE_EXPORT_DISKS,
69  ED_COMPRESS,
70  ED_BLOCKDEV_RENAME) = range(1, 12)
71
72
73 def _Prepare(calls):
74   """Converts list of calls to dictionary.
75
76   """
77   return utils.SequenceToDict(calls)
78
79
80 def _MigrationStatusPostProc(result):
81   """Post-processor for L{rpc.RpcRunner.call_instance_get_migration_status}.
82
83   """
84   if not result.fail_msg and result.payload is not None:
85     result.payload = objects.MigrationStatus.FromDict(result.payload)
86   return result
87
88
89 def _BlockdevFindPostProc(result):
90   """Post-processor for L{rpc.RpcRunner.call_blockdev_find}.
91
92   """
93   if not result.fail_msg and result.payload is not None:
94     result.payload = objects.BlockDevStatus.FromDict(result.payload)
95   return result
96
97
98 def _BlockdevGetMirrorStatusPostProc(result):
99   """Post-processor for L{rpc.RpcRunner.call_blockdev_getmirrorstatus}.
100
101   """
102   if not result.fail_msg:
103     result.payload = map(objects.BlockDevStatus.FromDict, result.payload)
104   return result
105
106
107 def _BlockdevGetMirrorStatusMultiPostProc(result):
108   """Post-processor for L{rpc.RpcRunner.call_blockdev_getmirrorstatus_multi}.
109
110   """
111   if not result.fail_msg:
112     for idx, (success, status) in enumerate(result.payload):
113       if success:
114         result.payload[idx] = (success, objects.BlockDevStatus.FromDict(status))
115
116   return result
117
118
119 def _OsGetPostProc(result):
120   """Post-processor for L{rpc.RpcRunner.call_os_get}.
121
122   """
123   if not result.fail_msg and isinstance(result.payload, dict):
124     result.payload = objects.OS.FromDict(result.payload)
125   return result
126
127
128 def _ImpExpStatusPostProc(result):
129   """Post-processor for import/export status.
130
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
134
135   """
136   if not result.fail_msg:
137     decoded = []
138
139     for i in result.payload:
140       if i is None:
141         decoded.append(None)
142         continue
143       decoded.append(objects.ImportExportStatus.FromDict(i))
144
145     result.payload = decoded
146
147   return result
148
149
150 def _TestDelayTimeout((duration, )):
151   """Calculate timeout for "test_delay" RPC.
152
153   """
154   return int(duration + 5)
155
156
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"),
168   ]
169
170 _STORAGE_CALLS = [
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),
187     ("op", None, None),
188     ], None, "Executes an operation on a storage unit"),
189   ]
190
191 _INSTANCE_CALLS = [
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"),
221     ], None,
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"),
255   ]
256
257 _IMPEXP_CALLS = [
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"),
292   ]
293
294 _X509_CALLS = [
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"),
301   ]
302
303 _BLOCKDEV_CALLS = [
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),
318     ], 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),
331     ("idx", 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"),
394   ]
395
396 _OS_CALLS = [
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"),
408   ]
409
410 _NODE_CALLS = [
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, [
415     ("vg_names", None,
416      "Names of the volume groups to ask for disk space information"),
417     ("hv_names", None,
418      "Names of the hypervisors to ask for node 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"),
430   ]
431
432 _MISC_CALLS = [
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, [
441     ("mode", None,
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),
457     ("env", 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"),
470   ]
471
472 CALLS = {
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"),
486     ]),
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"),
495       ], None,
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"),
503       ], None,
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"),
516     ]),
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"),
524     ]),
525   }