code.grnet.gr Git - ganeti-local/blob - lib/hypervisor/hv_base.py

   1 #
   2 #
   3
   4 # Copyright (C) 2006, 2007, 2008, 2009, 2010, 2012, 2013 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
  22 """Base class for all hypervisors
  23
  24 The syntax for the _CHECK variables and the contents of the PARAMETERS
  25 dict is the same, see the docstring for L{BaseHypervisor.PARAMETERS}.
  26
  27 @var _FILE_CHECK: stub for file checks, without the required flag
  28 @var _DIR_CHECK: stub for directory checks, without the required flag
  29 @var REQ_FILE_CHECK: mandatory file parameter
  30 @var OPT_FILE_CHECK: optional file parameter
  31 @var REQ_DIR_CHECK: mandatory directory parametr
  32 @var OPT_DIR_CHECK: optional directory parameter
  33 @var NO_CHECK: parameter without any checks at all
  34 @var REQUIRED_CHECK: parameter required to exist (and non-false), but
  35     without other checks; beware that this can't be used for boolean
  36     parameters, where you should use NO_CHECK or a custom checker
  37
  38 """
  39
  40 import os
  41 import re
  42 import logging
  43
  44
  45 from ganeti import errors
  46 from ganeti import utils
  47 from ganeti import constants
  48
  49
  50 def _IsCpuMaskWellFormed(cpu_mask):
  51   """Verifies if the given single CPU mask is valid
  52
  53   The single CPU mask should be in the form "a,b,c,d", where each
  54   letter is a positive number or range.
  55
  56   """
  57   try:
  58     cpu_list = utils.ParseCpuMask(cpu_mask)
  59   except errors.ParseError, _:
  60     return False
  61   return isinstance(cpu_list, list) and len(cpu_list) > 0
  62
  63
  64 def _IsMultiCpuMaskWellFormed(cpu_mask):
  65   """Verifies if the given multiple CPU mask is valid
  66
  67   A valid multiple CPU mask is in the form "a:b:c:d", where each
  68   letter is a single CPU mask.
  69
  70   """
  71   try:
  72     utils.ParseMultiCpuMask(cpu_mask)
  73   except errors.ParseError, _:
  74     return False
  75
  76   return True
  77
  78
  79 # Read the BaseHypervisor.PARAMETERS docstring for the syntax of the
  80 # _CHECK values
  81
  82 # must be afile
  83 _FILE_CHECK = (utils.IsNormAbsPath, "must be an absolute normalized path",
  84                os.path.isfile, "not found or not a file")
  85
  86 # must be a directory
  87 _DIR_CHECK = (utils.IsNormAbsPath, "must be an absolute normalized path",
  88               os.path.isdir, "not found or not a directory")
  89
  90 # CPU mask must be well-formed
  91 # TODO: implement node level check for the CPU mask
  92 _CPU_MASK_CHECK = (_IsCpuMaskWellFormed,
  93                    "CPU mask definition is not well-formed",
  94                    None, None)
  95
  96 # Multiple CPU mask must be well-formed
  97 _MULTI_CPU_MASK_CHECK = (_IsMultiCpuMaskWellFormed,
  98                          "Multiple CPU mask definition is not well-formed",
  99                          None, None)
 100
 101 # Check for validity of port number
 102 _NET_PORT_CHECK = (lambda x: 0 < x < 65535, "invalid port number",
 103                    None, None)
 104
 105 # Check that an integer is non negative
 106 _NONNEGATIVE_INT_CHECK = (lambda x: x >= 0, "cannot be negative", None, None)
 107
 108 # nice wrappers for users
 109 REQ_FILE_CHECK = (True, ) + _FILE_CHECK
 110 OPT_FILE_CHECK = (False, ) + _FILE_CHECK
 111 REQ_DIR_CHECK = (True, ) + _DIR_CHECK
 112 OPT_DIR_CHECK = (False, ) + _DIR_CHECK
 113 REQ_NET_PORT_CHECK = (True, ) + _NET_PORT_CHECK
 114 OPT_NET_PORT_CHECK = (False, ) + _NET_PORT_CHECK
 115 REQ_CPU_MASK_CHECK = (True, ) + _CPU_MASK_CHECK
 116 OPT_CPU_MASK_CHECK = (False, ) + _CPU_MASK_CHECK
 117 REQ_MULTI_CPU_MASK_CHECK = (True, ) + _MULTI_CPU_MASK_CHECK
 118 OPT_MULTI_CPU_MASK_CHECK = (False, ) + _MULTI_CPU_MASK_CHECK
 119 REQ_NONNEGATIVE_INT_CHECK = (True, ) + _NONNEGATIVE_INT_CHECK
 120 OPT_NONNEGATIVE_INT_CHECK = (False, ) + _NONNEGATIVE_INT_CHECK
 121
 122 # no checks at all
 123 NO_CHECK = (False, None, None, None, None)
 124
 125 # required, but no other checks
 126 REQUIRED_CHECK = (True, None, None, None, None)
 127
 128 # migration type
 129 MIGRATION_MODE_CHECK = (True, lambda x: x in constants.HT_MIGRATION_MODES,
 130                         "invalid migration mode", None, None)
 131
 132
 133 def ParamInSet(required, my_set):
 134   """Builds parameter checker for set membership.
 135
 136   @type required: boolean
 137   @param required: whether this is a required parameter
 138   @type my_set: tuple, list or set
 139   @param my_set: allowed values set
 140
 141   """
 142   fn = lambda x: x in my_set
 143   err = ("The value must be one of: %s" % utils.CommaJoin(my_set))
 144   return (required, fn, err, None, None)
 145
 146
 147 class BaseHypervisor(object):
 148   """Abstract virtualisation technology interface
 149
 150   The goal is that all aspects of the virtualisation technology are
 151   abstracted away from the rest of code.
 152
 153   @cvar PARAMETERS: a dict of parameter name: check type; the check type is
 154       a five-tuple containing:
 155           - the required flag (boolean)
 156           - a function to check for syntax, that will be used in
 157             L{CheckParameterSyntax}, in the master daemon process
 158           - an error message for the above function
 159           - a function to check for parameter validity on the remote node,
 160             in the L{ValidateParameters} function
 161           - an error message for the above function
 162   @type CAN_MIGRATE: boolean
 163   @cvar CAN_MIGRATE: whether this hypervisor can do migration (either
 164       live or non-live)
 165
 166   """
 167   PARAMETERS = {}
 168   ANCILLARY_FILES = []
 169   ANCILLARY_FILES_OPT = []
 170   CAN_MIGRATE = False
 171
 172   def StartInstance(self, instance, block_devices, startup_paused):
 173     """Start an instance."""
 174     raise NotImplementedError
 175
 176   def StopInstance(self, instance, force=False, retry=False, name=None):
 177     """Stop an instance
 178
 179     @type instance: L{objects.Instance}
 180     @param instance: instance to stop
 181     @type force: boolean
 182     @param force: whether to do a "hard" stop (destroy)
 183     @type retry: boolean
 184     @param retry: whether this is just a retry call
 185     @type name: string or None
 186     @param name: if this parameter is passed, the the instance object
 187         should not be used (will be passed as None), and the shutdown
 188         must be done by name only
 189
 190     """
 191     raise NotImplementedError
 192
 193   def CleanupInstance(self, instance_name):
 194     """Cleanup after a stopped instance
 195
 196     This is an optional method, used by hypervisors that need to cleanup after
 197     an instance has been stopped.
 198
 199     @type instance_name: string
 200     @param instance_name: instance name to cleanup after
 201
 202     """
 203     pass
 204
 205   def RebootInstance(self, instance):
 206     """Reboot an instance."""
 207     raise NotImplementedError
 208
 209   def ListInstances(self, hvparams=None):
 210     """Get the list of running instances."""
 211     raise NotImplementedError
 212
 213   def GetInstanceInfo(self, instance_name, hvparams=None):
 214     """Get instance properties.
 215
 216     @type instance_name: string
 217     @param instance_name: the instance name
 218     @type hvparams: dict of strings
 219     @param hvparams: hvparams to be used with this instance
 220
 221     @return: tuple (name, id, memory, vcpus, state, times)
 222
 223     """
 224     raise NotImplementedError
 225
 226   def GetAllInstancesInfo(self, hvparams=None):
 227     """Get properties of all instances.
 228
 229     @type hvparams: dict of strings
 230     @param hvparams: hypervisor parameter
 231     @return: list of tuples (name, id, memory, vcpus, stat, times)
 232
 233     """
 234     raise NotImplementedError
 235
 236   def GetNodeInfo(self, hvparams=None):
 237     """Return information about the node.
 238
 239     @type hvparams: dict of strings
 240     @param hvparams: hypervisor parameters
 241
 242     @return: a dict with at least the following keys (memory values in MiB):
 243           - memory_total: the total memory size on the node
 244           - memory_free: the available memory on the node for instances
 245           - memory_dom0: the memory used by the node itself, if available
 246           - cpu_total: total number of CPUs
 247           - cpu_dom0: number of CPUs used by the node OS
 248           - cpu_nodes: number of NUMA domains
 249           - cpu_sockets: number of physical CPU sockets
 250
 251     """
 252     raise NotImplementedError
 253
 254   @classmethod
 255   def GetInstanceConsole(cls, instance, primary_node, hvparams, beparams):
 256     """Return information for connecting to the console of an instance.
 257
 258     """
 259     raise NotImplementedError
 260
 261   @classmethod
 262   def GetAncillaryFiles(cls):
 263     """Return a list of ancillary files to be copied to all nodes as ancillary
 264     configuration files.
 265
 266     @rtype: (list of absolute paths, list of absolute paths)
 267     @return: (all files, optional files)
 268
 269     """
 270     # By default we return a member variable, so that if an hypervisor has just
 271     # a static list of files it doesn't have to override this function.
 272     assert set(cls.ANCILLARY_FILES).issuperset(cls.ANCILLARY_FILES_OPT), \
 273       "Optional ancillary files must be a subset of ancillary files"
 274
 275     return (cls.ANCILLARY_FILES, cls.ANCILLARY_FILES_OPT)
 276
 277   def Verify(self, hvparams=None):
 278     """Verify the hypervisor.
 279
 280     @type hvparams: dict of strings
 281     @param hvparams: hypervisor parameters to be verified against
 282
 283     @return: Problem description if something is wrong, C{None} otherwise
 284
 285     """
 286     raise NotImplementedError
 287
 288   def MigrationInfo(self, instance): # pylint: disable=R0201,W0613
 289     """Get instance information to perform a migration.
 290
 291     By default assume no information is needed.
 292
 293     @type instance: L{objects.Instance}
 294     @param instance: instance to be migrated
 295     @rtype: string/data (opaque)
 296     @return: instance migration information - serialized form
 297
 298     """
 299     return ""
 300
 301   def AcceptInstance(self, instance, info, target):
 302     """Prepare to accept an instance.
 303
 304     By default assume no preparation is needed.
 305
 306     @type instance: L{objects.Instance}
 307     @param instance: instance to be accepted
 308     @type info: string/data (opaque)
 309     @param info: migration information, from the source node
 310     @type target: string
 311     @param target: target host (usually ip), on this node
 312
 313     """
 314     pass
 315
 316   def BalloonInstanceMemory(self, instance, mem):
 317     """Balloon an instance memory to a certain value.
 318
 319     @type instance: L{objects.Instance}
 320     @param instance: instance to be accepted
 321     @type mem: int
 322     @param mem: actual memory size to use for instance runtime
 323
 324     """
 325     raise NotImplementedError
 326
 327   def FinalizeMigrationDst(self, instance, info, success):
 328     """Finalize the instance migration on the target node.
 329
 330     Should finalize or revert any preparation done to accept the instance.
 331     Since by default we do no preparation, we also don't have anything to do
 332
 333     @type instance: L{objects.Instance}
 334     @param instance: instance whose migration is being finalized
 335     @type info: string/data (opaque)
 336     @param info: migration information, from the source node
 337     @type success: boolean
 338     @param success: whether the migration was a success or a failure
 339
 340     """
 341     pass
 342
 343   def MigrateInstance(self, cluster_name, instance, target, live):
 344     """Migrate an instance.
 345
 346     @type cluster_name: string
 347     @param cluster_name: name of the cluster
 348     @type instance: L{objects.Instance}
 349     @param instance: the instance to be migrated
 350     @type target: string
 351     @param target: hostname (usually ip) of the target node
 352     @type live: boolean
 353     @param live: whether to do a live or non-live migration
 354
 355     """
 356     raise NotImplementedError
 357
 358   def FinalizeMigrationSource(self, instance, success, live):
 359     """Finalize the instance migration on the source node.
 360
 361     @type instance: L{objects.Instance}
 362     @param instance: the instance that was migrated
 363     @type success: bool
 364     @param success: whether the migration succeeded or not
 365     @type live: bool
 366     @param live: whether the user requested a live migration or not
 367
 368     """
 369     pass
 370
 371   def GetMigrationStatus(self, instance):
 372     """Get the migration status
 373
 374     @type instance: L{objects.Instance}
 375     @param instance: the instance that is being migrated
 376     @rtype: L{objects.MigrationStatus}
 377     @return: the status of the current migration (one of
 378              L{constants.HV_MIGRATION_VALID_STATUSES}), plus any additional
 379              progress info that can be retrieved from the hypervisor
 380
 381     """
 382     raise NotImplementedError
 383
 384   def _InstanceStartupMemory(self, instance):
 385     """Get the correct startup memory for an instance
 386
 387     This function calculates how much memory an instance should be started
 388     with, making sure it's a value between the minimum and the maximum memory,
 389     but also trying to use no more than the current free memory on the node.
 390
 391     @type instance: L{objects.Instance}
 392     @param instance: the instance that is being started
 393     @rtype: integer
 394     @return: memory the instance should be started with
 395
 396     """
 397     free_memory = self.GetNodeInfo(hvparams=instance.hvparams)["memory_free"]
 398     max_start_mem = min(instance.beparams[constants.BE_MAXMEM], free_memory)
 399     start_mem = max(instance.beparams[constants.BE_MINMEM], max_start_mem)
 400     return start_mem
 401
 402   @classmethod
 403   def CheckParameterSyntax(cls, hvparams):
 404     """Check the given parameters for validity.
 405
 406     This should check the passed set of parameters for
 407     validity. Classes should extend, not replace, this function.
 408
 409     @type hvparams:  dict
 410     @param hvparams: dictionary with parameter names/value
 411     @raise errors.HypervisorError: when a parameter is not valid
 412
 413     """
 414     for key in hvparams:
 415       if key not in cls.PARAMETERS:
 416         raise errors.HypervisorError("Parameter '%s' is not supported" % key)
 417
 418     # cheap tests that run on the master, should not access the world
 419     for name, (required, check_fn, errstr, _, _) in cls.PARAMETERS.items():
 420       if name not in hvparams:
 421         raise errors.HypervisorError("Parameter '%s' is missing" % name)
 422       value = hvparams[name]
 423       if not required and not value:
 424         continue
 425       if not value:
 426         raise errors.HypervisorError("Parameter '%s' is required but"
 427                                      " is currently not defined" % (name, ))
 428       if check_fn is not None and not check_fn(value):
 429         raise errors.HypervisorError("Parameter '%s' fails syntax"
 430                                      " check: %s (current value: '%s')" %
 431                                      (name, errstr, value))
 432
 433   @classmethod
 434   def ValidateParameters(cls, hvparams):
 435     """Check the given parameters for validity.
 436
 437     This should check the passed set of parameters for
 438     validity. Classes should extend, not replace, this function.
 439
 440     @type hvparams:  dict
 441     @param hvparams: dictionary with parameter names/value
 442     @raise errors.HypervisorError: when a parameter is not valid
 443
 444     """
 445     for name, (required, _, _, check_fn, errstr) in cls.PARAMETERS.items():
 446       value = hvparams[name]
 447       if not required and not value:
 448         continue
 449       if check_fn is not None and not check_fn(value):
 450         raise errors.HypervisorError("Parameter '%s' fails"
 451                                      " validation: %s (current value: '%s')" %
 452                                      (name, errstr, value))
 453
 454   @classmethod
 455   def PowercycleNode(cls, hvparams=None):
 456     """Hard powercycle a node using hypervisor specific methods.
 457
 458     This method should hard powercycle the node, using whatever
 459     methods the hypervisor provides. Note that this means that all
 460     instances running on the node must be stopped too.
 461
 462     @type hvparams: dict of strings
 463     @param hvparams: hypervisor params to be used on this node
 464
 465     """
 466     raise NotImplementedError
 467
 468   @staticmethod
 469   def GetLinuxNodeInfo(meminfo="/proc/meminfo", cpuinfo="/proc/cpuinfo"):
 470     """For linux systems, return actual OS information.
 471
 472     This is an abstraction for all non-hypervisor-based classes, where
 473     the node actually sees all the memory and CPUs via the /proc
 474     interface and standard commands. The other case if for example
 475     xen, where you only see the hardware resources via xen-specific
 476     tools.
 477
 478     @param meminfo: name of the file containing meminfo
 479     @type meminfo: string
 480     @param cpuinfo: name of the file containing cpuinfo
 481     @type cpuinfo: string
 482     @return: a dict with the following keys (values in MiB):
 483           - memory_total: the total memory size on the node
 484           - memory_free: the available memory on the node for instances
 485           - memory_dom0: the memory used by the node itself, if available
 486           - cpu_total: total number of CPUs
 487           - cpu_dom0: number of CPUs used by the node OS
 488           - cpu_nodes: number of NUMA domains
 489           - cpu_sockets: number of physical CPU sockets
 490
 491     """
 492     try:
 493       data = utils.ReadFile(meminfo).splitlines()
 494     except EnvironmentError, err:
 495       raise errors.HypervisorError("Failed to list node info: %s" % (err,))
 496
 497     result = {}
 498     sum_free = 0
 499     try:
 500       for line in data:
 501         splitfields = line.split(":", 1)
 502
 503         if len(splitfields) > 1:
 504           key = splitfields[0].strip()
 505           val = splitfields[1].strip()
 506           if key == "MemTotal":
 507             result["memory_total"] = int(val.split()[0]) / 1024
 508           elif key in ("MemFree", "Buffers", "Cached"):
 509             sum_free += int(val.split()[0]) / 1024
 510           elif key == "Active":
 511             result["memory_dom0"] = int(val.split()[0]) / 1024
 512     except (ValueError, TypeError), err:
 513       raise errors.HypervisorError("Failed to compute memory usage: %s" %
 514                                    (err,))
 515     result["memory_free"] = sum_free
 516
 517     cpu_total = 0
 518     try:
 519       fh = open(cpuinfo)
 520       try:
 521         cpu_total = len(re.findall(r"(?m)^processor\s*:\s*[0-9]+\s*$",
 522                                    fh.read()))
 523       finally:
 524         fh.close()
 525     except EnvironmentError, err:
 526       raise errors.HypervisorError("Failed to list node info: %s" % (err,))
 527     result["cpu_total"] = cpu_total
 528     # We assume that the node OS can access all the CPUs
 529     result["cpu_dom0"] = cpu_total
 530     # FIXME: export correct data here
 531     result["cpu_nodes"] = 1
 532     result["cpu_sockets"] = 1
 533
 534     return result
 535
 536   @classmethod
 537   def LinuxPowercycle(cls):
 538     """Linux-specific powercycle method.
 539
 540     """
 541     try:
 542       fd = os.open("/proc/sysrq-trigger", os.O_WRONLY)
 543       try:
 544         os.write(fd, "b")
 545       finally:
 546         fd.close()
 547     except OSError:
 548       logging.exception("Can't open the sysrq-trigger file")
 549       result = utils.RunCmd(["reboot", "-n", "-f"])
 550       if not result:
 551         logging.error("Can't run shutdown: %s", result.output)
 552
 553   @staticmethod
 554   def _FormatVerifyResults(msgs):
 555     """Formats the verification results, given a list of errors.
 556
 557     @param msgs: list of errors, possibly empty
 558     @return: overall problem description if something is wrong,
 559         C{None} otherwise
 560
 561     """
 562     if msgs:
 563       return "; ".join(msgs)
 564     else:
 565       return None