code.grnet.gr Git - ganeti-local/blob - 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})
  28   - List of arguments as tuples
  29
  30     - Name as string
  31     - Argument kind used for encoding/decoding
  32     - Description for docstring (can be C{None})
  33
  34   - Return value wrapper (e.g. for deserializing into L{objects}-based objects)
  35   - Short call description for docstring
  36
  37 """
  38
  39
  40 # Guidelines for choosing timeouts:
  41 # - call used during watcher: timeout of 1min, _TMO_URGENT
  42 # - trivial (but be sure it is trivial) (e.g. reading a file): 5min, _TMO_FAST
  43 # - other calls: 15 min, _TMO_NORMAL
  44 # - special calls (instance add, etc.): either _TMO_SLOW (1h) or huge timeouts
  45 TMO_URGENT = 60 # one minute
  46 TMO_FAST = 5 * 60 # five minutes
  47 TMO_NORMAL = 15 * 60 # 15 minutes
  48 TMO_SLOW = 3600 # one hour
  49 TMO_4HRS = 4 * 3600
  50 TMO_1DAY = 86400
  51
  52 SINGLE = "single-node"
  53 MULTI = "multi-node"
  54
  55 # Constants for encoding/decoding
  56 (ED_OBJECT_DICT,
  57  ED_OBJECT_DICT_LIST,
  58  ED_INST_DICT,
  59  ED_INST_DICT_HVP_BEP,
  60  ED_NODE_TO_DISK_DICT,
  61  ED_INST_DICT_OSP,
  62  ED_IMPEXP_IO,
  63  ED_FILE_DETAILS,
  64  ED_FINALIZE_EXPORT_DISKS,
  65  ED_COMPRESS,
  66  ED_BLOCKDEV_RENAME) = range(1, 12)
  67
  68 _FILE_STORAGE_CALLS = [
  69   ("file_storage_dir_create", SINGLE, TMO_FAST, [
  70     ("file_storage_dir", None, "File storage directory"),
  71     ], None, "Create the given file storage directory"),
  72   ("file_storage_dir_remove", SINGLE, TMO_FAST, [
  73     ("file_storage_dir", None, "File storage directory"),
  74     ], None, "Remove the given file storage directory"),
  75   ("file_storage_dir_rename", SINGLE, TMO_FAST, [
  76     ("old_file_storage_dir", None, "Old name"),
  77     ("new_file_storage_dir", None, "New name"),
  78     ], None, "Rename file storage directory"),
  79   ]
  80
  81 _STORAGE_CALLS = [
  82   ("storage_list", MULTI, TMO_NORMAL, [
  83     ("su_name", None, None),
  84     ("su_args", None, None),
  85     ("name", None, None),
  86     ("fields", None, None),
  87     ], None, "Get list of storage units"),
  88   ("storage_modify", SINGLE, TMO_NORMAL, [
  89     ("su_name", None, None),
  90     ("su_args", None, None),
  91     ("name", None, None),
  92     ("changes", None, None),
  93     ], None, "Modify a storage unit"),
  94   ("storage_execute", SINGLE, TMO_NORMAL, [
  95     ("su_name", None, None),
  96     ("su_args", None, None),
  97     ("name", None, None),
  98     ("op", None, None),
  99     ], None, "Executes an operation on a storage unit"),
 100   ]
 101
 102 _INSTANCE_CALLS = [
 103   ("instance_info", SINGLE, TMO_URGENT, [
 104     ("instance", None, "Instance name"),
 105     ("hname", None, "Hypervisor type"),
 106     ], None, "Returns information about a single instance"),
 107   ("all_instances_info", MULTI, TMO_URGENT, [
 108     ("hypervisor_list", None, "Hypervisors to query for instances"),
 109     ], None, "Returns information about all instances on the given nodes"),
 110   ("instance_list", MULTI, TMO_URGENT, [
 111     ("hypervisor_list", None, "Hypervisors to query for instances"),
 112     ], None, "Returns the list of running instances on the given nodes"),
 113   ("instance_reboot", SINGLE, TMO_NORMAL, [
 114     ("inst", ED_INST_DICT, "Instance object"),
 115     ("reboot_type", None, None),
 116     ("shutdown_timeout", None, None),
 117     ], None, "Returns the list of running instances on the given nodes"),
 118   ("instance_shutdown", SINGLE, TMO_NORMAL, [
 119     ("instance", ED_INST_DICT, "Instance object"),
 120     ("timeout", None, None),
 121     ], None, "Stops an instance"),
 122   ("instance_run_rename", SINGLE, TMO_SLOW, [
 123     ("instance", ED_INST_DICT, "Instance object"),
 124     ("old_name", None, None),
 125     ("debug", None, None),
 126     ], None, "Run the OS rename script for an instance"),
 127   ("instance_migratable", SINGLE, TMO_NORMAL, [
 128     ("instance", ED_INST_DICT, "Instance object"),
 129     ], None, "Checks whether the given instance can be migrated"),
 130   ("migration_info", SINGLE, TMO_NORMAL, [
 131     ("instance", ED_INST_DICT, "Instance object"),
 132     ], None,
 133     "Gather the information necessary to prepare an instance migration"),
 134   ("accept_instance", SINGLE, TMO_NORMAL, [
 135     ("instance", ED_INST_DICT, "Instance object"),
 136     ("info", None, "Result for the call_migration_info call"),
 137     ("target", None, "Target hostname (usually an IP address)"),
 138     ], None, "Prepare a node to accept an instance"),
 139   ("instance_finalize_migration_dst", SINGLE, TMO_NORMAL, [
 140     ("instance", ED_INST_DICT, "Instance object"),
 141     ("info", None, "Result for the call_migration_info call"),
 142     ("success", None, "Whether the migration was a success or failure"),
 143     ], None, "Finalize any target-node migration specific operation"),
 144   ("instance_migrate", SINGLE, TMO_SLOW, [
 145     ("instance", ED_INST_DICT, "Instance object"),
 146     ("target", None, "Target node name"),
 147     ("live", None, "Whether the migration should be done live or not"),
 148     ], None, "Migrate an instance"),
 149   ("instance_finalize_migration_src", SINGLE, TMO_SLOW, [
 150     ("instance", ED_INST_DICT, "Instance object"),
 151     ("success", None, "Whether the migration succeeded or not"),
 152     ("live", None, "Whether the user requested a live migration or not"),
 153     ], None, "Finalize the instance migration on the source node"),
 154   ("instance_get_migration_status", SINGLE, TMO_SLOW, [
 155     ("instance", ED_INST_DICT, "Instance object"),
 156     ], "self._MigrationStatusPostProc", "Report migration status"),
 157   ("instance_start", SINGLE, TMO_NORMAL, [
 158     ("instance_hvp_bep", ED_INST_DICT_HVP_BEP, None),
 159     ("startup_paused", None, None),
 160     ], None, "Starts an instance"),
 161   ("instance_os_add", SINGLE, TMO_1DAY, [
 162     ("instance_osp", ED_INST_DICT_OSP, None),
 163     ("reinstall", None, None),
 164     ("debug", None, None),
 165     ], None, "Starts an instance"),
 166   ]
 167
 168 _IMPEXP_CALLS = [
 169   ("import_start", SINGLE, TMO_NORMAL, [
 170     ("opts", ED_OBJECT_DICT, None),
 171     ("instance", ED_INST_DICT, None),
 172     ("component", None, None),
 173     ("dest", ED_IMPEXP_IO, "Import destination"),
 174     ], None, "Starts an import daemon"),
 175   ("export_start", SINGLE, TMO_NORMAL, [
 176     ("opts", ED_OBJECT_DICT, None),
 177     ("host", None, None),
 178     ("port", None, None),
 179     ("instance", ED_INST_DICT, None),
 180     ("component", None, None),
 181     ("source", ED_IMPEXP_IO, "Export source"),
 182     ], None, "Starts an export daemon"),
 183   ("impexp_status", SINGLE, TMO_FAST, [
 184     ("names", None, "Import/export names"),
 185     ], "self._ImpExpStatusPostProc", "Gets the status of an import or export"),
 186   ("impexp_abort", SINGLE, TMO_NORMAL, [
 187     ("name", None, "Import/export name"),
 188     ], None, "Aborts an import or export"),
 189   ("impexp_cleanup", SINGLE, TMO_NORMAL, [
 190     ("name", None, "Import/export name"),
 191     ], None, "Cleans up after an import or export"),
 192   ("export_info", SINGLE, TMO_FAST, [
 193     ("path", None, None),
 194     ], None, "Queries the export information in a given path"),
 195   ("finalize_export", SINGLE, TMO_NORMAL, [
 196     ("instance", ED_INST_DICT, None),
 197     ("snap_disks", ED_FINALIZE_EXPORT_DISKS, None),
 198     ], None, "Request the completion of an export operation"),
 199   ("export_list", MULTI, TMO_FAST, [], None, "Gets the stored exports list"),
 200   ("export_remove", SINGLE, TMO_FAST, [
 201     ("export", None, None),
 202     ], None, "Requests removal of a given export"),
 203   ]
 204
 205 _X509_CALLS = [
 206   ("x509_cert_create", SINGLE, TMO_NORMAL, [
 207     ("validity", None, "Validity in seconds"),
 208     ], None, "Creates a new X509 certificate for SSL/TLS"),
 209   ("x509_cert_remove", SINGLE, TMO_NORMAL, [
 210     ("name", None, "Certificate name"),
 211     ], None, "Removes a X509 certificate"),
 212   ]
 213
 214 _BLOCKDEV_CALLS = [
 215   ("bdev_sizes", MULTI, TMO_URGENT, [
 216     ("devices", None, None),
 217     ], None, "Gets the sizes of requested block devices present on a node"),
 218   ("blockdev_create", SINGLE, TMO_NORMAL, [
 219     ("bdev", ED_OBJECT_DICT, None),
 220     ("size", None, None),
 221     ("owner", None, None),
 222     ("on_primary", None, None),
 223     ("info", None, None),
 224     ], None, "Request creation of a given block device"),
 225   ("blockdev_wipe", SINGLE, TMO_SLOW, [
 226     ("bdev", ED_OBJECT_DICT, None),
 227     ("offset", None, None),
 228     ("size", None, None),
 229     ], None,
 230     "Request wipe at given offset with given size of a block device"),
 231   ("blockdev_remove", SINGLE, TMO_NORMAL, [
 232     ("bdev", ED_OBJECT_DICT, None),
 233     ], None, "Request removal of a given block device"),
 234   ("blockdev_pause_resume_sync", SINGLE, TMO_NORMAL, [
 235     ("disks", ED_OBJECT_DICT_LIST, None),
 236     ("pause", None, None),
 237     ], None, "Request a pause/resume of given block device"),
 238   ("blockdev_assemble", SINGLE, TMO_NORMAL, [
 239     ("disk", ED_OBJECT_DICT, None),
 240     ("owner", None, None),
 241     ("on_primary", None, None),
 242     ("idx", None, None),
 243     ], None, "Request assembling of a given block device"),
 244   ("blockdev_shutdown", SINGLE, TMO_NORMAL, [
 245     ("disk", ED_OBJECT_DICT, None),
 246     ], None, "Request shutdown of a given block device"),
 247   ("blockdev_addchildren", SINGLE, TMO_NORMAL, [
 248     ("bdev", ED_OBJECT_DICT, None),
 249     ("ndevs", ED_OBJECT_DICT_LIST, None),
 250     ], None, "Request adding a list of children to a (mirroring) device"),
 251   ("blockdev_removechildren", SINGLE, TMO_NORMAL, [
 252     ("bdev", ED_OBJECT_DICT, None),
 253     ("ndevs", ED_OBJECT_DICT_LIST, None),
 254     ], None, "Request removing a list of children from a (mirroring) device"),
 255   ("blockdev_close", SINGLE, TMO_NORMAL, [
 256     ("instance_name", None, None),
 257     ("disks", ED_OBJECT_DICT_LIST, None),
 258     ], None, "Closes the given block devices"),
 259   ("blockdev_getsize", SINGLE, TMO_NORMAL, [
 260     ("disks", ED_OBJECT_DICT_LIST, None),
 261     ], None, "Returns the size of the given disks"),
 262   ("drbd_disconnect_net", MULTI, TMO_NORMAL, [
 263     ("nodes_ip", None, None),
 264     ("disks", ED_OBJECT_DICT_LIST, None),
 265     ], None, "Disconnects the network of the given drbd devices"),
 266   ("drbd_attach_net", MULTI, TMO_NORMAL, [
 267     ("nodes_ip", None, None),
 268     ("disks", ED_OBJECT_DICT_LIST, None),
 269     ("instance_name", None, None),
 270     ("multimaster", None, None),
 271     ], None, "Connects the given DRBD devices"),
 272   ("drbd_wait_sync", MULTI, TMO_SLOW, [
 273     ("nodes_ip", None, None),
 274     ("disks", ED_OBJECT_DICT_LIST, None),
 275     ], None, "Waits for the synchronization of drbd devices is complete"),
 276   ("blockdev_grow", SINGLE, TMO_NORMAL, [
 277     ("cf_bdev", ED_OBJECT_DICT, None),
 278     ("amount", None, None),
 279     ("dryrun", None, None),
 280     ], None, "Request a snapshot of the given block device"),
 281   ("blockdev_export", SINGLE, TMO_1DAY, [
 282     ("cf_bdev", ED_OBJECT_DICT, None),
 283     ("dest_node", None, None),
 284     ("dest_path", None, None),
 285     ("cluster_name", None, None),
 286     ], None, "Export a given disk to another node"),
 287   ("blockdev_snapshot", SINGLE, TMO_NORMAL, [
 288     ("cf_bdev", ED_OBJECT_DICT, None),
 289     ], None, "Export a given disk to another node"),
 290   ("blockdev_rename", SINGLE, TMO_NORMAL, [
 291     ("devlist", ED_BLOCKDEV_RENAME, None),
 292     ], None, "Request rename of the given block devices"),
 293   ("blockdev_find", SINGLE, TMO_NORMAL, [
 294     ("disk", ED_OBJECT_DICT, None),
 295     ], "self._BlockdevFindPostProc",
 296     "Request identification of a given block device"),
 297   ("blockdev_getmirrorstatus", SINGLE, TMO_NORMAL, [
 298     ("disks", ED_OBJECT_DICT_LIST, None),
 299     ], "self._BlockdevGetMirrorStatusPostProc",
 300     "Request status of a (mirroring) device"),
 301   ("blockdev_getmirrorstatus_multi", MULTI, TMO_NORMAL, [
 302     ("node_disks", ED_NODE_TO_DISK_DICT, None),
 303     ], "self._BlockdevGetMirrorStatusMultiPostProc",
 304     "Request status of (mirroring) devices from multiple nodes"),
 305   ]
 306
 307 _OS_CALLS = [
 308   ("os_diagnose", MULTI, TMO_FAST, [], None,
 309    "Request a diagnose of OS definitions"),
 310   ("os_validate", MULTI, TMO_FAST, [
 311     ("required", None, None),
 312     ("name", None, None),
 313     ("checks", None, None),
 314     ("params", None, None),
 315     ], None, "Run a validation routine for a given OS"),
 316   ("os_get", SINGLE, TMO_FAST, [
 317     ("name", None, None),
 318     ], "self._OsGetPostProc", "Returns an OS definition"),
 319   ]
 320
 321 _NODE_CALLS = [
 322   ("node_has_ip_address", SINGLE, TMO_FAST, [
 323     ("address", None, "IP address"),
 324     ], None, "Checks if a node has the given IP address"),
 325   ("node_info", MULTI, TMO_URGENT, [
 326     ("vg_name", None,
 327      "Name of the volume group to ask for disk space information"),
 328     ("hypervisor_type", None,
 329      "Name of the hypervisor to ask for memory information"),
 330     ], None, "Return node information"),
 331   ("node_verify", MULTI, TMO_NORMAL, [
 332     ("checkdict", None, None),
 333     ("cluster_name", None, None),
 334     ], None, "Request verification of given parameters"),
 335   ("node_volumes", MULTI, TMO_FAST, [], None, "Gets all volumes on node(s)"),
 336   ("node_demote_from_mc", SINGLE, TMO_FAST, [], None,
 337    "Demote a node from the master candidate role"),
 338   ("node_powercycle", SINGLE, TMO_NORMAL, [
 339     ("hypervisor", None, "Hypervisor type"),
 340     ], None, "Tries to powercycle a node"),
 341   ]
 342
 343 _MISC_CALLS = [
 344   ("lv_list", MULTI, TMO_URGENT, [
 345     ("vg_name", None, None),
 346     ], None, "Gets the logical volumes present in a given volume group"),
 347   ("vg_list", MULTI, TMO_URGENT, [], None, "Gets the volume group list"),
 348   ("bridges_exist", SINGLE, TMO_URGENT, [
 349     ("bridges_list", None, "Bridges which must be present on remote node"),
 350     ], None, "Checks if a node has all the bridges given"),
 351   ("etc_hosts_modify", SINGLE, TMO_NORMAL, [
 352     ("mode", None,
 353      "Mode to operate; currently L{constants.ETC_HOSTS_ADD} or"
 354      " L{constants.ETC_HOSTS_REMOVE}"),
 355     ("name", None, "Hostname to be modified"),
 356     ("ip", None, "IP address (L{constants.ETC_HOSTS_ADD} only)"),
 357     ], None, "Modify hosts file with name"),
 358   ("drbd_helper", MULTI, TMO_URGENT, [], None, "Gets DRBD helper"),
 359   ("run_oob", SINGLE, TMO_NORMAL, [
 360     ("oob_program", None, None),
 361     ("command", None, None),
 362     ("remote_node", None, None),
 363     ("timeout", None, None),
 364     ], None, "Runs out-of-band command"),
 365   ("hooks_runner", MULTI, TMO_NORMAL, [
 366     ("hpath", None, None),
 367     ("phase", None, None),
 368     ("env", None, None),
 369     ], None, "Call the hooks runner"),
 370   ("iallocator_runner", SINGLE, TMO_NORMAL, [
 371     ("name", None, "Iallocator name"),
 372     ("idata", None, "JSON-encoded input string"),
 373     ], None, "Call an iallocator on a remote node"),
 374   ("test_delay", MULTI, None, [
 375     ("duration", None, None),
 376     ], None, "Sleep for a fixed time on given node(s)"),
 377   ("hypervisor_validate_params", MULTI, TMO_NORMAL, [
 378     ("hvname", None, "Hypervisor name"),
 379     ("hvfull", None, "Parameters to be validated"),
 380     ], None, "Validate hypervisor params"),
 381   ]
 382
 383 CALLS = {
 384   "RpcClientDefault": (_IMPEXP_CALLS + _X509_CALLS + _OS_CALLS + _NODE_CALLS +
 385     _FILE_STORAGE_CALLS + _MISC_CALLS + _INSTANCE_CALLS + _BLOCKDEV_CALLS +
 386     _STORAGE_CALLS),
 387   "RpcClientJobQueue": [
 388     ("jobqueue_update", MULTI, TMO_URGENT, [
 389       ("file_name", None, None),
 390       ("content", ED_COMPRESS, None),
 391       ], None, "Update job queue file"),
 392     ("jobqueue_purge", SINGLE, TMO_NORMAL, [], None, "Purge job queue"),
 393     ("jobqueue_rename", MULTI, TMO_URGENT, [
 394       ("rename", None, None),
 395       ], None, "Rename job queue file"),
 396     ],
 397   "RpcClientBootstrap": [
 398     ("node_start_master_daemons", SINGLE, TMO_FAST, [
 399       ("no_voting", None, None),
 400       ], None, "Starts master daemons on a node"),
 401     ("node_activate_master_ip", SINGLE, TMO_FAST, [
 402       ("master_params", ED_OBJECT_DICT, "Network parameters of the master"),
 403       ], None,
 404       "Activates master IP on a node"),
 405     ("node_stop_master", SINGLE, TMO_FAST, [], None,
 406      "Deactivates master IP and stops master daemons on a node"),
 407     ("node_deactivate_master_ip", SINGLE, TMO_FAST, [
 408       ("master_params", ED_OBJECT_DICT, "Network parameters of the master"),
 409       ], None,
 410      "Deactivates master IP on a node"),
 411     ("node_change_master_netmask", SINGLE, TMO_FAST, [
 412       ("old_netmask", None, "The old value of the netmask"),
 413       ("netmask", None, "The new value of the netmask"),
 414       ("master_ip", None, "The master IP"),
 415       ("master_netdev", None, "The master network device"),
 416       ], None, "Change master IP netmask"),
 417     ("node_leave_cluster", SINGLE, TMO_NORMAL, [
 418       ("modify_ssh_setup", None, None),
 419       ], None, "Requests a node to clean the cluster information it has"),
 420     ("master_info", MULTI, TMO_URGENT, [], None, "Query master info"),
 421     ("version", MULTI, TMO_URGENT, [], None, "Query node version"),
 422     ],
 423   "RpcClientConfig": [
 424     ("upload_file", MULTI, TMO_NORMAL, [
 425       ("file_name", ED_FILE_DETAILS, None),
 426       ], None, "Upload a file"),
 427     ("write_ssconf_files", MULTI, TMO_NORMAL, [
 428       ("values", None, None),
 429       ], None, "Write ssconf files"),
 430     ],
 431   }